[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