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

This concludes the translation of Evennia's docstrings to Google style. This Resolves #709.

Browse source
This commit is contained in:
Griatch 2015-09-27 20:23:49 +02:00
parent eb2bd8d44c
commit f73dc81274
1 changed files with 107 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

170
evennia/utils/utils.py
View file

@ -1210,18 +1210,21 @@ def string_similarity(string1, string2):
def string_suggestions(string, vocabulary, cutoff=0.6, maxnum=3): def string_suggestions(string, vocabulary, cutoff=0.6, maxnum=3):
""" """
Given a `string` and a `vocabulary`, return a match or a list of suggestions Given a `string` and a `vocabulary`, return a match or a list of
based on string similarity. suggestions based on string similarity.
Args: Args:
string (str)- a string to search for. string (str): A string to search for.
vocabulary (iterable) - a list of available strings. vocabulary (iterable): A list of available strings.
cutoff (int, 0-1) - limit the similarity matches (higher, the more cutoff (int, 0-1): Limit the similarity matches (the higher
exact is required). the value, the more exact a match is required).
maxnum (int) - maximum number of suggestions to return. maxnum (int): Maximum number of suggestions to return.
Returns: Returns:
list of suggestions from `vocabulary` (could be empty if there are suggestions (list): Suggestions from `vocabulary` that fall
no matches). under the `cutoff` setting. Could be empty if there are no
matches.
""" """
return [tup[1] for tup in sorted([(string_similarity(string, sugg), sugg) return [tup[1] for tup in sorted([(string_similarity(string, sugg), sugg)
for sugg in vocabulary], for sugg in vocabulary],
@ -1231,19 +1234,21 @@ def string_suggestions(string, vocabulary, cutoff=0.6, maxnum=3):
def string_partial_matching(alternatives, inp, ret_index=True): def string_partial_matching(alternatives, inp, ret_index=True):
""" """
Partially matches a string based on a list of `alternatives`. Matching Partially matches a string based on a list of `alternatives`.
is made from the start of each subword in each alternative. Case is not Matching is made from the start of each subword in each
important. So e.g. "bi sh sw" or just "big" or "shiny" or "sw" will match alternative. Case is not important. So e.g. "bi sh sw" or just
"Big shiny sword". Scoring is done to allow to separate by most common "big" or "shiny" or "sw" will match "Big shiny sword". Scoring is
demoninator. You will get multiple matches returned if appropriate. done to allow to separate by most common demoninator. You will get
multiple matches returned if appropriate.
Input: Args:
alternatives (list of str) - list of possible strings to match. alternatives (list of str): A list of possible strings to
inp (str) - search criterion. match.
ret_index (bool) - return list of indices (from alternatives inp (str): Search criterion.
array) or strings. ret_index (bool, optional): Return list of indices (from alternatives
array) instead of strings.
Returns: Returns:
list of matching indices or strings, or an empty list. matches (list): String-matches or indices if `ret_index` is `True`.
""" """
if not alternatives or not inp: if not alternatives or not inp:
@ -1279,31 +1284,37 @@ def string_partial_matching(alternatives, inp, ret_index=True):
def format_table(table, extra_space=1): def format_table(table, extra_space=1):
""" """
Note: `evennia.utils.prettytable` is more powerful than this, but this Note: `evennia.utils.evtable` is more powerful than this, but this
function can be useful when the number of columns and rows are function can be useful when the number of columns and rows are
unknown and must be calculated on the fly. unknown and must be calculated on the fly.
Takes a table of columns: [[val,val,val,...], [val,val,val,...], ...] Args.
where each val will be placed on a separate row in the column. All table (list): A list of lists to represent columns in the
columns must have the same number of rows (some positions may be table: `[[val,val,val,...], [val,val,val,...], ...]`, where
empty though). each val will be placed on a separate row in the
column. All columns must have the same number of rows (some
positions may be empty though).
extra_space (int, optional): Sets how much *minimum* extra
padding (in characters) should be left between columns.
The function formats the columns to be as wide as the widest member Returns:
of each column. table (list): A list of lists representing the rows to print
out one by one.
`extra_space` defines how much *minimum* extra padding should be left between Notes:
columns. The function formats the columns to be as wide as the widest member
of each column.
print the resulting list e.g. with: Examples:
```python ```python
for ir, row in enumarate(ftable): for ir, row in enumarate(ftable):
if ir == 0: if ir == 0:
# make first row white # make first row white
string += "\n{w" + ""join(row) + "{n" string += "\n{w" + ""join(row) + "{n"
else: else:
string += "\n" + "".join(row) string += "\n" + "".join(row)
print string print string
``` ```
""" """
if not table: if not table:
@ -1316,17 +1327,25 @@ def format_table(table, extra_space=1):
for icol, col in enumerate(table)]) for icol, col in enumerate(table)])
return ftable return ftable
def get_evennia_pids(): def get_evennia_pids():
""" """
Get the currently valid PIDs (Process IDs) of the Portal and Server Get the currently valid PIDs (Process IDs) of the Portal and
by trying to access a PID file. This can be used to determine if we Server by trying to access a PID file.
are in a subprocess by something like:
```python Returns:
self_pid = os.getpid() server, portal (tuple): The PIDs of the respective processes,
server_pid, portal_pid = get_evennia_pids() or two `None` values if not found.
is_subprocess = self_pid not in (server_pid, portal_pid)
``` Examples:
This can be used to determine if we are in a subprocess by
something like:
```python
self_pid = os.getpid()
server_pid, portal_pid = get_evennia_pids()
is_subprocess = self_pid not in (server_pid, portal_pid)
```
""" """
server_pidfile = os.path.join(settings.GAME_DIR, 'server.pid') server_pidfile = os.path.join(settings.GAME_DIR, 'server.pid')
portal_pidfile = os.path.join(settings.GAME_DIR, 'portal.pid') portal_pidfile = os.path.join(settings.GAME_DIR, 'portal.pid')
@ -1347,14 +1366,9 @@ from gc import get_referents
from sys import getsizeof from sys import getsizeof
def deepsize(obj, max_depth=4): def deepsize(obj, max_depth=4):
""" """
Get not only size of the given object, but also the Get not only size of the given object, but also the size of
size of objects referenced by the object, down to objects referenced by the object, down to `max_depth` distance
`max_depth` distance from the object. from the object.
Note that this measure is necessarily approximate
since some memory is shared between objects. The
`max_depth` of 4 is roughly tested to give reasonable
size information about database models and their handlers.
Args: Args:
obj (object): the object to be measured. obj (object): the object to be measured.
@ -1364,6 +1378,13 @@ def deepsize(obj, max_depth=4):
Returns: Returns:
size (int): deepsize of `obj` in Bytes. size (int): deepsize of `obj` in Bytes.
Notes:
This measure is necessarily approximate since some
memory is shared between objects. The `max_depth` of 4 is roughly
tested to give reasonable size information about database models
and their handlers.
""" """
def _recurse(o, dct, depth): def _recurse(o, dct, depth):
if max_depth >= 0 and depth > max_depth: if max_depth >= 0 and depth > max_depth:
@ -1383,8 +1404,8 @@ def deepsize(obj, max_depth=4):
_missing = object() _missing = object()
class lazy_property(object): class lazy_property(object):
""" """
Delays loading of property until first access. Credit goes to Delays loading of property until first access. Credit goes to the
the Implementation in the werkzeug suite: Implementation in the werkzeug suite:
http://werkzeug.pocoo.org/docs/utils/#werkzeug.utils.cached_property http://werkzeug.pocoo.org/docs/utils/#werkzeug.utils.cached_property
This should be used as a decorator in a class and in Evennia is This should be used as a decorator in a class and in Evennia is
@ -1396,8 +1417,8 @@ class lazy_property(object):
return AttributeHandler(self) return AttributeHandler(self)
``` ```
Once initialized, the `AttributeHandler` will be available Once initialized, the `AttributeHandler` will be available as a
as a property "attributes" on the object. property "attributes" on the object.
""" """
def __init__(self, func, name=None, doc=None): def __init__(self, func, name=None, doc=None):
@ -1421,19 +1442,34 @@ _STRIP_ANSI = None
_RE_CONTROL_CHAR = re.compile('[%s]' % re.escape(''.join([unichr(c) for c in range(0,32)])))# + range(127,160)]))) _RE_CONTROL_CHAR = re.compile('[%s]' % re.escape(''.join([unichr(c) for c in range(0,32)])))# + range(127,160)])))
def strip_control_sequences(string): def strip_control_sequences(string):
""" """
remove non-print text sequences from `string`. Remove non-print text sequences.
Args:
string (str): Text to strip.
Returns.
text (str): Stripped text.
""" """
global _STRIP_ANSI global _STRIP_ANSI
if not _STRIP_ANSI: if not _STRIP_ANSI:
from evennia.utils.ansi import strip_raw_ansi as _STRIP_ANSI from evennia.utils.ansi import strip_raw_ansi as _STRIP_ANSI
return _RE_CONTROL_CHAR.sub('', _STRIP_ANSI(string)) return _RE_CONTROL_CHAR.sub('', _STRIP_ANSI(string))
def calledby(callerdepth=1): def calledby(callerdepth=1):
""" """
Only to be used for debug purposes. Only to be used for debug purposes. Insert this debug function in
Insert this debug function in another function; it will print another function; it will print which function called it.
which function called it. With `callerdepth` > 1, it will print the
caller of the caller etc. Args:
callerdepth (int): Must be larger than 0. When > 1, it will
print the caller of the caller etc.
Returns:
calledby (str): A debug string detailing which routine called
us.
""" """
import inspect, os import inspect, os
stack = inspect.stack() stack = inspect.stack()
@ -1449,6 +1485,14 @@ def m_len(target):
""" """
Provides length checking for strings with MXP patterns, and falls Provides length checking for strings with MXP patterns, and falls
back to normal len for other objects. back to normal len for other objects.
Args:
target (string): A string with potential MXP components
to search.
Returns:
length (int): The length of `target`, ignoring MXP components.
""" """
# Would create circular import if in module root. # Would create circular import if in module root.
from evennia.utils.ansi import ANSI_PARSER from evennia.utils.ansi import ANSI_PARSER