From 972b5cd2e2699cc26a65713cb6ec3d39c19c997f Mon Sep 17 00:00:00 2001 From: tajmone Date: Mon, 9 Mar 2015 11:06:48 +0100 Subject: [PATCH] docstrings and typos in "\utils\" and "\scripts\" --- evennia/scripts/scripthandler.py | 10 +++++----- evennia/scripts/scripts.py | 22 +++++++++++----------- evennia/scripts/tickerhandler.py | 22 ++++++++++++++-------- evennia/utils/ansi.py | 16 ++++++++-------- evennia/utils/batchprocessors.py | 20 ++++++++++++-------- 5 files changed, 50 insertions(+), 40 deletions(-) diff --git a/evennia/scripts/scripthandler.py b/evennia/scripts/scripthandler.py index 6ec5cf635d..4e3eb78ee1 100644 --- a/evennia/scripts/scripthandler.py +++ b/evennia/scripts/scripthandler.py @@ -1,8 +1,8 @@ """ The script handler makes sure to check through all stored scripts to make sure they are still relevant. -An scripthandler is automatically added to all game objects. You -access it through the property 'scripts' on the game object. +A scripthandler is automatically added to all game objects. You +access it through the property `scripts` on the game object. """ from evennia.scripts.models import ScriptDB @@ -21,7 +21,7 @@ class ScriptHandler(object): obj - a reference to the object this handler is attached to. We retrieve all scripts attached to this object and check - if they are all peristent. If they are not, they are just + if they are all persistent. If they are not, they are just cruft left over from a server shutdown. """ self.obj = obj @@ -49,7 +49,7 @@ class ScriptHandler(object): def add(self, scriptclass, key=None, autostart=True): """ - Add an script to this object. + Add a script to this object. scriptclass - either a class object inheriting from Script, an instantiated script object @@ -83,7 +83,7 @@ class ScriptHandler(object): def get(self, scriptid): """ - Return one or all scripts on this object matching scriptid. Will return + Return one or all scripts on this object matching `scriptid`. Will return a list. """ return ScriptDB.objects.get_all_scripts_on_obj(self.obj, key=scriptid) diff --git a/evennia/scripts/scripts.py b/evennia/scripts/scripts.py index 582b8fe016..e74f2b56dd 100644 --- a/evennia/scripts/scripts.py +++ b/evennia/scripts/scripts.py @@ -24,7 +24,7 @@ _SESSIONS = None class ExtendedLoopingCall(LoopingCall): """ LoopingCall that can start at a delay different - than self.interval. + than `self.interval`. """ start_delay = None callcount = 0 @@ -63,8 +63,8 @@ class ExtendedLoopingCall(LoopingCall): self() else: if start_delay is not None and start_delay >= 0: - # we set start_delay after the _reshedule call to make - # next_call_time() find it until next reshedule. + # we set `start_delay` after the `_reschedule` call to make + # next_call_time() find it until next reschedule. self.interval = start_delay self._reschedule() self.interval = interval @@ -81,7 +81,7 @@ class ExtendedLoopingCall(LoopingCall): def _reschedule(self): """ Handle call rescheduling including - nulling start_delay and stopping if + nulling `start_delay` and stopping if number of repeats is reached. """ self.start_delay = None @@ -99,7 +99,7 @@ class ExtendedLoopingCall(LoopingCall): def next_call_time(self): """ Return the time in seconds until the next call. This takes - start_delay into account. + `start_delay` into account. """ if self.running: currentTime = self.clock.seconds() @@ -112,7 +112,7 @@ class ExtendedLoopingCall(LoopingCall): class ScriptBase(ScriptDB): """ Base class for scripts. Don't inherit from this, inherit - from the class 'Script' instead. + from the class `Script` instead. """ __metaclass__ = TypeclassBase objects = ScriptManager() @@ -193,7 +193,7 @@ class ScriptBase(ScriptDB): def time_until_next_repeat(self): """ Returns the time in seconds until the script will be - run again. If this is not a stepping script, returns None. + run again. If this is not a stepping script, returns `None`. This is not used in any way by the script's stepping system; it's only here for the user to be able to check in on their scripts and when they will next be run. @@ -207,7 +207,7 @@ class ScriptBase(ScriptDB): return None def remaining_repeats(self): - "Get the number of returning repeats. Returns None if unlimited repeats." + "Get the number of returning repeats. Returns `None` if unlimited repeats." task = self.ndb._task if task: return max(0, self.db_repeats - task.callcount) @@ -280,7 +280,7 @@ class ScriptBase(ScriptDB): def pause(self): """ This stops a running script and stores its active state. - It WILL NOT call that at_stop() hook. + It WILL NOT call that `at_stop()` hook. """ if not self.db._paused_time: # only allow pause if not already paused @@ -293,7 +293,7 @@ class ScriptBase(ScriptDB): def unpause(self): """ - Restart a paused script. This WILL call the at_start() hook. + Restart a paused script. This WILL call the `at_start()` hook. """ if self.db._paused_time: # only unpause if previously paused @@ -367,7 +367,7 @@ class DefaultScript(ScriptBase): desc (string) - optional description of script, shown in listings obj (Object) - optional object that this script is connected to and acts on (set automatically - by obj.scripts.add()) + by `obj.scripts.add()`) interval (int) - how often script should run, in seconds. <=0 turns off ticker start_delay (bool) - if the script should start repeating right diff --git a/evennia/scripts/tickerhandler.py b/evennia/scripts/tickerhandler.py index 79fbd096d8..daceadfd06 100644 --- a/evennia/scripts/tickerhandler.py +++ b/evennia/scripts/tickerhandler.py @@ -11,23 +11,27 @@ server reloads and be started automaticall on boot. Example: +```python from evennia.scripts.tickerhandler import TICKER_HANDLER # tick myobj every 15 seconds TICKER_HANDLER.add(myobj, 15) +``` -The handler will by default try to call a hook "at_tick()" +The handler will by default try to call a hook `at_tick()` on the subscribing object. The hook's name can be changed -if the "hook_key" keyword is given to the add() method (only +if the `hook_key` keyword is given to the `add()` method (only one such alternate name per interval though). The handler will transparently set up and add new timers behind the scenes to tick at given intervals, using a TickerPool. To remove: +```python TICKER_HANDLER.remove(myobj, 15) +``` -The interval must be given since a single object can be subcribed +The interval must be given since a single object can be subscribed to many different tickers at the same time. @@ -35,6 +39,7 @@ The TickerHandler's functionality can be overloaded by modifying the Ticker class and then changing TickerPool and TickerHandler to use the custom classes +```python class MyTicker(Ticker): # [doing custom stuff] @@ -42,10 +47,11 @@ class MyTickerPool(TickerPool): ticker_class = MyTicker class MyTickerHandler(TickerHandler): ticker_pool_class = MyTickerPool +``` If one wants to duplicate TICKER_HANDLER's auto-saving feature in -a custom handler one can make a custom AT_STARTSTOP_MODULE entry to -call the handler's save() and restore() methods when the server reboots. +a custom handler one can make a custom `AT_STARTSTOP_MODULE` entry to +call the handler's `save()` and `restore()` methods when the server reboots. """ from twisted.internet.defer import inlineCallbacks @@ -68,15 +74,15 @@ Ticker was not added.""" class Ticker(object): """ Represents a repeatedly running task that calls - hooks repeatedly. Overload _callback to change the + hooks repeatedly. Overload `_callback` to change the way it operates. """ @inlineCallbacks def _callback(self): """ - This will be called repeatedly every self.interval seconds. - self.subscriptions contain tuples of (obj, args, kwargs) for + This will be called repeatedly every `self.interval` seconds. + `self.subscriptions` contain tuples of (obj, args, kwargs) for each subscribing object. If overloading, this callback is expected to handle all diff --git a/evennia/utils/ansi.py b/evennia/utils/ansi.py index 4f11bd91cd..774b5917fe 100644 --- a/evennia/utils/ansi.py +++ b/evennia/utils/ansi.py @@ -67,28 +67,28 @@ _PARSE_CACHE_SIZE = 10000 class ANSIParser(object): """ - A class that parses ansi markup + A class that parses ANSI markup to ANSI command sequences We also allow to escape colour codes - by prepending with a \ for mux-style and xterm256, + by prepending with a \ for MUX-style and xterm256, an extra { for Merc-style codes """ def sub_ansi(self, ansimatch): """ - Replacer used by re.sub to replace ansi - markers with correct ansi sequences + Replacer used by `re.sub` to replace ANSI + markers with correct ANSI sequences """ return self.ansi_map.get(ansimatch.group(), "") def sub_xterm256(self, rgbmatch): """ - This is a replacer method called by re.sub with the matched + This is a replacer method called by `re.sub` with the matched tag. It must return the correct ansi sequence. - It checks self.do_xterm256 to determine if conversion - to standard ansi should be done or not. + It checks `self.do_xterm256` to determine if conversion + to standard ANSI should be done or not. """ if not rgbmatch: return "" @@ -183,7 +183,7 @@ class ANSIParser(object): Parses a string, subbing color codes according to the stored mapping. - strip_ansi flag instead removes all ansi markup. + strip_ansi flag instead removes all ANSI markup. """ if hasattr(string, '_raw_string'): diff --git a/evennia/utils/batchprocessors.py b/evennia/utils/batchprocessors.py index d07fb0553b..278ac7c1a6 100644 --- a/evennia/utils/batchprocessors.py +++ b/evennia/utils/batchprocessors.py @@ -26,7 +26,7 @@ the batch-code processor. There is no in-game character that moves and that can be affected by what is being built - the database is populated on the fly. The drawback is safety and entry threshold - the code is executed as would any server code, without mud-specific -permission checks and you have full access to modifying objects +permission-checks, and you have full access to modifying objects etc. You also need to know Python and Evennia's API. Hence it's recommended that the batch-code processor is limited only to superusers or highly trusted staff. @@ -37,11 +37,11 @@ superusers or highly trusted staff. Batch-command processor file syntax The batch-command processor accepts 'batchcommand files' e.g -'batch.ev', containing a sequence of valid evennia commands in a +`batch.ev`, containing a sequence of valid Evennia commands in a simple format. The engine runs each command in sequence, as if they had been run at the game prompt. -Each evennia command must be delimited by a line comment to mark its +Each Evennia command must be delimited by a line comment to mark its end. #INSERT path.batchcmdfile - this as the first entry on a line will @@ -56,6 +56,7 @@ editor or prompt. Example of batch.ev file: ---------------------------- +``` # batch file # all lines starting with # are comments; they also indicate # that a command definition is over. @@ -88,9 +89,11 @@ It seems the bottom of the box is a bit loose. # Done, the box is in the warehouse! (this last comment is not necessary to # close the @drop command since it's the end of the file) +``` + ------------------------- -An example batch file is contrib/examples/batch_example.ev. +An example batch file is `contrib/examples/batch_example.ev`. ========================================================================== @@ -98,13 +101,13 @@ An example batch file is contrib/examples/batch_example.ev. Batch-code processor file syntax -The Batch-code processor accepts full python modules (e.g. "batch.py") +The Batch-code processor accepts full python modules (e.g. `batch.py`) that looks identical to normal Python files with a few exceptions that allows them to the executed in blocks. This way of working assures a sequential execution of the file and allows for features like stepping from block to block (without executing those coming before), as well as automatic deletion of created objects etc. You can however also run -a batch-code python file directly using Python (and can also be de). +a batch-code Python file directly using Python (and can also be de). Code blocks are separated by python comments starting with special code words. @@ -140,6 +143,7 @@ caller - the object executing the script Example batch.py file ----------------------------------- +``` #HEADER import traceback @@ -162,7 +166,7 @@ caller.msg("The object was created!") #CODE script = create.create_script() - +``` """ import re @@ -191,7 +195,7 @@ def read_batchfile(pythonpath, file_ending='.py'): """ This reads the contents of a batch-file. Filename is considered to be a python path to a batch file - relative the directory specified in settings.py. + relative the directory specified in `settings.py`. file_ending specify which batchfile ending should be assumed (.ev or .py). The ending should not be included