Annikka/evennia
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docstrings and typos in "\utils\" and "\scripts\"

Browse source
This commit is contained in:
tajmone 2015-03-09 11:06:48 +01:00 • committed by Griatch
parent e13a9b2749
commit 972b5cd2e2
5 changed files with 50 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

10
evennia/scripts/scripthandler.py
View file

@ -1,8 +1,8 @@
""" """
The script handler makes sure to check through all stored scripts The script handler makes sure to check through all stored scripts
to make sure they are still relevant. to make sure they are still relevant.
An scripthandler is automatically added to all game objects. You A scripthandler is automatically added to all game objects. You
access it through the property 'scripts' on the game object. access it through the property `scripts` on the game object.
""" """
from evennia.scripts.models import ScriptDB from evennia.scripts.models import ScriptDB
@ -21,7 +21,7 @@ class ScriptHandler(object):
obj - a reference to the object this handler is attached to. obj - a reference to the object this handler is attached to.
We retrieve all scripts attached to this object and check 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. cruft left over from a server shutdown.
""" """
self.obj = obj self.obj = obj
@ -49,7 +49,7 @@ class ScriptHandler(object):
def add(self, scriptclass, key=None, autostart=True): 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 scriptclass - either a class object
inheriting from Script, an instantiated script object inheriting from Script, an instantiated script object
@ -83,7 +83,7 @@ class ScriptHandler(object):
def get(self, scriptid): 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. a list.
""" """
return ScriptDB.objects.get_all_scripts_on_obj(self.obj, key=scriptid) return ScriptDB.objects.get_all_scripts_on_obj(self.obj, key=scriptid)

22
evennia/scripts/scripts.py
View file

@ -24,7 +24,7 @@ _SESSIONS = None
class ExtendedLoopingCall(LoopingCall): class ExtendedLoopingCall(LoopingCall):
""" """
LoopingCall that can start at a delay different LoopingCall that can start at a delay different
than self.interval. than `self.interval`.
""" """
start_delay = None start_delay = None
callcount = 0 callcount = 0
@ -63,8 +63,8 @@ class ExtendedLoopingCall(LoopingCall):
self() self()
else: else:
if start_delay is not None and start_delay >= 0: if start_delay is not None and start_delay >= 0:
# we set start_delay after the _reshedule call to make # we set `start_delay` after the `_reschedule` call to make
# next_call_time() find it until next reshedule. # next_call_time() find it until next reschedule.
self.interval = start_delay self.interval = start_delay
self._reschedule() self._reschedule()
self.interval = interval self.interval = interval
@ -81,7 +81,7 @@ class ExtendedLoopingCall(LoopingCall):
def _reschedule(self): def _reschedule(self):
""" """
Handle call rescheduling including Handle call rescheduling including
nulling start_delay and stopping if nulling `start_delay` and stopping if
number of repeats is reached. number of repeats is reached.
""" """
self.start_delay = None self.start_delay = None
@ -99,7 +99,7 @@ class ExtendedLoopingCall(LoopingCall):
def next_call_time(self): def next_call_time(self):
""" """
Return the time in seconds until the next call. This takes Return the time in seconds until the next call. This takes
start_delay into account. `start_delay` into account.
""" """
if self.running: if self.running:
currentTime = self.clock.seconds() currentTime = self.clock.seconds()
@ -112,7 +112,7 @@ class ExtendedLoopingCall(LoopingCall):
class ScriptBase(ScriptDB): class ScriptBase(ScriptDB):
""" """
Base class for scripts. Don't inherit from this, inherit Base class for scripts. Don't inherit from this, inherit
from the class 'Script' instead. from the class `Script` instead.
""" """
__metaclass__ = TypeclassBase __metaclass__ = TypeclassBase
objects = ScriptManager() objects = ScriptManager()
@ -193,7 +193,7 @@ class ScriptBase(ScriptDB):
def time_until_next_repeat(self): def time_until_next_repeat(self):
""" """
Returns the time in seconds until the script will be 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 This is not used in any way by the script's stepping
system; it's only here for the user to be able to system; it's only here for the user to be able to
check in on their scripts and when they will next be run. check in on their scripts and when they will next be run.
@ -207,7 +207,7 @@ class ScriptBase(ScriptDB):
return None return None
def remaining_repeats(self): 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 task = self.ndb._task
if task: if task:
return max(0, self.db_repeats - task.callcount) return max(0, self.db_repeats - task.callcount)
@ -280,7 +280,7 @@ class ScriptBase(ScriptDB):
def pause(self): def pause(self):
""" """
This stops a running script and stores its active state. 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: if not self.db._paused_time:
# only allow pause if not already paused # only allow pause if not already paused
@ -293,7 +293,7 @@ class ScriptBase(ScriptDB):
def unpause(self): 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: if self.db._paused_time:
# only unpause if previously paused # only unpause if previously paused
@ -367,7 +367,7 @@ class DefaultScript(ScriptBase):
desc (string) - optional description of script, shown in listings desc (string) - optional description of script, shown in listings
obj (Object) - optional object that this script is connected to obj (Object) - optional object that this script is connected to
and acts on (set automatically and acts on (set automatically
by obj.scripts.add()) by `obj.scripts.add()`)
interval (int) - how often script should run, in seconds. interval (int) - how often script should run, in seconds.
<=0 turns off ticker <=0 turns off ticker
start_delay (bool) - if the script should start repeating right start_delay (bool) - if the script should start repeating right

22
evennia/scripts/tickerhandler.py
View file

@ -11,23 +11,27 @@ server reloads and be started automaticall on boot.
Example: Example:
```python
from evennia.scripts.tickerhandler import TICKER_HANDLER from evennia.scripts.tickerhandler import TICKER_HANDLER
# tick myobj every 15 seconds # tick myobj every 15 seconds
TICKER_HANDLER.add(myobj, 15) 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 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 one such alternate name per interval though). The
handler will transparently set up and add new timers behind handler will transparently set up and add new timers behind
the scenes to tick at given intervals, using a TickerPool. the scenes to tick at given intervals, using a TickerPool.
To remove: To remove:
```python
TICKER_HANDLER.remove(myobj, 15) 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. 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 Ticker class and then changing TickerPool and TickerHandler to use the
custom classes custom classes
```python
class MyTicker(Ticker): class MyTicker(Ticker):
# [doing custom stuff] # [doing custom stuff]
@ -42,10 +47,11 @@ class MyTickerPool(TickerPool):
ticker_class = MyTicker ticker_class = MyTicker
class MyTickerHandler(TickerHandler): class MyTickerHandler(TickerHandler):
ticker_pool_class = MyTickerPool ticker_pool_class = MyTickerPool
```
If one wants to duplicate TICKER_HANDLER's auto-saving feature in 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 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. call the handler's `save()` and `restore()` methods when the server reboots.
""" """
from twisted.internet.defer import inlineCallbacks from twisted.internet.defer import inlineCallbacks
@ -68,15 +74,15 @@ Ticker was not added."""
class Ticker(object): class Ticker(object):
""" """
Represents a repeatedly running task that calls Represents a repeatedly running task that calls
hooks repeatedly. Overload _callback to change the hooks repeatedly. Overload `_callback` to change the
way it operates. way it operates.
""" """
@inlineCallbacks @inlineCallbacks
def _callback(self): def _callback(self):
""" """
This will be called repeatedly every self.interval seconds. This will be called repeatedly every `self.interval` seconds.
self.subscriptions contain tuples of (obj, args, kwargs) for `self.subscriptions` contain tuples of (obj, args, kwargs) for
each subscribing object. each subscribing object.
If overloading, this callback is expected to handle all If overloading, this callback is expected to handle all

16
evennia/utils/ansi.py
View file

@ -67,28 +67,28 @@ _PARSE_CACHE_SIZE = 10000
class ANSIParser(object): class ANSIParser(object):
""" """
A class that parses ansi markup A class that parses ANSI markup
to ANSI command sequences to ANSI command sequences
We also allow to escape colour codes 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 an extra { for Merc-style codes
""" """
def sub_ansi(self, ansimatch): def sub_ansi(self, ansimatch):
""" """
Replacer used by re.sub to replace ansi Replacer used by `re.sub` to replace ANSI
markers with correct ansi sequences markers with correct ANSI sequences
""" """
return self.ansi_map.get(ansimatch.group(), "") return self.ansi_map.get(ansimatch.group(), "")
def sub_xterm256(self, rgbmatch): 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. tag. It must return the correct ansi sequence.
It checks self.do_xterm256 to determine if conversion It checks `self.do_xterm256` to determine if conversion
to standard ansi should be done or not. to standard ANSI should be done or not.
""" """
if not rgbmatch: if not rgbmatch:
return "" return ""
@ -183,7 +183,7 @@ class ANSIParser(object):
Parses a string, subbing color codes according to Parses a string, subbing color codes according to
the stored mapping. the stored mapping.
strip_ansi flag instead removes all ansi markup. strip_ansi flag instead removes all ANSI markup.
""" """
if hasattr(string, '_raw_string'): if hasattr(string, '_raw_string'):

20
evennia/utils/batchprocessors.py
View file

@ -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 that can be affected by what is being built - the database is
populated on the fly. The drawback is safety and entry threshold - the populated on the fly. The drawback is safety and entry threshold - the
code is executed as would any server code, without mud-specific 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 etc. You also need to know Python and Evennia's API. Hence it's
recommended that the batch-code processor is limited only to recommended that the batch-code processor is limited only to
superusers or highly trusted staff. superusers or highly trusted staff.
@ -37,11 +37,11 @@ superusers or highly trusted staff.
Batch-command processor file syntax Batch-command processor file syntax
The batch-command processor accepts 'batchcommand files' e.g 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 simple format. The engine runs each command in sequence, as if they
had been run at the game prompt. 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. end.
#INSERT path.batchcmdfile - this as the first entry on a line will #INSERT path.batchcmdfile - this as the first entry on a line will
@ -56,6 +56,7 @@ editor or prompt.
Example of batch.ev file: Example of batch.ev file:
---------------------------- ----------------------------
```
# batch file # batch file
# all lines starting with # are comments; they also indicate # all lines starting with # are comments; they also indicate
# that a command definition is over. # 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 # 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) # 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 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 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 allows them to the executed in blocks. This way of working assures a
sequential execution of the file and allows for features like stepping sequential execution of the file and allows for features like stepping
from block to block (without executing those coming before), as well from block to block (without executing those coming before), as well
as automatic deletion of created objects etc. You can however also run 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 blocks are separated by python comments starting with special
code words. code words.
@ -140,6 +143,7 @@ caller - the object executing the script
Example batch.py file Example batch.py file
----------------------------------- -----------------------------------
```
#HEADER #HEADER
import traceback import traceback
@ -162,7 +166,7 @@ caller.msg("The object was created!")
#CODE #CODE
script = create.create_script() script = create.create_script()
```
""" """
import re import re
@ -191,7 +195,7 @@ def read_batchfile(pythonpath, file_ending='.py'):
""" """
This reads the contents of a batch-file. This reads the contents of a batch-file.
Filename is considered to be a python path to 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 file_ending specify which batchfile ending should be
assumed (.ev or .py). The ending should not be included assumed (.ev or .py). The ending should not be included