-.. cnotmuch documentation master file, created by
+.. notmuch documentation master file, created by
sphinx-quickstart on Tue Feb 2 10:00:47 2010.
-.. currentmodule:: cnotmuch.notmuch
+.. currentmodule:: notmuch
-Welcome to notmuch's documentation!
-===================================
+Welcome to :mod:`notmuch`'s documentation
+===========================================
-The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
-The classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :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. More information on specific topics can be found on the following pages: (none here yet)
+This page contains the main API overview of notmuch |release|.
-Notmuch can be imported as:
+Notmuch can be imported as::
- from cnotmuch import notmuch
+ import notmuch
-or:
+or::
- from cnotmuch.notmuch import Query,Database
+ from notmuch import Query,Database
+
+More information on specific topics can be found on the following pages:
.. toctree::
:maxdepth: 1
-
+ notmuch
:mod:`notmuch` -- The Notmuch interface
-=============================================
+=================================================
-Document from cnotmuch.globals import nmlib,STATUS,NotmuchError
+.. automodule:: notmuch
-:class:`Database` -- The underlying notmuch database
------------------------------------------------------
+:todo: Document nmlib,STATUS
-.. autoclass:: Database
- :members:
+:class:`notmuch.Database` -- The underlying notmuch database
+---------------------------------------------------------------------
-:class:`Query` -- Represents a notmuch Query
------------------------------------------------
+.. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
-.. autoclass:: Query
- :members:
+ .. automethod:: create
+
+ .. automethod:: open(path, status=MODE.READ_ONLY)
+
+ .. automethod:: get_path
+
+ .. automethod:: get_version
+
+ .. automethod:: needs_upgrade
+
+ .. automethod:: upgrade
+
+ .. automethod:: get_directory
+
+ .. automethod:: add_message
+
+ .. automethod:: remove_message
+
+ .. automethod:: find_message
+
+ .. automethod:: get_all_tags
+
+ .. automethod:: create_query
+
+ .. note:: :meth:`create_query` was broken in release
+ 0.1 and is fixed since 0.1.1.
+
+ .. 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
+
+ .. 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
- .. note:: A Thread is what a call to notmuch.show() will return, containing a bunch of :class:`Message`\ s.
:class:`Messages` -- A bunch of messages
----------------------------------------
.. autoclass:: Messages
- :members:
+
+ .. automethod:: collect_tags
+
+ .. automethod:: __len__
:class:`Message` -- A single message
----------------------------------------
.. autoclass:: Message
- :members:
-:class:`Tags` -- A bunch of notmuch tags
-----------------------------------------
+ .. 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:
- .. data: '__notmuchcmd__'
+ .. 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
- This is the actual binary that will be executed in order to run a notmuch command. This is set to *notmuch* and should usually not be changed.
+ .. 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
------------------------------------------------
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
==================
projects / notmuch / blobdiff