1 .. notmuch documentation master file, created by
2 sphinx-quickstart on Tue Feb 2 10:00:47 2010.
4 .. currentmodule:: notmuch
6 Welcome to :mod:`notmuch`'s documentation
7 ===========================================
9 The :mod:`notmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
10 Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`.
12 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
14 :License: This module is covered under the GNU GPL v3 (or later).
16 This page contains the main API overview of notmuch |release|.
18 Notmuch can be imported as::
24 from notmuch import Query,Database
26 More information on specific topics can be found on the following pages:
33 :mod:`notmuch` -- The Notmuch interface
34 =================================================
36 .. automodule:: notmuch
38 :todo: Document nmlib,STATUS
40 :class:`notmuch.Database` -- The underlying notmuch database
41 ---------------------------------------------------------------------
43 .. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
45 .. automethod:: create
47 .. automethod:: open(path, status=MODE.READ_ONLY)
49 .. automethod:: get_path
51 .. automethod:: get_version
53 .. automethod:: needs_upgrade
55 .. automethod:: upgrade
57 .. automethod:: get_directory
59 .. automethod:: add_message
61 .. automethod:: remove_message
63 .. automethod:: find_message
65 .. automethod:: get_all_tags
67 .. automethod:: create_query
69 .. note:: :meth:`create_query` was broken in release
70 0.1 and is fixed since 0.1.1.
72 .. attribute:: Database.MODE
74 Defines constants that are used as the mode in which to open a database.
77 Open the database in read-only mode
80 Open the database in read-write mode
82 .. autoattribute:: db_p
84 :class:`notmuch.Query` -- A search query
85 -------------------------------------------------
87 .. autoclass:: notmuch.Query
89 .. automethod:: create
91 .. attribute:: Query.SORT
93 Defines constants that are used as the mode in which to open a database.
96 Sort by message date, oldest first.
99 Sort by message date, newest first.
102 Sort by email message ID.
105 Do not apply a special sort order (returns results in document id
108 .. automethod:: set_sort
112 Instance attribute :attr:`sort` contains the sort order (see
113 :attr:`Query.SORT`) if explicitely specified via
114 :meth:`set_sort`. By default it is set to `None`.
116 .. automethod:: search_threads
118 .. automethod:: search_messages
120 .. automethod:: count_messages
123 :class:`Messages` -- A bunch of messages
124 ----------------------------------------
126 .. autoclass:: Messages
128 .. automethod:: collect_tags
130 .. method:: __len__()
132 .. note:: :meth:`__len__` was removed in version 0.6 as it exhausted
133 the iterator and broke list(Messages()). Use the
134 :meth:`Query.count_messages` function or use
137 :class:`Message` -- A single message
138 ----------------------------------------
140 .. autoclass:: Message
142 .. automethod:: get_message_id
144 .. automethod:: get_thread_id
146 .. automethod:: get_replies
148 .. automethod:: get_filename
150 .. automethod:: get_filenames
155 This flag is automatically set by a
156 Query.search_threads on those messages that match the
157 query. This allows us to distinguish matches from the rest
158 of the messages in that thread.
160 .. automethod:: get_flag
162 .. automethod:: set_flag
164 .. automethod:: get_date
166 .. automethod:: get_header
168 .. automethod:: get_tags
170 .. automethod:: remove_tag
172 .. automethod:: add_tag
174 .. automethod:: remove_all_tags
176 .. automethod:: freeze
180 .. automethod:: format_as_text
182 .. automethod:: __str__
185 :class:`Tags` -- Notmuch tags
186 -----------------------------
191 .. automethod:: __len__
193 .. automethod:: __str__
196 :class:`notmuch.Threads` -- Threads iterator
197 -----------------------------------------------------
199 .. autoclass:: notmuch.Threads
201 .. automethod:: __len__
203 .. automethod:: __str__
205 :class:`Thread` -- A single thread
206 ------------------------------------
208 .. autoclass:: Thread
210 .. automethod:: get_thread_id
212 .. automethod:: get_total_messages
214 .. automethod:: get_toplevel_messages
216 .. automethod:: get_matched_messages
218 .. automethod:: get_authors
220 .. automethod:: get_subject
222 .. automethod:: get_oldest_date
224 .. automethod:: get_newest_date
226 .. automethod:: get_tags
228 .. automethod:: __str__
231 :class:`Filenames` -- An iterator over filenames
232 ------------------------------------------------
234 .. autoclass:: notmuch.database.Filenames
236 .. automethod:: notmuch.database.Filenames.__len__
238 :class:`notmuch.database.Directoy` -- A directory entry in the database
239 ------------------------------------------------------------------------
241 .. autoclass:: notmuch.database.Directory
243 .. automethod:: notmuch.database.Directory.get_child_files
245 .. automethod:: notmuch.database.Directory.get_child_directories
247 .. automethod:: notmuch.database.Directory.get_mtime
249 .. automethod:: notmuch.database.Directory.set_mtime
251 .. autoattribute:: notmuch.database.Directory.mtime
253 .. autoattribute:: notmuch.database.Directory.path
255 :exc:`NotmuchError` -- A Notmuch execution error
256 ------------------------------------------------
257 .. autoexception:: NotmuchError
260 This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
262 :class:`STATUS` -- Notmuch operation return status
263 --------------------------------------------------
267 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.
275 * DUPLICATE_MESSAGE_ID
278 * UNBALANCED_FREEZE_THAW