gillcup.actions¶
Gillcup Actions
Although arbitrary callables can be scheduled on a Gillcup
Clock
, one frequently schedules objects that are specifically
made for this purpose.
Using gillcup.Action
allows one to chain actions together in various
ways, allowing the developer to create complex effects.
-
class
gillcup.
Action
(clock=None, dt=0)[source]¶ A chainable “event” designed for being scheduled.
As any callable, an Action can be scheduled on a clock, either by
schedule()
, or by chaining, or, as a shortcut, directly from the constructor with the clock and dt arguments. Each Action may only be scheduled once.Other actions may be chained to an Action, that is, scheduled to run at some time after the Action is run.
Some Actions may represent a time interval or process rather than a discrete point in time. In these cases, chained actions are run after the interval is over or the process finishes.
Actions may be combined to form larger structures using helper Action subclasses as building blocks. As a shorthand, the following operators are available:
The
chain()
method and operators can be used with Actions, or regular callables (which are wrapped inFunctionCaller
), or with numbers (which create correspondingdelays
), or with iterables (which get wrapped inProcess
), or with None (which coerces into a no-op Action).-
chain
(action, dt=0)[source]¶ Schedule an action to be scheduled after this Action
The
action
argument may be a callable, number, or None, and is wrapped by an Action if necessary. See__init__
for more details.The
dt
argument can be given to delay the chained action by the specified time.If this Action has already been called, the chained action is scheduled immediately dt units after the current time. To prevent or modify this behavior, the caller can check the
chain_triggered
attribute.Returns the chained action.
-
gillcup.Action.
chain_triggered
¶ Set to true when this Action is finished, i.e. its chained actions have been triggered.
Overridable methods:
-
__call__
()[source]¶ Run this action.
Subclasses that represent discrete moments in time should call the superclass implementation when they are finished running.
Subclasses that represent time intervals (there’s a delay between the moment they are called and when they trigger chained actions) should call
expire()
when they are called, andtrigger_chain()
when they’re done.
Methods useful for subclasses:
-
expire
()[source]¶ Marks the Action as run.
Subclasses must call this method at the start of
__call__()
.
-
trigger_chain
()[source]¶ Schedule the chained actions.
Subclasses must call this method after the Action runs; see
__call__()
.
-
Building blocks for complex actions¶
-
class
gillcup.actions.
FunctionCaller
(function, *args, **kwargs)[source]¶ An Action that calls given function, passing args and kwargs to it
function can be any callable.
-
class
gillcup.actions.
Delay
(time, **kwargs)[source]¶ An Action that triggers chained actions after a given delay
The kwargs are passed to
gillcup.Action
‘s initializer.
-
class
gillcup.actions.
Sequence
(*actions, **kwargs)[source]¶ An Action that runs a series of Actions one after the other
Actions chained to a Sequence are triggered after the last Action in the sequence.
The kwargs are passed to
gillcup.Action
‘s initializer.
-
class
gillcup.actions.
Parallel
(*actions, **kwargs)[source]¶ Starts the given Actions, and triggers chained ones after all are done
That is, after all the given actions have triggered their chained actions, Parallel triggers its own chained actions.
The kwargs are passed to
gillcup.Action
‘s initializer.
-
class
gillcup.actions.
Process
(iterable, **kwargs)[source]¶ Wraps the given iterable
When triggered, takes an item from the iterable and schedules it, then chains the scheduling of the next item, and so on. When the underlying iterator is exhausted, chained actions are run.
The items in the underlying iterable can be callables, numbers or other iterables, as for
Action
‘s+
and|
operators.The kwargs are passed to
gillcup.Action
‘s initializer.See
process_generator()
for a simple way to create Processes.