From f9e7b01f572637992e1ca066d61ad5cde49b52ee Mon Sep 17 00:00:00 2001 From: Griatch Date: Thu, 20 Apr 2017 20:58:35 +0200 Subject: [PATCH] Add **kwargs options to at_* hooks to all typeclasses, for greater flexibility for users. Resolves #1276. --- evennia/commands/default/tests.py | 2 +- evennia/comms/comms.py | 83 +++++++++++++++----- evennia/objects/objects.py | 124 ++++++++++++++++++++++-------- evennia/players/players.py | 59 +++++++++++--- evennia/scripts/scripts.py | 32 ++++++-- 5 files changed, 228 insertions(+), 72 deletions(-) diff --git a/evennia/commands/default/tests.py b/evennia/commands/default/tests.py index 9e3ec66dc0..fc053b313a 100644 --- a/evennia/commands/default/tests.py +++ b/evennia/commands/default/tests.py @@ -74,7 +74,7 @@ class CommandTest(EvenniaTest): cmdobj.parse() cmdobj.func() cmdobj.at_post_cmd() - # clean out prettytable sugar. We only operate on text-type + # clean out evtable sugar. We only operate on text-type stored_msg = [args[0] if args and args[0] else kwargs.get("text",utils.to_str(kwargs, force_string=True)) for name, args, kwargs in receiver.msg.mock_calls] # Get the first element of a tuple if msg received a tuple instead of a string diff --git a/evennia/comms/comms.py b/evennia/comms/comms.py index f50d3bf4a8..ba35e4c552 100644 --- a/evennia/comms/comms.py +++ b/evennia/comms/comms.py @@ -100,11 +100,17 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): string = "" return string - def mute(self, subscriber): + def mute(self, subscriber, **kwargs): """ Adds an entity to the list of muted subscribers. A muted subscriber will no longer see channel messages, but may use channel commands. + + Args: + subscriber (Object or Player): Subscriber to mute. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ mutelist = self.mutelist if subscriber not in mutelist: @@ -113,11 +119,16 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): return True return False - def unmute(self, subscriber): + def unmute(self, subscriber, **kwargs): """ - Removes an entity to the list of muted subscribers. - A muted subscriber will no longer see channel messages, + Removes an entity to the list of muted subscribers. A muted subscriber will no longer see channel messages, but may use channel commands. + + Args: + subscriber (Object or Player): The subscriber to unmute. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ mutelist = self.mutelist if subscriber in mutelist: @@ -126,13 +137,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): return True return False - def connect(self, subscriber): + def connect(self, subscriber, **kwargs): """ Connect the user to this channel. This checks access. Args: subscriber (Player or Object): the entity to subscribe to this channel. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: success (bool): Whether or not the addition was @@ -154,13 +167,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): self.post_join_channel(subscriber) return True - def disconnect(self, subscriber): + def disconnect(self, subscriber, **kwargs): """ Disconnect entity from this channel. Args: subscriber (Player of Object): the entity to disconnect. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: success (bool): Whether or not the removal was @@ -179,7 +194,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): self.post_leave_channel(subscriber) return True - def access(self, accessing_obj, access_type='listen', default=False, no_superuser_bypass=False): + def access(self, accessing_obj, access_type='listen', default=False, no_superuser_bypass=False, **kwargs): """ Determines if another object has permission to access. @@ -189,6 +204,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): default (bool, optional): What to return if no lock of access_type was found no_superuser_bypass (bool, optional): Turns off superuser lock bypass. Be careful with this one. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: return (bool): Result of lock check. @@ -209,7 +226,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): CHANNELHANDLER.update() def message_transform(self, msgobj, emit=False, prefix=True, - sender_strings=None, external=False): + sender_strings=None, external=False, **kwargs): """ Generates the formatted string sent to listeners on a channel. @@ -220,6 +237,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): prefix (bool, optional): Prefix `msg` with a text given by `self.channel_prefix`. sender_strings (list, optional): Used by bots etc, one string per external sender. external (bool, optional): If this is an external sender or not. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ if sender_strings or external: @@ -231,7 +250,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): msgobj.message = body return msgobj - def distribute_message(self, msgobj, online=False): + def distribute_message(self, msgobj, online=False, **kwargs): """ Method for grabbing all listeners that a message should be sent to on this channel, and sending them a message. @@ -240,6 +259,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): msgobj (Msg or TempMsg): Message to distribute. online (bool): Only send to receivers who are actually online (not currently used): + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: This is also where logging happens, if enabled. @@ -332,7 +353,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): # hooks - def channel_prefix(self, msg=None, emit=False): + def channel_prefix(self, msg=None, emit=False, **kwargs): """ Hook method. How the channel should prefix itself for users. @@ -341,6 +362,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): msg (str, optional): Prefix text emit (bool, optional): Switches to emit mode, which usually means to not prefix the channel's info. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: prefix (str): The created channel prefix. @@ -348,12 +371,14 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): """ return '' if emit else '[%s] ' % self.key - def format_senders(self, senders=None): + def format_senders(self, senders=None, **kwargs): """ Hook method. Function used to format a list of sender names. Args: senders (list): Sender object names. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: formatted_list (str): The list of names formatted appropriately. @@ -368,7 +393,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): return '' return ', '.join(senders) - def pose_transform(self, msgobj, sender_string): + def pose_transform(self, msgobj, sender_string, **kwargs): """ Hook method. Detects if the sender is posing, and modifies the message accordingly. @@ -376,6 +401,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): Args: msgobj (Msg or TempMsg): The message to analyze for a pose. sender_string (str): The name of the sender/poser. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: string (str): A message that combines the `sender_string` @@ -398,7 +425,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): else: return '%s: %s' % (sender_string, message) - def format_external(self, msgobj, senders, emit=False): + def format_external(self, msgobj, senders, emit=False, **kwargs): """ Hook method. Used for formatting external messages. This is needed as a separate operation because the senders of external @@ -409,6 +436,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): msgobj (Msg or TempMsg): The message to send. senders (list): Strings, one per sender. emit (bool, optional): A sender-agnostic message or not. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: transformed (str): A formatted string. @@ -419,13 +448,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): senders = ', '.join(senders) return self.pose_transform(msgobj, senders) - def format_message(self, msgobj, emit=False): + def format_message(self, msgobj, emit=False, **kwargs): """ Hook method. Formats a message body for display. Args: msgobj (Msg or TempMsg): The message object to send. emit (bool, optional): The message is agnostic of senders. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: transformed (str): The formatted message. @@ -443,13 +474,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): senders = ', '.join(senders) return self.pose_transform(msgobj, senders) - def pre_join_channel(self, joiner): + def pre_join_channel(self, joiner, **kwargs): """ Hook method. Runs right before a channel is joined. If this returns a false value, channel joining is aborted. Args: joiner (object): The joining object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: should_join (bool): If `False`, channel joining is aborted. @@ -457,23 +490,27 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): """ return True - def post_join_channel(self, joiner): + def post_join_channel(self, joiner, **kwargs): """ Hook method. Runs right after an object or player joins a channel. Args: joiner (object): The joining object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def pre_leave_channel(self, leaver): + def pre_leave_channel(self, leaver, **kwargs): """ Hook method. Runs right before a user leaves a channel. If this returns a false value, leaving the channel will be aborted. Args: leaver (object): The leaving object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: should_leave (bool): If `False`, channel parting is aborted. @@ -481,17 +518,19 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): """ return True - def post_leave_channel(self, leaver): + def post_leave_channel(self, leaver, **kwargs): """ Hook method. Runs right after an object or player leaves a channel. Args: leaver (object): The leaving object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def pre_send_message(self, msg): + def pre_send_message(self, msg, **kwargs): """ Hook method. Runs before a message is sent to the channel and should return the message object, after any transformations. @@ -499,6 +538,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): Args: msg (Msg or TempMsg): Message to send. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: result (Msg, TempMsg or bool): If False, abort send. @@ -506,12 +547,14 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)): """ return msg - def post_send_message(self, msg): + def post_send_message(self, msg, **kwargs): """ Hook method. Run after a message is sent to the channel. Args: msg (Msg or TempMsg): Message sent. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass diff --git a/evennia/objects/objects.py b/evennia/objects/objects.py index 814d80acfa..eed07fe8be 100644 --- a/evennia/objects/objects.py +++ b/evennia/objects/objects.py @@ -1048,7 +1048,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ pass - def at_pre_puppet(self, player, session=None): + def at_pre_puppet(self, player, session=None, **kwargs): """ Called just before a Player connects to this object to puppet it. @@ -1056,14 +1056,20 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: player (Player): This is the connecting player. session (Session): Session controlling the connection. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass - def at_post_puppet(self): + def at_post_puppet(self, **kwargs): """ Called just after puppeting has been completed and all Player<->Object links have been established. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Note: You can use `self.player` and `self.sessions.get()` to get player and sessions at this point; the last entry in the @@ -1073,11 +1079,14 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ self.player.db._last_puppet = self - def at_pre_unpuppet(self): + def at_pre_unpuppet(self, **kwargs): """ Called just before beginning to un-connect a puppeting from this Player. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Note: You can use `self.player` and `self.sessions.get()` to get player and sessions at this point; the last entry in the @@ -1087,7 +1096,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ pass - def at_post_unpuppet(self, player, session=None): + def at_post_unpuppet(self, player, session=None, **kwargs): """ Called just after the Player successfully disconnected from this object, severing all connections. @@ -1097,6 +1106,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): from this object. session (Session): Session id controlling the connection that just disconnected. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass @@ -1140,13 +1151,15 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): # hooks called when moving the object - def at_before_move(self, destination): + def at_before_move(self, destination, **kwargs): """ Called just before starting to move this object to destination. Args: destination (Object): The object we are moving to + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: shouldmove (bool): If we should move or not. @@ -1159,7 +1172,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): # return has_perm(self, destination, "can_move") return True - def announce_move_from(self, destination, msg=None, mapping=None): + def announce_move_from(self, destination, msg=None, mapping=None, **kwargs): """ Called if the move is to be announced. This is called while we are still standing in the old @@ -1169,6 +1182,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): destination (Object): The place we are going to. msg (str, optional): a replacement message. mapping (dict, optional): additional mapping objects. + **kwargs (dict): 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, @@ -1200,7 +1215,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): location.msg_contents(string, exclude=(self, ), mapping=mapping) - def announce_move_to(self, source_location, msg=None, mapping=None): + def announce_move_to(self, source_location, msg=None, mapping=None, **kwargs): """ Called after the move if the move was not quiet. At this point we are standing in the new location. @@ -1209,14 +1224,17 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): source_location (Object): The place we came from msg (str, optional): the replacement message if location. mapping (dict, optional): additional mapping objects. + **kwargs (dict): 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 (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. """ @@ -1253,7 +1271,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): destination.msg_contents(string, exclude=(self, ), mapping=mapping) - def at_after_move(self, source_location): + def at_after_move(self, source_location, **kwargs): """ Called after move has completed, regardless of quiet mode or not. Allows changes to the object due to the location it is @@ -1261,22 +1279,26 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: source_location (Object): Wwhere we came from. This may be `None`. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_object_leave(self, moved_obj, target_location): + def at_object_leave(self, moved_obj, target_location, **kwargs): """ 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. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_object_receive(self, moved_obj, source_location): + def at_object_receive(self, moved_obj, source_location, **kwargs): """ Called after an object has been moved into this object. @@ -1284,11 +1306,13 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): moved_obj (Object): The object moved into this one source_location (Object): Where `moved_object` came from. Note that this could be `None`. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_traverse(self, traversing_object, target_location): + def at_traverse(self, traversing_object, target_location, **kwargs): """ This hook is responsible for handling the actual traversal, normally by calling @@ -1301,11 +1325,13 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: traversing_object (Object): Object traversing us. target_location (Object): Where target is going. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_after_traverse(self, traversing_object, source_location): + def at_after_traverse(self, traversing_object, source_location, **kwargs): """ Called just after an object successfully used this object to traverse to another object (i.e. this object is a type of @@ -1314,19 +1340,23 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: traversing_object (Object): The object traversing us. source_location (Object): Where `traversing_object` came from. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: The target location should normally be available as `self.destination`. """ pass - def at_failed_traverse(self, traversing_object): + def at_failed_traverse(self, traversing_object, **kwargs): """ This is called if an object fails to traverse this object for some reason. Args: traversing_object (Object): The object that failed traversing us. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: Using the default exits, this hook will not be called if an @@ -1387,13 +1417,15 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): # hooks called by the default cmdset. - def return_appearance(self, looker): + def return_appearance(self, looker, **kwargs): """ This formats a description. It is the hook a 'look' command should call. Args: looker (Object): Object doing the looking. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ if not looker: return "" @@ -1420,7 +1452,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): string += "\n|wYou see:|n " + ", ".join(users + things) return string - def at_look(self, target): + def at_look(self, target, **kwargs): """ Called when this object performs a look. It allows to customize just what this means. It will not itself @@ -1430,6 +1462,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): target (Object): 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 + overriding the call (unused by default). Returns: lookstring (str): A ready-processed look string @@ -1450,22 +1484,27 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): return description - def at_desc(self, looker=None): + def at_desc(self, looker=None, **kwargs): """ This is called whenever someone looks at this object. - looker (Object): The object requesting the description. + Args: + looker (Object, optional): The object requesting the description. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_get(self, getter): + def at_get(self, getter, **kwargs): """ Called by the default `get` command when this object has been picked up. Args: getter (Object): The object getting this object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: This hook cannot stop the pickup from happening. Use @@ -1474,7 +1513,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ pass - def at_give(self, giver, getter): + def at_give(self, giver, getter, **kwargs): """ Called by the default `give` command when this object has been given. @@ -1482,6 +1521,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: giver (Object): The object giving this object. getter (Object): The object getting this object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: This hook cannot stop the give from happening. Use @@ -1490,13 +1531,15 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ pass - def at_drop(self, dropper): + def at_drop(self, dropper, **kwargs): """ Called by the default `drop` command when this object has been dropped. Args: dropper (Object): The object which just dropped this object. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: This hook cannot stop the drop from happening. Use @@ -1505,7 +1548,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): """ pass - def at_say(self, speaker, message): + def at_say(self, speaker, message, **kwargs): """ Called on this object if an object inside this object speaks. The string returned from this method is the final form of the @@ -1514,6 +1557,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)): Args: speaker (Object): The object speaking. message (str): The words spoken. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: You should not need to add things like 'you say: ' or @@ -1551,7 +1596,7 @@ class DefaultCharacter(DefaultObject): # add the default cmdset self.cmdset.add_default(settings.CMDSET_CHARACTER, permanent=True) - def at_after_move(self, source_location): + def at_after_move(self, source_location, **kwargs): """ We make sure to look around after a move. @@ -1559,7 +1604,7 @@ class DefaultCharacter(DefaultObject): if self.location.access(self, "view"): self.msg(self.at_look(self.location)) - def at_pre_puppet(self, player, session=None): + def at_pre_puppet(self, player, session=None, **kwargs): """ Return the character from storage in None location in `at_post_unpuppet`. Args: @@ -1575,11 +1620,14 @@ class DefaultCharacter(DefaultObject): else: player.msg("|r%s has no location and no home is set.|n" % self, session=session) # Note to set home. - def at_post_puppet(self): + def at_post_puppet(self, **kwargs): """ Called just after puppeting has been completed and all Player<->Object links have been established. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Note: You can use `self.player` and `self.sessions.get()` to get player and sessions at this point; the last entry in the @@ -1594,7 +1642,7 @@ class DefaultCharacter(DefaultObject): obj.msg("%s has entered the game." % self.get_display_name(obj), from_obj=from_obj) self.location.for_contents(message, exclude=[self], from_obj=self) - def at_post_unpuppet(self, player, session=None): + def at_post_unpuppet(self, player, session=None, **kwargs): """ We stove away the character when the player goes ooc/logs off, otherwise the character object will remain in the room also @@ -1605,6 +1653,8 @@ class DefaultCharacter(DefaultObject): from this object. session (Session): Session controlling the connection that just disconnected. + **kwargs (dict): 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. @@ -1694,6 +1744,8 @@ class ExitCommand(command.Command): Args: caller (Object): 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. @@ -1804,7 +1856,7 @@ class DefaultExit(DefaultObject): """ self.cmdset.remove_default() - def at_traverse(self, traversing_object, target_location): + def at_traverse(self, traversing_object, target_location, **kwargs): """ This implements the actual traversal. The traverse lock has already been checked (in the Exit command) at this point. @@ -1812,6 +1864,8 @@ class DefaultExit(DefaultObject): Args: traversing_object (Object): Object traversing us. target_location (Object): Where target is going. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ source_location = traversing_object.location @@ -1825,12 +1879,14 @@ class DefaultExit(DefaultObject): # No shorthand error message. Call hook. self.at_failed_traverse(traversing_object) - def at_failed_traverse(self, traversing_object): + def at_failed_traverse(self, traversing_object, **kwargs): """ Overloads the default hook to implement a simple default error message. Args: traversing_object (Object): The object that failed traversing us. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: Using the default exits, this hook will not be called if an diff --git a/evennia/players/players.py b/evennia/players/players.py index 0ea588dfe7..2c67e360f4 100644 --- a/evennia/players/players.py +++ b/evennia/players/players.py @@ -664,7 +664,7 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): """ pass - def at_first_login(self): + def at_first_login(self, **kwargs): """ Called the very first time this player logs into the game. Note that this is called *before* at_pre_login, so no session @@ -672,14 +672,22 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): this point. This hook is intended for player-specific setup like configurations. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass - def at_pre_login(self): + def at_pre_login(self, **kwargs): """ Called every time the user logs in, just before the actual login-state is set. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass @@ -706,13 +714,15 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): else: logger.log_info("[%s]: %s" % (now, message)) - def at_post_login(self, session=None): + def at_post_login(self, session=None, **kwargs): """ Called at the end of the login process, just before letting the player loose. Args: session (Session, optional): Session logging in, if any. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Notes: This is called *before* an eventual Character's @@ -754,7 +764,7 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): self.msg(self.at_look(target=self.db._playable_characters, session=session)) - def at_failed_login(self, session): + def at_failed_login(self, session, **kwargs): """ Called by the login process if a user account is targeted correctly but provided with an invalid password. By default it does nothing, @@ -762,42 +772,60 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): Args: session (session): Session logging in. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ pass - def at_disconnect(self, reason=None): + def at_disconnect(self, reason=None, **kwargs): """ Called just before user is disconnected. Args: reason (str, optional): The reason given for the disconnect, (echoed to the connection channel by default). + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ reason = reason and "(%s)" % reason or "" self._send_to_connect_channel("|R%s disconnected %s|n" % (self.key, reason)) - def at_post_disconnect(self): + def at_post_disconnect(self, **kwargs): """ This is called *after* disconnection is complete. No messages can be relayed to the player from here. After this call, the player should not be accessed any more, making this a good spot for deleting it (in the case of a guest player account, for example). + + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass - def at_message_receive(self, message, from_obj=None): + def at_message_receive(self, message, from_obj=None, **kwargs): """ This is currently unused. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ return True - def at_message_send(self, message, to_object): + def at_message_send(self, message, to_object, **kwargs): """ This is currently unused. + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass @@ -817,7 +845,7 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): """ pass - def at_look(self, target=None, session=None): + def at_look(self, target=None, session=None, **kwargs): """ Called when this object executes a look. It allows to customize just what this means. @@ -826,6 +854,8 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)): target (Object or list, optional): An object or a list objects to inspect. session (Session, optional): The session doing this look. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). Returns: look_string (str): A prepared look string, ready to send @@ -898,13 +928,15 @@ class DefaultGuest(DefaultPlayer): This class is used for guest logins. Unlike Players, Guests and their characters are deleted after disconnection. """ - def at_post_login(self, session=None): + def at_post_login(self, session=None, **kwargs): """ In theory, guests only have one character regardless of which MULTISESSION_MODE we're in. They don't get a choice. Args: session (Session, optional): Session connecting. + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). """ self._send_to_connect_channel("|G%s connected|n" % self.key) @@ -922,9 +954,14 @@ class DefaultGuest(DefaultPlayer): print "deleting Character:", character character.delete() - def at_post_disconnect(self): + def at_post_disconnect(self, **kwargs): """ Once having disconnected, destroy the guest's characters and + + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ super(DefaultGuest, self).at_post_disconnect() characters = self.db._playable_characters diff --git a/evennia/scripts/scripts.py b/evennia/scripts/scripts.py index 6764b2e7a8..4fdef4ef69 100644 --- a/evennia/scripts/scripts.py +++ b/evennia/scripts/scripts.py @@ -115,7 +115,6 @@ class ExtendedLoopingCall(LoopingCall): self.starttime = self.clock.seconds() self() - def next_call_time(self): """ Get the next call time. This also takes the eventual effect @@ -473,11 +472,16 @@ class DefaultScript(ScriptBase): if task: task.force_repeat() - def at_first_save(self): + def at_first_save(self, **kwargs): """ This is called after very first time this object is saved. Generally, you don't need to overload this, but only the hooks called by this method. + + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ self.at_script_creation() @@ -516,10 +520,10 @@ class DefaultScript(ScriptBase): # auto-start script (default) self.start() - def at_script_creation(self): """ Only called once, by the create function. + """ pass @@ -528,28 +532,44 @@ class DefaultScript(ScriptBase): Is called to check if the script is valid to run at this time. Should return a boolean. The method is assumed to collect all needed information from its related self.obj. + """ return not self._is_deleted - def at_start(self): + def at_start(self, **kwargs): """ Called whenever the script is started, which for persistent scripts is at least once every server start. It will also be called when starting again after a pause (such as after a server reload) + + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass - def at_repeat(self): + def at_repeat(self, **kwargs): """ Called repeatedly if this Script is set to repeat regularly. + + Args: + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass - def at_stop(self): + def at_stop(self, **kwargs): """ Called whenever when it's time for this script to stop (either because is_valid returned False or it runs out of iterations) + + Args + **kwargs (dict): Arbitrary, optional arguments for users + overriding the call (unused by default). + """ pass