chiark - git - mdw - disorder/blob - python/disorder.py.in

   1 #
   2 # Copyright (C) 2004, 2005, 2007 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, pattern):
 483     """Rescan one or more collections.
 484
 485     Arguments:
 486     pattern -- glob pattern matching collections to rescan.
 487
 488     Only trusted users can perform this operation.
 489     """
 490     self._simple("rescan", pattern)
 491
 492   def version(self):
 493     """Return the server's version number."""
 494     return _split(self._simple("version")[1])[0]
 495
 496   def playing(self):
 497     """Return the currently playing track.
 498
 499     If a track is playing then it is returned as a dictionary.  See
 500     disorder_protocol(5) for the meanings of the keys.  All keys are
 501     plain strings but the values will be unicode strings.
 502
 503     If no track is playing then None is returned."""
 504     res, details = self._simple("playing")
 505     if res % 10 != 9:
 506       try:
 507         return _queueEntry(details)
 508       except _splitError, s:
 509         raise protocolError(self.who, s.str())
 510     else:
 511       return None
 512
 513   def _somequeue(self, command):
 514     self._simple(command)
 515     try:
 516       return map(lambda s: _queueEntry(s), self._body())
 517     except _splitError, s:
 518       raise protocolError(self.who, s.str())
 519
 520   def recent(self):
 521     """Return a list of recently played tracks.
 522
 523     The return value is a list of dictionaries corresponding to
 524     recently played tracks.  The oldest track comes first.
 525
 526     See disorder_protocol(5) for the meanings of the keys.  All keys are
 527     plain strings but the values will be unicode strings."""
 528     return self._somequeue("recent")
 529
 530   def queue(self):
 531     """Return the current queue.
 532
 533     The return value is a list of dictionaries corresponding to
 534     recently played tracks.  The next track to be played comes first.
 535
 536     See disorder_protocol(5) for the meanings of the keys.  All keys are
 537     plain strings but the values will be unicode strings."""
 538     return self._somequeue("queue")
 539
 540   def _somedir(self, command, dir, re):
 541     if re:
 542       self._simple(command, dir, re[0])
 543     else:
 544       self._simple(command, dir)
 545     return self._body()
 546
 547   def directories(self, dir, *re):
 548     """List subdirectories of a directory.
 549
 550     Arguments:
 551     dir -- directory to list, or '' for the whole root.
 552     re -- regexp that results must match.  Optional.
 553
 554     The return value is a list of the (nonempty) subdirectories of dir.
 555     If dir is '' then a list of top-level directories is returned.
 556
 557     If a regexp is specified then the basename of each result must
 558     match.  Matching is case-independent.  See pcrepattern(3).
 559     """
 560     return self._somedir("dirs", dir, re)
 561
 562   def files(self, dir, *re):
 563     """List files within a directory.
 564
 565     Arguments:
 566     dir -- directory to list, or '' for the whole root.
 567     re -- regexp that results must match.  Optional.
 568
 569     The return value is a list of playable files in dir.  If dir is ''
 570     then a list of top-level files is returned.
 571
 572     If a regexp is specified then the basename of each result must
 573     match.  Matching is case-independent.  See pcrepattern(3).
 574     """
 575     return self._somedir("files", dir, re)
 576
 577   def allfiles(self, dir, *re):
 578     """List subdirectories and files within a directory.
 579
 580     Arguments:
 581     dir -- directory to list, or '' for the whole root.
 582     re -- regexp that results must match.  Optional.
 583
 584     The return value is a list of all (nonempty) subdirectories and
 585     files within dir.  If dir is '' then a list of top-level files and
 586     directories is returned.
 587
 588     If a regexp is specified then the basename of each result must
 589     match.  Matching is case-independent.  See pcrepattern(3).
 590     """
 591     return self._somedir("allfiles", dir, re)
 592
 593   def set(self, track, key, value):
 594     """Set a preference value.
 595
 596     Arguments:
 597     track -- the track to modify
 598     key -- the preference name
 599     value -- the new preference value
 600     """
 601     self._simple("set", track, key, value)
 602
 603   def unset(self, track, key):
 604     """Unset a preference value.
 605
 606     Arguments:
 607     track -- the track to modify
 608     key -- the preference to remove
 609     """
 610     self._simple("set", track, key, value)
 611
 612   def get(self, track, key):
 613     """Get a preference value.
 614
 615     Arguments:
 616     track -- the track to query
 617     key -- the preference to remove
 618
 619     The return value is the preference.
 620     """
 621     ret, details = self._simple("get", track, key)
 622     if ret == 555:
 623       return None
 624     else:
 625       return _split(details)[0]
 626
 627   def prefs(self, track):
 628     """Get all the preferences for a track.
 629
 630     Arguments:
 631     track -- the track to query
 632
 633     The return value is a dictionary of all the track's preferences.
 634     Note that even nominally numeric values remain encoded as strings.
 635     """
 636     self._simple("prefs", track)
 637     r = {}
 638     for line in self._body():
 639       try:
 640         kv = _split(line)
 641       except _splitError, s:
 642         raise protocolError(self.who, s.str())
 643       if len(kv) != 2:
 644         raise protocolError(self.who, "invalid prefs body line")
 645       r[kv[0]] = kv[1]
 646     return r
 647
 648   def _boolean(self, s):
 649     return s[1] == 'yes'
 650
 651   def exists(self, track):
 652     """Return true if a track exists
 653
 654     Arguments:
 655     track -- the track to check for"""
 656     return self._boolean(self._simple("exists", track))
 657
 658   def enabled(self):
 659     """Return true if playing is enabled"""
 660     return self._boolean(self._simple("enabled"))
 661
 662   def random_enabled(self):
 663     """Return true if random play is enabled"""
 664     return self._boolean(self._simple("random-enabled"))
 665
 666   def random_enable(self):
 667     """Enable random play."""
 668     self._simple("random-enable")
 669
 670   def random_disable(self):
 671     """Disable random play."""
 672     self._simple("random-disable")
 673
 674   def length(self, track):
 675     """Return the length of a track in seconds.
 676
 677     Arguments:
 678     track -- the track to query.
 679     """
 680     ret, details = self._simple("length", track)
 681     return int(details)
 682
 683   def search(self, words):
 684     """Search for tracks.
 685
 686     Arguments:
 687     words -- the set of words to search for.
 688
 689     The return value is a list of track path names, all of which contain
 690     all of the required words (in their path name, trackname
 691     preferences, etc.)
 692     """
 693     self._simple("search", _quote(words))
 694     return self._body()
 695
 696   def tags(self):
 697     """List all tags
 698
 699     The return value is a list of all tags which apply to at least one
 700     track."""
 701     self._simple("tags")
 702     return self._body()
 703
 704   def stats(self):
 705     """Get server statistics.
 706
 707     The return value is list of statistics.
 708     """
 709     self._simple("stats")
 710     return self._body()
 711
 712   def dump(self):
 713     """Get all preferences.
 714
 715     The return value is an encoded dump of the preferences database.
 716     """
 717     self._simple("dump")
 718     return self._body()
 719
 720   def set_volume(self, left, right):
 721     """Set volume.
 722
 723     Arguments:
 724     left -- volume for the left speaker.
 725     right --  volume for the right speaker.
 726     """
 727     self._simple("volume", left, right)
 728
 729   def get_volume(self):
 730     """Get volume.
 731
 732     The return value a tuple consisting of the left and right volumes.
 733     """
 734     ret, details = self._simple("volume")
 735     return map(int,string.split(details))
 736
 737   def move(self, track, delta):
 738     """Move a track in the queue.
 739
 740     Arguments:
 741     track -- the name or ID of the track to move
 742     delta -- the number of steps towards the head of the queue to move
 743     """
 744     ret, details = self._simple("move", track, str(delta))
 745     return int(details)
 746
 747   def moveafter(self, target, tracks):
 748     """Move a track in the queue
 749
 750     Arguments:
 751     target -- target ID or None
 752     tracks -- a list of IDs to move
 753
 754     If target is '' or is not in the queue then the tracks are moved to
 755     the head of the queue.
 756
 757     Otherwise the tracks are moved to just after the target."""
 758     if target is None:
 759       target = ''
 760     self._simple("moveafter", target, *tracks)
 761
 762   def log(self, callback):
 763     """Read event log entries as they happen.
 764
 765     Each event log entry is handled by passing it to callback.
 766
 767     The callback takes two arguments, the first is the client and the
 768     second the line from the event log.
 769
 770     The callback should return True to continue or False to stop (don't
 771     forget this, or your program will mysteriously misbehave).  Once you
 772     stop reading the log the connection is useless and should be deleted.
 773
 774     It is suggested that you use the disorder.monitor class instead of
 775     calling this method directly, but this is not mandatory.
 776
 777     See disorder_protocol(5) for the event log syntax.
 778
 779     Arguments:
 780     callback -- function to call with log entry
 781     """
 782     ret, details = self._simple("log")
 783     while True:
 784       l = self._line()
 785       self._debug(client.debug_body, "<<< %s" % l)
 786       if l != '' and l[0] == '.':
 787         if l == '.':
 788           return
 789         l = l[1:]
 790       if not callback(self, l):
 791         break
 792
 793   def pause(self):
 794     """Pause the current track."""
 795     self._simple("pause")
 796
 797   def resume(self):
 798     """Resume after a pause."""
 799     self._simple("resume")
 800
 801   def part(self, track, context, part):
 802     """Get a track name part
 803
 804     Arguments:
 805     track -- the track to query
 806     context -- the context ('sort' or 'display')
 807     part -- the desired part (usually 'artist', 'album' or 'title')
 808
 809     The return value is the preference
 810     """
 811     ret, details = self._simple("part", track, context, part)
 812     return _split(details)[0]
 813
 814   def setglobal(self, key, value):
 815     """Set a global preference value.
 816
 817     Arguments:
 818     key -- the preference name
 819     value -- the new preference value
 820     """
 821     self._simple("set-global", key, value)
 822
 823   def unsetglobal(self, key):
 824     """Unset a global preference value.
 825
 826     Arguments:
 827     key -- the preference to remove
 828     """
 829     self._simple("set-global", key, value)
 830
 831   def getglobal(self, key):
 832     """Get a global preference value.
 833
 834     Arguments:
 835     key -- the preference to look up
 836
 837     The return value is the preference
 838     """
 839     ret, details = self._simple("get-global", key)
 840     if ret == 555:
 841       return None
 842     else:
 843       return _split(details)[0]
 844
 845   def make_cookie(self):
 846     """Create a login cookie"""
 847     ret, details = self._simple("make-cookie")
 848     return _split(details)[0]
 849
 850   def revoke(self):
 851     """Revoke a login cookie"""
 852     self._simple("revoke")
 853
 854   def adduser(self, user, password):
 855     """Create a user"""
 856     self._simple("adduser", user, password)
 857
 858   def deluser(self, user):
 859     """Delete a user"""
 860     self._simple("deluser", user)
 861
 862   def userinfo(self, user, key):
 863     """Get user information"""
 864     res, details = self._simple("userinfo", user, key)
 865     if res == 555:
 866       return None
 867     return _split(details)[0]
 868
 869   def edituser(self, user, key, value):
 870     """Set user information"""
 871     self._simple("edituser", user, key, value)
 872
 873   def users(self):
 874     """List all users
 875
 876     The return value is a list of all users."""
 877     self._simple("users")
 878     return self._body()
 879
 880   def register(self, username, password, email):
 881     """Register a user"""
 882     res, details = self._simple("register", username, password, email)
 883     return _split(details)[0]
 884
 885   def confirm(self, confirmation):
 886     """Confirm a user registration"""
 887     res, details = self._simple("confirm", confirmation)
 888
 889   ########################################################################
 890   # I/O infrastructure
 891
 892   def _line(self):
 893     # read one response line and return as some suitable string object
 894     #
 895     # If an I/O error occurs, disconnect from the server.
 896     #
 897     # XXX does readline() DTRT regarding character encodings?
 898     try:
 899       l = self.r.readline()
 900       if not re.search("\n", l):
 901         raise communicationError(self.who, "peer disconnected")
 902       l = l[:-1]
 903     except:
 904       self._disconnect()
 905       raise
 906     return unicode(l, "UTF-8")
 907
 908   def _response(self):
 909     # read a response as a (code, details) tuple
 910     l = self._line()
 911     self._debug(client.debug_proto, "<== %s" % l)
 912     m = _response.match(l)
 913     if m:
 914       return int(m.group(1)), m.group(2)
 915     else:
 916       raise protocolError(self.who, "invalid response %s")
 917
 918   def _send(self, *command):
 919     # Quote and send a command
 920     #
 921     # Returns the encoded command.
 922     quoted = _quote(command)
 923     self._debug(client.debug_proto, "==> %s" % quoted)
 924     encoded = quoted.encode("UTF-8")
 925     try:
 926       self.w.write(encoded)
 927       self.w.write("\n")
 928       self.w.flush()
 929       return encoded
 930     except IOError, e:
 931       # e.g. EPIPE
 932       self._disconnect()
 933       raise communicationError(self.who, e)
 934     except:
 935       self._disconnect()
 936       raise
 937
 938   def _simple(self, *command):
 939     # Issue a simple command, throw an exception on error
 940     #
 941     # If an I/O error occurs, disconnect from the server.
 942     #
 943     # On success or 'normal' errors returns response as a (code, details) tuple
 944     #
 945     # On error raise operationError
 946     if self.state == 'disconnected':
 947       self.connect()
 948     if command:
 949       cmd = self._send(*command)
 950     else:
 951       cmd = None
 952     res, details = self._response()
 953     if res / 100 == 2 or res == 555:
 954       return res, details
 955     raise operationError(res, details, cmd)
 956
 957   def _body(self):
 958     # Fetch a dot-stuffed body
 959     result = []
 960     while True:
 961       l = self._line()
 962       self._debug(client.debug_body, "<<< %s" % l)
 963       if l != '' and l[0] == '.':
 964         if l == '.':
 965           return result
 966         l = l[1:]
 967       result.append(l)
 968
 969   ########################################################################
 970   # Configuration file parsing
 971
 972   def _readfile(self, path):
 973     # Read a configuration file
 974     #
 975     # Arguments:
 976     #
 977     # path -- path of file to read
 978
 979     # handlers for various commands
 980     def _collection(self, command, args):
 981       if len(args) != 3:
 982         return "'%s' takes three args" % command
 983       self.config["collections"].append(args)
 984
 985     def _unary(self, command, args):
 986       if len(args) != 1:
 987         return "'%s' takes only one arg" % command
 988       self.config[command] = args[0]
 989
 990     def _include(self, command, args):
 991       if len(args) != 1:
 992         return "'%s' takes only one arg" % command
 993       self._readfile(args[0])
 994
 995     def _any(self, command, args):
 996       self.config[command] = args
 997
 998     # mapping of options to handlers
 999     _options = { "collection": _collection,
1000                  "username": _unary,
1001                  "password": _unary,
1002                  "home": _unary,
1003                  "connect": _any,
1004                  "include": _include }
1005
1006     # the parser
1007     for lno, line in enumerate(file(path, "r")):
1008       try:
1009         fields = _split(line, 'comments')
1010       except _splitError, s:
1011         raise parseError(path, lno + 1, str(s))
1012       if fields:
1013         command = fields[0]
1014         # we just ignore options we don't know about, so as to cope gracefully
1015         # with version skew (and nothing to do with implementor laziness)
1016         if command in _options:
1017           e = _options[command](self, command, fields[1:])
1018           if e:
1019             self._parseError(path, lno + 1, e)
1020
1021   def _parseError(self, path, lno, s):
1022     raise parseError(path, lno, s)
1023
1024 ########################################################################
1025 # monitor class
1026
1027 class monitor:
1028   """DisOrder event log monitor class
1029
1030   Intended to be subclassed with methods corresponding to event log messages
1031   the implementor cares about over-ridden."""
1032
1033   def __init__(self, c=None):
1034     """Constructor for the monitor class
1035
1036     Can be passed a client to use.  If none is specified then one
1037     will be created specially for the purpose.
1038
1039     Arguments:
1040     c -- client"""
1041     if c == None:
1042       c = client();
1043     self.c = c
1044
1045   def run(self):
1046     """Start monitoring logs.  Continues monitoring until one of the
1047     message-specific methods returns False.  Can be called more than once
1048     (but not recursively!)"""
1049     self.c.log(self._callback)
1050
1051   def when(self):
1052     """Return the timestamp of the current (or most recent) event log entry"""
1053     return self.timestamp
1054
1055   def _callback(self, c, line):
1056     try:
1057       bits = _split(line)
1058     except:
1059       return self.invalid(line)
1060     if(len(bits) < 2):
1061       return self.invalid(line)
1062     self.timestamp = int(bits[0], 16)
1063     keyword = bits[1]
1064     bits = bits[2:]
1065     if keyword == 'completed':
1066       if len(bits) == 1:
1067         return self.completed(bits[0])
1068     elif keyword == 'failed':
1069       if len(bits) == 2:
1070         return self.failed(bits[0], bits[1])
1071     elif keyword == 'moved':
1072       if len(bits) == 3:
1073         try:
1074           n = int(bits[1])
1075         except:
1076           return self.invalid(line)
1077         return self.moved(bits[0], n, bits[2])
1078     elif keyword == 'playing':
1079       if len(bits) == 1:
1080         return self.playing(bits[0], None)
1081       elif len(bits) == 2:
1082         return self.playing(bits[0], bits[1])
1083     elif keyword == 'queue' or keyword == 'recent-added':
1084       try:
1085         q = _list2dict(bits)
1086       except:
1087         return self.invalid(line)
1088       if keyword == 'queue':
1089         return self.queue(q)
1090       if keyword == 'recent-added':
1091         return self.recent_added(q)
1092     elif keyword == 'recent-removed':
1093       if len(bits) == 1:
1094         return self.recent_removed(bits[0])
1095     elif keyword == 'removed':
1096       if len(bits) == 1:
1097         return self.removed(bits[0], None)
1098       elif len(bits) == 2:
1099         return self.removed(bits[0], bits[1])
1100     elif keyword == 'scratched':
1101       if len(bits) == 2:
1102         return self.scratched(bits[0], bits[1])
1103     return self.invalid(line)
1104
1105   def completed(self, track):
1106     """Called when a track completes.
1107
1108     Arguments:
1109     track -- track that completed"""
1110     return True
1111
1112   def failed(self, track, error):
1113     """Called when a player suffers an error.
1114
1115     Arguments:
1116     track -- track that failed
1117     error -- error indicator"""
1118     return True
1119
1120   def moved(self, id, offset, user):
1121     """Called when a track is moved in the queue.
1122
1123     Arguments:
1124     id -- queue entry ID
1125     offset -- distance moved
1126     user -- user responsible"""
1127     return True
1128
1129   def playing(self, track, user):
1130     """Called when a track starts playing.
1131
1132     Arguments:
1133     track -- track that has started
1134     user -- user that submitted track, or None"""
1135     return True
1136
1137   def queue(self, q):
1138     """Called when a track is added to the queue.
1139
1140     Arguments:
1141     q -- dictionary of new queue entry"""
1142     return True
1143
1144   def recent_added(self, q):
1145     """Called when a track is added to the recently played list
1146
1147     Arguments:
1148     q -- dictionary of new queue entry"""
1149     return True
1150
1151   def recent_removed(self, id):
1152     """Called when a track is removed from the recently played list
1153
1154     Arguments:
1155     id -- ID of removed entry (always the oldest)"""
1156     return True
1157
1158   def removed(self, id, user):
1159     """Called when a track is removed from the queue, either manually
1160     or in order to play it.
1161
1162     Arguments:
1163     id -- ID of removed entry
1164     user -- user responsible (or None if we're playing this track)"""
1165     return True
1166
1167   def scratched(self, track, user):
1168     """Called when a track is scratched
1169
1170     Arguments:
1171     track -- track that was scratched
1172     user -- user responsible"""
1173     return True
1174
1175   def invalid(self, line):
1176     """Called when an event log line cannot be interpreted
1177
1178     Arguments:
1179     line -- line that could not be understood"""
1180     return True
1181
1182 # Local Variables:
1183 # mode:python
1184 # py-indent-offset:2
1185 # comment-column:40
1186 # fill-column:72
1187 # End: