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 .. automethod:: __len__
132 :class:`Message` -- A single message
133 ----------------------------------------
135 .. autoclass:: Message
137 .. automethod:: get_message_id
139 .. automethod:: get_thread_id
141 .. automethod:: get_replies
143 .. automethod:: get_filename
145 .. automethod:: get_filenames
150 This flag is automatically set by a
151 Query.search_threads on those messages that match the
152 query. This allows us to distinguish matches from the rest
153 of the messages in that thread.
155 .. automethod:: get_flag
157 .. automethod:: set_flag
159 .. automethod:: get_date
161 .. automethod:: get_header
163 .. automethod:: get_tags
165 .. automethod:: remove_tag
167 .. automethod:: add_tag
169 .. automethod:: remove_all_tags
171 .. automethod:: freeze
175 .. automethod:: format_as_text
177 .. automethod:: __str__
180 :class:`Tags` -- Notmuch tags
181 -----------------------------
186 .. automethod:: __len__
188 .. automethod:: __str__
191 :class:`notmuch.Threads` -- Threads iterator
192 -----------------------------------------------------
194 .. autoclass:: notmuch.Threads
196 .. automethod:: __len__
198 .. automethod:: __str__
200 :class:`Thread` -- A single thread
201 ------------------------------------
203 .. autoclass:: Thread
205 .. automethod:: get_thread_id
207 .. automethod:: get_total_messages
209 .. automethod:: get_toplevel_messages
211 .. automethod:: get_matched_messages
213 .. automethod:: get_authors
215 .. automethod:: get_subject
217 .. automethod:: get_oldest_date
219 .. automethod:: get_newest_date
221 .. automethod:: get_tags
223 .. automethod:: __str__
226 :class:`Filenames` -- An iterator over filenames
227 ------------------------------------------------
229 .. autoclass:: notmuch.database.Filenames
231 .. automethod:: notmuch.database.Filenames.__len__
233 :class:`notmuch.database.Directoy` -- A directory entry in the database
234 ------------------------------------------------------------------------
236 .. autoclass:: notmuch.database.Directory
238 .. automethod:: notmuch.database.Directory.get_child_files
240 .. automethod:: notmuch.database.Directory.get_child_directories
242 .. automethod:: notmuch.database.Directory.get_mtime
244 .. automethod:: notmuch.database.Directory.set_mtime
246 .. autoattribute:: notmuch.database.Directory.mtime
248 .. autoattribute:: notmuch.database.Directory.path
250 :exc:`NotmuchError` -- A Notmuch execution error
251 ------------------------------------------------
252 .. autoexception:: NotmuchError
255 This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
257 :class:`STATUS` -- Notmuch operation return status
258 --------------------------------------------------
262 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.
270 * DUPLICATE_MESSAGE_ID
273 * UNBALANCED_FREEZE_THAW