Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-16 21:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

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
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)

22
evennia/scripts/scripts.py
View file

@ -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

22
evennia/scripts/tickerhandler.py
View file

@ -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

16
evennia/utils/ansi.py
View file

@ -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'):

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
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