From 128555383f5fe6b879ac8b0d4b9fc9ec44c06ece Mon Sep 17 00:00:00 2001 From: Wojciech Polak Date: Sat, 29 Aug 2009 22:38:21 +0200 Subject: Update pydocs. * python/mailutils/__init__.py: Update pydocs. * python/mailutils/mailbox.py: Likewise. * python/mailutils/mailcap.py: Likewise. * python/mailutils/registrar.py: Likewise. * python/mailutils/sieve.py: Likewise. --- python/mailutils/__init__.py | 22 ++++++++++++++++++++++ python/mailutils/mailbox.py | 33 +++++++++++++++++++++++++++++---- python/mailutils/mailcap.py | 2 +- python/mailutils/registrar.py | 21 +++++++++++++++++++++ python/mailutils/sieve.py | 4 ++-- 5 files changed, 75 insertions(+), 7 deletions(-) diff --git a/python/mailutils/__init__.py b/python/mailutils/__init__.py index fb355a979..490fc3015 100644 --- a/python/mailutils/__init__.py +++ b/python/mailutils/__init__.py @@ -16,6 +16,28 @@ # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, # MA 02110-1301 USA +""" +A Python interface to Mailutils framework. + +GNU Mailutils is a rich and powerful protocol-independent mail +framework. It contains a series of useful mail libraries, clients, +and servers. These are the primary mail utilities for the GNU system. +The central library is capable of handling electronic mail in various +mailbox formats and protocols, both local and remote. Specifically, +this project contains a POP3 server, an IMAP4 server, and a Sieve mail +filter. It also provides a POSIX `mailx' client, and a collection of +other handy tools. + +This software is part of the GNU Project and belongs to the Free +Software Foundation. All libraries are licensed using the GNU LGPL. +The documentation is licensed under the GNU FDL, and everything else +is licensed using the GNU GPL. + +See http://www.gnu.org/software/mailutils/ for more information about +GNU Mailutils. + +""" + __all__ = [ "error", "address", diff --git a/python/mailutils/mailbox.py b/python/mailutils/mailbox.py index af4905a61..1eda85fd0 100644 --- a/python/mailutils/mailbox.py +++ b/python/mailutils/mailbox.py @@ -28,7 +28,19 @@ from mailutils.error import MailboxError class MailboxBase: def open (self, mode = 0): - """Open the connection.""" + """Open the connection. + + 'mode' may be a string, consisting of the characters described + below, giving the access mode for the mailbox. + + mode Meaning + -------------------------------------------------------- + r Open for reading. + w Open for writing. + a Open for appending to the end of the mailbox. + c Create the mailbox if it does not exist. + + """ if isinstance (mode, types.StringType): from mailutils import stream flags = 0 @@ -84,14 +96,14 @@ class MailboxBase: return unseen def get_message (self, msgno): - """Retrieve message number MSGNO.""" + """Retrieve message number 'msgno'.""" status, c_msg = mailbox.get_message (self.mbox, msgno) if status: raise MailboxError (status) return message.Message (c_msg) def append_message (self, msg): - """Append MSG to the mailbox.""" + """Append 'msg' to the mailbox.""" status = mailbox.append_message (self.mbox, msg.msg) if status: raise MailboxError (status) @@ -135,19 +147,21 @@ class MailboxBase: return size def get_folder (self): - """Get the FOLDER.""" + """Get the Folder object.""" status, fld = mailbox.get_folder (self.mbox) if status: raise MailboxError (status) return folder.Folder (fld) def get_debug (self): + """Get the Debug object.""" status, dbg = mailbox.get_debug (self.mbox) if status: raise MailboxError (status) return debug.Debug (dbg) def get_url (self): + """Get the Url object.""" status, u = mailbox.get_url (self.mbox) if status: raise MailboxError (status) @@ -206,6 +220,17 @@ class Mailbox (MailboxBase): class MailboxDefault (MailboxBase): def __init__ (self, name = None): + """MailboxDefault creates a Mailbox object for the supplied + mailbox 'name'. Before creating, the name is expanded using + the rules below: + + % --> system mailbox for the real uid + %user --> system mailbox for the given user + ~/file --> /home/user/file + ~user/file --> /home/user/file + +file --> /home/user/Mail/file + =file --> /home/user/Mail/file + """ self.mbox = mailbox.MailboxType () status = mailbox.create_default (self.mbox, name) if status: diff --git a/python/mailutils/mailcap.py b/python/mailutils/mailcap.py index e4e1bce92..14db0534c 100644 --- a/python/mailutils/mailcap.py +++ b/python/mailutils/mailcap.py @@ -59,7 +59,7 @@ class Mailcap: return count def get_entry (self, item): - """Return in MailcapEntry the mailcap entry of ITEM.""" + """Return in MailcapEntry the mailcap entry of 'item'.""" status, entry = mailcap.get_entry (self.mc, item) if status: raise MailcapError (status) diff --git a/python/mailutils/registrar.py b/python/mailutils/registrar.py index a68bd38a3..cb45708e1 100644 --- a/python/mailutils/registrar.py +++ b/python/mailutils/registrar.py @@ -22,6 +22,27 @@ import types from mailutils.c_api import registrar def register_format (name = None): + """Register desired mailutils 'name' format. + + A list or tuple of strings can be given. + Each element must be one of the following strings: + + Argument Meaning + -------------------------------------------------------------- + 'mbox' Regular UNIX mbox format + 'mh' MH mailbox format + 'maildir' Maildir mailbox format + 'pop' POP mailbox format + 'pops' POPS mailbox format + 'imap' IMAP mailbox format + 'imaps' IMAPS mailbox format + 'sendmail' sendmail mailer format + 'smtp' SMTP mailer format + + If called without arguments, the function registers all available + formats. + + """ if name == None: registrar.register_format () elif isinstance (name, types.TupleType) \ diff --git a/python/mailutils/sieve.py b/python/mailutils/sieve.py index 75e91ba68..38cbf6a0b 100644 --- a/python/mailutils/sieve.py +++ b/python/mailutils/sieve.py @@ -53,7 +53,7 @@ class Machine: raise SieveMachineError (status) def compile (self, name): - """Compile the sieve script from the file NAME.""" + """Compile the sieve script from the file 'name'.""" status = sieve.compile (self.mach, name) if status: raise SieveMachineError (status) @@ -73,7 +73,7 @@ class Machine: def message (self, msg): """Execute the code from the given instance of sieve machine - over the MSG.""" + over the 'msg'.""" status = sieve.message (self.mach, msg.msg) if status: raise SieveMachineError (status) -- cgit v1.2.1