From 870c0f5f75e15c2269a4bb9f5eb537e1668699f3 Mon Sep 17 00:00:00 2001 From: Griatch Date: Mon, 1 Apr 2024 17:47:24 +0200 Subject: [PATCH] Clean up objects/objects.py docstrings --- evennia/objects/objects.py | 541 +++++++++++++++++++------------------ 1 file changed, 272 insertions(+), 269 deletions(-) diff --git a/evennia/objects/objects.py b/evennia/objects/objects.py index 4d765e6500..57d29dd722 100644 --- a/evennia/objects/objects.py +++ b/evennia/objects/objects.py @@ -4,8 +4,6 @@ This module defines the basic `DefaultObject` and its children These are the (default) starting points for all in-game visible entities. -This is the v1.0 develop version (for ref in doc building). - """ import time import typing @@ -54,7 +52,7 @@ class ObjectSessionHandler: Initializes the handler. Args: - obj (Object): The object on which the handler is defined. + obj (DefaultObject): The object on which the handler is defined. """ self.obj = obj @@ -81,7 +79,7 @@ class ObjectSessionHandler: sessid (int, optional): A specific session id. Returns: - sessions (list): The sessions connected to this object. If `sessid` is given, + list: The sessions connected to this object. If `sessid` is given, this is a list of one (or zero) elements. Notes: @@ -111,7 +109,7 @@ class ObjectSessionHandler: Alias to get(), returning all sessions. Returns: - sessions (list): All sessions. + list: All sessions. """ return self.get() @@ -146,7 +144,7 @@ class ObjectSessionHandler: Remove session from handler. Args: - session (Session or int): Session or session id to remove. + Session or int: Session or session id to remove. """ try: @@ -174,7 +172,7 @@ class ObjectSessionHandler: Get amount of sessions connected. Returns: - sesslen (int): Number of sessions handled. + int: Number of sessions handled. """ return len(self._sessid_cache) @@ -186,7 +184,7 @@ class ObjectSessionHandler: class DefaultObject(ObjectDB, metaclass=TypeclassBase): """ - This is the root typeclass object, representing all entities that + This is the root Object typeclass, representing all entities that have an actual presence in-game. DefaultObjects generally have a location. They can also be manipulated and looked at. Game entities you define should inherit from DefaultObject at some distance. @@ -223,23 +221,27 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): @lazy_property def cmdset(self): + """CmdSetHandler""" return CmdSetHandler(self, True) @lazy_property def scripts(self): + """ScriptHandler""" return ScriptHandler(self) @lazy_property def nicks(self): + """NickHandler""" return NickHandler(self, ModelAttributeBackend) @lazy_property def sessions(self): + """SessionHandler""" return ObjectSessionHandler(self) @property def is_connected(self): - # we get an error for objects subscribed to channels without this + """True if this object is associated with an Account with any connected sessions.""" if self.account: # seems sane to pass on the account return self.account.is_connected else: @@ -247,11 +249,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): @property def has_account(self): - """ - Convenience property for checking if an active account is - currently connected to this object. - - """ + """True is this object has an associated account.""" return self.sessions.count() def get_cmdset_providers(self) -> dict[str, "CmdSetProvider"]: @@ -272,10 +270,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): @property def is_superuser(self): - """ - Check if user has an account, and if so, if it is a superuser. - - """ + """True if this object has an account and that account is a superuser.""" return ( self.db_account and self.db_account.is_superuser @@ -289,23 +284,23 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): This should be publically available. Args: - exclude (Object): Object to exclude from returned + exclude (DefaultObject): Object to exclude from returned contents list content_type (str): A content_type to filter by. None for no filtering. Returns: - contents (list): List of contents of this Object. + list: List of contents of this Object. Notes: - Also available as the `contents` property, minus exclusion - and filtering. + Also available as the `.contents` property, but that doesn't allow for exclusion and + filtering on content-types. """ return self.contents_cache.get(exclude=exclude, content_type=content_type) def contents_set(self, *args): - "You cannot replace this property" + "Makes sure `.contents` is read-only. Raises `AttributeError` if trying to set it." raise AttributeError( "{}.contents is read-only. Use obj.move_to or " "obj.location to move an object here.".format(self.__class__) @@ -317,7 +312,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): def exits(self): """ Returns all exits from this object, i.e. all objects at this - location having the property destination != `None`. + location having the property .destination != `None`. """ return [exi for exi in self.contents if exi.destination] @@ -353,8 +348,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): **kwargs (any): These are the same as passed to the `search` method. Returns: - tuple: `(should_return, str or Obj)`, where `should_return` is a boolean indicating - the `.search` method should return the result immediately without further + tuple: A tuple `(should_return, str or Obj)`, where `should_return` is a boolean + indicating the `.search` method should return the result immediately without further processing. If `should_return` is `True`, the second element of the tuple is the result that is returned. @@ -369,15 +364,15 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): def get_search_candidates(self, searchdata, **kwargs): """ - Get the candidates for a search. Also the `candidates` provided to the - search function is included, and could be modified in-place here. + Helper for the `.search` method. Get the candidates for a search. Also the `candidates` + provided to the search function is included, and could be modified in-place here. Args: searchdata (str): The search criterion (could be modified by `get_search_query_replacement`). **kwargs (any): These are the same as passed to the `search` method. Returns: - list: A list of objects to search between. + list: A list of objects possibly relevant for the search. Notes: If `searchdata` is a #dbref, this method should always return `None`. This is because @@ -429,8 +424,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): **kwargs, ): """ - This is a wrapper for actually searching for objects, used by the `search` method. - This is broken out into a separate method to allow for easier overriding in child classes. + Helper for the `.search` method. This is a wrapper for actually searching for objects, used + by the `search` method. This is broken out into a separate method to allow for easier + overriding in child classes. Args: searchdata (str): The search criterion. @@ -441,6 +437,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): use_dbref (bool): Allow dbref search. tags (list): Tags to search for. + Returns: + queryset or iterable: The result of the search. + """ return ObjectDB.objects.search_object( @@ -462,10 +461,10 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): results (list): The list of results from the search. Returns: - tuple: `(stacked, results)`, where `stacked` is a boolean indicating if the - result is stacked and `results` is the list of results to return. If `stacked` - is True, the ".search" method will return `results` immediately without further - processing (it will not result in a multimatch-error). + tuple: A tuple `(stacked, results)`, where `stacked` is a boolean indicating if the + result is stacked and `results` is the list of results to return. If `stacked` + is True, the ".search" method will return `results` immediately without further + processing (it will not result in a multimatch-error). Notes: The `stacked` keyword argument is an integer that controls the max size of each stack @@ -699,16 +698,17 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): echo eventual standard error messages. Default `False`. Returns: - result (Account, None or list): Just what is returned depends on - the `quiet` setting: - - `quiet=True`: No match or multumatch auto-echoes errors - to self.msg, then returns `None`. The esults are passed - through `settings.SEARCH_AT_RESULT` and - `settings.SEARCH_AT_MULTIMATCH_INPUT`. If there is a - unique match, this will be returned. - - `quiet=True`: No automatic error messaging is done, and - what is returned is always a list with 0, 1 or more - matching Accounts. + DefaultAccount, None or list: What is returned depends on + the `quiet` setting: + + - `quiet=False`: No match or multumatch auto-echoes errors + to self.msg, then returns `None`. The esults are passed + through `settings.SEARCH_AT_RESULT` and + `settings.SEARCH_AT_MULTIMATCH_INPUT`. If there is a + unique match, this will be returned. + - `quiet=True`: No automatic error messaging is done, and + what is returned is always a list with 0, 1 or more + matching Accounts. """ if isinstance(searchdata, str): @@ -741,15 +741,15 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): change operating paramaters for commands at run-time. Returns: - defer (Deferred): This is an asynchronous Twisted object that - will not fire until the command has actually finished - executing. To overload this one needs to attach - callback functions to it, with addCallback(function). - This function will be called with an eventual return - value from the command execution. This return is not - used at all by Evennia by default, but might be useful - for coders intending to implement some sort of nested - command structure. + Deferred: This is an asynchronous Twisted object that + will not fire until the command has actually finished + executing. To overload this one needs to attach + callback functions to it, with addCallback(function). + This function will be called with an eventual return + value from the command execution. This return is not + used at all by Evennia by default, but might be useful + for coders intending to implement some sort of nested + command structure. """ # break circular import issues @@ -768,28 +768,27 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): """ Emits something to a session attached to the object. - Args: - text (str or tuple, optional): The message to send. This + Keyword Args: + text (str or tuple): The message to send. This is treated internally like any send-command, so its value can be a tuple if sending multiple arguments to the `text` oob command. - from_obj (obj or list, optional): object that is sending. If + from_obj (DefaultObject, DefaultAccount, Session, or list): object that is sending. If given, at_msg_send will be called. This value will be passed on to the protocol. If iterable, will execute hook on all entities in it. - session (Session or list, optional): Session or list of + session (Session or list): Session or list of Sessions to relay data to, if any. If set, will force send to these sessions. If unset, who receives the message depends on the MULTISESSION_MODE. - options (dict, optional): Message-specific option-value + options (dict): Message-specific option-value pairs. These will be applied at the protocol level. - Keyword Args: - any (string or tuples): All kwarg keys not listed above + **kwargs (string or tuples): All kwarg keys not listed above will be treated as send-command names and their arguments (which can be a string or a tuple). Notes: - `at_msg_receive` will be called on this Object. + The `at_msg_receive` method will be called on this Object. All extra kwargs will be passed on to the protocol. """ @@ -822,16 +821,6 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): for session in sessions: session.data_out(**kwargs) - def get_contents_unique(self, caller=None): - """ - Get a mapping of contents that are visually unique to the caller, along with - how many of each there are. - - Args: - caller (Object, optional): The object to check visibility from. If not given, - the current object will be used. - """ - def for_contents(self, func, exclude=None, **kwargs): """ Runs a function on every object contained within this one. @@ -908,11 +897,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Examples: - Let's assume - - `player1.key -> "Player1"`, - `player1.get_display_name(looker=player2) -> "The First girl"` - - `player2.key -> "Player2"`, - `player2.get_display_name(looker=player1) -> "The Second girl"` + Let's assume: + + - `player1.key` -> "Player1", + - `player1.get_display_name(looker=player2)` -> "The First girl" + - `player2.key` -> "Player2", + - `player2.get_display_name(looker=player1)` -> "The Second girl" Actor-stance: :: @@ -989,12 +979,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Moves this object to a new location. Args: - destination (Object): Reference to the object to move to. This + destination (DefaultObject): Reference to the object to move to. This can also be an exit object, in which case the destination property is used as destination. quiet (bool): If true, turn off the calling of the emit hooks (announce_move_to/from etc) - emit_to_obj (Object): object to receive error messages + emit_to_obj (DefaultObject): object to receive error messages use_destination (bool): Default is for objects to use the "destination" property of destinations as the target to move to. Turning off this keyword allows objects to move "inside" exit objects. @@ -1009,31 +999,28 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): the text message generated by announce_move_to and announce_move_from by defining their {"type": move_type} for outgoing text. This can be used for altering messages and/or overloaded hook behaviors. - - Keyword Args: - Passed on to announce_move_to and announce_move_from hooks. - Exits will set the "exit_obj" kwarg to themselves. + **kwargs: Passed on to announce_move_to and announce_move_from hooks. Exits will set + the "exit_obj" kwarg to themselves. Returns: - result (bool): True/False depending on if there were problems with the move. - This method may also return various error messages to the - `emit_to_obj`. + bool: True/False depending on if there were problems with the move. This method may also + return various error messages to the `emit_to_obj`. Notes: No access checks are done in this method, these should be handled before calling `move_to`. - The `DefaultObject` hooks called (if `move_hooks=True`) are, in order: + The `DefaultObject` hooks called (if `move_hooks=True`) are, in order: - 1. `self.at_pre_move(destination)` (abort if return False) - 2. `source_location.at_pre_object_leave(self, destination)` (abort if return False) - 3. `destination.at_pre_object_receive(self, source_location)` (abort if return False) - 4. `source_location.at_object_leave(self, destination)` - 5. `self.announce_move_from(destination)` - 6. (move happens here) - 7. `self.announce_move_to(source_location)` - 8. `destination.at_object_receive(self, source_location)` - 9. `self.at_post_move(source_location)` + 1. `self.at_pre_move(destination)` (abort if return False) + 2. `source_location.at_pre_object_leave(self, destination)` (abort if return False) + 3. `destination.at_pre_object_receive(self, source_location)` (abort if return False) + 4. `source_location.at_object_leave(self, destination)` + 5. `self.announce_move_from(destination)` + 6. (move happens here) + 7. `self.announce_move_to(source_location)` + 8. `destination.at_object_receive(self, source_location)` + 9. `self.at_post_move(source_location)` """ @@ -1206,12 +1193,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Classmethod called during .create() to determine default locks for the object. Args: - account (Account): Account to attribute this object to. + account (DefaultAccount): Account to attribute this object to. caller (DefaultObject): The object which is creating this one. **kwargs: Arbitrary input. Returns: - lockstring (str): A lockstring to use for this object. + str: A lockstring to use for this object. """ pid = f"pid({account.id})" if account else None cid = f"id({caller.id})" if caller else None @@ -1239,15 +1226,17 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Keyword Args: - account (Account): Account to attribute this object to. + account (DefaultAccount): Account to attribute this object to. caller (DefaultObject): The object which is creating this one. description (str): Brief description for this object. ip (str): IP address of creator (for object auditing). method (str): The method of creation. Defaults to "create". Returns: - object (Object): A newly created object of the given typeclass. - errors (list): A list of errors in string form, if any. + tuple: A tuple (Object, errors): A newly created object of the given typeclass. This + will be `None` if there are errors. The second element is then a list of errors that + occurred during creation. If this is empty, it's safe to assume the object was created + successfully. """ errors = [] @@ -1303,7 +1292,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): new_key (string): New key/name of copied object. If new_key is not specified, the copy will be named _copy by default. Returns: - copy (Object): A copy of this object. + Object: A copy of this object. """ @@ -1333,10 +1322,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): covered by .copy(), this can be used to deal with it. Args: - new_obj (Object): The new Copy of this object. + new_obj (DefaultObject): The new Copy of this object. - Returns: - None """ pass @@ -1347,8 +1334,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): locations, as well as clean up all exits to/from the object. Returns: - noerror (bool): Returns whether or not the delete completed - successfully or not. + bool: Whether or not the delete completed successfully or not. """ global _ScriptDB @@ -1400,14 +1386,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): in whatever way. Args: - accessing_obj (Object): Object trying to access this one. + accessing_obj (DefaultObject): Object trying to access this one. access_type (str, optional): Type of access sought. default (bool, optional): What to return if no lock of access_type was found. no_superuser_bypass (bool, optional): If `True`, don't skip lock check for superuser (be careful with this one). - - Keyword Args: - Passed on to the at_access hook along with the result of the access check. + **kwargs: Passed on to the at_access hook along with the result of the access check. """ result = super().access( @@ -1425,7 +1409,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: obj_list (list): List of objects to filter. - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: list: The filtered list of visible objects. @@ -1447,7 +1431,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Displays the name of the object in a viewer-aware manner. Args: - looker (TypedObject): The object or account that is looking at or getting information + looker (DefaultObject): The object or account that is looking at or getting information for this object. Returns: @@ -1466,11 +1450,11 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): object's dbref in parentheses, if the looker has permission to see it. Args: - looker (Object): The object looking at this object. + looker (DefaultObject): The object looking at this object. Returns: str: The dbref of this object, if the looker has permission to see it. Otherwise, an - empty string is returned. + empty string is returned. Notes: By default, this becomes a string (#dbref) attached to the object's name. @@ -1490,7 +1474,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: count (int): Number of objects of this type - looker (Object): Onlooker. Not used by default. + looker (DefaultObject): Onlooker. Not used by default. Keyword Args: key (str): Optional key to pluralize. If not given, the object's `.get_display_name()` @@ -1501,7 +1485,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Returns: tuple: This is a tuple `(str, str)` with the singular and plural forms of the key - including the count. + including the count. Examples: :: @@ -1547,7 +1531,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'header' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The header display string. @@ -1560,7 +1544,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'desc' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The desc display string. @@ -1573,7 +1557,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'exits' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The exits display data. @@ -1589,7 +1573,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'characters' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The character display data. @@ -1608,7 +1592,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'things' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The things display data. @@ -1635,7 +1619,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Get the 'footer' component of the object description. Called by `return_appearance`. Args: - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The footer display string. @@ -1649,7 +1633,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: appearance (str): The compiled appearance string. - looker (Object): Object doing the looking. + looker (DefaultObject): Object doing the looking. **kwargs: Arbitrary data for use when overriding. Returns: str: The final formatted output. @@ -1662,19 +1646,19 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Main callback used by 'look' for the object to describe itself. This formats a description. By default, this looks for the `appearance_template` string set on this class and populates it with formatting keys - 'name', 'desc', 'exits', 'characters', 'things' as well as - (currently empty) 'header'/'footer'. Each of these values are - retrieved by a matching method `.get_display_*`, such as `get_display_name`, - `get_display_footer` etc. + 'name', 'desc', 'exits', 'characters', 'things' as well as + (currently empty) 'header'/'footer'. Each of these values are + retrieved by a matching method `.get_display_*`, such as `get_display_name`, + `get_display_footer` etc. Args: - looker (Object): Object doing the looking. Passed into all helper methods. + looker (DefaultObject): Object doing the looking. Passed into all helper methods. **kwargs (dict): Arbitrary, optional arguments for users overriding the call. This is passed into all helper methods. Returns: str: The description of this entity. By default this includes - the entity's name, description and any contents inside it. + the entity's name, description and any contents inside it. Notes: To simply change the layout of how the object displays itself (like @@ -1855,7 +1839,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): have no cmdsets. Keyword Args: - caller (Object, Account or Session): The object requesting the cmdsets. + caller (DefaultObject, DefaultAccount or Session): The object requesting the cmdsets. current (CmdSet): The current merged cmdset. force_init (bool): If `True`, force a re-build of the cmdset. (seems unused) **kwargs: Arbitrary input for overloads. @@ -1868,7 +1852,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Called by the CommandHandler to get a list of cmdsets to merge. Args: - caller (obj): The object requesting the cmdsets. + caller (DefaultObject): The object requesting the cmdsets. current (cmdset): The current merged cmdset. **kwargs: Arbitrary input for overloads. @@ -1883,9 +1867,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): it. Args: - account (Account): This is the connecting account. + account (DefaultAccount): This is the connecting account. session (Session): Session controlling the connection. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -1897,12 +1881,11 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Account<->Object links have been established. Args: - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). - Note: - You can use `self.account` and `self.sessions.get()` to get - account and sessions at this point; the last entry in the - list from `self.sessions.get()` is the latest Session + Notes: + You can use `self.account` and `self.sessions.get()` to get account and sessions at this + point; the last entry in the list from `self.sessions.get()` is the latest Session puppeting this Object. """ @@ -1915,9 +1898,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): this Account. Args: - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). - Note: + Notes: You can use `self.account` and `self.sessions.get()` to get account and sessions at this point; the last entry in the list from `self.sessions.get()` is the latest Session @@ -1932,12 +1915,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): this object, severing all connections. Args: - account (Account): The account object that just disconnected + account (DefaultAccount): The account object that just disconnected from this object. This can be `None` if this is called automatically (such as after a cleanup operation). session (Session): Session id controlling the connection that just disconnected. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -1972,9 +1955,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): result (bool): The outcome of the access call. accessing_obj (Object or Account): The entity trying to gain access. access_type (str): The type of access that was requested. - - Keyword Args: - Unused by default, added for possible expandability in a game. + **kwargs: Arbitrary, optional arguments. Unused by default. """ pass @@ -1987,19 +1968,19 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): destination. Return False to abort move. Args: - destination (Object): The object we are moving to + destination (DefaultObject): The object we are moving to move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: bool: If we should move or not. Notes: - If this method returns False/None, the move is cancelled + If this method returns `False` or `None`, the move is cancelled before it is even started. """ @@ -2011,14 +1992,16 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): previously 'inside' it. Return False to abort move. Args: - leaving_object (Object): The object that is about to leave. - destination (Object): Where object is going to. - **kwargs (dict): Arbitrary, optional arguments for users + leaving_object (DefaultObject): The object that is about to leave. + destination (DefaultObject): Where object is going to. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: bool: If `leaving_object` should be allowed to leave or not. - Notes: If this method returns False, None, the move is canceled before + Notes: + + If this method returns `False` or `None`, the move is canceled before it even started. """ @@ -2031,16 +2014,18 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): remains where it was. Args: - arriving_object (Object): The object moved into this one - source_location (Object): Where `moved_object` came from. + arriving_object (DefaultObject): The object moved into this one + source_location (DefaultObject): Where `moved_object` came from. Note that this could be `None`. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: bool: If False, abort move and `moved_obj` remains where it was. - Notes: If this method returns False, None, the move is canceled before + Notes: + + If this method returns `False` or `None`, the move is canceled before it even started. """ @@ -2056,23 +2041,26 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): location. Args: - destination (Object): The place we are going to. + destination (DefaultObject): The place we are going to. msg (str, optional): a replacement message. mapping (dict, optional): additional mapping objects. move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). - You can override this method and call its parent with a - message to simply change the default message. In the string, - you can use the following as mappings (between braces): - object: the object which is moving. - exit: the exit from which the object is moving (if found). - origin: the location of the object before the move. - destination: the location of the object after moving. + Notes: + + You can override this method and call its parent with a + message to simply change the default message. In the string, + you can use the following as mappings: + + - `{object}`: the object which is moving. + - `{exit}`: the exit from which the object is moving (if found). + - `{origin}`: the location of the object before the move. + - `{destination}`: the location of the object after moving. """ if not self.location: @@ -2108,24 +2096,27 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): we are standing in the new location. Args: - source_location (Object): The place we came from + source_location (DefaultObject): The place we came from msg (str, optional): the replacement message if location. mapping (dict, optional): additional mapping objects. move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Notes: + You can override this method and call its parent with a message to simply change the default message. In the string, you can use the following as mappings (between braces): - object: the object which is moving. - exit: the exit from which the object is moving (if found). - origin: the location of the object before the move. - destination: the location of the object after moving. + + + - `{object}`: the object which is moving. + - `{exit}`: the exit from which the object is moving (if found). + - `{origin}`: the location of the object before the move. + - `{destination}`: the location of the object after moving. """ @@ -2179,12 +2170,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): now in. Args: - source_location (Object): Where we came from. This may be `None`. + source_location (DefaultObject): Where we came from. This may be `None`. move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -2198,13 +2189,13 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Called just before an object leaves from inside this object Args: - moved_obj (Object): The object leaving - target_location (Object): Where `moved_obj` is going. + moved_obj (DefaultObject): The object leaving + target_location (DefaultObject): Where `moved_obj` is going. move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -2215,14 +2206,14 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Called after an object has been moved into this object. Args: - moved_obj (Object): The object moved into this one - source_location (Object): Where `moved_object` came from. + moved_obj (DefaultObject): The object moved into this one + source_location (DefaultObject): Where `moved_object` came from. Note that this could be `None`. move_type (str): The type of move. "give", "traverse", etc. This is an arbitrary string provided to obj.move_to(). Useful for altering messages or altering logic depending on the kind of movement. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -2239,9 +2230,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): called. Args: - traversing_object (Object): Object traversing us. - target_location (Object): Where target is going. - **kwargs (dict): Arbitrary, optional arguments for users + traversing_object (DefaultObject): Object traversing us. + target_location (DefaultObject): Where target is going. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -2254,8 +2245,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Exit) Args: - traversing_object (Object): The object traversing us. - source_location (Object): Where `traversing_object` came from. + traversing_object (DefaultObject): The object traversing us. + source_location (DefaultObject): Where `traversing_object` came from. **kwargs (dict): Arbitrary, optional arguments for users overriding the call (unused by default). @@ -2273,8 +2264,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): some reason. Args: - traversing_object (Object): The object that failed traversing us. - **kwargs (dict): Arbitrary, optional arguments for users + traversing_object (DefaultObject): The object that failed traversing us. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Notes: @@ -2301,9 +2292,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: text (str, optional): The message received. from_obj (any, optional): The object sending the message. - - Keyword Args: - This includes any keywords sent to the `msg` method. + **kwargs: This includes any keywords sent to the `msg` method. Returns: receive (bool): If this message should be received. @@ -2323,9 +2312,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: text (str, optional): Text to send. to_obj (any, optional): The object to send to. - - Keyword Args: - Keywords passed from msg() + **kwargs: Keywords passed from msg(). Notes: Since this method is executed by `from_obj`, if no `from_obj` @@ -2345,13 +2332,13 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Helper method to return_appearance. Args: - looker (Object): The entity looking. - **kwargs (any): Passed from `return_appearance`. Unused by default. + looker (DefaultObject): The entity looking. + **kwargs: Passed from `return_appearance`. Unused by default. Returns: dict: A dict of lists categorized by type. Byt default this - contains 'exits', 'characters' and 'things'. The elements of these - lists are the actual objects. + contains 'exits', 'characters' and 'things'. The elements of these + lists are the actual objects. """ @@ -2371,16 +2358,16 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): for return_appearance. Args: - looker (Object): The entity looking. - **kwargs (any): Passed from `return_appearance`. Passed into + looker (DefaultObject): The entity looking. + **kwargs: Passed from `return_appearance`. Passed into `get_display_name` for each found entity. Returns: dict: A dict of lists categorized by type. Byt default this - contains 'exits', 'characters' and 'things'. The elements - of these lists are strings - names of the objects that - can depend on the looker and also be grouped in the case - of multiple same-named things etc. + contains 'exits', 'characters' and 'things'. The elements + of these lists are strings - names of the objects that + can depend on the looker and also be grouped in the case + of multiple same-named things etc. Notes: This method shouldn't add extra coloring to the names beyond what is @@ -2418,17 +2405,16 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): send any data. Args: - target (Object): The target being looked at. This is + target (DefaultObject): The target being looked at. This is commonly an object or the current location. It will be checked for the "view" type access. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call. This will be passed into return_appearance, get_display_name and at_desc but is not used by default. Returns: - lookstring (str): A ready-processed look string - potentially ready to return to the looker. + str: A ready-processed look string potentially ready to return to the looker. """ if not target.access(self, "view"): @@ -2451,7 +2437,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Args: looker (Object, optional): The object requesting the description. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). """ @@ -2463,12 +2449,12 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): picked up. Args: - getter (Object): The object about to get this object. - **kwargs (dict): Arbitrary, optional arguments for users + getter (DefaultObject): The object about to get this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: - shouldget (bool): If the object should be gotten or not. + bool: If the object should be gotten or not. Notes: If this method returns False/None, the getting is cancelled @@ -2485,8 +2471,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): picked up. Args: - getter (Object): The object getting this object. - **kwargs (dict): Arbitrary, optional arguments for users + getter (DefaultObject): The object getting this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Notes: @@ -2502,16 +2488,16 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): given. Args: - giver (Object): The object about to give this object. - getter (Object): The object about to get this object. - **kwargs (dict): Arbitrary, optional arguments for users + giver (DefaultObject): The object about to give this object. + getter (DefaultObject): The object about to get this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: shouldgive (bool): If the object should be given or not. Notes: - If this method returns False/None, the giving is cancelled + If this method returns `False` or `None`, the giving is cancelled before it is even started. """ @@ -2526,9 +2512,9 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): given. Args: - giver (Object): The object giving this object. - getter (Object): The object getting this object. - **kwargs (dict): Arbitrary, optional arguments for users + giver (DefaultObject): The object giving this object. + getter (DefaultObject): The object getting this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Notes: @@ -2544,15 +2530,15 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): dropped. Args: - dropper (Object): The object which will drop this object. - **kwargs (dict): Arbitrary, optional arguments for users + dropper (DefaultObject): The object which will drop this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Returns: - shoulddrop (bool): If the object should be dropped or not. + bool: If the object should be dropped or not. Notes: - If this method returns False/None, the dropping is cancelled + If this method returns `False` or `None`, the dropping is cancelled before it is even started. """ @@ -2573,8 +2559,8 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): dropped. Args: - dropper (Object): The object which just dropped this object. - **kwargs (dict): Arbitrary, optional arguments for users + dropper (DefaultObject): The object which just dropped this object. + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). Notes: @@ -2600,11 +2586,11 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): a say. This is sent by the whisper command by default. Other verbal commands could use this hook in similar ways. - receivers (Object or iterable): If set, this is the target or targets for the + receivers (DefaultObject or iterable): If set, this is the target or targets for the say/whisper. Returns: - message (str): The (possibly modified) text to be spoken. + str: The (possibly modified) text to be spoken. """ return message @@ -2635,7 +2621,7 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): msg_self (bool or str, optional): If boolean True, echo `message` to self. If a string, return that message. If False or unset, don't echo to self. msg_location (str, optional): The message to echo to self's location. - receivers (Object or iterable, optional): An eventual receiver or receivers of the + receivers (DefaultObject or iterable, optional): An eventual receiver or receivers of the message (by default only used by whispers). msg_receivers(str): Specific message to pass to the receiver(s). This will parsed with the {receiver} placeholder replaced with the given receiver. @@ -2649,20 +2635,22 @@ class DefaultObject(ObjectDB, metaclass=TypeclassBase): Messages can contain {} markers. These are substituted against the values passed in the `mapping` argument. + :: msg_self = 'You say: "{speech}"' msg_location = '{object} says: "{speech}"' msg_receivers = '{object} whispers: "{speech}"' Supported markers by default: - {self}: text to self-reference with (default 'You') - {speech}: the text spoken/whispered by self. - {object}: the object speaking. - {receiver}: replaced with a single receiver only for strings meant for a specific - receiver (otherwise 'None'). - {all_receivers}: comma-separated list of all receivers, - if more than one, otherwise same as receiver - {location}: the location where object is. + + - {self}: text to self-reference with (default 'You') + - {speech}: the text spoken/whispered by self. + - {object}: the object speaking. + - {receiver}: replaced with a single receiver only for strings meant for a specific + receiver (otherwise 'None'). + - {all_receivers}: comma-separated list of all receivers, + if more than one, otherwise same as receiver + - {location}: the location where object is. """ msg_type = "say" @@ -2778,12 +2766,13 @@ class DefaultCharacter(DefaultObject): Classmethod called during .create() to determine default locks for the object. Args: - account (Account): Account to attribute this object to. + account (DefaultAccount): Account to attribute this object to. caller (DefaultObject): The object which is creating this one. **kwargs: Arbitrary input. Returns: - lockstring (str): A lockstring to use for this object. + str: A lockstring to use for this object. + """ pid = f"pid({account.id})" if account else None character = kwargs.get("character", None) @@ -2895,16 +2884,24 @@ class DefaultCharacter(DefaultObject): @classmethod def normalize_name(cls, name): """ - Normalize the character name prior to creating. Note that this should be refactored to - support i18n for non-latin scripts, but as we (currently) have no bug reports requesting - better support of non-latin character sets, requiring character names to be latinified is an - acceptable option. + Normalize the character name prior to creating. Args: name (str) : The name of the character Returns: - latin_name (str) : A valid name. + str : A valid, latinized name. + + Notes: + + The main purpose of this is to make sure that character names are not created with + special unicode characters that look visually identical to latin charaters. This could + be used to impersonate other characters. + + This method should be refactored to support i18n for non-latin names, but as we + (currently) have no bug reports requesting better support of non-latin character sets, + requiring character names to be latinified is an acceptable default option. + """ from evennia.utils.utils import latinify @@ -2919,10 +2916,10 @@ class DefaultCharacter(DefaultObject): Args: name (str) : The name of the character - Kwargs: + Keyword Args: account (DefaultAccount, optional) : The account creating the character. Returns: - error (str, optional) : A non-empty error message if there is a problem, otherwise False. + str or None: A non-empty error message if there is a problem, otherwise `None`. """ if account and cls.objects.filter_family(db_key__iexact=name): @@ -2967,7 +2964,7 @@ class DefaultCharacter(DefaultObject): """ Return the character from storage in None location in `at_post_unpuppet`. Args: - account (Account): This is the connecting account. + account (DefaultAccount): This is the connecting account. session (Session): Session controlling the connection. """ @@ -2994,7 +2991,8 @@ class DefaultCharacter(DefaultObject): Args: **kwargs (dict): Arbitrary, optional arguments for users overriding the call (unused by default). - Note: + Notes: + You can use `self.account` and `self.sessions.get()` to get account and sessions at this point; the last entry in the list from `self.sessions.get()` is the latest Session @@ -3019,15 +3017,16 @@ class DefaultCharacter(DefaultObject): after the account logged off ("headless", so to say). Args: - account (Account): The account object that just disconnected + account (DefaultAccount): The account object that just disconnected from this object. session (Session): Session controlling the connection that just disconnected. Keyword Args: reason (str): If given, adds a reason for the unpuppet. This is set when the user is auto-unpuppeted due to being link-dead. - **kwargs (dict): Arbitrary, optional arguments for users + **kwargs: Arbitrary, optional arguments for users overriding the call (unused by default). + """ if not self.sessions.count(): # only remove this char from grid if no sessions control it anymore. @@ -3113,8 +3112,9 @@ class DefaultRoom(DefaultObject): method (str): The method used to create the room. Defaults to "create". Returns: - room (Object): A newly created Room of the given typeclass. - errors (list): A list of errors in string form, if any. + tuple: A tuple `(Object, error)` with the newly created Room of the given typeclass, + or `None` if there was an error. If there was an error, `error` will be a list of + error strings. """ errors = [] @@ -3166,8 +3166,7 @@ class DefaultRoom(DefaultObject): def basetype_setup(self): """ - Simple room setup setting locks to make sure the room - cannot be picked up. + Simple room setup setting locks to make sure the room cannot be picked up. """ @@ -3215,13 +3214,13 @@ class ExitCommand(_COMMAND_DEFAULT_CLASS): Shows a bit of information on where the exit leads. Args: - caller (Object): The object (usually a character) that entered an ambiguous command. + caller (DefaultObject): The object (usually a character) that entered an ambiguous command. **kwargs (dict): Arbitrary, optional arguments for users overriding the call (unused by default). Returns: - A string with identifying information to disambiguate the command, conventionally with a - preceding space. + str: A string with identifying information to disambiguate the command, conventionally + with a preceding space. """ if self.obj.destination: @@ -3263,7 +3262,7 @@ class DefaultExit(DefaultObject): exit's name, triggering the movement between rooms. Args: - exidbobj (Object): The DefaultExit object to base the command on. + exidbobj (DefaultObject): The DefaultExit object to base the command on. """ @@ -3313,15 +3312,16 @@ class DefaultExit(DefaultObject): location (Room): The room to create this exit in. Keyword Args: - account (AccountDB): Account to associate this Exit with. - caller (ObjectDB): The Object creating this Object. + account (DefaultAccountDB): Account to associate this Exit with. + caller (DefaultObject): The Object creating this Object. description (str): Brief description for this object. ip (str): IP address of creator (for object auditing). destination (Room): The room to which this exit should go. Returns: - exit (Object): A newly created Room of the given typeclass. - errors (list): A list of errors in string form, if any. + tuple: A tuple `(Object, errors)`, where the object is the newly + created exit of the given typeclass, or `None` if there was an error. + If there was an error, `errors` will be a list of error strings. """ errors = [] @@ -3375,7 +3375,7 @@ class DefaultExit(DefaultObject): def basetype_setup(self): """ - Setup exit-security + Setup exit-security. You should normally not need to overload this - if you do make sure you include all the functionality in this method. @@ -3409,7 +3409,7 @@ class DefaultExit(DefaultObject): has no cmdsets. Keyword Args: - caller (Object, Account or Session): The object requesting the cmdsets. + caller (DefaultObject, DefaultAccount or Session): The object requesting the cmdsets. current (CmdSet): The current merged cmdset. force_init (bool): If `True`, force a re-build of the cmdset (for example to update aliases). @@ -3425,6 +3425,7 @@ class DefaultExit(DefaultObject): This is called when this objects is re-loaded from cache. When that happens, we make sure to remove any old ExitCmdSet cmdset (this most commonly occurs when renaming an existing exit) + """ self.cmdset.remove_default() @@ -3434,8 +3435,8 @@ class DefaultExit(DefaultObject): already been checked (in the Exit command) at this point. Args: - traversing_object (Object): Object traversing us. - target_location (Object): Where target is going. + traversing_object (DefaultObject): Object traversing us. + target_location (DefaultObject): Where target is going. **kwargs (dict): Arbitrary, optional arguments for users overriding the call (unused by default). @@ -3456,7 +3457,7 @@ class DefaultExit(DefaultObject): Overloads the default hook to implement a simple default error message. Args: - traversing_object (Object): The object that failed traversing us. + traversing_object (DefaultObject): The object that failed traversing us. **kwargs (dict): Arbitrary, optional arguments for users overriding the call (unused by default). @@ -3475,10 +3476,12 @@ class DefaultExit(DefaultObject): Args: return_all (bool): Whether to return available results as a - list or single matching exit. + queryset or single matching exit. Returns: - queryset or exit (Exit): The matching exit(s). + Exit or queryset: The matching exit(s). If `return_all` is `True`, this + will be a queryset of all matching exits. Otherwise, it will be the first Exit matched. + """ query = ObjectDB.objects.filter(db_location=self.destination, db_destination=self.location) if return_all: