From deb6194aaaff89a81728e751fd690eb03d910b72 Mon Sep 17 00:00:00 2001 From: davewiththenicehat <54369722+davewiththenicehat@users.noreply.github.com> Date: Mon, 10 May 2021 12:38:47 -0400 Subject: [PATCH 1/2] delay docstring update delay docstring update The old one had not been properly updated or formatted. --- evennia/utils/utils.py | 48 +++++++++++++++++------------------------- 1 file changed, 19 insertions(+), 29 deletions(-) diff --git a/evennia/utils/utils.py b/evennia/utils/utils.py index 4d0d3a6c42..88ad8002c5 100644 --- a/evennia/utils/utils.py +++ b/evennia/utils/utils.py @@ -1021,44 +1021,34 @@ _TASK_HANDLER = None def delay(timedelay, callback, *args, **kwargs): - """ - Delay the calling of a callback (function). + """Delay the calling of a callback (function). + + The task handler (`evennia.scripts.taskhandler.TaskHandler`) will + be called for persistent or non-persistent tasks. + + If persistent is set to True. + The callback, its arguments and other keyword arguments will be saved + (serialized) in the database, assuming they can be. The callback will + be executed even after a server restart/reload, taking into account the + specified delay (and server down time). + Keep in mind that persistent tasks arguments and callback should not + use memory references. + All task's whose time delays have passed will be called on server startup. Args: timedelay (int or float): The delay in seconds callback (callable): Will be called as `callback(*args, **kwargs)` after `timedelay` seconds. args (any, optional): Will be used as arguments to callback + Keyword Args: - persistent (bool, optional): Should make the delay persistent - over a reboot or reload. Defaults to False. - any (any): Will be used as keyword arguments to callback. + persistent (bool, optional): should make the delay persistent + over a reboot or reload + any (any, optional): Will be used as keyword arguments to callback. Returns: - deferred or int: If ``persistent`` kwarg is `False`, return deferred - that will fire with callback after `timedelay` seconds. Note that - if `timedelay()` is used in the commandhandler callback chain, the - callback chain can be defined directly in the command body and - don't need to be specified here. Reference twisted.internet.defer.Deferred. - If persistent kwarg is set, return the task's ID as an integer. This is - intended for use with ``evennia.scripts.taskhandler.TASK_HANDLER`` - `.do_task` and `.remove` methods. - - Note: - The task handler (`evennia.scripts.taskhandler.TASK_HANDLER`) will - be called for persistent or non-persistent tasks. - If persistent is set to True, the callback, its arguments - and other keyword arguments will be saved (serialized) in the database, - assuming they can be. The callback will be executed even after - a server restart/reload, taking into account the specified delay - (and server down time). - Keep in mind that persistent tasks arguments and callback should not - use memory references. - If persistent is set to True the delay function will return an int - which is the task's id itended for use with TASK_HANDLER's do_task - and remove methods. - - All task's whose time delays have passed will be called on server startup. + task (TaskHandlerTask): A task instance. + Reference: evennia.scripts.taskhandler.TaskHandlerTask """ global _TASK_HANDLER From 1cc1731d54f6ce0277a1e2d74a3db6e54d321ce1 Mon Sep 17 00:00:00 2001 From: davewiththenicehat <54369722+davewiththenicehat@users.noreply.github.com> Date: Tue, 11 May 2021 16:46:19 -0400 Subject: [PATCH 2/2] utils.delay docstring update Updated docstring to show delay returns a TaskHandlerTask instance. --- evennia/utils/utils.py | 44 +++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/evennia/utils/utils.py b/evennia/utils/utils.py index 88ad8002c5..4aadc02768 100644 --- a/evennia/utils/utils.py +++ b/evennia/utils/utils.py @@ -1021,34 +1021,38 @@ _TASK_HANDLER = None def delay(timedelay, callback, *args, **kwargs): - """Delay the calling of a callback (function). - - The task handler (`evennia.scripts.taskhandler.TaskHandler`) will - be called for persistent or non-persistent tasks. - - If persistent is set to True. - The callback, its arguments and other keyword arguments will be saved - (serialized) in the database, assuming they can be. The callback will - be executed even after a server restart/reload, taking into account the - specified delay (and server down time). - Keep in mind that persistent tasks arguments and callback should not - use memory references. - All task's whose time delays have passed will be called on server startup. + """ + Delay the calling of a callback (function). Args: - timedelay (int or float): The delay in seconds + timedelay (int or float): The delay in seconds. callback (callable): Will be called as `callback(*args, **kwargs)` after `timedelay` seconds. - args (any, optional): Will be used as arguments to callback + args (any): Will be used as arguments to callback. Keyword Args: - persistent (bool, optional): should make the delay persistent - over a reboot or reload - any (any, optional): Will be used as keyword arguments to callback. + persistent (bool, optional): If True the delay remains after a server restart. + persistent is False by default. + any (any): Will be used as keyword arguments to callback. Returns: - task (TaskHandlerTask): A task instance. - Reference: evennia.scripts.taskhandler.TaskHandlerTask + task (TaskHandlerTask): An instance of a task. + Refer to, evennia.scripts.taskhandler.TaskHandlerTask + + Note: + The task handler (`evennia.scripts.taskhandler.TASK_HANDLER`) will + be called for persistent or non-persistent tasks. + If persistent is set to True, the callback, its arguments + and other keyword arguments will be saved (serialized) in the database, + assuming they can be. The callback will be executed even after + a server restart/reload, taking into account the specified delay + (and server down time). + Keep in mind that persistent tasks arguments and callback should not + use memory references. + If persistent is set to True the delay function will return an int + which is the task's id itended for use with TASK_HANDLER's do_task + and remove methods. + All persistent tasks whose time delays have passed will be called on server startup. """ global _TASK_HANDLER