From e84db3df548eceb516830486992b581a584198f4 Mon Sep 17 00:00:00 2001 From: Griatch Date: Fri, 15 May 2015 20:05:37 +0200 Subject: [PATCH] Converted all docstrings in the commands submodule (not the default commands themselves) to Google style as per #709. --- evennia/commands/cmdset.py | 389 ++++++++++++++++++++---------- evennia/commands/cmdsethandler.py | 87 +++++-- evennia/commands/command.py | 110 ++++++--- 3 files changed, 402 insertions(+), 184 deletions(-) diff --git a/evennia/commands/cmdset.py b/evennia/commands/cmdset.py index 2c70587d34..b10855d50a 100644 --- a/evennia/commands/cmdset.py +++ b/evennia/commands/cmdset.py @@ -1,17 +1,30 @@ """ -A cmdset holds a set of commands available to the object or to other -objects near it. All the commands a player can give (look, @create etc) -are stored as the default cmdset on the player object and managed using the -CmdHandler object (see cmdhandler.py). -The power of having command sets in CmdSets like this is that CmdSets -can be merged together according to individual rules to create a new -on-the-fly CmdSet that is some combination of the -previous ones. Their function are borrowed to a large parts from mathematical -Set theory, it should not be much of a problem to understand. +A Command Set (CmdSet) holds a set of commands. The Cmdsets can be +merged and combined to create new sets of commands in a +non-destructive way. This makes them very powerful for implementing +custom game states where different commands (or different variations +of commands) are available to the players depending on circumstance. + +The available merge operations are partly borrowed from mathematical +Set theory. + + +* Union The two command sets are merged so that as many commands as + possible of each cmdset ends up in the merged cmdset. Same-name + commands are merged by priority. This is the most common default. + Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5 +* Intersect - Only commands found in *both* cmdsets (i.e. which have + same names) end up in the merged cmdset, with the higher-priority + cmdset replacing the lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1 +* Replace - The commands of this cmdset completely replaces the + lower-priority cmdset's commands, regardless of if same-name commands + exist. Ex: A1,A3 + B1,B2,B4,B5 = A1,A3 +* Remove - This removes the relevant commands from the + lower-priority cmdset completely. They are not replaced with + anything, so this in effects uses the high-priority cmdset as a filter + to affect the low-priority cmdset. Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5 -See CmdHandler for practical examples on how to apply cmdsets -together to create interesting in-game effects. """ from weakref import WeakKeyDictionary @@ -24,10 +37,12 @@ class _CmdSetMeta(type): """ This metaclass makes some minor on-the-fly convenience fixes to the cmdset class. + """ def __init__(mcs, *args, **kwargs): """ Fixes some things in the cmdclass + """ # by default we key the cmdset the same as the # name of its class. @@ -43,83 +58,83 @@ class _CmdSetMeta(type): class CmdSet(object): """ - This class describes a unique cmdset that understands priorities. CmdSets - can be merged and made to perform various set operations on each other. - CmdSets have priorities that affect which of their ingoing commands - gets used. + This class describes a unique cmdset that understands priorities. + CmdSets can be merged and made to perform various set operations + on each other. CmdSets have priorities that affect which of their + ingoing commands gets used. - In the examples, cmdset A always have higher priority than cmdset B. + In the examples, cmdset A always have higher priority than cmdset B. - key - the name of the cmdset. This can be used on its own for game - operations + key - the name of the cmdset. This can be used on its own for game + operations - mergetype (partly from Set theory): + mergetype (partly from Set theory): - Union - The two command sets are merged so that as many - commands as possible of each cmdset ends up in the - merged cmdset. Same-name commands are merged by - priority. This is the most common default. - Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5 - Intersect - Only commands found in *both* cmdsets - (i.e. which have same names) end up in the merged - cmdset, with the higher-priority cmdset replacing the - lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1 - Replace - The commands of this cmdset completely replaces - the lower-priority cmdset's commands, regardless - of if same-name commands exist. - Ex: A1,A3 + B1,B2,B4,B5 = A1,A3 - Remove - This removes the relevant commands from the - lower-priority cmdset completely. They are not - replaced with anything, so this in effects uses the - high-priority cmdset as a filter to affect the - low-priority cmdset. - Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5 + Union - The two command sets are merged so that as many + commands as possible of each cmdset ends up in the + merged cmdset. Same-name commands are merged by + priority. This is the most common default. + Ex: A1,A3 + B1,B2,B4,B5 = A1,B2,A3,B4,B5 + Intersect - Only commands found in *both* cmdsets + (i.e. which have same names) end up in the merged + cmdset, with the higher-priority cmdset replacing the + lower one. Ex: A1,A3 + B1,B2,B4,B5 = A1 + Replace - The commands of this cmdset completely replaces + the lower-priority cmdset's commands, regardless + of if same-name commands exist. + Ex: A1,A3 + B1,B2,B4,B5 = A1,A3 + Remove - This removes the relevant commands from the + lower-priority cmdset completely. They are not + replaced with anything, so this in effects uses the + high-priority cmdset as a filter to affect the + low-priority cmdset. + Ex: A1,A3 + B1,B2,B4,B5 = B2,B4,B5 - Note: Commands longer than 2 characters and starting - with double underscrores, like '__noinput_command' - are considered 'system commands' and are - excempt from all merge operations - they are - ALWAYS included across mergers and only affected - if same-named system commands replace them. + Note: Commands longer than 2 characters and starting + with double underscrores, like '__noinput_command' + are considered 'system commands' and are + excempt from all merge operations - they are + ALWAYS included across mergers and only affected + if same-named system commands replace them. - priority- All cmdsets are always merged in pairs of two so that - the higher set's mergetype is applied to the - lower-priority cmdset. Default commands have priority 0, - high-priority ones like Exits and Channels have 10 and 9. - Priorities can be negative as well to give default - commands preference. + priority- All cmdsets are always merged in pairs of two so that + the higher set's mergetype is applied to the + lower-priority cmdset. Default commands have priority 0, + high-priority ones like Exits and Channels have 10 and 9. + Priorities can be negative as well to give default + commands preference. - duplicates - determines what happens when two sets of equal - priority merge. Default has the first of them in the - merger (i.e. A above) automatically taking - precedence. But if allow_duplicates is true, the - result will be a merger with more than one of each - name match. This will usually lead to the player - receiving a multiple-match error higher up the road, - but can be good for things like cmdsets on non-player - objects in a room, to allow the system to warn that - more than one 'ball' in the room has the same 'kick' - command defined on it, so it may offer a chance to - select which ball to kick ... Allowing duplicates - only makes sense for Union and Intersect, the setting - is ignored for the other mergetypes. + duplicates - determines what happens when two sets of equal + priority merge. Default has the first of them in the + merger (i.e. A above) automatically taking + precedence. But if allow_duplicates is true, the + result will be a merger with more than one of each + name match. This will usually lead to the player + receiving a multiple-match error higher up the road, + but can be good for things like cmdsets on non-player + objects in a room, to allow the system to warn that + more than one 'ball' in the room has the same 'kick' + command defined on it, so it may offer a chance to + select which ball to kick ... Allowing duplicates + only makes sense for Union and Intersect, the setting + is ignored for the other mergetypes. - key_mergetype (dict) - allows the cmdset to define a unique - mergetype for particular cmdsets. Format is - {CmdSetkeystring:mergetype}. Priorities still apply. - Example: {'Myevilcmdset','Replace'} which would make - sure for this set to always use 'Replace' on - Myevilcmdset no matter what overall mergetype this set - has. + key_mergetype (dict) - allows the cmdset to define a unique + mergetype for particular cmdsets. Format is + {CmdSetkeystring:mergetype}. Priorities still apply. + Example: {'Myevilcmdset','Replace'} which would make + sure for this set to always use 'Replace' on + Myevilcmdset no matter what overall mergetype this set + has. - no_objs - don't include any commands from nearby objects - when searching for suitable commands - no_exits - ignore the names of exits when matching against - commands - no_channels - ignore the name of channels when matching against - commands (WARNING- this is dangerous since the - player can then not even ask staff for help if - something goes wrong) + no_objs - don't include any commands from nearby objects + when searching for suitable commands + no_exits - ignore the names of exits when matching against + commands + no_channels - ignore the name of channels when matching against + commands (WARNING- this is dangerous since the + player can then not even ask staff for help if + something goes wrong) """ @@ -146,10 +161,16 @@ class CmdSet(object): """ Creates a new CmdSet instance. - cmdsetobj - this is the database object to which this particular - instance of cmdset is related. It is often a character but - may also be a regular object. + Args: + cmdsetobj (Session, Player, Object, optional): This is the database object + to which this particular instance of cmdset is related. It + is often a character but may also be a regular object, Player + or Session. + key (str, optional): The idenfier for this cmdset. This + helps if wanting to selectively remov cmdsets. + """ + if key: self.key = key self.commands = [] @@ -167,7 +188,20 @@ class CmdSet(object): # Priority-sensitive merge operations for cmdsets def _union(self, cmdset_a, cmdset_b): - "C = A U B. CmdSet A is assumed to have higher priority" + """ + Merge two sets using union merger + + Args: + cmdset_a (Cmdset): Cmdset given higher priority in the case of a tie. + cmdset_b (Cmdset): Cmdset given lower priority in the case of a tie. + + Returns: + cmdset_c (Cmdset): The result of A U B operation. + + Notes: + Union, C = A U B, means that C gets all elements from both A and B. + + """ cmdset_c = cmdset_a._duplicate() # we make copies, not refs by use of [:] cmdset_c.commands = cmdset_a.commands[:] @@ -179,7 +213,23 @@ class CmdSet(object): return cmdset_c def _intersect(self, cmdset_a, cmdset_b): - "C = A (intersect) B. A is assumed higher priority" + """ + Merge two sets using intersection merger + + Args: + cmdset_a (Cmdset): Cmdset given higher priority in the case of a tie. + cmdset_b (Cmdset): Cmdset given lower priority in the case of a tie. + + Returns: + cmdset_c (Cmdset): The result of A (intersect) B operation. + + Notes: + Intersection, C = A (intersect) B, means that C only gets the + parts of A and B that are the same (that is, the commands + of each set having the same name. Only the one of these + having the higher prio ends up in C). + + """ cmdset_c = cmdset_a._duplicate() if cmdset_a.duplicates and cmdset_a.priority == cmdset_b.priority: for cmd in [cmd for cmd in cmdset_a if cmd in cmdset_b]: @@ -190,22 +240,56 @@ class CmdSet(object): return cmdset_c def _replace(self, cmdset_a, cmdset_b): - "C = A + B where the result is A." + """ + Replace the contents of one set with another + + Args: + cmdset_a (Cmdset): Cmdset replacing + cmdset_b (Cmdset): Cmdset to replace + + Returns: + cmdset_c (Cmdset): This is indentical to cmdset_a. + + Notes: + C = A, where B is ignored. + + """ cmdset_c = cmdset_a._duplicate() cmdset_c.commands = cmdset_a.commands[:] return cmdset_c def _remove(self, cmdset_a, cmdset_b): - "C = A + B, where B is filtered by A" + """ + Filter a set by another. + + Args: + cmdset_a (Cmdset): Cmdset acting as a removal filter. + cmdset_b (Cmdset): Cmdset to filter + + Returns: + cmdset_c (Cmdset): B, with all matching commands from A removed. + + Notes: + C = B - A, where A is used to remove the commands of B. + + """ + cmdset_c = cmdset_a._duplicate() cmdset_c.commands = [cmd for cmd in cmdset_b if not cmd in cmdset_a] return cmdset_c def _instantiate(self, cmd): """ - checks so that object is an instantiated command - and not, say a cmdclass. If it is, instantiate it. - Other types, like strings, are passed through. + checks so that object is an instantiated command and not, say + a cmdclass. If it is, instantiate it. Other types, like + strings, are passed through. + + Args: + cmd (any): Entity to analyze. + + Returns: + result (any): An instantiated Command or the input unmodified. + """ try: return cmd() @@ -214,8 +298,11 @@ class CmdSet(object): def _duplicate(self): """ - Returns a new cmdset with the same settings as this one - (no actual commands are copied over) + Returns a new cmdset with the same settings as this one (no + actual commands are copied over) + + Returns: + cmdset (Cmdset): A copy of the current cmdset. """ cmdset = CmdSet() for key, val in ((key, getattr(self, key)) for key in self.to_duplicate): @@ -233,20 +320,29 @@ class CmdSet(object): def __str__(self): """ Show all commands in cmdset when printing it. + + Returns: + commands (str): Representation of commands in Cmdset. + """ return ", ".join([str(cmd) for cmd in sorted(self.commands, key=lambda o:o.key)]) def __iter__(self): """ Allows for things like 'for cmd in cmdset': + + Returns: + iterable (iter): Commands in Cmdset. + """ return iter(self.commands) def __contains__(self, othercmd): """ - Returns True if this cmdset contains the given command (as defined - by command name and aliases). This allows for things + Returns True if this cmdset contains the given command (as + defined by command name and aliases). This allows for things like 'if cmd in cmdset' + """ ret = self._contains_cache.get(othercmd) if ret is None: @@ -333,18 +429,26 @@ class CmdSet(object): def add(self, cmd): """ - Add a command, a list of commands or a cmdset to this cmdset. + Add a new command or commands to this CmdSetcommand, a list of + commands or a cmdset to this cmdset. Note that this is *not* + a merge operation (that is handled by the + operator). - Note that if cmd already exists in set, - it will replace the old one (no priority checking etc - at this point; this is often used to overload - default commands). + Args: + cmd (Command, list, Cmdset): This allows for adding one or + more commands to this Cmdset in one go. If another Cmdset + is given, all its commands will be added. + + Notes: + If cmd already exists in set, it will replace the old one + (no priority checking etc happens here). This is very useful + when overloading default commands). + + If cmd is another cmdset class or -instance, the commands of + that command set is added to this one, as if they were part of + the original cmdset definition. No merging or priority checks + are made, rather later added commands will simply replace + existing ones to make a unique set. - If cmd is another cmdset class or -instance, the commands - of that command set is added to this one, as if they were part - of the original cmdset definition. No merging or priority checks - are made, rather later added commands will simply replace - existing ones to make a unique set. """ if inherits_from(cmd, "evennia.commands.cmdset.CmdSet"): @@ -391,16 +495,26 @@ class CmdSet(object): def remove(self, cmd): """ Remove a command instance from the cmdset. - cmd can be either a cmd instance or a key string. + + Args: + cmd (Command or str): Either the Command object to remove + or the key of such a command. + """ cmd = self._instantiate(cmd) self.commands = [oldcmd for oldcmd in self.commands if oldcmd != cmd] def get(self, cmd): """ - Return the command in this cmdset that matches the - given command. cmd may be either a command instance or - a key string. + Get a command from the cmdset. This is mostly useful to + check if the command is part of this cmdset or not. + + Args: + cmd (Command or str): Either the Command object or its key. + + Returns: + cmd (Command): The first matching Command in the set. + """ cmd = self._instantiate(cmd) for thiscmd in self.commands: @@ -408,26 +522,46 @@ class CmdSet(object): return thiscmd def count(self): - "Return number of commands in set" + """ + Number of commands in set. + + Returns: + N (int): Number of commands in this Cmdset. + + """ return len(self.commands) def get_system_cmds(self): """ - Return system commands in the cmdset, defined as - commands starting with double underscore __. - These are excempt from merge operations. + Get system commands in cmdset + + Returns: + sys_cmds (list): The system commands in the set. + + Notes: + As far as the Cmdset is concerned, system commands are any + commands with a key starting with double underscore __. + These are excempt from merge operations. + """ return self.system_commands - #return [cmd for cmd in self.commands if cmd.key.startswith('__')] def make_unique(self, caller): """ - This is an unsafe command meant to clean out a cmdset of - doublet commands after it has been created. It is useful - for commands inheriting cmdsets from the cmdhandler where - obj-based cmdsets always are added double. Doublets will - be weeded out with preference to commands defined on caller, - otherwise just by first-come-first-served. + Remove duplicate command-keys (unsafe) + + Args: + caller (object): Commands on this object will + get preference in the duplicate removal. + + Notes: + This is an unsafe command meant to clean out a cmdset of + doublet commands after it has been created. It is useful + for commands inheriting cmdsets from the cmdhandler where + obj-based cmdsets always are added double. Doublets will + be weeded out with preference to commands defined on + caller, otherwise just by first-come-first-served. + """ unique = {} for cmd in self.commands: @@ -442,10 +576,17 @@ class CmdSet(object): def get_all_cmd_keys_and_aliases(self, caller=None): """ - Returns a list of all command keys and aliases - available in this cmdset. If caller is given, the - commands is checked for access on the "call" type - before being returned. + Collects keys/aliases from commands + + Args: + caller (Object, optional): If set, this is used to check access permissions + on each command. Only commands that pass are returned. + + Returns: + names (list): A list of all command keys and aliases in this cmdset. If `caller` + was given, this list will only contain commands to which `caller` passed + the `call` locktype check. + """ names = [] if caller: @@ -458,7 +599,7 @@ class CmdSet(object): def at_cmdset_creation(self): """ Hook method - this should be overloaded in the inheriting - class, and should take care of populating the cmdset - by use of self.add(). + class, and should take care of populating the cmdset by use of + self.add(). """ pass diff --git a/evennia/commands/cmdsethandler.py b/evennia/commands/cmdsethandler.py index 2e856cd877..918d08a79e 100644 --- a/evennia/commands/cmdsethandler.py +++ b/evennia/commands/cmdsethandler.py @@ -75,12 +75,16 @@ _CACHED_CMDSETS = {} _CMDSET_PATHS = utils.make_iter(settings.CMDSET_PATHS) class _ErrorCmdSet(CmdSet): - "This is a special cmdset used to report errors" + """ + This is a special cmdset used to report errors. + """ key = "_CMDSET_ERROR" errmessage = "Error when loading cmdset." class _EmptyCmdSet(CmdSet): - "This cmdset represents an empty cmdset" + """ + This cmdset represents an empty cmdset + """ key = "_EMPTY_CMDSET" priority = -101 mergetype = "Union" @@ -173,8 +177,12 @@ class CmdSetHandler(object): """ This method is called whenever an object is recreated. - obj - this is a reference to the game object this handler - belongs to. + Args: + obj (Object): An reference to the game object this handler + belongs to. + init_true (bool, optional): Set when the handler is initializing + and loads the current cmdset. + """ self.obj = obj @@ -194,7 +202,9 @@ class CmdSetHandler(object): self.update(init_mode=True) #is then called from the object __init__. def __str__(self): - "Display current commands" + """ + Display current commands + """ string = "" mergelist = [] @@ -239,10 +249,16 @@ class CmdSetHandler(object): def _import_cmdset(self, cmdset_path, emit_to_obj=None): """ - Method wrapper for import_cmdset. - load a cmdset from a module. - cmdset_path - the python path to an cmdset object. - emit_to_obj - object to send error messages to + Method wrapper for import_cmdset; Loads a cmdset from a + module. + + Args: + cmdset_path (str): The python path to an cmdset object. + emit_to_obj (Object): The object to send error messages to + + Returns: + cmdset (Cmdset): The imported cmdset. + """ if not emit_to_obj: emit_to_obj = self.obj @@ -250,11 +266,13 @@ class CmdSetHandler(object): def update(self, init_mode=False): """ - Re-adds all sets in the handler to have an updated - current set. + Re-adds all sets in the handler to have an updated current + set. - init_mode is used right after this handler was - created; it imports all permanent cmdsets from db. + Args: + init_mode (bool, optional): Used automatically right after + this handler was created; it imports all permanent cmdsets + from the database. """ if init_mode: # reimport all permanent cmdsets @@ -291,11 +309,11 @@ class CmdSetHandler(object): Args: cmdset (CmdSet or str): Can be a cmdset object or the python path to such an object. - emit_to_obj (Object, optional): An object to receive error messages. - permanent (bool, optional): This cmdset will remain across a server reboot. - default_cmdset (Cmdset, optional): Insert this to replace the - default cmdset position (there is only one such position, - always at the bottom of the stack). + emit_to_obj (Object, optional): An object to receive error messages. + permanent (bool, optional): This cmdset will remain across a server reboot. + default_cmdset (Cmdset, optional): Insert this to replace the + default cmdset position (there is only one such position, + always at the bottom of the stack). Notes: An interesting feature of this method is if you were to send @@ -337,6 +355,12 @@ class CmdSetHandler(object): def add_default(self, cmdset, emit_to_obj=None, permanent=True): """ Shortcut for adding a default cmdset. + + Args: + cmdset (Cmdset): The Cmdset to add. + emit_to_obj (Object, optional): Gets error messages + permanent (bool, optional): The new Cmdset should survive a server reboot. + """ self.add(cmdset, emit_to_obj=emit_to_obj, permanent=permanent, default_cmdset=True) @@ -413,6 +437,7 @@ class CmdSetHandler(object): def remove_default(self): """ This explicitly deletes only the default cmdset. + """ self.remove(default_cmdset=True) # legacy alias @@ -421,15 +446,19 @@ class CmdSetHandler(object): def all(self): """ - Returns the list of cmdsets. Mostly useful to check - if stack if empty or not. + Show all cmdsets. + + Returns: + cmdsets (list): All the command sets currently in the handler. + """ return self.cmdset_stack def clear(self): """ - Removes all extra Command sets from the handler, leaving only the - default one. + Removes all Command Sets from the handler except the default one + (use `self.remove_default` to remove that). + """ self.cmdset_stack = [self.cmdset_stack[0]] storage = self.obj.cmdset_storage @@ -441,7 +470,15 @@ class CmdSetHandler(object): def has_cmdset(self, cmdset_key, must_be_default=False): """ checks so the cmdsethandler contains a cmdset with the given key. - must_be_default - only match against the default cmdset. + + Args: + cmdset_key (str): Cmdset key to check + must_be_default (bool, optional): Only return True if + the checked cmdset is the default one. + + Returns: + has_cmdset (bool): Whether or not the cmdset is in the handler. + """ if must_be_default: return self.cmdset_stack and self.cmdset_stack[0].key == cmdset_key @@ -451,7 +488,9 @@ class CmdSetHandler(object): def reset(self): """ Force reload of all cmdsets in handler. This should be called - after _CACHED_CMDSETS have been cleared (normally by @reload). + after _CACHED_CMDSETS have been cleared (normally this is + handled automatically by @reload). + """ new_cmdset_stack = [] for cmdset in self.cmdset_stack: diff --git a/evennia/commands/command.py b/evennia/commands/command.py index 2eae1bb087..2a8dc41348 100644 --- a/evennia/commands/command.py +++ b/evennia/commands/command.py @@ -150,9 +150,12 @@ class Command(object): # sessid - which session-id (if any) is responsible for triggering this command def __init__(self, **kwargs): - """the lockhandler works the same as for objects. + """ + The lockhandler works the same as for objects. optional kwargs will be set as properties on the Command at runtime, - overloading evential same-named class properties.""" + overloading evential same-named class properties. + + """ if kwargs: _init_command(self, **kwargs) @@ -161,14 +164,23 @@ class Command(object): return LockHandler(self) def __str__(self): - "Print the command" + """ + Print the command key + """ return self.key def __eq__(self, cmd): """ Compare two command instances to each other by matching their key and aliases. - input can be either a cmd object or the name of a command. + + Args: + cmd (Command or str): Allows for equating both Command + objects and their keys. + + Returns: + equal (bool): If the commands are equal or not. + """ try: # first assume input is a command (the most common case) @@ -179,9 +191,10 @@ class Command(object): def __ne__(self, cmd): """ - The logical negation of __eq__. Since this is one of the - most called methods in Evennia (along with __eq__) we do some - code-duplication here rather than issuing a method-lookup to __eq__. + The logical negation of __eq__. Since this is one of the most + called methods in Evennia (along with __eq__) we do some + code-duplication here rather than issuing a method-lookup to + __eq__. """ try: return not cmd.key in self._matcheset @@ -190,11 +203,15 @@ class Command(object): def __contains__(self, query): """ - This implements searches like 'if query in cmd'. It's a fuzzy matching - used by the help system, returning True if query can be found - as a substring of the commands key or its aliases. + This implements searches like 'if query in cmd'. It's a fuzzy + matching used by the help system, returning True if query can + be found as a substring of the commands key or its aliases. - query (str) - query to match against. Should be lower case. + Args: + query (str): query to match against. Should be lower case. + + Returns: + result (bool): Fuzzy matching result. """ return any(query in keyalias for keyalias in self._keyaliases) @@ -205,7 +222,11 @@ class Command(object): in order to determine if this is the one we wanted. cmdname was previously extracted from the raw string by the system. - cmdname (str) is always lowercase when reaching this point. + Args: + cmdname (str): Always lowercase when reaching this point. + + Returns: + result (bool): Match result. """ return cmdname in self._matchset @@ -216,25 +237,38 @@ class Command(object): is allowed to execute this command. It should return a boolean value and is not normally something that need to be changed since it's using the Evennia permission system directly. + + Args: + srcobj (Object): Object trying to gain permission + access_type (str, optional): The lock type to check. + default (bool, optional): The fallbacl result if no lock + of matching `access_type` is found on this Command. + """ return self.lockhandler.check(srcobj, access_type, default=default) def msg(self, msg="", to_obj=None, from_obj=None, sessid=None, all_sessions=False, **kwargs): """ - This is a shortcut instad of calling msg() directly on an object - it - will detect if caller is an Object or a Player and also appends - self.sessid automatically. + This is a shortcut instad of calling msg() directly on an + object - it will detect if caller is an Object or a Player and + also appends self.sessid automatically. + + Args: + msg (str, optional): Text string of message to send. + to_obj (Object, optional): Target object of message. Defaults to self.caller. + from_obj (Object, optional): Source of message. Defaults to to_obj. + sessid (int, optional): Supply data only to a unique + session id (normally not used - this is only potentially + useful if to_obj is a Player object different from + self.caller or self.caller.player). + all_sessions (bool): Default is to send only to the session + connected to the target object + + Kwargs: + kwargs (any): These are all passed on to the message mechanism. Common + keywords are `oob` and `raw`. - msg - text string of message to send - to_obj - target object of message. Defaults to self.caller - from_obj - source of message. Defaults to to_obj - data - optional dictionary of data - sessid - supply data only to a unique sessid (normally not used - - this is only potentially useful if to_obj is a Player object - different from self.caller or self.caller.player) - all_sessions (bool) - default is to send only to the session - connected to the target object """ from_obj = from_obj or self.caller to_obj = to_obj or from_obj @@ -263,9 +297,10 @@ class Command(object): def at_pre_cmd(self): """ - This hook is called before self.parse() on all commands. - If this hook returns anything but False/None, the command + This hook is called before self.parse() on all commands. If + this hook returns anything but False/None, the command sequence is aborted. + """ pass @@ -273,27 +308,30 @@ class Command(object): """ This hook is called after the command has finished executing (after self.func()). + """ pass def parse(self): """ Once the cmdhandler has identified this as the command we - want, this function is run. If many of your commands have - a similar syntax (for example 'cmd arg1 = arg2') you should simply - define this once and just let other commands of the same form - inherit from this. See the docstring of this module for - which object properties are available to use - (notably self.args). + want, this function is run. If many of your commands have a + similar syntax (for example 'cmd arg1 = arg2') you should + simply define this once and just let other commands of the + same form inherit from this. See the docstring of this module + for which object properties are available to use (notably + self.args). + """ pass def func(self): """ - This is the actual executing part of the command. - It is called directly after self.parse(). See the docstring - of this module for which object properties are available - (beyond those set in self.parse()) + This is the actual executing part of the command. It is + called directly after self.parse(). See the docstring of this + module for which object properties are available (beyond those + set in self.parse()) + """ # a simple test command to show the available properties string = "-" * 50