[PATCH 14/17] Improve in-code documentation
Sebastian Spaeth
Sebastian at SSpaeth.de
Mon Nov 29 16:02:22 GMT 2010
Signed-off-by: Sebastian Spaeth <Sebastian at SSpaeth.de>
---
docs/source/index.rst | 237 ++++------------------------------------
docs/source/offlineimap.rst | 142 +++++++++++++------------
offlineimap/__init__.py | 3 +-
offlineimap/accounts.py | 10 ++
offlineimap/folder/Base.py | 14 ++-
offlineimap/repository/Base.py | 4 +-
offlineimap/ui/detector.py | 2 +-
7 files changed, 122 insertions(+), 290 deletions(-)
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 457019c..dff8620 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -5,8 +5,9 @@
Welcome to :mod:`offlineimaps`'s documentation
===========================================
-The :mod:`offlineimap` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
-Within :mod:`notmuch`, the classes :class:`OfflineImap` provides the high-level functionality. :class:`Repository` provide most of the core functionality, returning :class:`Folder`.
+The :mod:`offlineimap` module provides the user interface for synchronization between IMAP servers and MailDirs or between IMAP servers. The homepage containing the source code repository can be found at the `offlineimap wiki <https://github.com/spaetz/offlineimap/wiki>`_.
+
+Within :mod:`offlineimap`, the classes :class:`OfflineImap` provides the high-level functionality. The rest of the classes should usually not needed to be touched by the user. A folder is represented by a :class:`offlineimap.folder.Base.BaseFolder` or any derivative :mod:`offlineimap.folder`.
.. moduleauthor:: John Goerzen, Sebastian Spaeth <Sebastian at SSpaeth.de>
@@ -16,7 +17,7 @@ This page contains the main API overview of OfflineImap |release|.
Notmuch can be imported as::
- import OfflineImap
+ from offlineimap import OfflineImap
More information on specific topics can be found on the following pages:
@@ -25,46 +26,36 @@ More information on specific topics can be found on the following pages:
offlineimap
-:mod:`notmuch` -- The Notmuch interface
+:mod:`offlineimap` -- The OfflineImap module
=================================================
.. automodule:: offlineimap
-:todo: Document nmlib,STATUS
-
-:class:`notmuch.Database` -- The underlying notmuch database
----------------------------------------------------------------------
-
-.. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
-
- .. automethod:: create
-
- .. automethod:: open(path, status=MODE.READ_ONLY)
-
- .. automethod:: get_path
+.. autoclass:: offlineimap.OfflineImap(cmdline_opts = None)
- .. automethod:: get_version
+ .. automethod:: parse_commandline
- .. automethod:: needs_upgrade
+ .. automethod:: write_pidfile
- .. automethod:: upgrade
+ .. automethod:: delete_pidfile
- .. automethod:: get_directory
+ .. automethod:: lock
- .. automethod:: add_message
+ .. automethod:: unlock
- .. automethod:: remove_message
+ .. autoattribute:: ui
- .. automethod:: find_message
+ :todo: Document
- .. automethod:: get_all_tags
+:mod:`offlineimap.folder` -- Basic representation of a local or remote Mail folder
+---------------------------------------------------------------------------------------------------------
- .. automethod:: create_query
-
- .. note:: :meth:`create_query` was broken in release
- 0.1 and is fixed since 0.1.1.
+.. autoclass:: offlineimap.folder.Base.BaseFolder
+ :members:
+ :inherited-members:
- .. attribute:: Database.MODE
+.. .. note:: :meth:`foo`
+.. .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database.
@@ -74,198 +65,14 @@ More information on specific topics can be found on the following pages:
MODE.READ_WRITE
Open the database in read-write mode
- .. autoattribute:: db_p
-
-:class:`notmuch.Query` -- A search query
--------------------------------------------------
-
-.. autoclass:: notmuch.Query
-
- .. automethod:: create
-
- .. attribute:: Query.SORT
-
- Defines constants that are used as the mode in which to open a database.
-
- SORT.OLDEST_FIRST
- Sort by message date, oldest first.
-
- SORT.NEWEST_FIRST
- Sort by message date, newest first.
-
- SORT.MESSAGE_ID
- Sort by email message ID.
-
- SORT.UNSORTED
- Do not apply a special sort order (returns results in document id
- order).
-
- .. automethod:: set_sort
-
- .. attribute:: sort
-
- Instance attribute :attr:`sort` contains the sort order (see
- :attr:`Query.SORT`) if explicitely specified via
- :meth:`set_sort`. By default it is set to `None`.
-
- .. automethod:: search_threads
-
- .. automethod:: search_messages
-
- .. automethod:: count_messages
-
-
-:class:`Messages` -- A bunch of messages
-----------------------------------------
-
-.. autoclass:: Messages
-
- .. automethod:: collect_tags
-
- .. automethod:: __len__
-
-:class:`Message` -- A single message
-----------------------------------------
-
-.. autoclass:: Message
-
- .. automethod:: get_message_id
-
- .. automethod:: get_thread_id
-
- .. automethod:: get_replies
-
- .. automethod:: get_filename
-
- .. attribute:: FLAG
-
- FLAG.MATCH
- This flag is automatically set by a
- Query.search_threads on those messages that match the
- query. This allows us to distinguish matches from the rest
- of the messages in that thread.
-
- .. automethod:: get_flag
-
- .. automethod:: set_flag
-
- .. automethod:: get_date
-
- .. automethod:: get_header
-
- .. automethod:: get_tags
-
- .. automethod:: remove_tag
-
- .. automethod:: add_tag
-
- .. automethod:: remove_all_tags
- .. automethod:: freeze
-
- .. automethod:: thaw
-
- .. automethod:: format_as_text
-
- .. automethod:: __str__
-
-
-:class:`Tags` -- Notmuch tags
------------------------------
-
-.. autoclass:: Tags
- :members:
-
- .. automethod:: __len__
-
- .. automethod:: __str__
-
-
-:class:`notmuch.Threads` -- Threads iterator
------------------------------------------------------
-
-.. autoclass:: notmuch.Threads
-
- .. automethod:: __len__
-
- .. automethod:: __str__
-
-:class:`Thread` -- A single thread
-------------------------------------
-
-.. autoclass:: Thread
-
- .. automethod:: get_thread_id
-
- .. automethod:: get_total_messages
-
- .. automethod:: get_toplevel_messages
-
- .. automethod:: get_matched_messages
-
- .. automethod:: get_authors
-
- .. automethod:: get_subject
-
- .. automethod:: get_oldest_date
-
- .. automethod:: get_newest_date
-
- .. automethod:: get_tags
-
- .. automethod:: __str__
-
-
-:class:`Filenames` -- An iterator over filenames
-------------------------------------------------
-
-.. autoclass:: notmuch.database.Filenames
-
- .. automethod:: notmuch.database.Filenames.__len__
-
-:class:`notmuch.database.Directoy` -- A directory entry in the database
-------------------------------------------------------------------------
-
-.. autoclass:: notmuch.database.Directory
-
- .. automethod:: notmuch.database.Directory.get_child_files
-
- .. automethod:: notmuch.database.Directory.get_child_directories
-
- .. automethod:: notmuch.database.Directory.get_mtime
-
- .. automethod:: notmuch.database.Directory.set_mtime
-
- .. autoattribute:: notmuch.database.Directory.mtime
-
- .. autoattribute:: notmuch.database.Directory.path
-
-:exc:`NotmuchError` -- A Notmuch execution error
+:exc:`OfflineImapException` -- A Notmuch execution error
------------------------------------------------
-.. autoexception:: NotmuchError
+.. autoexception:: offlineimap.OfflineImapException
:members:
This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
-:class:`STATUS` -- Notmuch operation return status
---------------------------------------------------
-
-.. data:: STATUS
-
- STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.
-
- * SUCCESS
- * OUT_OF_MEMORY
- * READ_ONLY_DATABASE
- * XAPIAN_EXCEPTION
- * FILE_ERROR
- * FILE_NOT_EMAIL
- * DUPLICATE_MESSAGE_ID
- * NULL_POINTER
- * TAG_TOO_LONG
- * UNBALANCED_FREEZE_THAW
- * NOT_INITIALIZED
-
Indices and tables
==================
diff --git a/docs/source/offlineimap.rst b/docs/source/offlineimap.rst
index 32e1783..f206c11 100644
--- a/docs/source/offlineimap.rst
+++ b/docs/source/offlineimap.rst
@@ -1,68 +1,74 @@
-The notmuch 'binary'
-====================
-
-The cnotmuch module provides *notmuch*, a python reimplementation of the standard notmuch binary for two purposes: first, to allow running the standard notmuch testsuite over the cnotmuch bindings (for correctness and performance testing) and second, to give some examples as to how to use cnotmuch. 'Notmuch' provides a command line interface to your mail database.
-
-A standard install via `easy_install cnotmuch` will not install the notmuch binary, however it is available in the `cnotmuch source code repository <http://bitbucket.org/spaetz/cnotmuch/src/>`_.
-
-
-It is invoked with the following pattern: `notmuch <command> [args...]`.
-
-Where <command> and [args...] are as follows:
-
- **setup** Interactively setup notmuch for first use.
- This has not yet been implemented, and will probably not be
- implemented unless someone puts in the effort.
-
- **new** [--verbose]
- Find and import new messages to the notmuch database.
-
- This has not been implemented yet. We cheat by calling
- the regular "notmuch" binary (which must be in your path
- somewhere).
-
- **search** [options...] <search-terms> [...] Search for messages matching the given search terms.
-
- This has been implemented but for the `--format` and
- `--sort` options.
-
- **show** <search-terms> [...]
- Show all messages matching the search terms.
-
- This has been partially implemented, we show a stub for each
- found message, but do not output the full message body yet.
-
- **count** <search-terms> [...]
- Count messages matching the search terms.
-
- This has been fully implemented.
-
- **reply** [options...] <search-terms> [...]
- Construct a reply template for a set of messages.
-
- This has not been implemented yet.
-
- **tag** +<tag>|-<tag> [...] [--] <search-terms> [...]
- Add/remove tags for all messages matching the search terms.
-
- This has been fully implemented.
-
- **dump** [<filename>]
- Create a plain-text dump of the tags for each message.
-
- This has been fully implemented.
- **restore** <filename>
- Restore the tags from the given dump file (see 'dump').
-
- This has been fully implemented.
-
- **search-tags** [<search-terms> [...] ]
- List all tags found in the database or matching messages.
-
- This has been fully implemented.
-
- **help** [<command>]
- This message, or more detailed help for the named command.
-
- The 'help' page has been implemented, help for single
- commands are missing though. Patches are welcome.
+The offlineimap 'binary'
+========================
+
+Offlineimap is invoked with the following pattern: `offlineimap [args...]`.
+
+Where [args...] are as follows:
+
+Options:
+ --version show program's version number and exit
+ -h, --help show this help message and exit
+ -1 Disable all multithreading operations and use solely a
+ single-thread sync. This effectively sets the
+ maxsyncaccounts and all maxconnections configuration
+ file variables to 1.
+ -P DIR Sets OfflineIMAP into profile mode. The program will
+ create DIR (it must not already exist). As it runs,
+ Python profiling information about each thread is
+ logged into profiledir. Please note: This option is
+ present for debugging and optimization only, and
+ should NOT be used unless you have a specific reason
+ to do so. It will significantly slow program
+ performance, may reduce reliability, and can generate
+ huge amounts of data. This option implies the
+ singlethreading option (-1).
+ -a ACCOUNTS Overrides the accounts section in the config file.
+ Lets you specify a particular account or set of
+ accounts to sync without having to edit the config
+ file. You might use this to exclude certain accounts,
+ or to sync some accounts that you normally prefer not
+ to.
+ -c FILE Specifies a configuration file to use in lieu of
+ ~/.offlineimaprc.
+
+ -d type1,[type2...] Enables debugging for OfflineIMAP. This is useful if
+ you are trying to track down a malfunction or figure
+ out what is going on under the hood. I suggest that
+ you use this with -1 in order to make the results more
+ sensible. This option requires one or more debugtypes,
+ separated by commas. These define what exactly will
+ be debugged, and so far include the options: imap,
+ thread,maildir or ALL. The imap option will enable
+ IMAP protocol stream and parsing debugging. Note that
+ the output may contain passwords, so take care to
+ remove that from the debugging output before sending
+ it to anyone else. The maildir option will enable
+ debugging for certain Maildir operations.
+
+ -l FILE Log to FILE
+
+ -f folder1,[folder2...]
+ Only sync the specified folders. The 'folder's are the
+ *untranslated* foldernames. This command-line option
+ overrides any 'folderfilter' and 'folderincludes'
+ options in the configuration file.
+
+ -k `[section:]option=value`
+ Override configuration file option. If"section" is
+ omitted, it defaults to "general". Any underscores
+ "_" in the section name are replaced with spaces:
+ for instance, to override option "autorefresh" in
+ the "[Account Personal]" section in the config file
+ one would use "-k Account_Personal:autorefresh=30".
+
+ -o Run only once, ignoring any autorefresh setting in the
+ configuration file.
+ -q Run only quick synchronizations. Ignore any flag
+ updates on IMAP servers.
+ -u INTERFACE Specifies an alternative user interface to use. This
+ overrides the default specified in the configuration
+ file. The UI specified with -u will be forced to be
+ used, even if checks determine that it is not usable.
+ Possible interface choices are: Curses.Blinkenlights,
+ TTY.TTYUI, Noninteractive.Basic, Noninteractive.Quiet,
+ Machine.MachineUI
diff --git a/offlineimap/__init__.py b/offlineimap/__init__.py
index 660dd16..62cce11 100644
--- a/offlineimap/__init__.py
+++ b/offlineimap/__init__.py
@@ -15,7 +15,8 @@ banner = __bigcopyright__ + """
This software comes with ABSOLUTELY NO WARRANTY; see the file
COPYING for details. This is free software, and you are welcome
-to distribute it under the conditions laid out in COPYING."""
+to distribute it under the conditions laid out in COPYING.
+"""
__homepage__ = "http://github.com/spaetz/offlineimap"
__license__ = "Licensed under the GNU GPL v2+ (v2 or any later version)."
diff --git a/offlineimap/accounts.py b/offlineimap/accounts.py
index b4dd135..2f1e9f4 100644
--- a/offlineimap/accounts.py
+++ b/offlineimap/accounts.py
@@ -99,12 +99,21 @@ def AccountListGenerator(customconfig):
def AccountHashGenerator(customconfig):
retval = {}
for item in AccountListGenerator(customconfig):
+ # item is a class:`Account`
retval[item.getname()] = item
return retval
mailboxes = []
class Account(CustomConfig.ConfigHelperMixin):
+ """IMAP account base class.
+
+ If you need a syncable account, use class:`SyncableAccount`..
+
+ ConfigHelperMixin requires a class to provide the getconfig() and
+ getsection() functions and allows calls such as
+ getconfint(option[, default])."""
+
def __init__(self, config, name):
self.config = config
self.name = name
@@ -123,6 +132,7 @@ class Account(CustomConfig.ConfigHelperMixin):
return self.config
def getname(self):
+ """Return name of the account."""
return self.name
def getsection(self):
diff --git a/offlineimap/folder/Base.py b/offlineimap/folder/Base.py
index 897bb54..289d2ac 100644
--- a/offlineimap/folder/Base.py
+++ b/offlineimap/folder/Base.py
@@ -24,14 +24,22 @@ import os.path, re
import sys
class BaseFolder:
+ """Basic representation of a mail folder in either an IMAP server or on a Maildir.
+
+ This class provides common functinoality for all implementations
+ and would rarely be directly used, but rather be inherited by any of the Implementation classes, such as
+ :class:`offlineimap.folder.IMAP.IMAPFolder` """
+
def __init__(self):
self.uidlock = Lock()
self.cachedMessageList = False
"""whether we already got and cached the message list"""
self.messagelist = {}
-
- def getname(self):
- """Returns name"""
+ """populated with {UID: ('FIXME')}"""
+
+ @property
+ def name(self):
+ """Returns name of the folder"""
return self.name
def suggeststhreads(self):
diff --git a/offlineimap/repository/Base.py b/offlineimap/repository/Base.py
index 45a20cc..ed0b1a8 100644
--- a/offlineimap/repository/Base.py
+++ b/offlineimap/repository/Base.py
@@ -132,11 +132,11 @@ class BaseRepository(CustomConfig.ConfigHelperMixin):
It does NOT sync the contents of those folders.
For every time dest.makefolder() is called, also call makefolder()
- on each folder in copyfolders."""
+ on each folder in copyfolders.
+ :param dest: a repository implementations, e.g. class:`MaildirRepository`"""
src = self
srcfolders = src.getfolders()
destfolders = dest.getfolders()
-
# Create hashes with the names, but convert the source folders
# to the dest folder's sep.
diff --git a/offlineimap/ui/detector.py b/offlineimap/ui/detector.py
index 4ec7503..8071636 100644
--- a/offlineimap/ui/detector.py
+++ b/offlineimap/ui/detector.py
@@ -1,4 +1,4 @@
-# UI base class
+# available UI detection
# Copyright (C) 2002 John Goerzen
# <jgoerzen at complete.org>
#
--
1.7.1
More information about the OfflineIMAP-project
mailing list