[hackers] [wmii] Add API docs to pygmi and pyxp. || Kris Maglione

changeset: 2525:77c003f02dae
user: Kris Maglione <jg_AT_suckless.org>
date: Fri Oct 09 22:23:00 2009 -0400
files: alternative_wmiircs/python/pygmi/event.py alternative_wmiircs/python/pygmi/util.py
description:
Add API docs to pygmi and pyxp.

diff -r a1498ca4aa13 -r 77c003f02dae alternative_wmiircs/python/pygmi/event.py
--- a/alternative_wmiircs/python/pygmi/event.py Fri Oct 09 20:34:23 2009 -0400
+++ b/alternative_wmiircs/python/pygmi/event.py Fri Oct 09 22:23:00 2009 -0400
@@ -4,12 +4,34 @@
 import traceback
 
 import pygmi
+from pygmi.util import prop
 from pygmi import monitor, client, curry, call, program_list, _
 
 __all__ = ('keys', 'events', 'Match')
 
 class Match(object):
+ """
+ A class used for matching events based on simple patterns.
+ """
     def __init__(self, *args):
+ """
+ Creates a new Match object based on arbitrary arguments
+ which constitute a match pattern. Each argument matches an
+ element of the original event. Arguments are matched based
+ on their type:
+
+ _: Matches anything
+ set: Matches any string equal to any of its elements
+ list: Matches any string equal to any of its elements
+ tuple: Matches any string equal to any of its elements
+
+ Additionally, any type with a 'search' attribute matches if
+ that callable attribute returns True given element in
+ question as its first argument.
+
+ Any other object matches if it compares equal to the
+ element.
+ """
         self.args = args
         self.matchers = []
         for a in args:
@@ -26,11 +48,24 @@
             self.matchers.append(a)
 
     def match(self, string):
+ """
+ Returns true if this object matches an arbitrary string when
+ split on ascii spaces.
+ """
         ary = string.split(' ', len(self.matchers))
         if all(m(a) for m, a in zip(self.matchers, ary)):
             return ary
 
 def flatten(items):
+ """
+ Given an iterator which returns (key, value) pairs, returns a
+ new iterator of (k, value) pairs such that every list- or
+ tuple-valued key in the original sequence yields an individual
+ pair.
+
+ Example: flatten({(1, 2, 3): 'foo', 4: 'bar'}.items()) ->
+ (1, 'foo'), (2: 'foo'), (3: 'foo'), (4: 'bar')
+ """
     for k, v in items:
         if not isinstance(k, (list, tuple)):
             k = k,
@@ -38,12 +73,29 @@
             yield key, v
 
 class Events():
+ """
+ A class to handle events read from wmii's '/event' file.
+ """
     def __init__(self):
+ """
+ Initializes the event handler
+ """
         self.events = {}
         self.eventmatchers = {}
         self.alive = True
 
     def dispatch(self, event, args=''):
+ """
+ Distatches an event to any matching event handlers.
+
+ The handler which specifically matches the event name will
+ be called first, followed by any handlers with a 'match'
+ method which matches the event name concatenated to the args
+ string.
+
+ Param event: The name of the event to dispatch.
+ Param args: The single arguments string for the event.
+ """
         try:
             if event in self.events:
                 self.events[event](args)
@@ -55,6 +107,11 @@
             traceback.print_exc(sys.stderr)
 
     def loop(self):
+ """
+ Enters teh event loop, reading lines from wmii's '/event'
+ and dispatching them, via #dispatch, to event handlers.
+ Continues so long as #alive is True.
+ """
         keys.mode = 'main'
         for line in client.readlines('/event'):
             if not self.alive:
@@ -63,6 +120,21 @@
         self.alive = False
 
     def bind(self, items={}, **kwargs):
+ """
+ Binds a number of event handlers for wmii events. Keyword
+ arguments other than 'items' are added to the 'items' dict.
+ Handlers are called by #loop when a matching line is read
+ from '/event'. Each handler is called with, as its sole
+ argument, the string read from /event with its first token
+ stripped.
+
+ Param items: A dict of action-handler pairs to bind. Passed
+ through pygmi.event.flatten. Keys with a 'match' method,
+ such as pygmi.event.Match objects or regular expressions,
+ are matched against the entire event string. Any other
+ object matches if it compares equal to the first token of
+ the event.
+ """
         kwargs.update(items)
         for k, v in flatten(kwargs.iteritems()):
             if hasattr(k, 'match'):
@@ -71,11 +143,24 @@
                 self.events[k] = v
 
     def event(self, fn):
+ """
+ A decorator which binds its wrapped function, as via #bind,
+ for the event which matches its name.
+ """
         self.bind({fn.__name__: fn})
 events = Events()
 
 class Keys(object):
+ """
+ A class to manage wmii key bindings.
+ """
     def __init__(self):
+ """
+ Initializes the class and binds an event handler for the Key
+ event, as via pygmi.event.events.bind.
+
+ Takes no arguments.
+ """
         self.modes = {}
         self.modelist = []
         self.mode = 'main'
@@ -101,9 +186,11 @@
                           self.modes[mode]['import'].items());
 
         client.write('/keys', '\n'.join(self._keys.keys()) + '\n')
- mode = property(lambda self: self._mode, _set_mode)
 
- @property
+ mode = property(lambda self: self._mode, _set_mode,
+ doc="The current mode for which to dispatch keys")
+
+ @prop(doc="Returns a short help text describing the bound keys in all modes")
     def help(self):
         return '\n\n'.join(
             ('Mode %s\n' % mode['name']) +
@@ -116,6 +203,28 @@
                          for name in self.modelist))
 
     def bind(self, mode='main', keys=(), import_={}):
+ """
+ Binds a series of keys for the given 'mode'. Keys may be
+ specified as a dict or as a sequence of tuple values and
+ strings.
+
+ In the latter case, documentation may be interspersed with
+ key bindings. Any value in the sequence which is not a tuple
+ begins a new key group, with that value as a description.
+ A tuple with two values is considered a key-value pair,
+ where the value is the handler for the named key. A
+ three valued tuple is considered a key-description-value
+ tuple, with the same semantics as above.
+
+ Each key binding is interpolated with the values of
+ #defs, as if processed by (key % self.defs)
+
+ Param mode: The name of the mode for which to bind the keys.
+ Param keys: A sequence of keys to bind.
+ Param import_: A dict specifying keys which should be
+ imported from other modes, of the form
+ { 'mode': ['key1', 'key2', ...] }
+ """
         self._add_mode(mode)
         mode = self.modes[mode]
         group = None
@@ -147,12 +256,21 @@
             mode['import'][k % self.defs] = wrap_import(v, k)
 
     def dispatch(self, key):
+ """
+ Dispatches a key event for the current mode.
+
+ Param key: The key spec for which to dispatch.
+ """
         mode = self.modes[self.mode]
         if key in self._keys:
             return self._keys[key](key)
 keys = Keys()
 
 class Actions(object):
+ """
+ A class to represent user-callable actions. All methods without
+ leading underscores in their names are treated as callable actions.
+ """
     def __getattr__(self, name):
         if name.startswith('_') or name.endswith('_'):
             raise AttributeError()
@@ -166,11 +284,16 @@
         return action
 
     def _call(self, args):
+ """
+ Calls a method named for the first token of 'args', with the
+ rest of the string as its first argument. If the method
+ doesn't exist, a trailing underscore is appended.
+ """
         a = args.split(' ', 1)
         if a:
             getattr(self, a[0])(*a[1:])
 
- @property
+ @prop(doc="Returns the names of the public methods callable as actions, with trailing underscores stripped.")
     def _choices(self):
         return sorted(
             program_list(pygmi.confpath) +
diff -r a1498ca4aa13 -r 77c003f02dae alternative_wmiircs/python/pygmi/util.py
--- a/alternative_wmiircs/python/pygmi/util.py Fri Oct 09 20:34:23 2009 -0400
+++ b/alternative_wmiircs/python/pygmi/util.py Fri Oct 09 22:23:00 2009 -0400
@@ -3,7 +3,7 @@
 
 import pygmi
 
-__all__ = 'call', 'message', 'program_list', 'curry', 'find_script', '_'
+__all__ = 'call', 'message', 'program_list', 'curry', 'find_script', '_', 'prop'
 
 def _():
     pass
@@ -56,4 +56,10 @@
         if os.access('%s/%s' % (path, name), os.X_OK):
             return '%s/%s' % (path, name)
 
+def prop(**kwargs):
+ def prop_(wrapped):
+ kwargs['fget'] = wrapped
+ return property(**kwargs)
+ return prop_
+
 # vim:se sts=4 sw=4 et:
Received on Sun Oct 11 2009 - 09:36:09 UTC