From d449acb57bc3e425be86f39d39240ebc8a4ed6cc Mon Sep 17 00:00:00 2001 From: Griatch Date: Thu, 8 Oct 2020 23:23:27 +0200 Subject: [PATCH] Continue to clean up docstrings --- docs/Makefile | 2 +- evennia/server/portal/ssh.py | 23 ++++++++++++----------- evennia/server/portal/telnet.py | 25 +++++++++++++------------ evennia/server/sessionhandler.py | 16 +++++++++------- evennia/server/signals.py | 11 +++++++---- evennia/typeclasses/attributes.py | 7 ++++--- evennia/typeclasses/managers.py | 16 ++++++++-------- 7 files changed, 54 insertions(+), 46 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 759a78765c..2d8e455503 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -118,7 +118,7 @@ quickstrict: local: make _check-env - make clean + #make clean make _autodoc-index make _html-build @echo "" diff --git a/evennia/server/portal/ssh.py b/evennia/server/portal/ssh.py index 9f73bf3b79..565846ee12 100644 --- a/evennia/server/portal/ssh.py +++ b/evennia/server/portal/ssh.py @@ -277,17 +277,18 @@ class SshProtocol(Manhole, session.Session): text (str): The first argument is always the text string to send. No other arguments are considered. Keyword Args: - options (dict): Send-option flags - - mxp: Enforce MXP link support. - - ansi: Enforce no ANSI colors. - - xterm256: Enforce xterm256 colors, regardless of TTYPE setting. - - nocolor: Strip all colors. - - raw: Pass string through without any ansi processing - (i.e. include Evennia ansi markers but do not - convert them into ansi tokens) - - echo: Turn on/off line echo on the client. Turn - off line echo for client, for example for password. - Note that it must be actively turned back on again! + options (dict): Send-option flags: + + - mxp: Enforce MXP link support. + - ansi: Enforce no ANSI colors. + - xterm256: Enforce xterm256 colors, regardless of TTYPE setting. + - nocolor: Strip all colors. + - raw: Pass string through without any ansi processing + (i.e. include Evennia ansi markers but do not + convert them into ansi tokens) + - echo: Turn on/off line echo on the client. Turn + off line echo for client, for example for password. + Note that it must be actively turned back on again! """ # print "telnet.send_text", args,kwargs # DEBUG diff --git a/evennia/server/portal/telnet.py b/evennia/server/portal/telnet.py index 8bdf31035c..70a3b815ef 100644 --- a/evennia/server/portal/telnet.py +++ b/evennia/server/portal/telnet.py @@ -388,18 +388,19 @@ class TelnetProtocol(Telnet, StatefulTelnetProtocol, Session): text (str): The first argument is always the text string to send. No other arguments are considered. Keyword Args: - options (dict): Send-option flags - - mxp: Enforce MXP link support. - - ansi: Enforce no ANSI colors. - - xterm256: Enforce xterm256 colors, regardless of TTYPE. - - noxterm256: Enforce no xterm256 color support, regardless of TTYPE. - - nocolor: Strip all Color, regardless of ansi/xterm256 setting. - - raw: Pass string through without any ansi processing - (i.e. include Evennia ansi markers but do not - convert them into ansi tokens) - - echo: Turn on/off line echo on the client. Turn - off line echo for client, for example for password. - Note that it must be actively turned back on again! + options (dict): Send-option flags: + + - mxp: Enforce MXP link support. + - ansi: Enforce no ANSI colors. + - xterm256: Enforce xterm256 colors, regardless of TTYPE. + - noxterm256: Enforce no xterm256 color support, regardless of TTYPE. + - nocolor: Strip all Color, regardless of ansi/xterm256 setting. + - raw: Pass string through without any ansi processing + (i.e. include Evennia ansi markers but do not + convert them into ansi tokens) + - echo: Turn on/off line echo on the client. Turn + off line echo for client, for example for password. + Note that it must be actively turned back on again! """ text = args[0] if args else "" diff --git a/evennia/server/sessionhandler.py b/evennia/server/sessionhandler.py index 6b13e177e0..9b78fc3378 100644 --- a/evennia/server/sessionhandler.py +++ b/evennia/server/sessionhandler.py @@ -177,11 +177,13 @@ class SessionHandler(dict): send-instruction, with the keyword itself being the name of the instruction (like "text"). Suitable values for each keyword are: - - arg -> [[arg], {}] - - [args] -> [[args], {}] - - {kwargs} -> [[], {kwargs}] - - [args, {kwargs}] -> [[arg], {kwargs}] - - [[args], {kwargs}] -> [[args], {kwargs}] + :: + + arg -> [[arg], {}] + [args] -> [[args], {}] + {kwargs} -> [[], {kwargs}] + [args, {kwargs}] -> [[arg], {kwargs}] + [[args], {kwargs}] -> [[args], {kwargs}] Returns: kwargs (dict): A cleaned dictionary of cmdname:[[args],{kwargs}] pairs, @@ -761,7 +763,7 @@ class ServerSessionHandler(SessionHandler): Given a client identification hash (for session types that offer them) return all sessions with a matching hash. - Args + Args: csessid (str): The session hash. Returns: sessions (list): The sessions with matching .csessid, if any. @@ -827,7 +829,7 @@ class ServerSessionHandler(SessionHandler): """ Split incoming data into its inputfunc counterparts. This should be called by the serversession.data_in - as sessionhandler.call_inputfunc(self, **kwargs). + as `sessionhandler.call_inputfunc(self, **kwargs)`. We also intercept OOB communication here. diff --git a/evennia/server/signals.py b/evennia/server/signals.py index fd96becc6f..5527fe425d 100644 --- a/evennia/server/signals.py +++ b/evennia/server/signals.py @@ -2,21 +2,24 @@ This module brings Django Signals into Evennia. These are events that can be subscribed to by importing a given Signal and using the following code. +:: -THIS_SIGNAL.connect(callback, sender_object) + THIS_SIGNAL.connect(callback, sender_object`) -When other code calls THIS_SIGNAL.send(sender, **kwargs), the callback +When other code calls `THIS_SIGNAL.send(sender, **kwargs)`, the callback will be triggered. Callbacks must be in the following format: +:: -def my_callback(sender, **kwargs): - ... + def my_callback(sender, **kwargs): + ... This is used on top of hooks to make certain features easier to add to contribs without necessitating a full takeover of hooks that may be in high demand. + """ from django.dispatch import Signal diff --git a/evennia/typeclasses/attributes.py b/evennia/typeclasses/attributes.py index 053361ed2c..a33987c71e 100644 --- a/evennia/typeclasses/attributes.py +++ b/evennia/typeclasses/attributes.py @@ -596,6 +596,7 @@ class AttributeHandler(object): *args (tuple): Each argument should be a tuples (can be of varying length) representing the Attribute to add to this object. Supported tuples are + - `(key, value)` - `(key, value, category)` - `(key, value, category, lockstring)` @@ -847,9 +848,9 @@ def initialize_nick_templates(in_template, out_template): matched by the in_template. Returns: - regex (regex): Regex to match against strings - template (str): Template with markers {arg1}, {arg2}, etc for - replacement using the standard .format method. + (regex, str): Regex to match against strings and a template + Template with markers `{arg1}`, `{arg2}`, etc for + replacement using the standard `.format` method. Raises: NickTemplateInvalid: If the in/out template does not have a matching diff --git a/evennia/typeclasses/managers.py b/evennia/typeclasses/managers.py index 6aa3ffd840..88c35d2122 100644 --- a/evennia/typeclasses/managers.py +++ b/evennia/typeclasses/managers.py @@ -31,15 +31,15 @@ class TypedObjectManager(idmapper.manager.SharedMemoryManager): # Attribute manager methods def get_attribute( - self, key=None, category=None, value=None, strvalue=None, obj=None, attrtype=None, **kwargs - ): + self, key=None, category=None, value=None, strvalue=None, + obj=None, attrtype=None, **kwargs): """ Return Attribute objects by key, by category, by value, by - strvalue, by object (it is stored on) or with a combination of + `strvalue`, by object (it is stored on) or with a combination of those criteria. - Attrs: - key (str, optional): The attribute's key to search for + Args: + key (str, optional): The attribute's key to search for. category (str, optional): The category of the attribute(s) to search for. value (str, optional): The attribute value to search for. @@ -52,7 +52,7 @@ class TypedObjectManager(idmapper.manager.SharedMemoryManager): precedence if given. obj (Object, optional): On which object the Attribute to search for is. - attrype (str, optional): An attribute-type to search for. + attrtype (str, optional): An attribute-type to search for. By default this is either `None` (normal Attributes) or `"nick"`. kwargs (any): Currently unused. Reserved for future use. @@ -84,7 +84,7 @@ class TypedObjectManager(idmapper.manager.SharedMemoryManager): """ Get a nick, in parallel to `get_attribute`. - Attrs: + Args: key (str, optional): The nicks's key to search for category (str, optional): The category of the nicks(s) to search for. value (str, optional): The attribute value to search for. Note that this @@ -170,7 +170,7 @@ class TypedObjectManager(idmapper.manager.SharedMemoryManager): Return Tag objects by key, by category, by object (it is stored on) or with a combination of those criteria. - Attrs: + Args: key (str, optional): The Tag's key to search for category (str, optional): The Tag of the attribute(s) to search for.