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

Start add docs again

Browse source
This commit is contained in:
Griatch 2020-10-08 21:45:18 +02:00
parent b7fc975379
commit d414cc3ccd
61 changed files with 235 additions and 236 deletions
Download patch file Download diff file Expand all files Collapse all files

6
evennia/server/connection_wizard.py
View file

@ -57,7 +57,7 @@ class ConnectionWizard(object):
"""
Ask a yes/no question inline.
Kwargs:
Keyword Args:
prompt (str): The prompt to ask.
default (str): "yes" or "no", used if pressing return.
Returns:
@ -83,7 +83,7 @@ class ConnectionWizard(object):
"""
Ask multiple-choice question, get response inline.
Kwargs:
Keyword Args:
prompt (str): Input prompt.
options (list): List of options. Will be indexable by sequence number 1...
default (int): The list index+1 of the default choice, if any
@ -114,7 +114,7 @@ class ConnectionWizard(object):
"""
Get arbitrary input inline.
Kwargs:
Keyword Args:
prompt (str): The display prompt.
default (str): If empty input, use this.
validator (callable): If given, the input will be passed

2
evennia/server/evennia_launcher.py
View file

@ -1639,7 +1639,7 @@ def error_check_python_modules(show_warnings=False):
python source files themselves). Best they fail already here
before we get any further.
Kwargs:
Keyword Args:
show_warnings (bool): If non-fatal warning messages should be shown.
"""

14
evennia/server/inputfuncs.py
View file

@ -164,7 +164,7 @@ def client_options(session, *args, **kwargs):
This allows the client an OOB way to inform us about its name and capabilities.
This will be integrated into the session settings
Kwargs:
Keyword Args:
get (bool): If this is true, return the settings as a dict
(ignore all other kwargs).
client (str): A client identifier, like "mushclient".
@ -282,7 +282,7 @@ def login(session, *args, **kwargs):
Peform a login. This only works if session is currently not logged
in. This will also automatically throttle too quick attempts.
Kwargs:
Keyword Args:
name (str): Account name
password (str): Plain-text password
@ -308,7 +308,7 @@ def get_value(session, *args, **kwargs):
Return the value of a given attribute or db_property on the
session's current account or character.
Kwargs:
Keyword Args:
name (str): Name of info value to return. Only names
in the _gettable dictionary earlier in this module
are accepted.
@ -325,7 +325,7 @@ def _testrepeat(**kwargs):
This is a test function for using with the repeat
inputfunc.
Kwargs:
Keyword Args:
session (Session): Session to return to.
"""
import time
@ -342,7 +342,7 @@ def repeat(session, *args, **kwargs):
this is meant as an example of limiting the number of
possible call functions.
Kwargs:
Keyword Args:
callback (str): The function to call. Only functions
from the _repeatable dictionary earlier in this
module are available.
@ -403,7 +403,7 @@ def monitor(session, *args, **kwargs):
"""
Adds monitoring to a given property or Attribute.
Kwargs:
Keyword Args:
name (str): The name of the property or Attribute
to report. No db_* prefix is needed. Only names
in the _monitorable dict earlier in this module
@ -485,7 +485,7 @@ def webclient_options(session, *args, **kwargs):
If kwargs is not empty, the key/values stored in there will be persisted
to the account object.
Kwargs:
Keyword Args:
<option name>: an option to save
"""
account = session.account

2
evennia/server/portal/grapevine.py
View file

@ -303,7 +303,7 @@ class GrapevineClient(WebSocketClientProtocol, Session):
"""
Send data grapevine -> Evennia
Kwargs:
Keyword Args:
data (dict): Converted json data.
"""

6
evennia/server/portal/irc.py
View file

@ -275,7 +275,7 @@ class IRCBot(irc.IRCClient, Session):
"""
Data IRC -> Server.
Kwargs:
Keyword Args:
text (str): Ingoing text.
kwargs (any): Other data from protocol.
@ -306,7 +306,7 @@ class IRCBot(irc.IRCClient, Session):
Args:
text (str): Outgoing text.
Kwargs:
Keyword Args:
user (str): the nick to send
privately to.
@ -375,7 +375,7 @@ class IRCBotFactory(protocol.ReconnectingClientFactory):
Args:
sessionhandler (SessionHandler): Reference to the main Sessionhandler.
Kwargs:
Keyword Args:
uid (int): Bot user id.
botname (str): Bot name (seen in IRC channel).
channel (str): IRC channel to connect to.

4
evennia/server/portal/portalsessionhandler.py
View file

@ -375,7 +375,7 @@ class PortalSessionHandler(SessionHandler):
Args:
session (PortalSession): Session receiving data.
Kwargs:
Keyword Args:
kwargs (any): Other data from protocol.
Notes:
@ -433,7 +433,7 @@ class PortalSessionHandler(SessionHandler):
Args:
session (Session): Session sending data.
Kwargs:
Keyword Args:
kwargs (any): Each key is a command instruction to the
protocol on the form key = [[args],{kwargs}]. This will
call a method send_<key> on the protocol. If no such

2
evennia/server/portal/rss.py
View file

@ -88,7 +88,7 @@ class RSSReader(Session):
"""
Data RSS -> Evennia.
Kwargs:
Keyword Args:
text (str): Incoming text
kwargs (any): Options from protocol.

24
evennia/server/portal/ssh.py
View file

@ -263,7 +263,7 @@ class SshProtocol(Manhole, session.Session):
"""
Data Evennia -> User
Kwargs:
Keyword Args:
kwargs (any): Options to the protocol.
"""
@ -276,18 +276,18 @@ class SshProtocol(Manhole, session.Session):
Args:
text (str): The first argument is always the text string to send. No other arguments
are considered.
Kwargs:
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!
- 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

28
evennia/server/portal/telnet.py
View file

@ -360,7 +360,7 @@ class TelnetProtocol(Telnet, StatefulTelnetProtocol, Session):
"""
Data User -> Evennia
Kwargs:
Keyword Args:
kwargs (any): Options from the protocol.
"""
@ -373,7 +373,7 @@ class TelnetProtocol(Telnet, StatefulTelnetProtocol, Session):
"""
Data Evennia -> User
Kwargs:
Keyword Args:
kwargs (any): Options to the protocol
"""
self.sessionhandler.data_out(self, **kwargs)
@ -387,19 +387,19 @@ class TelnetProtocol(Telnet, StatefulTelnetProtocol, Session):
Args:
text (str): The first argument is always the text string to send. No other arguments
are considered.
Kwargs:
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!
- 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 ""

74
evennia/server/portal/telnet_oob.py
View file

@ -11,8 +11,8 @@ 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.
(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:
@ -159,14 +159,15 @@ 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
```
::
[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.
@ -233,25 +234,24 @@ class TelnetOOB(object):
to have adopted). A cmdname without Package will end
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}]
```
[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
"""
@ -287,14 +287,13 @@ class TelnetOOB(object):
Notes:
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}]
```
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
@ -388,14 +387,13 @@ class TelnetOOB(object):
We assume the structure is valid JSON.
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}]
```
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):

4
evennia/server/portal/webclient.py
View file

@ -242,7 +242,7 @@ class WebSocketClient(WebSocketServerProtocol, Session):
Args:
text (str): Text to send.
Kwargs:
Keyword Args:
options (dict): Options-dict with the following keys understood:
- raw (bool): No parsing at all (leave ansi-to-html markers unparsed).
- nocolor (bool): Clean out all color.
@ -297,7 +297,7 @@ class WebSocketClient(WebSocketServerProtocol, Session):
cmdname (str): The first argument will always be the oob cmd name.
*args (any): Remaining args will be arguments for `cmd`.
Kwargs:
Keyword Args:
options (dict): These are ignored for oob commands. Use command
arguments (which can hold dicts) to send instructions to the
client instead.

8
evennia/server/portal/webclient_ajax.py
View file

@ -382,7 +382,7 @@ class AjaxWebClientSession(session.Session):
"""
Data User -> Evennia
Kwargs:
Keyword Args:
kwargs (any): Incoming data.
"""
@ -392,7 +392,7 @@ class AjaxWebClientSession(session.Session):
"""
Data Evennia -> User
Kwargs:
Keyword Args:
kwargs (any): Options to the protocol
"""
self.sessionhandler.data_out(self, **kwargs)
@ -405,7 +405,7 @@ class AjaxWebClientSession(session.Session):
Args:
text (str): Text to send.
Kwargs:
Keyword Args:
options (dict): Options-dict with the following keys understood:
- raw (bool): No parsing at all (leave ansi-to-html markers unparsed).
- nocolor (bool): Remove all color.
@ -457,7 +457,7 @@ class AjaxWebClientSession(session.Session):
cmdname (str): The first argument will always be the oob cmd name.
*args (any): Remaining args will be arguments for `cmd`.
Kwargs:
Keyword Args:
options (dict): These are ignored for oob commands. Use command
arguments (which can hold dicts) to send instructions to the
client instead.

23
evennia/server/server.py
View file

@ -399,17 +399,18 @@ class Evennia(object):
"""
Shuts down the server from inside it.
mode - sets the server restart mode.
'reload' - server restarts, no "persistent" scripts
are stopped, at_reload hooks called.
'reset' - server restarts, non-persistent scripts stopped,
at_shutdown hooks called but sessions will not
be disconnected.
'shutdown' - like reset, but server will not auto-restart.
_reactor_stopping - this is set if server is stopped by a kill
command OR this method was already called
once - in both cases the reactor is
dead/stopping already.
Keyword Args:
mode (str): Sets the server restart mode:
- 'reload': server restarts, no "persistent" scripts
are stopped, at_reload hooks called.
- 'reset' - server restarts, non-persistent scripts stopped,
at_shutdown hooks called but sessions will not
be disconnected.
-'shutdown' - like reset, but server will not auto-restart.
_reactor_stopping: This is set if server is stopped by a kill
command OR this method was already called
once - in both cases the reactor is dead/stopping already.
"""
if _reactor_stopping and hasattr(self, "shutdown_complete"):
# this means we have already passed through this method

15
evennia/server/serversession.py
View file

@ -343,7 +343,7 @@ class ServerSession(Session):
"""
Update the protocol_flags and sync them with Portal.
Kwargs:
Keyword Args:
key, value - A key:value pair to set in the
protocol_flags dictionary.
@ -361,7 +361,7 @@ class ServerSession(Session):
"""
Sending data from Evennia->Client
Kwargs:
Keyword Args:
text (str or tuple)
any (str or tuple): Send-commands identified
by their keys. Or "options", carrying options
@ -375,14 +375,15 @@ class ServerSession(Session):
Receiving data from the client, sending it off to
the respective inputfuncs.
Kwargs:
kwargs (any): Incoming data from protocol on
Keyword Args:
any: Incoming data from protocol on
the form `{"commandname": ((args), {kwargs}),...}`
Notes:
This method is here in order to give the user
a single place to catch and possibly process all incoming data from
the client. It should usually always end by sending
this data off to `self.sessionhandler.call_inputfuncs(self, **kwargs)`.
"""
self.sessionhandler.call_inputfuncs(self, **kwargs)
@ -392,9 +393,7 @@ class ServerSession(Session):
Args:
text (str): String input.
Kwargs:
any (str or tuple): Send-commands identified
kwargs (str or tuple): Send-commands identified
by their keys. Or "options", carrying options
for the protocol(s).
@ -421,7 +420,7 @@ class ServerSession(Session):
session (Session): This is here to make API consistent with
Account/Object.execute_cmd. If given, data is passed to
that Session, otherwise use self.
Kwargs:
Keyword Args:
Other keyword arguments will be added to the found command
object instace as variables before it executes. This is
unused by default Evennia but may be used to set flags and

4
evennia/server/session.py
View file

@ -177,7 +177,7 @@ class Session(object):
protocols can use this right away. Portal sessions
should overload this to format/handle the outgoing data as needed.
Kwargs:
Keyword Args:
kwargs (any): Other data to the protocol.
"""
@ -187,7 +187,7 @@ class Session(object):
"""
Hook for protocols to send incoming data to the engine.
Kwargs:
Keyword Args:
kwargs (any): Other data from the protocol.
"""

2
evennia/server/sessionhandler.py
View file

@ -834,7 +834,7 @@ class ServerSessionHandler(SessionHandler):
Args:
sessions (Session): Session.
Kwargs:
Keyword Args:
kwargs (any): Incoming data from protocol on
the form `{"commandname": ((args), {kwargs}),...}`

2
evennia/server/throttle.py
View file

@ -22,7 +22,7 @@ class Throttle(object):
"""
Allows setting of throttle parameters.
Kwargs:
Keyword Args:
limit (int): Max number of failures before imposing limiter
timeout (int): number of timeout seconds after
max number of tries has been reached.