py/tripe.py.in: More-or-less consistent quoting in docstrings.

diff --git a/py/tripe.py.in b/py/tripe.py.in
index fca38102500854181115a7c2ced84d48b20114e2..ac616ae82acb748efba11046f3c0a82c55bbec17 100644 (file)
--- a/py/tripe.py.in
+++ b/py/tripe.py.in
@@ -150,7 +150,7 @@ def readnonblockingly(sock, len):
   """
   Nonblocking read from SOCK.
 
   """
   Nonblocking read from SOCK.
 

-  Try to return LEN bytes.  If couldn't read anything, return None.  EOF is
+  Try to return LEN bytes.  If couldn't read anything, return `None'.  EOF is

   returned as an empty string.
   """
   try:
   returned as an empty string.
   """
   try:


@@ -212,7 +212,7 @@ class TripeConnection (object):
     Disconnect the physical connection.
 
     Invoke the `disconnected' method, giving the provided REASON, which
     Disconnect the physical connection.
 
     Invoke the `disconnected' method, giving the provided REASON, which

-    should be either None or an exception.
+    should be either `None' or an exception.

     """
     if not me.sock: return
     me.disconnected(reason)
     """
     if not me.sock: return
     me.disconnected(reason)


@@ -251,7 +251,7 @@ class TripeConnection (object):
 
     Call `line' on each complete line, and `eof' if the connection closed.
     Subclasses which attach this class to an I/O-event system should call
 
     Call `line' on each complete line, and `eof' if the connection closed.
     Subclasses which attach this class to an I/O-event system should call

-    this method when the socket (CONN.sock) is ready for reading.
+    this method when the socket (the `sock' attribute) is ready for reading.

     """
     while me.sock is not None:
       try:
     """
     while me.sock is not None:
       try:


@@ -301,7 +301,7 @@ class SelIOWatcher (object):
   Integration with mLib's I/O event system.
 
   You can replace this object with a different one for integration with,
   Integration with mLib's I/O event system.
 
   You can replace this object with a different one for integration with,

-  e.g., glib's main loop, by setting CONN.iowatcher to a different object
+  e.g., glib's main loop, by setting `CONN.iowatcher' to a different object

   while the CONN is disconnected.
   """
 
   while the CONN is disconnected.
   """
 


@@ -313,7 +313,7 @@ class SelIOWatcher (object):
     """
     Called when a connection is made.
 
     """
     Called when a connection is made.
 

-    SOCK is the socket.  The watcher must arrange to call CONN.receive when
+    SOCK is the socket.  The watcher must arrange to call `CONN.receive' when

     data is available.
     """
     me._selfile = M.SelFile(sock.fileno(), M.SEL_READ, me._conn.receive)
     data is available.
     """
     me._selfile = M.SelFile(sock.fileno(), M.SEL_READ, me._conn.receive)


@@ -331,7 +331,7 @@ class SelIOWatcher (object):
 
     That is, basically, do one iteration of a main select loop, processing
     all of the events, and then return.  This isn't needed for
 
     That is, basically, do one iteration of a main select loop, processing
     all of the events, and then return.  This isn't needed for

-    TripeCommandDispatcher, but runservices wants it.
+    `TripeCommandDispatcher', but `runservices' wants it.

     """
     M.select()
 
     """
     M.select()
 


@@ -439,8 +439,8 @@ class TripeCommand (object):
 
   Subclasses must implement a method to handle server responses:
 
 
   Subclasses must implement a method to handle server responses:
 

-    * response(CODE, *ARGS): CODE is one of the strings 'OK', 'INFO' or
-      'FAIL'; ARGS are the remaining tokens from the server's response.
+    * response(CODE, *ARGS): CODE is one of the strings `OK', `INFO' or
+      `FAIL'; ARGS are the remaining tokens from the server's response.

   """
 
   def __init__(me, words):
   """
 
   def __init__(me, words):


@@ -462,7 +462,7 @@ class TripeSynchronousCommand (TripeCommand):
   terminating response (`OK' or `FAIL') is received or become very
   confused.
 
   terminating response (`OK' or `FAIL') is received or become very
   confused.
 

-  Mostly it's better to use the TripeCommandIterator to do this
+  Mostly it's better to use the `TripeCommandIterator' to do this

   automatically.
   """
 
   automatically.
   """
 


@@ -477,7 +477,7 @@ class TripeSynchronousCommand (TripeCommand):
 
 class TripeError (StandardError):
   """
 
 class TripeError (StandardError):
   """

-  A tripe command failed with an error (a FAIL code).  The args attribute
+  A tripe command failed with an error (a `FAIL' code).  The args attribute

   contains a list of the server's message tokens.
   """
   pass
   contains a list of the server's message tokens.
   """
   pass


@@ -487,12 +487,12 @@ class TripeCommandIterator (object):
   Iterator interface to a tripe command.
 
   The values returned by the iterator are lists of tokens from the server's
   Iterator interface to a tripe command.
 
   The values returned by the iterator are lists of tokens from the server's

-  INFO lines, as processed by the given filter function, if any.  The
-  iterator completes normally (by raising StopIteration) if the server
-  reported OK, and raises an exception if the command failed for some reason.
+  `INFO' lines, as processed by the given filter function, if any.  The
+  iterator completes normally (by raising `StopIteration') if the server
+  reported `OK', and raises an exception if the command failed for some reason.

 
 

-  A TripeError is raised if the server issues a FAIL code.  If the connection
-  failed, some other exception is raised.
+  A `TripeError' is raised if the server issues a `FAIL' code.  If the
+  connection failed, some other exception is raised.

   """
 
   def __init__(me, dispatcher, words, bg = False, filter = None):
   """
 
   def __init__(me, dispatcher, words, bg = False, filter = None):


@@ -521,10 +521,10 @@ class TripeCommandIterator (object):
     """
     Iterator protocol: return the next piece of information from the server.
 
     """
     Iterator protocol: return the next piece of information from the server.
 

-    INFO responses are filtered and returned as the values of the iteration.
-    FAIL and CONNERR responses are turned into exceptions and raised.
-    Finally, OK is turned into StopIteration, which should cause a normal end
-    to the iteration process.
+    `INFO' responses are filtered and returned as the values of the
+    iteration.  `FAIL' and `CONNERR' responses are turned into exceptions and
+    raised.  Finally, `OK' is turned into `StopIteration', which should cause
+    a normal end to the iteration process.

     """
     thing = me.dcr.switch()
     code, rest = thing
     """
     thing = me.dcr.switch()
     code, rest = thing


@@ -551,7 +551,7 @@ def _tokenjoin(words):
   return ' '.join(words)
 
 def _keyvals(iter):
   return ' '.join(words)
 
 def _keyvals(iter):

-  """Return a dictionary formed from the KEY=VALUE pairs returned by the
+  """Return a dictionary formed from the `KEY=VALUE' pairs returned by the

   iterator ITER."""
   kv = {}
   for ww in iter:
   iterator ITER."""
   kv = {}
   for ww in iter:


@@ -589,10 +589,10 @@ def _tracelike(iter):
 
 def _kwopts(kw, allowed):
   """Parse keyword arguments into options.  ALLOWED is a list of allowable
 
 def _kwopts(kw, allowed):
   """Parse keyword arguments into options.  ALLOWED is a list of allowable

-  keywords; raise errors if other keywords are present.  KEY = VALUE becomes
-  an option pair -KEY VALUE if VALUE is a string, just the option -KEY if
-  VALUE is a true non-string, or nothing if VALUE is false..  Insert a `--'
-  at the end to stop the parser getting confused."""
+  keywords; raise errors if other keywords are present.  `KEY = VALUE'
+  becomes an option pair `-KEY VALUE' if VALUE is a string, just the option
+  `-KEY' if VALUE is a true non-string, or nothing if VALUE is false.  Insert
+  a `--' at the end to stop the parser getting confused."""

   opts = []
   amap = {}
   for a in allowed: amap[a] = True
   opts = []
   amap = {}
   for a in allowed: amap[a] = True


@@ -648,20 +648,20 @@ class TripeCommandDispatcher (TripeConnection):
   This is probably the most important class in this module to understand.
 
   Lines from the server are parsed into tokens.  The first token is a code
   This is probably the most important class in this module to understand.
 
   Lines from the server are parsed into tokens.  The first token is a code

-  (OK or NOTE or something) explaining what kind of line this is.  The
+  (`OK' or `NOTE' or something) explaining what kind of line this is.  The

   `handler' attribute is a dictionary mapping server line codes to handler
   functions, which are applied to the words of the line as individual
   `handler' attribute is a dictionary mapping server line codes to handler
   functions, which are applied to the words of the line as individual

-  arguments.  *Exception*: the content of TRACE lines is not tokenized.
+  arguments.  *Exception*: the content of `TRACE' lines is not tokenized.

 
   There are default handlers for server codes which respond to commands.
 
   There are default handlers for server codes which respond to commands.

-  Commands arrive as TripeCommand instances through the `rawcommand'
+  Commands arrive as `TripeCommand' instances through the `rawcommand'

   interface.  The dispatcher keeps track of which command objects represent
   which jobs, and sends responses on to the appropriate command objects by
   interface.  The dispatcher keeps track of which command objects represent
   which jobs, and sends responses on to the appropriate command objects by

-  invoking their `response' methods.  Command objects don't see the
-  BG... codes, because the dispatcher has already transformed them into
-  regular codes when it was looking up job code.
+  invoking their `response' methods.  Command objects don't see the `BG...'
+  codes, because the dispatcher has already transformed them into regular
+  codes when it was looking up the job tag.

 
 

-  The dispatcher also has a special response code of its own: CONNERR
+  The dispatcher also has a special response code of its own: `CONNERR'

   indicates that the connection failed and the command has therefore been
   lost.  This is sent to all outstanding commands when a connection error is
   encountered: rather than a token list, it is accompanied by an exception
   indicates that the connection failed and the command has therefore been
   lost.  This is sent to all outstanding commands when a connection error is
   encountered: rather than a token list, it is accompanied by an exception


@@ -741,7 +741,7 @@ class TripeCommandDispatcher (TripeConnection):
     Disconnection hook.
 
     If a subclass hooks overrides this method, it must call us; sends a
     Disconnection hook.
 
     If a subclass hooks overrides this method, it must call us; sends a

-    special CONNERR code to all incomplete commands.
+    special `CONNERR' code to all incomplete commands.

     """
     TripeConnection.disconnected(me, reason)
     for cmd in me.cmd.itervalues():
     """
     TripeConnection.disconnected(me, reason)
     for cmd in me.cmd.itervalues():


@@ -786,7 +786,7 @@ class TripeCommandDispatcher (TripeConnection):
 
   def _detach(me, _, tag):
     """
 
   def _detach(me, _, tag):
     """

-    Respond to a BGDETACH TAG message.
+    Respond to a `BGDETACH' TAG message.

 
     Move the current foreground command to the background.
     """
 
     Move the current foreground command to the background.
     """


@@ -796,10 +796,12 @@ class TripeCommandDispatcher (TripeConnection):
 
   def _response(me, code, tag, *w):
     """
 
   def _response(me, code, tag, *w):
     """

-    Respond to an OK, INFO or FAIL message.
+    Respond to an `OK', `INFO' or `FAIL' message.

 
     If this is a message for a background job, find the tag; then dispatch
 
     If this is a message for a background job, find the tag; then dispatch

-    the result to the command object.
+    the result to the command object.  This is also called by `_fgresponse'
+    (wth TAG set to `None') to handle responses for foreground commands, and
+    is therefore a useful method to extend or override in subclasses.

     """
     if code.startswith('BG'):
       code = code[2:]
     """
     if code.startswith('BG'):
       code = code[2:]


@@ -816,7 +818,7 @@ class TripeCommandDispatcher (TripeConnection):
 
   def rawcommand(me, cmd):
     """
 
   def rawcommand(me, cmd):
     """

-    Submit the TripeCommand CMD to the server, and look after it until it
+    Submit the `TripeCommand' CMD to the server, and look after it until it

     completes.
     """
     if not me.connectedp():
     completes.
     """
     if not me.connectedp():


@@ -932,8 +934,8 @@ class TripeAsynchronousCommand (TripeCommand):
   and associate the command with the queue.  Responses arriving for the
   command will be put on the queue as an triple of the form (TAG, CODE, REST)
   -- where TAG is an object of your choice, not interpreted by this class,
   and associate the command with the queue.  Responses arriving for the
   command will be put on the queue as an triple of the form (TAG, CODE, REST)
   -- where TAG is an object of your choice, not interpreted by this class,

-  CODE is the server's response code (OK, INFO, FAIL), and REST is the list
-  of the rest of the server's tokens.
+  CODE is the server's response code (`OK', `INFO', `FAIL', or `CONNERR'),
+  and REST is the list of the rest of the server's tokens.

 
   Using this, you can write coroutines which process many commands (and
   possibly other events) simultaneously.
 
   Using this, you can write coroutines which process many commands (and
   possibly other events) simultaneously.


@@ -984,15 +986,15 @@ class TripeServiceManager (TripeCommandDispatcher):
   There is usually only one instance of this class, called svcmgr.  Some of
   the support functions in this module assume that this is the case.
 
   There is usually only one instance of this class, called svcmgr.  Some of
   the support functions in this module assume that this is the case.
 

-  To use, run mLib.select in a loop until the quitp method returns true;
+  To use, run `mLib.select' in a loop until the quitp method returns true;

   then, in a non-root coroutine, register your services by calling `add', and
   then call `running' when you've finished setting up.
 
   then, in a non-root coroutine, register your services by calling `add', and
   then call `running' when you've finished setting up.
 

-  The instance handles server service messages SVCJOB, SVCCANCEL and
-  SVCCLAIM.  It maintains a table of running services.  Incoming jobs cause
-  the service's `job' method to be invoked; SVCCANCEL sends a
-  TripeJobCancelled exception to the handler coroutine, and SVCCLAIM causes
-  the relevant service to be deregistered.
+  The instance handles server service messages `SVCJOB', `SVCCANCEL' and
+  `SVCCLAIM'.  It maintains a table of running services.  Incoming jobs cause
+  the service's `job' method to be invoked; `SVCCANCEL' sends a
+  `TripeJobCancelled' exception to the handler coroutine, and `SVCCLAIM'
+  causes the relevant service to be deregistered.

 
   There is no base class for jobs, but a job must implement two methods:
 
 
   There is no base class for jobs, but a job must implement two methods:
 


@@ -1033,7 +1035,7 @@ class TripeServiceManager (TripeCommandDispatcher):
     me._quitp = 0
 
   def addsvc(me, svc):
     me._quitp = 0
 
   def addsvc(me, svc):

-    """Register a new service; SVC is a TripeService instance."""
+    """Register a new service; SVC is a `TripeService' instance."""

     assert svc.name not in me.svc
     me.svcclaim(svc.name, svc.version)
     me.svc[svc.name] = svc
     assert svc.name not in me.svc
     me.svcclaim(svc.name, svc.version)
     me.svc[svc.name] = svc


@@ -1092,8 +1094,8 @@ class TripeService (object):
   The NAME and VERSION are passed on to the server.  The CMDTAB is a
   dictionary mapping command names (in lowercase) to command objects.
 
   The NAME and VERSION are passed on to the server.  The CMDTAB is a
   dictionary mapping command names (in lowercase) to command objects.
 

-  If the CMDTAB doesn't have entries for commands HELP and QUIT then defaults
-  are provided.
+  If the CMDTAB doesn't have entries for commands `HELP' and `QUIT' then
+  defaults are provided.

 
   TripeService itself is mostly agnostic about the nature of command objects,
   but the TripeServiceJob class (below) has some requirements.  The built-in
 
   TripeService itself is mostly agnostic about the nature of command objects,
   but the TripeServiceJob class (below) has some requirements.  The built-in


@@ -1176,22 +1178,22 @@ class TripeServiceJob (Coroutine):
   """
   Job handler coroutine.
 
   """
   Job handler coroutine.
 

-  A standard TripeService invokes a TripeServiceJob for each incoming job
-  request, passing it the jobid, command and arguments, and a command
-  object.  The command object needs the following attributes.
+  A standard `TripeService' invokes a `TripeServiceJob' for each incoming job
+  request, passing it the jobid, command and arguments, and a command object.
+  The command object needs the following attributes.

 
   usage                 A usage list (excluding the command name) showing
                         arguments and options.
 
   run(*ARGS)            Function to react to the command with ARGS split into
                         separate arguments.  Invoked in a coroutine.  The
 
   usage                 A usage list (excluding the command name) showing
                         arguments and options.
 
   run(*ARGS)            Function to react to the command with ARGS split into
                         separate arguments.  Invoked in a coroutine.  The

-                        svcinfo function (not the TripeCommandDispatcher
-                        method) may be used to send INFO lines.  The function
-                        may raise TripeJobError to send a FAIL response back,
-                        or TripeSyntaxError to send a generic usage error.
-                        TripeJobCancelled exceptions are trapped silently.
-                        Other exceptions are translated into a generic
-                        internal-error message.
+                        `svcinfo function (not the `TripeCommandDispatcher'
+                        method) may be used to send `INFO' lines.  The
+                        function may raise `TripeJobError' to send a `FAIL'
+                        response back, or `TripeSyntaxError' to send a
+                        generic usage error.  `TripeJobCancelled' exceptions
+                        are trapped silently.  Other exceptions are
+                        translated into a generic internal-error message.

 
   This class automatically takes care of sending some closing response to the
   job, and for informing the service manager that the job is completed.
 
   This class automatically takes care of sending some closing response to the
   job, and for informing the service manager that the job is completed.


@@ -1205,7 +1207,7 @@ class TripeServiceJob (Coroutine):
 
     The job is created with id JID, for service SVC, processing command name
     CMD (which the service resolved into the command object COMMAND, or
 
     The job is created with id JID, for service SVC, processing command name
     CMD (which the service resolved into the command object COMMAND, or

-    None), and with the arguments ARGS.
+    `None'), and with the arguments ARGS.

     """
     Coroutine.__init__(me)
     me.jid = jid
     """
     Coroutine.__init__(me)
     me.jid = jid


@@ -1252,7 +1254,7 @@ class TripeServiceJob (Coroutine):
 
 def svcinfo(*args):
   """
 
 def svcinfo(*args):
   """

-  If invoked from a TripeServiceJob coroutine, sends an INFO line to the
+  If invoked from a TripeServiceJob coroutine, sends an `INFO' line to the

   job's sender, automatically using the correct job id.
   """
   svcmgr.svcinfo(Coroutine.getcurrent().jid, *args)
   job's sender, automatically using the correct job id.
   """
   svcmgr.svcinfo(Coroutine.getcurrent().jid, *args)


@@ -1282,13 +1284,13 @@ def runservices(socket, tab, init = None, setup = None, daemon = False):
 
     (NAME, VERSION, COMMANDS)
 
 
     (NAME, VERSION, COMMANDS)
 

-  or a service object (e.g., a TripeService instance).
+  or a service object (e.g., a `TripeService' instance).

 
   COMMANDS is a dictionary mapping command names to tuples
 
     (MIN, MAX, USAGE, FUNC)
 
 
   COMMANDS is a dictionary mapping command names to tuples
 
     (MIN, MAX, USAGE, FUNC)
 

-  of arguments for a TripeServiceCommand object.
+  of arguments for a `TripeServiceCommand' object.

 
   If DAEMON is true, then the process is forked into the background before we
   start.  If INIT is given, it is called in the main coroutine, immediately
 
   If DAEMON is true, then the process is forked into the background before we
   start.  If INIT is given, it is called in the main coroutine, immediately


@@ -1375,7 +1377,7 @@ class OptParse (object):
     """
     Iterator protocol: return the next option.
 
     """
     Iterator protocol: return the next option.
 

-    If we've run out, raise StopIteration.
+    If we've run out, raise `StopIteration'.

     """
     if len(me.args) == 0 or \
        len(me.args[0]) < 2 or \
     """
     if len(me.args) == 0 or \
        len(me.args[0]) < 2 or \


@@ -1392,7 +1394,7 @@ class OptParse (object):
     """
     Return the argument for the most recent option.
 
     """
     Return the argument for the most recent option.
 

-    If none is available, raise TripeSyntaxError.
+    If none is available, raise `TripeSyntaxError'.

     """
     if len(me.args) == 0:
       raise TripeSyntaxError
     """
     if len(me.args) == 0:
       raise TripeSyntaxError