[Zope3-checkins] SVN: Zope3/trunk/src/zope/app/ Update doc strings to ReST

Phil Ruggera pruggera at san.rr.com
Wed Aug 4 02:05:39 EDT 2004


Log message for revision 26893:
  Update doc strings to ReST


Changed:
  U   Zope3/trunk/src/zope/app/location/__init__.py
  U   Zope3/trunk/src/zope/app/location/interfaces.py
  U   Zope3/trunk/src/zope/app/location/location.py
  U   Zope3/trunk/src/zope/app/location/pickling.py
  U   Zope3/trunk/src/zope/app/mail/delivery.py
  U   Zope3/trunk/src/zope/app/mail/event.py
  U   Zope3/trunk/src/zope/app/mail/interfaces.py
  U   Zope3/trunk/src/zope/app/mail/maildir.py
  U   Zope3/trunk/src/zope/app/mail/mailer.py
  U   Zope3/trunk/src/zope/app/mail/metaconfigure.py
  U   Zope3/trunk/src/zope/app/mail/metadirectives.py


-=-
Modified: Zope3/trunk/src/zope/app/location/__init__.py
===================================================================
--- Zope3/trunk/src/zope/app/location/__init__.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/location/__init__.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,7 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.app.location.location import Location, locate, LocationIterator
 from zope.app.location.location import inside, LocationProxy

Modified: Zope3/trunk/src/zope/app/location/interfaces.py
===================================================================
--- Zope3/trunk/src/zope/app/location/interfaces.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/location/interfaces.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from zope.interface import Interface, Attribute
 from zope import schema
 

Modified: Zope3/trunk/src/zope/app/location/location.py
===================================================================
--- Zope3/trunk/src/zope/app/location/location.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/location/location.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 import zope.interface
 from zope.app.location.interfaces import ILocation
 from zope.proxy import removeAllProxies
@@ -23,7 +25,7 @@
 from zope.app.decorator import DecoratedSecurityCheckerDescriptor
 
 class Location(object):
-    """Stupid mix-in that defines __parent__ and __name__ attributes
+    """Stupid mix-in that defines `__parent__` and `__name__` attributes
 
     Usage within an Object field:
     >>> from zope.interface import implements, Interface
@@ -123,7 +125,7 @@
     __doc__ = """Location-object proxy
 
     This is a non-picklable proxy that can be put around objects that
-    don't implement ILocation.
+    don't implement `ILocation`.
 
     >>> l = [1, 2, 3]
     >>> p = LocationProxy(l, "Dad", "p")

Modified: Zope3/trunk/src/zope/app/location/pickling.py
===================================================================
--- Zope3/trunk/src/zope/app/location/pickling.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/location/pickling.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,7 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.app.location.interfaces import ILocation
 from zope.app.location.location import Location, inside
@@ -26,7 +27,7 @@
 import zope.interface
 
 def locationCopy(loc):
-    """Return a copy of an object,, and anything in it
+    """Return a copy of an object, and anything in it
 
     If object in the location refer to objects outside of the
     location, then the copies of the objects in the location refer to
@@ -84,14 +85,14 @@
 class CopyPersistent(object):
     """Persistence hooks for copying locations
 
-    See locationCopy above.
+    See `locationCopy` above.
 
     We get initialized with an initial location:
 
     >>> o1 = Location()
     >>> persistent = CopyPersistent(o1)
 
-    We provide an id function that returns None when given a non-location:
+    We provide an `id` function that returns None when given a non-location:
 
     >>> persistent.id(42)
 
@@ -102,7 +103,7 @@
     >>> persistent.id(o2)
 
     But, if we get a location outside the original location, we assign
-    it an id and return the id:
+    it an `id` and return the `id`:
 
     >>> o3 = Location()
     >>> id3 = persistent.id(o3)
@@ -115,8 +116,8 @@
     >>> id4 is id3
     0
 
-    If we ask for the id of an outside location more than once, we
-    always get the same id back:
+    If we ask for the `id` of an outside location more than once, we
+    always get the same `id` back:
 
     >> persistent.id(o4) == id4
     1
@@ -159,16 +160,16 @@
 class PathPersistent(object):
     """Persistence hooks for pickling locations
 
-    See locationCopy above.
+    See `locationCopy` above.
 
     Unlike copy persistent, we use paths for ids of outside locations
     so that we can separate pickling and unpickling in time.  We have
     to compute paths and traverse objects to load paths, but paths can
-    be stored for later use, unlike the ids used by CopyPersistent.
+    be stored for later use, unlike the ids used by `CopyPersistent`.
 
-    We require outside locations that can be adapted to ITraversable.
+    We require outside locations that can be adapted to `ITraversable`.
     To simplify the example, we'll use a simple traversable location
-    defined in zope.app.location.tests, TLocation.
+    defined in `zope.app.location.tests`, `TLocation`.
 
     Normally, general adapters are used to make objects traversable.
 

Modified: Zope3/trunk/src/zope/app/mail/delivery.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/delivery.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/delivery.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -13,10 +13,12 @@
 ##############################################################################
 """Mail Delivery utility implementation
 
-This module contains various implementations of MailDeliverys.
+This module contains various implementations of `MailDeliverys`.
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 import rfc822
 import threading
 import logging
@@ -116,7 +118,7 @@
 
 class QueueProcessorThread(threading.Thread):
     """This thread is started at configuration time from the
-    mail:queuedDelivery directive handler.
+    `mail:queuedDelivery` directive handler.
     """
     log = logging.getLogger("QueueProcessorThread")
     __stopped = False
@@ -128,7 +130,7 @@
     def setMaildir(self, maildir):
         """Set the maildir.
 
-        This method is used just to provide a maildir stubs ."""
+        This method is used just to provide a `maildir` stubs ."""
         self.maildir = maildir
 
     def setQueuePath(self, path):
@@ -139,7 +141,7 @@
 
     def _parseMessage(self, message):
         """Extract fromaddr and toaddrs from the first two lines of
-        the message.
+        the `message`.
 
         Returns a fromaddr string, a toaddrs tuple and the message
         string.

Modified: Zope3/trunk/src/zope/app/mail/event.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/event.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/event.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from zope.interface import implements
 
 from zope.app.mail.interfaces import IMailSentEvent, IMailErrorEvent

Modified: Zope3/trunk/src/zope/app/mail/interfaces.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/interfaces.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/interfaces.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,22 +15,22 @@
 
 Email sending from Zope 3 applications works as follows:
 
-- A Zope 3 application locates a mail delivery utility ('IMailDelivery') and
+- A Zope 3 application locates a mail delivery utility (`IMailDelivery`) and
   feeds a message to it. It gets back a unique message ID so it can keep
-  track of the message by subscribing to 'IMailEvent' events.
+  track of the message by subscribing to `IMailEvent` events.
 
 - The utility registers with the transaction system to make sure the
   message is only sent when the transaction commits successfully.  (Among
-  other things this avoids duplicate messages on 'ConflictErrors'.)
+  other things this avoids duplicate messages on `ConflictErrors`.)
 
-- If the delivery utility is a 'IQueuedMailDelivery', it puts the message into
+- If the delivery utility is a `IQueuedMailDelivery`, it puts the message into
   a queue (a Maildir mailbox in the file system). A separate process or thread
-  ('IMailQueueProcessor') watches the queue and delivers messages
+  (`IMailQueueProcessor`) watches the queue and delivers messages
   asynchronously. Since the queue is located in the file system, it survives
   Zope restarts or crashes and the mail is not lost.  The queue processor
   can implement batching to keep the server load low.
 
-- If the delivery utility is a IDirectMailDelivery, it delivers messages
+- If the delivery utility is a `IDirectMailDelivery`, it delivers messages
   synchronously during the transaction commit.  This is not a very good idea,
   as it makes the user wait.  Note that transaction commits must not fail,
   but that is not a problem, because mail delivery problems dispatch an
@@ -40,21 +40,22 @@
   executed during the transaction commit phase.  There should be a way to
   start a new transaction for event processing after this one is commited.
 
-- An 'IMailQueueProcessor' or 'IDirectMailDelivery' actually delivers the
-  messages by using a mailer ('IMailer') component that encapsulates the
+- An `IMailQueueProcessor` or `IDirectMailDelivery` actually delivers the
+  messages by using a mailer (`IMailer`) component that encapsulates the
   delivery process.  There are currently two mailers:
 
-    - 'ISMTPMailer' sends all messages to a relay host using SMTP
+    - `ISMTPMailer` sends all messages to a relay host using SMTP
 
-    - 'ISendmailMailer' sends messages by calling an external process (usually
+    - `ISendmailMailer` sends messages by calling an external process (usually
       /usr/lib/sendmail on Unix systems).
 
-- If mail delivery succeeds, an 'IMailSentEvent' is dispatched by the mailer.
-  If mail delivery fails, no exceptions are raised, but an 'IMailErrorEvent' is
+- If mail delivery succeeds, an `IMailSentEvent` is dispatched by the mailer.
+  If mail delivery fails, no exceptions are raised, but an `IMailErrorEvent` is
   dispatched by the mailer.
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
 
 from zope.interface import Interface, Attribute
 from zope.schema import Object, TextLine, Int, Password, BytesLine
@@ -69,17 +70,17 @@
     def send(fromaddr, toaddrs, message):
         """Send an email message.
 
-        'fromaddr' is the sender address (byte string),
+        `fromaddr` is the sender address (byte string),
 
-        'toaddrs' is a sequence of recipient addresses (byte strings).
+        `toaddrs` is a sequence of recipient addresses (byte strings).
 
-        'message' is a byte string that contains both headers and body
+        `message` is a byte string that contains both headers and body
         formatted according to RFC 2822.  If it does not contain a Message-Id
         header, it will be generated and added automatically.
 
         Returns the message ID.
 
-        You can subscribe to IMailEvent events for notification about problems
+        You can subscribe to `IMailEvent` events for notification about problems
         or successful delivery.
 
         Messages are actually sent during transaction commit.
@@ -131,18 +132,18 @@
     def send(fromaddr, toaddrs, message):
         """Send an email message.
 
-        'fromaddr' is the sender address (unicode string),
+        `fromaddr` is the sender address (unicode string),
 
-        'toaddrs' is a sequence of recipient addresses (unicode strings).
+        `toaddrs` is a sequence of recipient addresses (unicode strings).
 
-        'message' contains both headers and body formatted according to RFC
+        `message` contains both headers and body formatted according to RFC
         2822.  It should contain at least Date, From, To, and Message-Id
         headers.
 
         Messages are sent immediatelly.
 
-        Dispatches an IMailSentEvent on successful delivery, otherwise an
-        IMailErrorEvent.
+        Dispatches an `IMailSentEvent` on successful delivery, otherwise an
+        `IMailErrorEvent`.
         """
 
 
@@ -201,20 +202,20 @@
 class IMaildirFactory(Interface):
 
     def __call__(dirname, create=False):
-        """Opens a Maildir folder at a given filesystem path.
+        """Opens a `Maildir` folder at a given filesystem path.
 
-        If 'create' is True, the folder will be created when it does not
-        exist.  If 'create' is False and the folder does not exist, an
-        exception (OSError) will be raised.
+        If `create` is ``True``, the folder will be created when it does not
+        exist.  If `create` is ``False`` and the folder does not exist, an
+        exception (``OSError``) will be raised.
 
         If path points to a file or an existing directory that is not a
-        valid Maildir folder, an exception is raised regardless of the
-        'create' argument.
+        valid `Maildir` folder, an exception is raised regardless of the
+        `create` argument.
         """
 
 
 class IMaildir(Interface):
-    """Read/write access to Maildir folders.
+    """Read/write access to `Maildir` folders.
 
     See http://www.qmail.org/man/man5/maildir.html for detailed format
     description.
@@ -225,48 +226,48 @@
         """
 
     def newMessage():
-        """Creates a new message in the maildir.
+        """Creates a new message in the `maildir`.
 
-        Returns a file-like object for a new file in the 'tmp' subdirectory
-        of the Maildir.  After writing message contents to it, call the
-        commit() or abort() method on it.
+        Returns a file-like object for a new file in the ``tmp`` subdirectory
+        of the `Maildir`.  After writing message contents to it, call the
+        ``commit()`` or ``abort()`` method on it.
 
-        The returned object implements IMaildirMessageWriter.
+        The returned object implements `IMaildirMessageWriter`.
         """
 
 
 class IMaildirMessageWriter(Interface):
-    """A file-like object to a new message in a Maildir."""
+    """A file-like object to a new message in a `Maildir`."""
 
     def write(str):
         """Writes a string to the file.
 
         There is no return value. Due to buffering, the string may not actually
-        show up in the file until the commit() method is called.
+        show up in the file until the ``commit()`` method is called.
         """
 
     def writelines(sequence):
         """Writes a sequence of strings to the file.
 
         The sequence can be any iterable object producing strings, typically a
-        list of strings. There is no return value.  'writelines' does not add
+        list of strings. There is no return value.  ``writelines`` does not add
         any line separators.
         """
 
     def commit():
-        """Commits the new message using the Maildir protocol.
+        """Commits the new message using the `Maildir` protocol.
 
         First, the message file is flushed, closed, then it is moved from
-        'tmp' into 'new' subdirectory of the maildir.
+        ``tmp`` into ``new`` subdirectory of the maildir.
 
-        Calling commit() more than once is allowed.
+        Calling ``commit()`` more than once is allowed.
         """
 
     def abort():
         """Aborts the new message.
 
-        The message file is closed and removed from the 'tmp' subdirectory
-        of the maildir.
+        The message file is closed and removed from the ``tmp`` subdirectory
+        of the `maildir`.
 
-        Calling abort() more than once is allowed.
+        Calling ``abort()`` more than once is allowed.
         """

Modified: Zope3/trunk/src/zope/app/mail/maildir.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/maildir.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/maildir.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -11,10 +11,12 @@
 # FOR A PARTICULAR PURPOSE.
 #
 ##############################################################################
-"""Read/write access to Maildir folders.
+"""Read/write access to `Maildir` folders.
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 import os
 import socket
 import time
@@ -25,13 +27,13 @@
      IMaildirFactory, IMaildir, IMaildirMessageWriter
 
 class Maildir(object):
-    """See zope.app.interfaces.mail.IMaildir"""
+    """See `zope.app.interfaces.mail.IMaildir`"""
 
     classProvides(IMaildirFactory)
     implements(IMaildir)
 
     def __init__(self, path, create=False):
-        "See zope.app.interfaces.mail.IMaildirFactory"
+        "See `zope.app.interfaces.mail.IMaildirFactory`"
         self.path = path
 
         def access(path):
@@ -54,7 +56,7 @@
             raise ValueError('%s is not a Maildir folder' % path)
 
     def __iter__(self):
-        "See zope.app.interfaces.mail.IMaildir"
+        "See `zope.app.interfaces.mail.IMaildir`"
         join = os.path.join
         subdir_cur = join(self.path, 'cur')
         subdir_new = join(self.path, 'new')
@@ -69,7 +71,7 @@
         return iter(new_messages + cur_messages)
 
     def newMessage(self):
-        "See zope.app.interfaces.mail.IMaildir"
+        "See `zope.app.interfaces.mail.IMaildir`"
         # NOTE: http://www.qmail.org/man/man5/maildir.html says, that the first
         #       step of the delivery process should be a chdir.  Chdirs and
         #       threading do not mix.  Is that chdir really necessary?
@@ -96,7 +98,7 @@
 
 
 class MaildirMessageWriter(object):
-    """See zope.app.interfaces.mail.IMaildirMessageWriter"""
+    """See `zope.app.interfaces.mail.IMaildirMessageWriter`"""
 
     implements(IMaildirMessageWriter)
 

Modified: Zope3/trunk/src/zope/app/mail/mailer.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/mailer.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/mailer.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -17,6 +17,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from os import popen
 from smtplib import SMTP
 

Modified: Zope3/trunk/src/zope/app/mail/metaconfigure.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/metaconfigure.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/metaconfigure.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from zope.configuration.exceptions import ConfigurationError
 
 from zope.security.checker import InterfaceChecker, CheckerPublic

Modified: Zope3/trunk/src/zope/app/mail/metadirectives.py
===================================================================
--- Zope3/trunk/src/zope/app/mail/metadirectives.py	2004-08-04 05:10:21 UTC (rev 26892)
+++ Zope3/trunk/src/zope/app/mail/metadirectives.py	2004-08-04 06:05:38 UTC (rev 26893)
@@ -15,6 +15,8 @@
 
 $Id$
 """
+__docformat__ = 'restructuredtext'
+
 from zope.configuration.fields import Path
 from zope.interface import Interface
 from zope.schema import TextLine, ASCII, BytesLine, Int



More information about the Zope3-Checkins mailing list