def 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.
"""
chan = kwargs.pop('chan', None)
if kwargs:
raise TypeError('invalid keyword argument for this function')
if self.generator is None or self.channel is None:
raise generator.ScheduleError('sender has never been scheduled')
if chan is None:
chan = self.channel
if not chan.active:
raise generator.ChannelError(
'cannot send event to inactive channel')
gen = self.generator
evname = check_prop_name(evname)
ev = (evname, ) + args
gen.sendevent(ev, chan)
def set_prop(self, key, val):
"""set_prop(key, val) -> None
Set a property on this channel.
"""
key = check_prop_name(key)
self.propmap[key] = val
def del_prop(self, key):
"""del_prop(key) -> None
Delete a property from this 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).
"""
key = check_prop_name(key)
if key in self.propmap:
self.propmap.pop(key)
def has_prop(self, key):
"""has_prop(key) -> bool
See whether this channel has a given property. If none is set, see
if one is inherited from the parent.
"""
key = check_prop_name(key)
chan = self
while chan:
if key in chan.propmap:
return True
chan = chan.parent
return False
def get_prop(self, key, default=None):
"""get_prop(key, default=None) -> any
Get a property from this 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().
"""
key = check_prop_name(key)
chan = self
while chan:
if key in chan.propmap:
return chan.propmap[key]
chan = chan.parent
return default
def 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.
"""
if self.generator is None or self.channel is None:
raise generator.ScheduleError('listener has never been scheduled')
if event is None:
ls = [han for han in self.handlers]
else:
event = check_prop_name(event)
ls = [han for han in self.handlers if han.event == event]
if not ls:
return
gen = self.generator
gen.remhandlers(ls)
def 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.
"""
if not self.inited:
raise generator.ScheduleError('agent is uninitialized')
if self.generator is None or self.channel is None:
raise generator.ScheduleError('listener has never been scheduled')
if chan is None:
chan = self.channel
if not chan.active:
raise generator.ChannelError('cannot listen to inactive channel')
if event is None:
event = self.selected_event
if event is None:
raise generator.ScheduleError('must specify event to listen for')
if callable(event):
event = event()
if event is None:
raise generator.ScheduleError(
'must return event to listen for')
if event != '':
event = check_prop_name(event)
if handle is None:
handle = self.receive
gen = self.generator
han = Handler(self, handle, event, chan, hold)
gen.addhandler(han)
return han