From ed8290aec8fc14031e3a05a1680116f7a6280f05 Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 20 Sep 2020 20:29:02 +0200 Subject: [PATCH] Clean up docstrings --- docs/source/Coding-Introduction.md | 2 +- evennia/server/portal/portalsessionhandler.py | 10 ++-- evennia/server/portal/telnet_oob.py | 51 +++++++++++-------- .../server/profiling/dummyrunner_settings.py | 19 ++++--- 4 files changed, 49 insertions(+), 33 deletions(-) diff --git a/docs/source/Coding-Introduction.md b/docs/source/Coding-Introduction.md index ed6d8e9537..258d9e2a34 100644 --- a/docs/source/Coding-Introduction.md +++ b/docs/source/Coding-Introduction.md @@ -58,5 +58,5 @@ Some people find reading documentation extremely dull and shun it out of princip And finally, of course, have fun! -[feature-request]: (https://github.com/evennia/evennia/issues/new?title=Feature+Request%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Description+of+the+suggested+feature+and+how+it+is+supposed+to+work+for+the+admin%2fend+user%3a%0D%0A%0D%0A%0D%0A%23%23%23%23+A+list+of+arguments+for+why+you+think+this+new+feature+should+be+included+in+Evennia%3a%0D%0A%0D%0A1.%0D%0A2.%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+requirements+or+ideas+on+implementation%3a%0D%0A%0D%0A +[feature-request]: https://github.com/evennia/evennia/issues/new?title=Feature+Request%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Description+of+the+suggested+feature+and+how+it+is+supposed+to+work+for+the+admin%2fend+user%3a%0D%0A%0D%0A%0D%0A%23%23%23%23+A+list+of+arguments+for+why+you+think+this+new+feature+should+be+included+in+Evennia%3a%0D%0A%0D%0A1.%0D%0A2.%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+requirements+or+ideas+on+implementation%3a%0D%0A%0D%0A [bug]: https://github.com/evennia/evennia/issues/new?title=Bug%3a+%3Cdescriptive+title+here%3E&body=%23%23%23%23+Steps+to+reproduce+the+issue%3a%0D%0A%0D%0A1.+%0D%0A2.+%0D%0A3.+%0D%0A%0D%0A%23%23%23%23+What+I+expect+to+see+and+what+I+actually+see+%28tracebacks%2c+error+messages+etc%29%3a%0D%0A%0D%0A%0D%0A%0D%0A%23%23%23%23+Extra+information%2c+such+as+Evennia+revision%2frepo%2fbranch%2c+operating+system+and+ideas+for+how+to+solve%3a%0D%0A%0D%0A diff --git a/evennia/server/portal/portalsessionhandler.py b/evennia/server/portal/portalsessionhandler.py index 0f4c6cb560..580e229770 100644 --- a/evennia/server/portal/portalsessionhandler.py +++ b/evennia/server/portal/portalsessionhandler.py @@ -225,16 +225,16 @@ class PortalSessionHandler(SessionHandler): def server_connect(self, protocol_path="", config=dict()): """ Called by server to force the initialization of a new protocol - instance. Server wants this instance to get a unique sessid - and to be connected back as normal. This is used to initiate - irc/rss etc connections. + instance. Server wants this instance to get a unique sessid and to be + connected back as normal. This is used to initiate irc/rss etc + connections. Args: - protocol_path (st): Full python path to the class factory + protocol_path (str): Full python path to the class factory for the protocol used, eg 'evennia.server.portal.irc.IRCClientFactory' config (dict): Dictionary of configuration options, fed as - **kwarg to protocol class' __init__ method. + `**kwarg` to protocol class `__init__` method. Raises: RuntimeError: If The correct factory class is not found. diff --git a/evennia/server/portal/telnet_oob.py b/evennia/server/portal/telnet_oob.py index 7931dcb2a4..baa964918a 100644 --- a/evennia/server/portal/telnet_oob.py +++ b/evennia/server/portal/telnet_oob.py @@ -10,19 +10,22 @@ how and if they are handled. Examples of OOB instructions could be to instruct the client to play sounds or to update a graphical health bar. -> Note that in Evennia's Web client, all send commands are "OOB -commands", (including the "text" one), there is no equivalence to -MSDP/GMCP for the webclient since it doesn't need it. +> Note that in Evennia's Web client, all send commands are "OOB commands", + (including the "text" one), there is no equivalence to MSDP/GMCP for the + webclient since it doesn't need it. This implements the following telnet OOB communication protocols: -- MSDP (Mud Server Data Protocol), as per - http://tintin.sourceforge.net/msdp/ -- GMCP (Generic Mud Communication Protocol) as per - http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29 -Following the lead of KaVir's protocol snippet, we first check if -client supports MSDP and if not, we fallback to GMCP with a MSDP -header where applicable. +- MSDP (Mud Server Data Protocol), as per + http://tintin.sourceforge.net/msdp/ +- GMCP (Generic Mud Communication Protocol) as per + http://www.ironrealms.com/rapture/manual/files/FeatGMCP-txt.html#Generic_MUD_Communication_Protocol%28GMCP%29 + +Following the lead of KaVir's protocol snippet, we first check if client +supports MSDP and if not, we fallback to GMCP with a MSDP header where +applicable. + +---- """ import re @@ -156,17 +159,17 @@ class TelnetOOB(object): Notes: The output of this encoding will be MSDP structures on these forms: - + ``` [cmdname, [], {}] -> VAR cmdname VAL "" [cmdname, [arg], {}] -> VAR cmdname VAL arg [cmdname, [args],{}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE [cmdname, [], {kwargs}] -> VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE [cmdname, [args], {kwargs}] -> VAR cmdname VAL ARRAYOPEN VAL arg VAL arg ... ARRAYCLOSE VAR cmdname VAL TABLEOPEN VAR key VAL val ... TABLECLOSE - - Further nesting is not supported, so if an array argument - consists of an array (for example), that array will be - json-converted to a string. + ``` + Further nesting is not supported, so if an array argument consists + of an array (for example), that array will be json-converted to a + string. """ msdp_cmdname = "{msdp_var}{msdp_cmdname}{msdp_val}".format( @@ -231,20 +234,24 @@ class TelnetOOB(object): up in the Core package, while Core package names will be stripped on the Evennia side. + ``` [cmd.name, [], {}] -> Cmd.Name [cmd.name, [arg], {}] -> Cmd.Name arg [cmd.name, [args],{}] -> Cmd.Name [args] [cmd.name, [], {kwargs}] -> Cmd.Name {kwargs} [cmdname, [args, {kwargs}] -> Core.Cmdname [[args],{kwargs}] + ``` Notes: There are also a few default mappings between evennia outputcmds and GMCP: - client_options -> Core.Supports.Get - get_inputfuncs -> Core.Commands.Get - get_value -> Char.Value.Get - repeat -> Char.Repeat.Update - monitor -> Char.Monitor.Update + ``` + client_options -> Core.Supports.Get + get_inputfuncs -> Core.Commands.Get + get_value -> Char.Value.Get + repeat -> Char.Repeat.Update + monitor -> Char.Monitor.Update + ``` """ @@ -281,11 +288,13 @@ class TelnetOOB(object): Clients should always send MSDP data on one of the following forms: + ``` cmdname '' -> [cmdname, [], {}] cmdname val -> [cmdname, [val], {}] cmdname array -> [cmdname, [array], {}] cmdname table -> [cmdname, [], {table}] cmdname array cmdname table -> [cmdname, [array], {table}] + ``` Observe that all MSDP_VARS are used to identify cmdnames, so if there are multiple arrays with the same cmdname @@ -380,11 +389,13 @@ class TelnetOOB(object): The following is parsed into Evennia's formal structure: + ``` Core.Name -> [name, [], {}] Core.Name string -> [name, [string], {}] Core.Name [arg, arg,...] -> [name, [args], {}] Core.Name {key:arg, key:arg, ...} -> [name, [], {kwargs}] Core.Name [[args], {kwargs}] -> [name, [args], {kwargs}] + ``` """ if isinstance(data, list): diff --git a/evennia/server/profiling/dummyrunner_settings.py b/evennia/server/profiling/dummyrunner_settings.py index 69f417f56c..d971f35a7d 100644 --- a/evennia/server/profiling/dummyrunner_settings.py +++ b/evennia/server/profiling/dummyrunner_settings.py @@ -14,7 +14,9 @@ ACTIONS - see below ACTIONS is a tuple +``` (login_func, logout_func, (0.3, func1), (0.1, func2) ... ) +``` where the first entry is the function to call on first connect, with a chance of occurring given by CHANCE_OF_LOGIN. This function is usually @@ -33,14 +35,15 @@ returns a string or a list of command strings to execute. Use the client object for optionally saving data between actions. The client object has the following relevant properties and methods: - key - an optional client key. This is only used for dummyrunner output. + +- key - an optional client key. This is only used for dummyrunner output. Default is "Dummy-" - cid - client id - gid - globally unique id, hashed with time stamp - istep - the current step - exits - an empty list. Can be used to store exit names - objs - an empty list. Can be used to store object names - counter() - returns a unique increasing id, hashed with time stamp +- cid - client id +- gid - globally unique id, hashed with time stamp +- istep - the current step +- exits - an empty list. Can be used to store exit names +- objs - an empty list. Can be used to store object names +- counter() - returns a unique increasing id, hashed with time stamp to make it unique also between dummyrunner instances. The return should either be a single command string or a tuple of @@ -49,6 +52,8 @@ TIMESTEP with a chance given by CHANCE_OF_ACTION by in the order given (no randomness) and allows for setting up a more complex chain of commands (such as creating an account and logging in). +--- + """ # Dummy runner settings