| | |
- Agent
- Handler
class Agent |
| |
Agent: base class for Boodler agents.
Methods and fields to be overridden:
init() -- set the agent up
run() -- perform the agent's action
receive() -- perform the agent's action
Publicly readable fields:
channel -- the channel in which this agent is running
firsttime -- True the first time the run() method is called
Methods which can be called from a run() method:
sched_note() -- schedule a note to be played
sched_note_duration() -- schedule a note to be played for an extended time
sched_note_pan() -- schedule a note to be played at a stereo position
sched_note_duration_pan() -- schedule a note, extended and stereo
sched_note_params() -- schedule a note, allowing all parameters
sched_agent() -- schedule another agent to run
resched() -- schedule self to run again
new_channel() -- create a channel
new_channel_pan() -- create a channel at a stereo position
listen() -- begin listening for events
unlisten() -- stop listening
get_root_channel() -- return the root channel of the channel tree
post_listener_agent() -- post another agent to listen for events
send_event() -- create an event, which posted agents may receive
get_prop() -- get a property from the agent's channel
has_prop() -- see whether the agent's channel has a given property
set_prop() -- set a property on the agent's channel
del_prop() -- delete a property from the agent's channel
load_described() -- load a named module or agent
Class methods:
get_title() -- return a string which describes the agent
get_argument_list() -- return the argument specification for the agent
get_class_name() -- return the qualified names of the module and Agent
|
| |
Methods defined here:
- __init__(self, *args, **kwargs)
- del_prop(self, key)
- del_prop(key) -> None
Delete a property from the agent's channel. If none is set, this
has no effect.
Note that this does not affect parent channels. So get_prop(key)
may still return a value after del_prop(key).
- get_prop(self, key, default=None)
- get_prop(key, default=None) -> any
Get a property from the agent's channel. If none is set, see if
one is inherited from the parent. If there is no inherited value
either, return None, or the given default.
Note that None is a legal property value. To distinguish between
no property and a property set to None, use has_prop().
- get_root_channel(self)
- get_root_channel() -> channel
Return the root channel of the channel tree.
- has_prop(self, key)
- has_prop(key) -> bool
See whether the agent's channel has a given property. If none is
set, see if one is inherited from the parent.
- init(self)
- init(...)
Set the agent up. The arguments are passed along from the
constructor call. Each subclass of Agent may override
this method; if it wants to accept constructor arguments, it
must override this.
- listen(self, event=None, handle=None, hold=None, chan=None)
- listen(event=self.selected_event, handle=self.receive, hold=None,
chan=self.channel) -> Handler
Begin listening for events. The event should be a string, or a
function which returns a string. (If no event is given, the
agent.selected_event field will be consulted.) The agent will
listen on the given channel, or (if none is given) on the
agent's own channel.
The agent will react whenever a matching event is seen on the
channel. An event matches if it is equal to the selected event
string, or begins with it; and if it is in the listening channel,
or a subchannel of it. (So event "foo.bar" will trigger agents
listening for event "foo.bar", "foo", or "".)
When an agent is triggered, its receive() method is run. (If you
pass a different function as handle, that function will be run.)
The hold value indicates whether the agent's channel will be kept
alive for as long as it listens. If this is False/None, the channel
will follow the usual rule and expire as soon as nothing is scheduled
on it. (A listening agent does not automatically count as scheduled!)
If the listening channel is not the same as the agent's own channel,
you may pass one of the constants HoldRun or HoldListen, to keep
just one of them alive. A True value will keep both.
The listen() method returns a Handler object. You may store this
for later use; it has a cancel() method which may be used to stop
listening.
- load_described(self, val, wantmodule=False)
- load_described(val, wantmodule=False) -> Agent or module
Load a named agent or module. The argument should be a string (or
list of strings, or sparse Tree) giving a fully qualified name:
package.name/AgentName
package.name:version.needed/AgentName
package.name::exact.version.number/AgentName
To load an agent with arguments, just append the arguments.
package.name/AgentName 0.5 2
Just as on the command line, arguments referring to more agents
go in parentheses:
package.name/AgentName (package.name/AnotherAgent 2)
To get an entire module, pass wantmodule=True. (And leave off the
"/AgentName" part, and don't use any arguments.)
This method is not intended for module creation time (loading one
module which another depends on). It bypasses Boodler's dependency
tracking. Use this method when your agent is using a user-specified
value to find an arbitrary Boodler entity.
- new_channel(self, startvolume=1.0, parent=None)
- new_channel(startvolume=1, parent=self.channel) -> channel
Create a new channel. The startvolume is the volume the channel
is initially set to; this will affect all sounds played in the
channel and any subchannels. The new channel will be a subchannel
of parent -- if None or not supplied, it will be a subchannel of
the channel that the agent (self) is running in.
- new_channel_pan(self, pan=None, startvolume=1.0, parent=None)
- new_channel_pan(pan=0, startvolume=1, parent=self.channel) -> channel
Create a new channel, panning the stereo origin of its sounds.
(See the stereo module.) The startvolume is the volume the channel
is initially set to; this will affect all sounds played in the
channel and any subchannels. The new channel will be a subchannel
of parent -- if None or not supplied, it will be a subchannel of
the channel that the agent (self) is running in.
- post_listener_agent(self, ag, chan=None, event=None, handle=None, hold=None, listenchan=None)
- post_listener_agent(agent, chan=self.channel,
event=ag.selected_event, handle=ag.receive, hold=None,
listenchan=chan)
Post an agent to listen for events. This is equivalent to
sched_agent(ag, handle=ag.listen(...))
That is, the agent must not currently be scheduled. It runs
immediately, but only to call its listen() method, with any
arguments you pass in.
- receive(self, event)
- receive(event)
Perform the agent's action when an appropriate event arrives.
Each subclass of Agent which listens for events must override this
method (or provide an alternative handler).
The event is a tuple, starting with a string, followed (possibly)
by more values.
- resched(self, delay=None, chan=None, handle=None)
- resched(delay=None, chan=self.channel, handle=self.run)
Reschedule the current agent (self). The delay is a time (in
seconds) to delay before the agent runs again. The channel, if
None or not supplied, defaults to the same channel that self is
running in.
If delay is not supplied, it defaults to the delay used when this
agent was first scheduled. Note that if this value was zero,
you will probably cause an infinite loop.
The agent's run() method will be called, unless you specify a
handle different function.
- run(self)
- run()
Perform the agent's action. Each subclass of Agent must override
this method.
- sched_agent(self, ag, delay=0, chan=None, handle=None)
- sched_agent(agent, delay=0, chan=self.channel, handle=self.run)
Schedule an agent to run. This may be the current agent (self) or
a newly-created agent. The delay is a time (in seconds) to delay
before the agent runs. The channel, if None or not supplied,
defaults to the same channel that self is running in. The agent's
run() method will be called, unless you specify a different
handle function.
- sched_note(self, samp, pitch=1.0, volume=1.0, delay=0, chan=None)
- sched_note(sample, pitch=1, volume=1, delay=0, chan=self.channel)
-> duration
Schedule a note to play. The sound is loaded from samp (which can
be a filename, File, or Sample object). The pitch is given as a
multiple of the sound's original frequency; the volume is given
as a fraction of the sound's original volume. The delay is a time
(in seconds) to delay before the note is played. The channel,
if None or not supplied, defaults to the same channel the agent is
running in.
This returns the expected duration of the sound, in seconds.
- sched_note_duration(self, samp, duration, pitch=1.0, volume=1.0, delay=0, chan=None)
- sched_note_duration(sample, duration, pitch=1, volume=1, delay=0,
chan=self.channel) -> duration
Schedule a note to play, extending the original sound sample to a
longer period of time. The duration is given in seconds.
The sound is loaded from samp (which can be a filename,
File, or Sample object). The pitch is given as a multiple of the
sound's original frequency; the volume is given as a fraction
of the sound's original volume. The delay is a time (in seconds)
to delay before the note is played. The channel, if None or not
supplied, defaults to the same channel the agent is running in.
This returns the expected duration of the sound, in seconds. Due to
the way sounds are looped, this may be slightly longer than the
given duration.
- sched_note_duration_pan(self, samp, duration, pan=None, pitch=1.0, volume=1.0, delay=0, chan=None)
- sched_note_duration_pan(sample, duration, pan=0, pitch=1, volume=1,
delay=0, chan=self.channel) -> duration
Schedule a note to play, panning the stereo origin of the sound.
The pan value defaults to 0, meaning no shift in origin;
-1 means directly to the left; 1 means directly to the right. The
value may also be an object created by the stereo module.
The sound is loaded from samp (which can be a filename, File,
or Sample object). The pitch is given as a multiple of the
sound's original frequency; the volume is given as a fraction
of the sound's original volume. The delay is a time (in seconds)
to delay before the note is played. The channel, if None or not
supplied, defaults to the same channel the agent is running in.
This extends the original sound sample to a longer period of time.
The duration is given in seconds. This returns the expected duration
of the sound, in seconds. Due to the way sounds are looped, this may
be slightly longer than the given duration.
- sched_note_pan(self, samp, pan=None, pitch=1.0, volume=1.0, delay=0, chan=None)
- sched_note_pan(sample, pan=0, pitch=1, volume=1, delay=0,
chan=self.channel) -> duration
Schedule a note to play, panning the stereo origin of the sound.
The pan value defaults to 0, meaning no shift in origin;
-1 means directly to the left; 1 means directly to the right. The
value may also be an object created by the stereo module.
The sound is loaded from samp (which can be a filename, File,
or Sample object). The pitch is given as a multiple of the
sound's original frequency; the volume is given as a fraction
of the sound's original volume. The delay is a time (in seconds)
to delay before the note is played. The channel, if None or not
supplied, defaults to the same channel the agent is running in.
This returns the expected duration of the sound, in seconds.
- sched_note_params(self, samp, **args)
- sched_note_params(sample, param=value, param=value...) -> duration
Schedule a note to play. This method understands all the arguments
used by the other sched_note methods, but they must be supplied as
named keywords. The arguments may be in any order.
For example: "sched_note_params(snd, volume=0.5, pitch=2)"
The valid arguments, and their default values:
pitch = 1 (original pitch)
volume = 1 (full volume)
delay = 0 (play immediately)
pan = None (no stereo shift)
duration = 0 (exactly once through the sound)
chan = None (play in agent's own channel)
- send_event(self, evname, *args, **kwargs)
- send_event(event, ..., chan=self.channel)
Send an event. The event consists of the given name, followed by
zero or more arguments (which may be any Python object). The
event is sent on the given channel, or (if none given) on the
agent's own channel.
- set_prop(self, key, val)
- set_prop(key, val) -> None
Set a property on the agent's channel.
- unlisten(self, event=None)
- unlisten(event=None) -> None
Stop listening. If no event argument is given, stop listening to
all events. If an event is given, stop listening for that specific
event.
Class methods defined here:
- get_argument_list(cla) from __builtin__.classobj
- get_argument_list() -> ArgList
Return the argument list specification for the class.
- get_class_name(cla) from __builtin__.classobj
- get_class_name() -> (str, str, bool)
Return the qualified name of the module, and of the Agent class
within the module. These strings are intended for logging and
error messages.
If the bool return value is true, the module came from the
package collection; it is a package name (although with no version
information). If the value is false, the module came from
sys.path.
- get_title(cla) from __builtin__.classobj
- get_title() -> string
Return the name of the agent. This normally returns the title
value from the agent's metadata. (An agent class can override
this behavior, but there is usually no reason to do so.)
Data and other attributes defined here:
- cached_argument_lists = {}
- cached_class_names = {}
- inited = False
- selected_event = None
|
class Handler |
| |
Handler: Represents the state of one agent listening for one event.
This is mostly a data object; the generator module uses its fields.
It does export one method, cancel(), for Agent code to make use of.
Public methods:
cancel() -- stop listening
Internal methods:
finalize() -- shut down the object
|
| |
Methods defined here:
- __init__(self, ag, func, event, chan, hold)
- cancel(self)
- cancel() -> None
Stop listening. It is safe to call this more than once.
- finalize(self)
- finalize() -> None
Shut down the Handler object and drop all references.
This is an internal call. It should only be called by
Generator.remhandlers(), and only after the listen has been
cancelled.
| |