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

Add **kwargs options to at_* hooks to all typeclasses, for greater flexibility for users. Resolves #1276.

Browse source
This commit is contained in:
Griatch 2017-04-20 20:58:35 +02:00
parent cf77d90c71
commit f9e7b01f57
5 changed files with 228 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

2
evennia/commands/default/tests.py
View file

@ -74,7 +74,7 @@ class CommandTest(EvenniaTest):
cmdobj.parse() cmdobj.parse()
cmdobj.func() cmdobj.func()
cmdobj.at_post_cmd() 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)) 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] 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 # Get the first element of a tuple if msg received a tuple instead of a string

83
evennia/comms/comms.py
View file

@ -100,11 +100,17 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
string = "<None>" string = "<None>"
return string return string
def mute(self, subscriber): def mute(self, subscriber, **kwargs):
""" """
Adds an entity to the list of muted subscribers. Adds an entity to the list of muted subscribers.
A muted subscriber will no longer see channel messages, A muted subscriber will no longer see channel messages,
but may use channel commands. 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 mutelist = self.mutelist
if subscriber not in mutelist: if subscriber not in mutelist:
@ -113,11 +119,16 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
return True return True
return False return False
def unmute(self, subscriber): def unmute(self, subscriber, **kwargs):
""" """
Removes an entity to the list of muted subscribers. Removes an entity to the list of muted subscribers. A muted subscriber will no longer see channel messages,
A muted subscriber will no longer see channel messages,
but may use channel commands. 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 mutelist = self.mutelist
if subscriber in mutelist: if subscriber in mutelist:
@ -126,13 +137,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
return True return True
return False return False
def connect(self, subscriber): def connect(self, subscriber, **kwargs):
""" """
Connect the user to this channel. This checks access. Connect the user to this channel. This checks access.
Args: Args:
subscriber (Player or Object): the entity to subscribe subscriber (Player or Object): the entity to subscribe
to this channel. to this channel.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
success (bool): Whether or not the addition was success (bool): Whether or not the addition was
@ -154,13 +167,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
self.post_join_channel(subscriber) self.post_join_channel(subscriber)
return True return True
def disconnect(self, subscriber): def disconnect(self, subscriber, **kwargs):
""" """
Disconnect entity from this channel. Disconnect entity from this channel.
Args: Args:
subscriber (Player of Object): the subscriber (Player of Object): the
entity to disconnect. entity to disconnect.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
success (bool): Whether or not the removal was success (bool): Whether or not the removal was
@ -179,7 +194,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
self.post_leave_channel(subscriber) self.post_leave_channel(subscriber)
return True 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. 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 default (bool, optional): What to return if no lock of access_type was found
no_superuser_bypass (bool, optional): Turns off superuser no_superuser_bypass (bool, optional): Turns off superuser
lock bypass. Be careful with this one. lock bypass. Be careful with this one.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
return (bool): Result of lock check. return (bool): Result of lock check.
@ -209,7 +226,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
CHANNELHANDLER.update() CHANNELHANDLER.update()
def message_transform(self, msgobj, emit=False, prefix=True, 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. 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`. 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. sender_strings (list, optional): Used by bots etc, one string per external sender.
external (bool, optional): If this is an external sender or not. 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: if sender_strings or external:
@ -231,7 +250,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
msgobj.message = body msgobj.message = body
return msgobj 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 Method for grabbing all listeners that a message should be
sent to on this channel, and sending them a message. 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. msgobj (Msg or TempMsg): Message to distribute.
online (bool): Only send to receivers who are actually online online (bool): Only send to receivers who are actually online
(not currently used): (not currently used):
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
This is also where logging happens, if enabled. This is also where logging happens, if enabled.
@ -332,7 +353,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
# hooks # 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. 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 msg (str, optional): Prefix text
emit (bool, optional): Switches to emit mode, which usually emit (bool, optional): Switches to emit mode, which usually
means to not prefix the channel's info. means to not prefix the channel's info.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
prefix (str): The created channel prefix. prefix (str): The created channel prefix.
@ -348,12 +371,14 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
""" """
return '' if emit else '[%s] ' % self.key 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. Hook method. Function used to format a list of sender names.
Args: Args:
senders (list): Sender object names. senders (list): Sender object names.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
formatted_list (str): The list of names formatted appropriately. formatted_list (str): The list of names formatted appropriately.
@ -368,7 +393,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
return '' return ''
return ', '.join(senders) 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 Hook method. Detects if the sender is posing, and modifies the
message accordingly. message accordingly.
@ -376,6 +401,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
Args: Args:
msgobj (Msg or TempMsg): The message to analyze for a pose. msgobj (Msg or TempMsg): The message to analyze for a pose.
sender_string (str): The name of the sender/poser. sender_string (str): The name of the sender/poser.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
string (str): A message that combines the `sender_string` string (str): A message that combines the `sender_string`
@ -398,7 +425,7 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
else: else:
return '%s: %s' % (sender_string, message) 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 Hook method. Used for formatting external messages. This is
needed as a separate operation because the senders of external 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. msgobj (Msg or TempMsg): The message to send.
senders (list): Strings, one per sender. senders (list): Strings, one per sender.
emit (bool, optional): A sender-agnostic message or not. emit (bool, optional): A sender-agnostic message or not.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
transformed (str): A formatted string. transformed (str): A formatted string.
@ -419,13 +448,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
senders = ', '.join(senders) senders = ', '.join(senders)
return self.pose_transform(msgobj, 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. Hook method. Formats a message body for display.
Args: Args:
msgobj (Msg or TempMsg): The message object to send. msgobj (Msg or TempMsg): The message object to send.
emit (bool, optional): The message is agnostic of senders. emit (bool, optional): The message is agnostic of senders.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
transformed (str): The formatted message. transformed (str): The formatted message.
@ -443,13 +474,15 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
senders = ', '.join(senders) senders = ', '.join(senders)
return self.pose_transform(msgobj, 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 Hook method. Runs right before a channel is joined. If this
returns a false value, channel joining is aborted. returns a false value, channel joining is aborted.
Args: Args:
joiner (object): The joining object. joiner (object): The joining object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
should_join (bool): If `False`, channel joining is aborted. should_join (bool): If `False`, channel joining is aborted.
@ -457,23 +490,27 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
""" """
return True 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. Hook method. Runs right after an object or player joins a channel.
Args: Args:
joiner (object): The joining object. joiner (object): The joining object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass 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 Hook method. Runs right before a user leaves a channel. If this returns a false
value, leaving the channel will be aborted. value, leaving the channel will be aborted.
Args: Args:
leaver (object): The leaving object. leaver (object): The leaving object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
should_leave (bool): If `False`, channel parting is aborted. should_leave (bool): If `False`, channel parting is aborted.
@ -481,17 +518,19 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
""" """
return True 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. Hook method. Runs right after an object or player leaves a channel.
Args: Args:
leaver (object): The leaving object. leaver (object): The leaving object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass 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 Hook method. Runs before a message is sent to the channel and
should return the message object, after any transformations. should return the message object, after any transformations.
@ -499,6 +538,8 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
Args: Args:
msg (Msg or TempMsg): Message to send. msg (Msg or TempMsg): Message to send.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
result (Msg, TempMsg or bool): If False, abort send. result (Msg, TempMsg or bool): If False, abort send.
@ -506,12 +547,14 @@ class DefaultChannel(with_metaclass(TypeclassBase, ChannelDB)):
""" """
return msg 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. Hook method. Run after a message is sent to the channel.
Args: Args:
msg (Msg or TempMsg): Message sent. msg (Msg or TempMsg): Message sent.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass

124
evennia/objects/objects.py
View file

@ -1048,7 +1048,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
""" """
pass 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 Called just before a Player connects to this object to puppet
it. it.
@ -1056,14 +1056,20 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
player (Player): This is the connecting player. player (Player): This is the connecting player.
session (Session): Session controlling the connection. session (Session): Session controlling the connection.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
def at_post_puppet(self): def at_post_puppet(self, **kwargs):
""" """
Called just after puppeting has been completed and all Called just after puppeting has been completed and all
Player<->Object links have been established. Player<->Object links have been established.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Note: Note:
You can use `self.player` and `self.sessions.get()` to get You can use `self.player` and `self.sessions.get()` to get
player and sessions at this point; the last entry in the 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 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 Called just before beginning to un-connect a puppeting from
this Player. this Player.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Note: Note:
You can use `self.player` and `self.sessions.get()` to get You can use `self.player` and `self.sessions.get()` to get
player and sessions at this point; the last entry in the player and sessions at this point; the last entry in the
@ -1087,7 +1096,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
""" """
pass 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 Called just after the Player successfully disconnected from
this object, severing all connections. this object, severing all connections.
@ -1097,6 +1106,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
from this object. from this object.
session (Session): Session id controlling the connection that session (Session): Session id controlling the connection that
just disconnected. just disconnected.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
@ -1140,13 +1151,15 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
# hooks called when moving the object # 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 Called just before starting to move this object to
destination. destination.
Args: Args:
destination (Object): The object we are moving to destination (Object): The object we are moving to
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
shouldmove (bool): If we should move or not. 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 has_perm(self, destination, "can_move")
return True 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 if the move is to be announced. This is
called while we are still standing in the old 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. destination (Object): The place we are going to.
msg (str, optional): a replacement message. msg (str, optional): a replacement message.
mapping (dict, optional): additional mapping objects. 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 You can override this method and call its parent with a
message to simply change the default message. In the string, 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) 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 Called after the move if the move was not quiet. At this point
we are standing in the new location. 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 source_location (Object): The place we came from
msg (str, optional): the replacement message if location. msg (str, optional): the replacement message if location.
mapping (dict, optional): additional mapping objects. 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 Notes:
message to simply change the default message. In the string, You can override this method and call its parent with a
you can use the following as mappings (between braces): message to simply change the default message. In the string,
object: the object which is moving. you can use the following as mappings (between braces):
exit: the exit from which the object is moving (if found). object: the object which is moving.
origin: the location of the object before the move. exit: the exit from which the object is moving (if found).
destination: the location of the object after moving. 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) 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 Called after move has completed, regardless of quiet mode or
not. Allows changes to the object due to the location it is not. Allows changes to the object due to the location it is
@ -1261,22 +1279,26 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
source_location (Object): Wwhere we came from. This may be `None`. 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 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 Called just before an object leaves from inside this object
Args: Args:
moved_obj (Object): The object leaving moved_obj (Object): The object leaving
target_location (Object): Where `moved_obj` is going. target_location (Object): Where `moved_obj` is going.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass 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. 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 moved_obj (Object): The object moved into this one
source_location (Object): Where `moved_object` came from. source_location (Object): Where `moved_object` came from.
Note that this could be `None`. Note that this could be `None`.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass 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, This hook is responsible for handling the actual traversal,
normally by calling normally by calling
@ -1301,11 +1325,13 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
traversing_object (Object): Object traversing us. traversing_object (Object): Object traversing us.
target_location (Object): Where target is going. target_location (Object): Where target is going.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass 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 Called just after an object successfully used this object to
traverse to another object (i.e. this object is a type of traverse to another object (i.e. this object is a type of
@ -1314,19 +1340,23 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
traversing_object (Object): The object traversing us. traversing_object (Object): The object traversing us.
source_location (Object): Where `traversing_object` came from. source_location (Object): Where `traversing_object` came from.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
The target location should normally be available as `self.destination`. The target location should normally be available as `self.destination`.
""" """
pass 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 This is called if an object fails to traverse this object for
some reason. some reason.
Args: Args:
traversing_object (Object): The object that failed traversing us. traversing_object (Object): The object that failed traversing us.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
Using the default exits, this hook will not be called if an 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. # 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 This formats a description. It is the hook a 'look' command
should call. should call.
Args: Args:
looker (Object): Object doing the looking. looker (Object): Object doing the looking.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
if not looker: if not looker:
return "" return ""
@ -1420,7 +1452,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
string += "\n|wYou see:|n " + ", ".join(users + things) string += "\n|wYou see:|n " + ", ".join(users + things)
return string return string
def at_look(self, target): def at_look(self, target, **kwargs):
""" """
Called when this object performs a look. It allows to Called when this object performs a look. It allows to
customize just what this means. It will not itself 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 target (Object): The target being looked at. This is
commonly an object or the current location. It will commonly an object or the current location. It will
be checked for the "view" type access. be checked for the "view" type access.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
lookstring (str): A ready-processed look string lookstring (str): A ready-processed look string
@ -1450,22 +1484,27 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
return description return description
def at_desc(self, looker=None): def at_desc(self, looker=None, **kwargs):
""" """
This is called whenever someone looks at this object. 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 pass
def at_get(self, getter): def at_get(self, getter, **kwargs):
""" """
Called by the default `get` command when this object has been Called by the default `get` command when this object has been
picked up. picked up.
Args: Args:
getter (Object): The object getting this object. getter (Object): The object getting this object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
This hook cannot stop the pickup from happening. Use This hook cannot stop the pickup from happening. Use
@ -1474,7 +1513,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
""" """
pass 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 Called by the default `give` command when this object has been
given. given.
@ -1482,6 +1521,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
giver (Object): The object giving this object. giver (Object): The object giving this object.
getter (Object): The object getting this object. getter (Object): The object getting this object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
This hook cannot stop the give from happening. Use This hook cannot stop the give from happening. Use
@ -1490,13 +1531,15 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
""" """
pass pass
def at_drop(self, dropper): def at_drop(self, dropper, **kwargs):
""" """
Called by the default `drop` command when this object has been Called by the default `drop` command when this object has been
dropped. dropped.
Args: Args:
dropper (Object): The object which just dropped this object. dropper (Object): The object which just dropped this object.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
This hook cannot stop the drop from happening. Use This hook cannot stop the drop from happening. Use
@ -1505,7 +1548,7 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
""" """
pass 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. Called on this object if an object inside this object speaks.
The string returned from this method is the final form of the The string returned from this method is the final form of the
@ -1514,6 +1557,8 @@ class DefaultObject(with_metaclass(TypeclassBase, ObjectDB)):
Args: Args:
speaker (Object): The object speaking. speaker (Object): The object speaking.
message (str): The words spoken. message (str): The words spoken.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
You should not need to add things like 'you say: ' or You should not need to add things like 'you say: ' or
@ -1551,7 +1596,7 @@ class DefaultCharacter(DefaultObject):
# add the default cmdset # add the default cmdset
self.cmdset.add_default(settings.CMDSET_CHARACTER, permanent=True) 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. We make sure to look around after a move.
@ -1559,7 +1604,7 @@ class DefaultCharacter(DefaultObject):
if self.location.access(self, "view"): if self.location.access(self, "view"):
self.msg(self.at_look(self.location)) 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`. Return the character from storage in None location in `at_post_unpuppet`.
Args: Args:
@ -1575,11 +1620,14 @@ class DefaultCharacter(DefaultObject):
else: else:
player.msg("|r%s has no location and no home is set.|n" % self, session=session) # Note to set home. 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 Called just after puppeting has been completed and all
Player<->Object links have been established. Player<->Object links have been established.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Note: Note:
You can use `self.player` and `self.sessions.get()` to get You can use `self.player` and `self.sessions.get()` to get
player and sessions at this point; the last entry in the 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) 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) 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, We stove away the character when the player goes ooc/logs off,
otherwise the character object will remain in the room also otherwise the character object will remain in the room also
@ -1605,6 +1653,8 @@ class DefaultCharacter(DefaultObject):
from this object. from this object.
session (Session): Session controlling the connection that session (Session): Session controlling the connection that
just disconnected. just disconnected.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
if not self.sessions.count(): if not self.sessions.count():
# only remove this char from grid if no sessions control it anymore. # only remove this char from grid if no sessions control it anymore.
@ -1694,6 +1744,8 @@ class ExitCommand(command.Command):
Args: Args:
caller (Object): The object (usually a character) that entered an ambiguous command. 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: Returns:
A string with identifying information to disambiguate the command, conventionally with a preceding space. 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() 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 This implements the actual traversal. The traverse lock has
already been checked (in the Exit command) at this point. already been checked (in the Exit command) at this point.
@ -1812,6 +1864,8 @@ class DefaultExit(DefaultObject):
Args: Args:
traversing_object (Object): Object traversing us. traversing_object (Object): Object traversing us.
target_location (Object): Where target is going. 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 source_location = traversing_object.location
@ -1825,12 +1879,14 @@ class DefaultExit(DefaultObject):
# No shorthand error message. Call hook. # No shorthand error message. Call hook.
self.at_failed_traverse(traversing_object) 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. Overloads the default hook to implement a simple default error message.
Args: Args:
traversing_object (Object): The object that failed traversing us. traversing_object (Object): The object that failed traversing us.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
Using the default exits, this hook will not be called if an Using the default exits, this hook will not be called if an

59
evennia/players/players.py
View file

@ -664,7 +664,7 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)):
""" """
pass pass
def at_first_login(self): def at_first_login(self, **kwargs):
""" """
Called the very first time this player logs into the game. Called the very first time this player logs into the game.
Note that this is called *before* at_pre_login, so no session 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 this point. This hook is intended for player-specific setup
like configurations. like configurations.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
def at_pre_login(self): def at_pre_login(self, **kwargs):
""" """
Called every time the user logs in, just before the actual Called every time the user logs in, just before the actual
login-state is set. login-state is set.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
@ -706,13 +714,15 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)):
else: else:
logger.log_info("[%s]: %s" % (now, message)) 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 Called at the end of the login process, just before letting
the player loose. the player loose.
Args: Args:
session (Session, optional): Session logging in, if any. session (Session, optional): Session logging in, if any.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Notes: Notes:
This is called *before* an eventual Character's 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, self.msg(self.at_look(target=self.db._playable_characters,
session=session)) 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 Called by the login process if a user account is targeted correctly
but provided with an invalid password. By default it does nothing, but provided with an invalid password. By default it does nothing,
@ -762,42 +772,60 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)):
Args: Args:
session (session): Session logging in. session (session): Session logging in.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
def at_disconnect(self, reason=None): def at_disconnect(self, reason=None, **kwargs):
""" """
Called just before user is disconnected. Called just before user is disconnected.
Args: Args:
reason (str, optional): The reason given for the disconnect, reason (str, optional): The reason given for the disconnect,
(echoed to the connection channel by default). (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 "" reason = reason and "(%s)" % reason or ""
self._send_to_connect_channel("|R%s disconnected %s|n" % (self.key, reason)) 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 This is called *after* disconnection is complete. No messages
can be relayed to the player from here. After this call, the can be relayed to the player from here. After this call, the
player should not be accessed any more, making this a good player should not be accessed any more, making this a good
spot for deleting it (in the case of a guest player account, spot for deleting it (in the case of a guest player account,
for example). for example).
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
def at_message_receive(self, message, from_obj=None): def at_message_receive(self, message, from_obj=None, **kwargs):
""" """
This is currently unused. This is currently unused.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
return True return True
def at_message_send(self, message, to_object): def at_message_send(self, message, to_object, **kwargs):
""" """
This is currently unused. This is currently unused.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
@ -817,7 +845,7 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)):
""" """
pass 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 Called when this object executes a look. It allows to customize
just what this means. just what this means.
@ -826,6 +854,8 @@ class DefaultPlayer(with_metaclass(TypeclassBase, PlayerDB)):
target (Object or list, optional): An object or a list target (Object or list, optional): An object or a list
objects to inspect. objects to inspect.
session (Session, optional): The session doing this look. session (Session, optional): The session doing this look.
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
Returns: Returns:
look_string (str): A prepared look string, ready to send 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 This class is used for guest logins. Unlike Players, Guests and
their characters are deleted after disconnection. 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 In theory, guests only have one character regardless of which
MULTISESSION_MODE we're in. They don't get a choice. MULTISESSION_MODE we're in. They don't get a choice.
Args: Args:
session (Session, optional): Session connecting. 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) self._send_to_connect_channel("|G%s connected|n" % self.key)
@ -922,9 +954,14 @@ class DefaultGuest(DefaultPlayer):
print "deleting Character:", character print "deleting Character:", character
character.delete() character.delete()
def at_post_disconnect(self): def at_post_disconnect(self, **kwargs):
""" """
Once having disconnected, destroy the guest's characters and 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() super(DefaultGuest, self).at_post_disconnect()
characters = self.db._playable_characters characters = self.db._playable_characters

32
evennia/scripts/scripts.py
View file

@ -115,7 +115,6 @@ class ExtendedLoopingCall(LoopingCall):
self.starttime = self.clock.seconds() self.starttime = self.clock.seconds()
self() self()
def next_call_time(self): def next_call_time(self):
""" """
Get the next call time. This also takes the eventual effect Get the next call time. This also takes the eventual effect
@ -473,11 +472,16 @@ class DefaultScript(ScriptBase):
if task: if task:
task.force_repeat() 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. This is called after very first time this object is saved.
Generally, you don't need to overload this, but only the hooks Generally, you don't need to overload this, but only the hooks
called by this method. called by this method.
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
self.at_script_creation() self.at_script_creation()
@ -516,10 +520,10 @@ class DefaultScript(ScriptBase):
# auto-start script (default) # auto-start script (default)
self.start() self.start()
def at_script_creation(self): def at_script_creation(self):
""" """
Only called once, by the create function. Only called once, by the create function.
""" """
pass pass
@ -528,28 +532,44 @@ class DefaultScript(ScriptBase):
Is called to check if the script is valid to run at this time. 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 Should return a boolean. The method is assumed to collect all
needed information from its related self.obj. needed information from its related self.obj.
""" """
return not self._is_deleted return not self._is_deleted
def at_start(self): def at_start(self, **kwargs):
""" """
Called whenever the script is started, which for persistent Called whenever the script is started, which for persistent
scripts is at least once every server start. It will also be scripts is at least once every server start. It will also be
called when starting again after a pause (such as after a called when starting again after a pause (such as after a
server reload) server reload)
Args:
**kwargs (dict): Arbitrary, optional arguments for users
overriding the call (unused by default).
""" """
pass pass
def at_repeat(self): def at_repeat(self, **kwargs):
""" """
Called repeatedly if this Script is set to repeat regularly. 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 pass
def at_stop(self): def at_stop(self, **kwargs):
""" """
Called whenever when it's time for this script to stop (either Called whenever when it's time for this script to stop (either
because is_valid returned False or it runs out of iterations) 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 pass