From 8141935a9bf1e4c6dbda2eda46437e31fccb844e Mon Sep 17 00:00:00 2001 From: Griatch Date: Sun, 17 Apr 2016 10:47:41 +0200 Subject: [PATCH] Cleaned up docstrings for evmenu and eveditor. Also, rev 74a3395 referred to EvEditor, not EvMenu (both now support persistent saving) --- evennia/utils/eveditor.py | 19 ++++++++++++++++--- evennia/utils/evmenu.py | 39 +++++++++++++++++++++++++++++---------- 2 files changed, 45 insertions(+), 13 deletions(-) diff --git a/evennia/utils/eveditor.py b/evennia/utils/eveditor.py index b6c2b3b0cd..b9a6d0ce8a 100644 --- a/evennia/utils/eveditor.py +++ b/evennia/utils/eveditor.py @@ -18,7 +18,7 @@ and initialize it: from evennia.utils.eveditor import EvEditor - EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key="") + EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key="", persistent=True) - caller is the user of the editor, the one to see all feedback. - loadfunc(caller) is called when the editor is first launched; the @@ -31,6 +31,11 @@ and initialize it: no automatic quit messages will be given. - key is an optional identifier for the editing session, to be displayed in the editor. +- persistent means the editor state will be saved to the database making it + survive a server reload. Note that using this mode, the load- save- + and quit-funcs must all be possible to pickle - notable unusable + callables are class methods and functions defined inside other + functions. With persistent=False, no such restriction exists. """ from builtins import object @@ -619,8 +624,16 @@ class EvEditor(object): key (str, optional): An optional key for naming this session and make it unique from other editing sessions. persistent (bool, optional): Make the editor survive a reboot. Note - that if this is set, all callables must be functions (not methods) - since they have to able to pickle. + that if this is set, all callables must be possible to pickle + + Notes: + In persistent mode, all the input callables (savefunc etc) + must be possible to be *pickled*, this excludes e.g. + callables that are class methods or functions defined + dynamically or as part of another function. In + non-persistent mode no such restrictions exist. + + """ self._key = key diff --git a/evennia/utils/evmenu.py b/evennia/utils/evmenu.py index 47ccb33385..71a28162dd 100644 --- a/evennia/utils/evmenu.py +++ b/evennia/utils/evmenu.py @@ -5,7 +5,8 @@ This implements a full menu system for Evennia. It is considerably more flexible than the older contrib/menusystem.py and also uses menu plugin modules. -To start the menu, just import the EvMenu class from this module, +To start the menu, just import the EvMenu class from this module. +Example usage: ```python @@ -14,7 +15,7 @@ To start the menu, just import the EvMenu class from this module, EvMenu(caller, menu_module_path, startnode="node1", cmdset_mergetype="Replace", cmdset_priority=1, - auto_quit=True, cmd_on_exit="look") + auto_quit=True, cmd_on_exit="look", persistent=True) ``` Where `caller` is the Object to use the menu on - it will get a new @@ -24,6 +25,13 @@ keyword options of the Menu() initialization call you can start the menu at different places in the menu definition file, adjust if the menu command should overload the normal commands or not, etc. +The `perstent` keyword will make the menu survive a server reboot. +It is `False` by default. Note that if using persistent mode, every +node and callback in the menu must be possible to be *pickled*, this +excludes e.g. callables that are class methods or functions defined +dynamically or as part of another function. In non-persistent mode +no such restrictions exist. + The menu is defined in a module (this can be the same module as the command definition too) with function defintions: @@ -389,11 +397,12 @@ class EvMenu(object): def __init__(self, caller, menudata, startnode="start", cmdset_mergetype="Replace", cmdset_priority=1, auto_quit=True, auto_look=True, auto_help=True, - cmd_on_exit="look", persistent=False, + cmd_on_exit="look", nodetext_formatter=dedent_strip_nodetext_formatter, options_formatter=evtable_options_formatter, node_formatter=underline_node_formatter, - input_parser=evtable_parse_input): + input_parser=evtable_parse_input, + persistent=False): """ Initialize the menu tree and start the caller onto the first node. @@ -438,10 +447,6 @@ class EvMenu(object): The callback function takes two parameters, the caller then the EvMenu object. This is called after cleanup is complete. Set to None to not call any command. - persistent (bool, optional): Make the Menu persistent (i.e. it will - survive a reload. This will make the Menu cmdset persistent. Use - with caution - if your menu is buggy you may end up in a state - you can't get out of! nodetext_formatter (callable, optional): This callable should be on the form `function(nodetext, has_options, caller=None)`, where `nodetext` is the node text string and `has_options` a boolean specifying if there @@ -474,10 +479,23 @@ class EvMenu(object): It should use the helper method of the menuobject to goto new nodes, show help texts etc. See the default `evtable_parse_input` function for help with parsing. + persistent (bool, optional): Make the Menu persistent (i.e. it will + survive a reload. This will make the Menu cmdset persistent. Use + with caution - if your menu is buggy you may end up in a state + you can't get out of! Also note that persistent mode requires + that all formatters, menu nodes and callables are possible to + *pickle*. Raises: EvMenuError: If the start/end node is not found in menu tree. + Notes: + In persistent mode, all nodes, formatters and callbacks in + the menu must be possible to be *pickled*, this excludes + e.g. callables that are class methods or functions defined + dynamically or as part of another function. In + non-persistent mode no such restrictions exist. + """ self._startnode = startnode self._menutree = self._parse_menudata(menudata) @@ -520,9 +538,10 @@ class EvMenu(object): "cmdset_mergetype": cmdset_mergetype, "cmdset_priority": cmdset_priority, "auto_quit": auto_quit, "auto_look": auto_look, "auto_help": auto_help, - "cmd_on_exit": cmd_on_exit, "persistent": persistent, + "cmd_on_exit": cmd_on_exit, "nodetext_formatter": nodetext_formatter, "options_formatter": options_formatter, - "node_formatter": node_formatter, "input_parser": input_parser})) + "node_formatter": node_formatter, "input_parser": input_parser, + "persistent": persistent,})) caller.attributes.add("_menutree_saved_startnode", startnode) except Exception as err: caller.msg(_ERROR_PERSISTENT_SAVING.format(error=err))