diff options
Diffstat (limited to 'bindings/python/docs/source')
| -rw-r--r-- | bindings/python/docs/source/conf.py | 22 | ||||
| -rw-r--r-- | bindings/python/docs/source/database.rst | 50 | ||||
| -rw-r--r-- | bindings/python/docs/source/filesystem.rst | 28 | ||||
| -rw-r--r-- | bindings/python/docs/source/index.rst | 284 | ||||
| -rw-r--r-- | bindings/python/docs/source/message.rst | 50 | ||||
| -rw-r--r-- | bindings/python/docs/source/messages.rst | 15 | ||||
| -rw-r--r-- | bindings/python/docs/source/notes.rst | 6 | ||||
| -rw-r--r-- | bindings/python/docs/source/notmuch.rst | 68 | ||||
| -rw-r--r-- | bindings/python/docs/source/query.rst | 41 | ||||
| -rw-r--r-- | bindings/python/docs/source/quickstart.rst | 19 | ||||
| -rw-r--r-- | bindings/python/docs/source/status_and_errors.rst | 6 | ||||
| -rw-r--r-- | bindings/python/docs/source/tags.rst | 17 | ||||
| -rw-r--r-- | bindings/python/docs/source/thread.rst | 26 | ||||
| -rw-r--r-- | bindings/python/docs/source/threads.rst | 10 |
14 files changed, 306 insertions, 336 deletions
diff --git a/bindings/python/docs/source/conf.py b/bindings/python/docs/source/conf.py index e0ee39c..9db377f 100644 --- a/bindings/python/docs/source/conf.py +++ b/bindings/python/docs/source/conf.py @@ -18,6 +18,24 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0,os.path.abspath('../..')) +class Mock(object): + def __init__(self, *args, **kwargs): + pass + + def __call__(self, *args, **kwargs): + return Mock() + + @classmethod + def __getattr__(self, name): + return Mock() if name not in ('__file__', '__path__') else '/dev/null' + +MOCK_MODULES = [ + 'ctypes', +] +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = Mock() + + from notmuch import __VERSION__,__AUTHOR__ # -- General configuration ----------------------------------------------------- @@ -39,8 +57,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'cnotmuch' -copyright = u'2010, ' + __AUTHOR__ +project = u'notmuch' +copyright = u'2010-2012, ' + __AUTHOR__ # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/bindings/python/docs/source/database.rst b/bindings/python/docs/source/database.rst new file mode 100644 index 0000000..2464bff --- /dev/null +++ b/bindings/python/docs/source/database.rst @@ -0,0 +1,50 @@ +:class:`Database` -- The underlying notmuch database +==================================================== + +.. currentmodule:: notmuch + +.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]]) + + .. automethod:: create + + .. automethod:: open(path, status=MODE.READ_ONLY) + + .. automethod:: close + + .. automethod:: get_path + + .. automethod:: get_version + + .. automethod:: needs_upgrade + + .. automethod:: upgrade + + .. automethod:: begin_atomic + + .. automethod:: end_atomic + + .. automethod:: get_directory + + .. automethod:: add_message + + .. automethod:: remove_message + + .. automethod:: find_message + + .. automethod:: find_message_by_filename + + .. automethod:: get_all_tags + + .. automethod:: create_query + + .. attribute:: Database.MODE + + Defines constants that are used as the mode in which to open a database. + + MODE.READ_ONLY + Open the database in read-only mode + + MODE.READ_WRITE + Open the database in read-write mode + + .. autoattribute:: db_p diff --git a/bindings/python/docs/source/filesystem.rst b/bindings/python/docs/source/filesystem.rst new file mode 100644 index 0000000..4eb7810 --- /dev/null +++ b/bindings/python/docs/source/filesystem.rst @@ -0,0 +1,28 @@ +Files and directories +===================== + +.. currentmodule:: notmuch + +:class:`Filenames` -- An iterator over filenames +------------------------------------------------ + +.. autoclass:: Filenames + + .. automethod:: Filenames.__len__ + +:class:`Directoy` -- A directory entry in the database +------------------------------------------------------ + +.. autoclass:: Directory + + .. automethod:: Directory.get_child_files + + .. automethod:: Directory.get_child_directories + + .. automethod:: Directory.get_mtime + + .. automethod:: Directory.set_mtime + + .. autoattribute:: Directory.mtime + + .. autoattribute:: Directory.path diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index f7d3d60..1cece5f 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -1,284 +1,36 @@ -.. notmuch documentation master file, created by - sphinx-quickstart on Tue Feb 2 10:00:47 2010. +Welcome to :mod:`notmuch`'s documentation +========================================= .. currentmodule:: notmuch -Welcome to :mod:`notmuch`'s documentation -=========================================== - -The :mod:`notmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library. -Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`. +The :mod:`notmuch` module provides an interface to the `notmuch +<http://notmuchmail.org>`_ functionality, directly interfacing to a +shared notmuch library. Within :mod:`notmuch`, the classes +:class:`Database`, :class:`Query` provide most of the core +functionality, returning :class:`Threads`, :class:`Messages` and +:class:`Tags`. .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de> :License: This module is covered under the GNU GPL v3 (or later). -This page contains the main API overview of notmuch |release|. - -Notmuch can be imported as:: - - import notmuch - -or:: - - from notmuch import Query, Database - - db = Database('path',create=True) - msgs = Query(db,'from:myself').search_messages() - - for msg in msgs: - print (msg) - -More information on specific topics can be found on the following pages: - .. toctree:: :maxdepth: 1 + quickstart + notes status_and_errors - notmuch - -:mod:`notmuch` -- The Notmuch interface -================================================= - -.. automodule:: notmuch - -: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 - - .. automethod:: get_version - - .. automethod:: needs_upgrade - - .. automethod:: upgrade - - .. automethod:: begin_atomic - - .. automethod:: end_atomic - - .. automethod:: get_directory - - .. automethod:: add_message - - .. automethod:: remove_message - - .. automethod:: find_message - - .. automethod:: find_message_by_filename - - .. automethod:: get_all_tags - - .. automethod:: create_query - - .. attribute:: Database.MODE - - Defines constants that are used as the mode in which to open a database. - - MODE.READ_ONLY - Open the database in read-only mode - - 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 - - .. method:: __len__() - - .. warning:: - - :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke - list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`. - -:class:`Message` -- A single message ----------------------------------------- - -.. autoclass:: Message - - .. automethod:: get_message_id - - .. automethod:: get_thread_id - - .. automethod:: get_replies - - .. automethod:: get_filename - - .. automethod:: get_filenames - - .. 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:: maildir_flags_to_tags - - .. automethod:: tags_to_maildir_flags - - .. automethod:: remove_tag - - .. automethod:: add_tag - - .. automethod:: remove_all_tags - - .. automethod:: freeze - - .. automethod:: thaw - - .. automethod:: format_message_as_json - - .. automethod:: format_message_as_text - - .. automethod:: __str__ - - -:class:`Tags` -- Notmuch tags ------------------------------ - -.. autoclass:: Tags - :members: - - .. method:: __len__ - - .. warning:: - - :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke - list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of - tags. - - .. 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 - - -The `next page <status_and_errors.html>`_ contains information on possible Status and Error values. + database + query + messages + message + tags + threads + thread + filesystem Indices and tables ================== * :ref:`genindex` * :ref:`search` - diff --git a/bindings/python/docs/source/message.rst b/bindings/python/docs/source/message.rst new file mode 100644 index 0000000..1a6cc3d --- /dev/null +++ b/bindings/python/docs/source/message.rst @@ -0,0 +1,50 @@ +:class:`Message` -- A single message +==================================== + +.. currentmodule:: notmuch + +.. autoclass:: Message + + .. automethod:: get_message_id + + .. automethod:: get_thread_id + + .. automethod:: get_replies + + .. automethod:: get_filename + + .. automethod:: get_filenames + + .. 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:: maildir_flags_to_tags + + .. automethod:: tags_to_maildir_flags + + .. automethod:: remove_tag + + .. automethod:: add_tag + + .. automethod:: remove_all_tags + + .. automethod:: freeze + + .. automethod:: thaw + + .. automethod:: __str__ diff --git a/bindings/python/docs/source/messages.rst b/bindings/python/docs/source/messages.rst new file mode 100644 index 0000000..3ccf505 --- /dev/null +++ b/bindings/python/docs/source/messages.rst @@ -0,0 +1,15 @@ +:class:`Messages` -- A bunch of messages +======================================== + +.. currentmodule:: notmuch + +.. autoclass:: Messages + + .. automethod:: collect_tags + + .. method:: __len__() + + .. warning:: + + :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke + list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`. diff --git a/bindings/python/docs/source/notes.rst b/bindings/python/docs/source/notes.rst new file mode 100644 index 0000000..a792748 --- /dev/null +++ b/bindings/python/docs/source/notes.rst @@ -0,0 +1,6 @@ +Interfacing with notmuch +======================== + +.. todo:: move the note about talloc out of the code + +.. automodule:: notmuch diff --git a/bindings/python/docs/source/notmuch.rst b/bindings/python/docs/source/notmuch.rst deleted file mode 100644 index 32e1783..0000000 --- a/bindings/python/docs/source/notmuch.rst +++ /dev/null @@ -1,68 +0,0 @@ -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. diff --git a/bindings/python/docs/source/query.rst b/bindings/python/docs/source/query.rst new file mode 100644 index 0000000..ddfc348 --- /dev/null +++ b/bindings/python/docs/source/query.rst @@ -0,0 +1,41 @@ +:class:`Query` -- A search query +================================ + +.. currentmodule:: notmuch + +.. autoclass:: 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 + + .. automethod:: count_threads diff --git a/bindings/python/docs/source/quickstart.rst b/bindings/python/docs/source/quickstart.rst new file mode 100644 index 0000000..609f42e --- /dev/null +++ b/bindings/python/docs/source/quickstart.rst @@ -0,0 +1,19 @@ +Quickstart and examples +======================= + +.. todo:: write a nice introduction +.. todo:: improve the examples + +Notmuch can be imported as:: + + import notmuch + +or:: + + from notmuch import Query, Database + + db = Database('path', create=True) + msgs = Query(db, 'from:myself').search_messages() + + for msg in msgs: + print(msg) diff --git a/bindings/python/docs/source/status_and_errors.rst b/bindings/python/docs/source/status_and_errors.rst index bc0d0d2..dd6e31f 100644 --- a/bindings/python/docs/source/status_and_errors.rst +++ b/bindings/python/docs/source/status_and_errors.rst @@ -5,6 +5,12 @@ Status and Errors Some methods return a status, indicating if an operation was successful and what the error was. Most of these status codes are expressed as a specific value, the :class:`notmuch.STATUS`. +.. note:: + + Prior to version 0.12 the exception classes and the enumeration + :class:`notmuch.STATUS` were defined in `notmuch.globals`. They + have since then been moved into `notmuch.errors`. + :class:`STATUS` -- Notmuch operation return value -------------------------------------------------- diff --git a/bindings/python/docs/source/tags.rst b/bindings/python/docs/source/tags.rst new file mode 100644 index 0000000..31527d4 --- /dev/null +++ b/bindings/python/docs/source/tags.rst @@ -0,0 +1,17 @@ +:class:`Tags` -- Notmuch tags +----------------------------- + +.. currentmodule:: notmuch + +.. autoclass:: Tags + :members: + + .. method:: __len__ + + .. warning:: + + :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke + list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of + tags. + + .. automethod:: __str__ diff --git a/bindings/python/docs/source/thread.rst b/bindings/python/docs/source/thread.rst new file mode 100644 index 0000000..4067872 --- /dev/null +++ b/bindings/python/docs/source/thread.rst @@ -0,0 +1,26 @@ +:class:`Thread` -- A single thread +================================== + +.. currentmodule:: notmuch + +.. 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__ diff --git a/bindings/python/docs/source/threads.rst b/bindings/python/docs/source/threads.rst new file mode 100644 index 0000000..e5a8c8a --- /dev/null +++ b/bindings/python/docs/source/threads.rst @@ -0,0 +1,10 @@ +:class:`Threads` -- Threads iterator +==================================== + +.. currentmodule:: notmuch + +.. autoclass:: Threads + + .. automethod:: __len__ + + .. automethod:: __str__ |