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