chiark / gitweb /
word break now comes from the table
[disorder] / python / disorder.py.in
1 #
2 # Copyright (C) 2004, 2005 Richard Kettlewell
3 #
4 # This program is free software; you can redistribute it and/or modify
5 # it under the terms of the GNU General Public License as published by
6 # the Free Software Foundation; either version 2 of the License, or
7 # (at your option) any later version.
8 #
9 # This program is distributed in the hope that it will be useful, but
10 # WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12 # General Public License for more details.
13 #
14 # You should have received a copy of the GNU General Public License
15 # along with this program; if not, write to the Free Software
16 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17 # USA
18 #
19
20 """Python support for DisOrder
21
22 Provides disorder.client, a class for accessing a DisOrder server.
23
24 Example 1:
25
26   #! /usr/bin/env python
27   import disorder
28   d = disorder.client()
29   p = d.playing()
30   if p:
31     print p['track']
32
33 Example 2:
34
35   #! /usr/bin/env python
36   import disorder
37   import sys
38   d = disorder.client()
39   for path in sys.argv[1:]:
40     d.play(path)
41
42 """
43
44 import re
45 import string
46 import os
47 import pwd
48 import socket
49 import binascii
50 import sha
51 import sys
52 import locale
53
54 _configfile = "pkgconfdir/config"
55 _dbhome = "pkgstatedir"
56
57 # various regexps we'll use
58 _ws = re.compile(r"^[ \t\n\r]+")
59 _squote = re.compile("'(([^\\\\']|\\\\[\\\\\"'n])+)'")
60 _dquote = re.compile("\"(([^\\\\\"]|\\\\[\\\\\"'n])+)\"")
61 _unquoted = re.compile("[^\"' \\t\\n\\r][^ \t\n\r]*")
62
63 _response = re.compile("([0-9]{3}) ?(.*)")
64
65 version = "_version_"
66
67 ########################################################################
68 # exception classes
69
70 class Error(Exception):
71   """Base class for DisOrder exceptions."""
72
73 class _splitError(Error):
74   # _split failed
75   def __init__(self, value):
76     self.value = value
77   def __str__(self):
78     return str(self.value)
79
80 class parseError(Error):
81   """Error parsing the configuration file."""
82   def __init__(self, path, line, details):
83     self.path = path
84     self.line = line
85     self.details = details
86   def __str__(self):
87     return "%s:%d: %s" % (self.path, self.line, self.details)
88
89 class protocolError(Error):
90   """DisOrder control protocol error.
91
92   Indicates a mismatch between the client and server's understanding of
93   the control protocol.
94   """
95   def __init__(self, who, error):
96     self.who = who
97     self.error = error
98   def __str__(self):
99     return "%s: %s" % (self.who, str(self.error))
100
101 class operationError(Error):
102   """DisOrder control protocol error response.
103
104   Indicates that an operation failed (e.g. an attempt to play a
105   nonexistent track).  The connection should still be usable.
106   """
107   def __init__(self, res, details):
108     self.res_ = int(res)
109     self.details_ = details
110   def __str__(self):
111     """Return the complete response string from the server.
112
113     Excludes the final newline.
114     """
115     return "%d %s" % (self.res_, self.details_)
116   def response(self):
117     """Return the response code from the server."""
118     return self.res_
119   def details(self):
120     """Returns the detail string from the server."""
121     return self.details_
122
123 class communicationError(Error):
124   """DisOrder control protocol communication error.
125
126   Indicates that communication with the server went wrong, perhaps
127   because the server was restarted.  The caller could report an error to
128   the user and wait for further user instructions, or even automatically
129   retry the operation.
130   """
131   def __init__(self, who, error):
132     self.who = who
133     self.error = error
134   def __str__(self):
135     return "%s: %s" % (self.who, str(self.error))
136
137 ########################################################################
138 # DisOrder-specific text processing
139
140 def _unescape(s):
141   # Unescape the contents of a string
142   #
143   # Arguments:
144   #
145   # s -- string to unescape
146   #
147   s = re.sub("\\\\n", "\n", s)
148   s = re.sub("\\\\(.)", "\\1", s)
149   return s
150
151 def _split(s, *comments):
152   # Split a string into fields according to the usual Disorder string splitting
153   # conventions.
154   #
155   # Arguments:
156   #
157   # s        -- string to parse
158   # comments -- if present, parse comments
159   #
160   # Return values:
161   #
162   # On success, a list of fields is returned.
163   #
164   # On error, disorder.parseError is thrown.
165   #
166   fields = []
167   while s != "":
168     # discard comments
169     if comments and s[0] == '#':
170       break
171     # strip spaces
172     m = _ws.match(s)
173     if m:
174       s = s[m.end():]
175       continue
176     # pick of quoted fields of both kinds
177     m = _squote.match(s)
178     if not m:
179       m = _dquote.match(s)
180     if m:
181       fields.append(_unescape(m.group(1)))
182       s = s[m.end():]
183       continue
184     # and unquoted fields
185     m = _unquoted.match(s)
186     if m:
187       fields.append(m.group(0))
188       s = s[m.end():]
189       continue
190     # anything left must be in error
191     if s[0] == '"' or s[0] == '\'':
192       raise _splitError("invalid quoted string")
193     else:
194       raise _splitError("syntax error")
195   return fields
196
197 def _escape(s):
198   # Escape the contents of a string
199   #
200   # Arguments:
201   #
202   # s -- string to escape
203   #
204   if re.search("[\\\\\"'\n \t\r]", s) or s == '':
205     s = re.sub(r'[\\"]', r'\\\g<0>', s)
206     s = re.sub("\n", r"\\n", s)
207     return '"' + s + '"'
208   else:
209     return s
210
211 def _quote(list):
212   # Quote a list of values
213   return ' '.join(map(_escape, list))
214
215 def _sanitize(s):
216   # Return the value of s in a form suitable for writing to stderr
217   return s.encode(locale.nl_langinfo(locale.CODESET), 'replace')
218
219 def _list2dict(l):
220   # Convert a list of the form [k1, v1, k2, v2, ..., kN, vN]
221   # to a dictionary {k1:v1, k2:v2, ..., kN:vN}
222   d = {}
223   i = iter(l)
224   try:
225     while True:
226       k = i.next()
227       v = i.next()
228       d[k] = v
229   except StopIteration:
230     pass
231   return d
232
233 def _queueEntry(s):
234   # parse a queue entry
235   return _list2dict(_split(s))
236
237 ########################################################################
238 # The client class
239
240 class client:
241   """DisOrder client class.
242
243   This class provides access to the DisOrder server either on this
244   machine or across the internet.
245
246   The server to connect to, and the username and password to use, are
247   determined from the configuration files as described in 'man
248   disorder_config'.
249
250   All methods will connect if necessary, as soon as you have a
251   disorder.client object you can start calling operational methods on
252   it.
253
254   However if the server is restarted then the next method called on a
255   connection will throw an exception.  This may be considered a bug.
256
257   All methods block until they complete.
258
259   Operation methods raise communicationError if the connection breaks,
260   protocolError if the response from the server is malformed, or
261   operationError if the response is valid but indicates that the
262   operation failed.
263   """
264
265   debug_proto = 0x0001
266   debug_body = 0x0002
267
268   def __init__(self):
269     """Constructor for DisOrder client class.
270
271     The constructor reads the configuration file, but does not connect
272     to the server.
273
274     If the environment variable DISORDER_PYTHON_DEBUG is set then the
275     debug flags are initialised to that value.  This can be overridden
276     with the debug() method below.
277
278     The constructor Raises parseError() if the configuration file is not
279     valid.
280     """
281     pw = pwd.getpwuid(os.getuid())
282     self.debugging = int(os.getenv("DISORDER_PYTHON_DEBUG", 0))
283     self.config = { 'collections': [],
284                     'username': pw.pw_name,
285                     'home': _dbhome }
286     home = os.getenv("HOME")
287     if not home:
288       home = pw.pw_dir
289     privconf = _configfile + "." + pw.pw_name
290     passfile = home + os.sep + ".disorder" + os.sep + "passwd"
291     self._readfile(_configfile)
292     if os.path.exists(privconf):
293       self._readfile(privconf)
294     if os.path.exists(passfile):
295       self._readfile(passfile)
296     self.state = 'disconnected'
297
298   def debug(self, bits):
299     """Enable or disable protocol debugging.  Debug messages are written
300     to sys.stderr.
301
302     Arguments:
303     bits -- bitmap of operations that should generate debug information
304
305     Bitmap values:
306     debug_proto -- dump control protocol messages (excluding bodies)
307     debug_body -- dump control protocol message bodies
308     """
309     self.debugging = bits
310
311   def _debug(self, bit, s):
312     # debug output
313     if self.debugging & bit:
314       sys.stderr.write(_sanitize(s))
315       sys.stderr.write("\n")
316       sys.stderr.flush()
317
318   def connect(self):
319     """Connect to the DisOrder server and authenticate.
320
321     Raises communicationError if connection fails and operationError if
322     authentication fails (in which case disconnection is automatic).
323
324     May be called more than once to retry connections (e.g. when the
325     server is down).  If we are already connected and authenticated,
326     this is a no-op.
327
328     Other operations automatically connect if we're not already
329     connected, so it is not strictly necessary to call this method.
330     """
331     if self.state == 'disconnected':
332       try:
333         self.state = 'connecting'
334         if 'connect' in self.config and len(self.config['connect']) > 0:
335           c = self.config['connect']
336           self.who = repr(c)            # temporarily
337           if len(c) == 1:
338             a = socket.getaddrinfo(None, c[0],
339                                    socket.AF_INET,
340                                    socket.SOCK_STREAM,
341                                    0,
342                                    0)
343           else:
344             a = socket.getaddrinfo(c[0], c[1],
345                                    socket.AF_INET,
346                                    socket.SOCK_STREAM,
347                                    0,
348                                    0)
349           a = a[0]
350           s = socket.socket(a[0], a[1], a[2]);
351           s.connect(a[4])
352           self.who = "%s" % a[3]
353         else:
354           s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM);
355           self.who = self.config['home'] + os.sep + "socket"
356           s.connect(self.who)
357         self.w = s.makefile("wb")
358         self.r = s.makefile("rb")
359         (res, challenge) = self._simple()
360         h = sha.sha()
361         h.update(self.config['password'])
362         h.update(binascii.unhexlify(challenge))
363         self._simple("user", self.config['username'], h.hexdigest())
364         self.state = 'connected'
365       except socket.error, e:
366         self._disconnect()
367         raise communicationError(self.who, e)
368       except:
369         self._disconnect()
370         raise
371
372   def _disconnect(self):
373     # disconnect from the server, whatever state we are in
374     try:
375       del self.w
376       del self.r
377     except:
378       pass
379     self.state = 'disconnected'
380     
381   ########################################################################
382   # Operations
383
384   def become(self, who):
385     """Become another user.
386
387     Arguments:
388     who -- the user to become.
389
390     Only trusted users can perform this operation.
391     """
392     self._simple("become", who)
393
394   def play(self, track):
395     """Play a track.
396
397     Arguments:
398     track -- the path of the track to play.
399     """
400     self._simple("play", track)
401
402   def remove(self, track):
403     """Remove a track from the queue.
404
405     Arguments:
406     track -- the path or ID of the track to remove.
407     """
408     self._simple("remove", track)
409
410   def enable(self):
411     """Enable playing."""
412     self._simple("enable")
413
414   def disable(self, *now):
415     """Disable playing.
416
417     Arguments:
418     now -- if present (with any value), the current track is stopped
419            too.
420     """
421     if now:
422       self._simple("disable", "now")
423     else:
424       self._simple("disable")
425
426   def scratch(self, *id):
427     """Scratch the currently playing track.
428
429     Arguments:
430     id -- if present, the ID of the track to scratch.
431     """
432     if id:
433       self._simple("scratch", id[0])
434     else:
435       self._simple("scratch")
436
437   def shutdown(self):
438     """Shut down the server.
439
440     Only trusted users can perform this operation.
441     """
442     self._simple("shutdown")
443
444   def reconfigure(self):
445     """Make the server reload its configuration.
446
447     Only trusted users can perform this operation.
448     """
449     self._simple("reconfigure")
450
451   def rescan(self, pattern):
452     """Rescan one or more collections.
453
454     Arguments:
455     pattern -- glob pattern matching collections to rescan.
456
457     Only trusted users can perform this operation.
458     """
459     self._simple("rescan", pattern)
460
461   def version(self):
462     """Return the server's version number."""
463     return self._simple("version")[1]
464
465   def playing(self):
466     """Return the currently playing track.
467
468     If a track is playing then it is returned as a dictionary.
469     If no track is playing then None is returned."""
470     res, details = self._simple("playing")
471     if res % 10 != 9:
472       try:
473         return _queueEntry(details)
474       except _splitError, s:
475         raise protocolError(self.who, s.str())
476     else:
477       return None
478
479   def _somequeue(self, command):
480     self._simple(command)
481     try:
482       return map(lambda s: _queueEntry(s), self._body())
483     except _splitError, s:
484       raise protocolError(self.who, s.str())
485
486   def recent(self):
487     """Return a list of recently played tracks.
488
489     The return value is a list of dictionaries corresponding to
490     recently played tracks.  The oldest track comes first."""
491     return self._somequeue("recent")
492
493   def queue(self):
494     """Return the current queue.
495
496     The return value is a list of dictionaries corresponding to
497     recently played tracks.  The next track to be played comes first."""
498     return self._somequeue("queue")
499
500   def _somedir(self, command, dir, re):
501     if re:
502       self._simple(command, dir, re[0])
503     else:
504       self._simple(command, dir)
505     return self._body()
506
507   def directories(self, dir, *re):
508     """List subdirectories of a directory.
509
510     Arguments:
511     dir -- directory to list, or '' for the whole root.
512     re -- regexp that results must match.  Optional.
513
514     The return value is a list of the (nonempty) subdirectories of dir.
515     If dir is '' then a list of top-level directories is returned.
516
517     If a regexp is specified then the basename of each result must
518     match.  Matching is case-independent.  See pcrepattern(3).
519     """
520     return self._somedir("dirs", dir, re)
521   
522   def files(self, dir, *re):
523     """List files within a directory.
524
525     Arguments:
526     dir -- directory to list, or '' for the whole root.
527     re -- regexp that results must match.  Optional.
528
529     The return value is a list of playable files in dir.  If dir is ''
530     then a list of top-level files is returned.
531
532     If a regexp is specified then the basename of each result must
533     match.  Matching is case-independent.  See pcrepattern(3).
534     """
535     return self._somedir("files", dir, re)
536
537   def allfiles(self, dir, *re):
538     """List subdirectories and files within a directory.
539
540     Arguments:
541     dir -- directory to list, or '' for the whole root.
542     re -- regexp that results must match.  Optional.
543
544     The return value is a list of all (nonempty) subdirectories and
545     files within dir.  If dir is '' then a list of top-level files and
546     directories is returned.
547     
548     If a regexp is specified then the basename of each result must
549     match.  Matching is case-independent.  See pcrepattern(3).
550     """
551     return self._somedir("allfiles", dir, re)
552
553   def set(self, track, key, value):
554     """Set a preference value.
555
556     Arguments:
557     track -- the track to modify
558     key -- the preference name
559     value -- the new preference value
560     """
561     self._simple("set", track, key, value)
562
563   def unset(self, track, key):
564     """Unset a preference value.
565
566     Arguments:
567     track -- the track to modify
568     key -- the preference to remove
569     """
570     self._simple("set", track, key, value)
571
572   def get(self, track, key):
573     """Get a preference value.
574
575     Arguments:
576     track -- the track to query
577     key -- the preference to remove
578
579     The return value is the preference 
580     """
581     ret, details = self._simple("get", track, key)
582     return details
583
584   def prefs(self, track):
585     """Get all the preferences for a track.
586
587     Arguments:
588     track -- the track to query
589
590     The return value is a dictionary of all the track's preferences.
591     Note that even nominally numeric values remain encoded as strings.
592     """
593     self._simple("prefs", track)
594     r = {}
595     for line in self._body():
596       try:
597         kv = _split(line)
598       except _splitError, s:
599         raise protocolError(self.who, s.str())
600       if len(kv) != 2:
601         raise protocolError(self.who, "invalid prefs body line")
602       r[kv[0]] = kv[1]
603     return r
604
605   def _boolean(self, s):
606     return s[1] == 'yes'
607
608   def exists(self, track):
609     """Return true if a track exists
610
611     Arguments:
612     track -- the track to check for"""
613     return self._boolean(self._simple("exists", track))
614
615   def enabled(self):
616     """Return true if playing is enabled"""
617     return self._boolean(self._simple("enabled"))
618
619   def random_enabled(self):
620     """Return true if random play is enabled"""
621     return self._boolean(self._simple("random-enabled"))
622
623   def random_enable(self):
624     """Enable random play."""
625     self._simple("random-enable")
626
627   def random_disable(self):
628     """Disable random play."""
629     self._simple("random-disable")
630
631   def length(self, track):
632     """Return the length of a track in seconds.
633
634     Arguments:
635     track -- the track to query.
636     """
637     ret, details = self._simple("length", track)
638     return int(details)
639
640   def search(self, words):
641     """Search for tracks.
642
643     Arguments:
644     words -- the set of words to search for.
645
646     The return value is a list of track path names, all of which contain
647     all of the required words (in their path name, trackname
648     preferences, etc.)
649     """
650     self._simple("search", *words)
651     return self._body()
652
653   def stats(self):
654     """Get server statistics.
655
656     The return value is list of statistics.
657     """
658     self._simple("stats")
659     return self._body()
660
661   def dump(self):
662     """Get all preferences.
663
664     The return value is an encoded dump of the preferences database.
665     """
666     self._simple("dump")
667     return self._body()
668
669   def set_volume(self, left, right):
670     """Set volume.
671
672     Arguments:
673     left -- volume for the left speaker.
674     right --  volume for the right speaker.
675     """
676     self._simple("volume", left, right)
677
678   def get_volume(self):
679     """Get volume.
680
681     The return value a tuple consisting of the left and right volumes.
682     """
683     ret, details = self._simple("volume")
684     return map(int,string.split(details))
685
686   def move(self, track, delta):
687     """Move a track in the queue.
688
689     Arguments:
690     track -- the name or ID of the track to move
691     delta -- the number of steps towards the head of the queue to move
692     """
693     ret, details = self._simple("move", track, str(delta))
694     return int(details)
695
696   def log(self, callback):
697     """Read event log entries as they happen.
698
699     Each event log entry is handled by passing it to callback.
700
701     The callback takes two arguments, the first is the client and the
702     second the line from the event log.
703     
704     The callback should return True to continue or False to stop (don't
705     forget this, or your program will mysteriously misbehave).
706
707     It is suggested that you use the disorder.monitor class instead of
708     calling this method directly, but this is not mandatory.
709
710     See disorder_protocol(5) for the event log syntax.
711
712     Arguments:
713     callback -- function to call with log entry
714     """
715     ret, details = self._simple("log")
716     while True:
717       l = self._line()
718       self._debug(client.debug_body, "<<< %s" % l)
719       if l != '' and l[0] == '.':
720         if l == '.':
721           return
722         l = l[1:]
723       if not callback(self, l):
724         break
725     # tell the server to stop sending, eat the remains of the body,
726     # eat the response
727     self._send("version")
728     self._body()
729     self._response()
730
731   def pause(self):
732     """Pause the current track."""
733     self._simple("pause")
734
735   def resume(self):
736     """Resume after a pause."""
737     self._simple("resume")
738
739   def part(self, track, context, part):
740     """Get a track name part
741
742     Arguments:
743     track -- the track to query
744     context -- the context ('sort' or 'display')
745     part -- the desired part (usually 'artist', 'album' or 'title')
746
747     The return value is the preference 
748     """
749     ret, details = self._simple("part", track, context, part)
750     return details
751
752   ########################################################################
753   # I/O infrastructure
754
755   def _line(self):
756     # read one response line and return as some suitable string object
757     #
758     # If an I/O error occurs, disconnect from the server.
759     #
760     # XXX does readline() DTRT regarding character encodings?
761     try:
762       l = self.r.readline()
763       if not re.search("\n", l):
764         raise communicationError(self.who, "peer disconnected")
765       l = l[:-1]
766     except:
767       self._disconnect()
768       raise
769     return unicode(l, "UTF-8")
770
771   def _response(self):
772     # read a response as a (code, details) tuple
773     l = self._line()
774     self._debug(client.debug_proto, "<== %s" % l)
775     m = _response.match(l)
776     if m:
777       return int(m.group(1)), m.group(2)
778     else:
779       raise protocolError(self.who, "invalid response %s")
780
781   def _send(self, *command):
782     quoted = _quote(command)
783     self._debug(client.debug_proto, "==> %s" % quoted)
784     encoded = quoted.encode("UTF-8")
785     try:
786       self.w.write(encoded)
787       self.w.write("\n")
788       self.w.flush()
789     except IOError, e:
790       # e.g. EPIPE
791       self._disconnect()
792       raise communicationError(self.who, e)
793     except:
794       self._disconnect()
795       raise
796
797   def _simple(self, *command):
798     # Issue a simple command, throw an exception on error
799     #
800     # If an I/O error occurs, disconnect from the server.
801     #
802     # On success returns response as a (code, details) tuple
803     #
804     # On error raise operationError
805     if self.state == 'disconnected':
806       self.connect()
807     if command:
808       self._send(*command)
809     res, details = self._response()
810     if res / 100 == 2:
811       return res, details
812     raise operationError(res, details)
813
814   def _body(self):
815     # Fetch a dot-stuffed body
816     result = []
817     while True:
818       l = self._line()
819       self._debug(client.debug_body, "<<< %s" % l)
820       if l != '' and l[0] == '.':
821         if l == '.':
822           return result
823         l = l[1:]
824       result.append(l)
825
826   ########################################################################
827   # Configuration file parsing
828
829   def _readfile(self, path):
830     # Read a configuration file
831     #
832     # Arguments:
833     #
834     # path -- path of file to read
835
836     # handlers for various commands
837     def _collection(self, command, args):
838       if len(args) != 3:
839         return "'%s' takes three args" % command
840       self.config["collections"].append(args)
841       
842     def _unary(self, command, args):
843       if len(args) != 1:
844         return "'%s' takes only one arg" % command
845       self.config[command] = args[0]
846
847     def _include(self, command, args):
848       if len(args) != 1:
849         return "'%s' takes only one arg" % command
850       self._readfile(args[0])
851
852     def _any(self, command, args):
853       self.config[command] = args
854
855     # mapping of options to handlers
856     _options = { "collection": _collection,
857                  "username": _unary,
858                  "password": _unary,
859                  "home": _unary,
860                  "connect": _any,
861                  "include": _include }
862
863     # the parser
864     for lno, line in enumerate(file(path, "r")):
865       try:
866         fields = _split(line, 'comments')
867       except _splitError, s:
868         raise parseError(path, lno + 1, str(s))
869       if fields:
870         command = fields[0]
871         # we just ignore options we don't know about, so as to cope gracefully
872         # with version skew (and nothing to do with implementor laziness)
873         if command in _options:
874           e = _options[command](self, command, fields[1:])
875           if e:
876             self._parseError(path, lno + 1, e)
877
878   def _parseError(self, path, lno, s):
879     raise parseError(path, lno, s)
880
881 ########################################################################
882 # monitor class
883
884 class monitor:
885   """DisOrder event log monitor class
886
887   Intended to be subclassed with methods corresponding to event log messages
888   the implementor cares about over-ridden."""
889
890   def __init__(self, c=None):
891     """Constructor for the monitor class
892
893     Can be passed a client to use.  If none is specified then one
894     will be created specially for the purpose.
895
896     Arguments:
897     c -- client"""
898     if c == None:
899       c = client();
900     self.c = c
901
902   def run(self):
903     """Start monitoring logs.  Continues monitoring until one of the
904     message-specific methods returns False.  Can be called more than once
905     (but not recursively!)"""
906     self.c.log(self._callback)
907
908   def when(self):
909     """Return the timestamp of the current (or most recent) event log entry"""
910     return self.timestamp
911
912   def _callback(self, c, line):
913     try:
914       bits = _split(line)
915     except:
916       return self.invalid(line)
917     if(len(bits) < 2):
918       return self.invalid(line)
919     self.timestamp = int(bits[0], 16)
920     keyword = bits[1]
921     bits = bits[2:]
922     if keyword == 'completed':
923       if len(bits) == 1:
924         return self.completed(bits[0])
925     elif keyword == 'failed':
926       if len(bits) == 2:
927         return self.failed(bits[0], bits[1])
928     elif keyword == 'moved':
929       if len(bits) == 3:
930         try:
931           n = int(bits[1])
932         except:
933           return self.invalid(line)
934         return self.moved(bits[0], n, bits[2])
935     elif keyword == 'playing':
936       if len(bits) == 1:
937         return self.playing(bits[0], None)
938       elif len(bits) == 2:
939         return self.playing(bits[0], bits[1])
940     elif keyword == 'queue' or keyword == 'recent-added':
941       try:
942         q = _list2dict(bits)
943       except:
944         return self.invalid(line)
945       if keyword == 'queue':
946         return self.queue(q)
947       if keyword == 'recent-added':
948         return self.recent_added(q)
949     elif keyword == 'recent-removed':
950       if len(bits) == 1:
951         return self.recent_removed(bits[0])
952     elif keyword == 'removed':
953       if len(bits) == 1:
954         return self.removed(bits[0], None)
955       elif len(bits) == 2:
956         return self.removed(bits[0], bits[1])
957     elif keyword == 'scratched':
958       if len(bits) == 2:
959         return self.scratched(bits[0], bits[1])
960     return self.invalid(line)
961
962   def completed(self, track):
963     """Called when a track completes.
964
965     Arguments:
966     track -- track that completed"""
967     return True
968
969   def failed(self, track, error):
970     """Called when a player suffers an error.
971
972     Arguments:
973     track -- track that failed
974     error -- error indicator"""
975     return True
976
977   def moved(self, id, offset, user):
978     """Called when a track is moved in the queue.
979
980     Arguments:
981     id -- queue entry ID
982     offset -- distance moved
983     user -- user responsible"""
984     return True
985
986   def playing(self, track, user):
987     """Called when a track starts playing.
988
989     Arguments:
990     track -- track that has started
991     user -- user that submitted track, or None"""
992     return True
993
994   def queue(self, q):
995     """Called when a track is added to the queue.
996
997     Arguments:
998     q -- dictionary of new queue entry"""
999     return True
1000
1001   def recent_added(self, q):
1002     """Called when a track is added to the recently played list
1003
1004     Arguments:
1005     q -- dictionary of new queue entry"""
1006     return True
1007
1008   def recent_removed(self, id):
1009     """Called when a track is removed from the recently played list
1010
1011     Arguments:
1012     id -- ID of removed entry (always the oldest)"""
1013     return True
1014
1015   def removed(self, id, user):
1016     """Called when a track is removed from the queue, either manually
1017     or in order to play it.
1018
1019     Arguments:
1020     id -- ID of removed entry
1021     user -- user responsible (or None if we're playing this track)"""
1022     return True
1023
1024   def scratched(self, track, user):
1025     """Called when a track is scratched
1026
1027     Arguments:
1028     track -- track that was scratched
1029     user -- user responsible"""
1030     return True
1031
1032   def invalid(self, line):
1033     """Called when an event log line cannot be interpreted
1034
1035     Arguments:
1036     line -- line that could not be understood"""
1037     return True
1038
1039 # Local Variables:
1040 # mode:python
1041 # py-indent-offset:2
1042 # comment-column:40
1043 # fill-column:72
1044 # End: