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)

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:

• + creates a Sequence of actions; one is run after the other.
• | creates a Parallel construct: all actions are started at once.

The chain() method and operators can be used with Actions, or regular callables (which are wrapped in FunctionCaller), or with numbers (which create corresponding delays), or with iterables (which get wrapped in Process), or with None (which coerces into a no-op Action).

chain(action, dt=0)

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__()

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, and trigger_chain() when they’re done.

Methods useful for subclasses:

expire()

Marks the Action as run.

Subclasses must call this method at the start of __call__().

trigger_chain()

Schedule the chained actions.

Subclasses must call this method after the Action runs; see __call__().

classmethod coerce(value)

Coerce value into an action.

Wraps functions in FunctionCallers, numbers in Delays, and None in a no-op.

Building blocks for complex actions

class gillcup.actions.FunctionCaller(function, *args, **kwargs)

An Action that calls given function, passing args and kwargs to it

function can be any callable.

class gillcup.actions.Delay(time, **kwargs)

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)

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)

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)

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.

gillcup.actions.process_generator(func)

Decorator for creating Processes

Used as a decorator on a generator function, it allows writing in a declarative style instead of callbacks, with yield statements for “asynchronousness”.