Python: module boodle.agent

boodle.agent | index boodle/agent.py

`agent: A module which contains the Agent class, the fundamental work
unit of Boodler.`

Modules
`` |  |
boopak.argdef boodle boodle.generator | logging boopak.pinfo boopak.pload | boodle.sample boopak.sparse boodle.stereo | types boopak.version

Classes
`` |  | 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.`

Functions
`` |  | load_described(loader, args, wantmodule=False) `load_described(loader, val, wantmodule=False) -> module or Agent Load a named module or agent. 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.`

Data
`` |  | HoldBoth = True HoldListen = 'listen' HoldRun = 'run' cboodle = <boodle.DummyDriver>