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:
34 :mod:`notmuch` -- The Notmuch interface
35 =================================================
37 .. automodule:: notmuch
39 :todo: Document nmlib,STATUS
41 :class:`notmuch.Database` -- The underlying notmuch database
42 ---------------------------------------------------------------------
44 .. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
46 .. automethod:: create
48 .. automethod:: open(path, status=MODE.READ_ONLY)
50 .. automethod:: get_path
52 .. automethod:: get_version
54 .. automethod:: needs_upgrade
56 .. automethod:: upgrade
58 .. automethod:: begin_atomic
60 .. automethod:: end_atomic
62 .. automethod:: get_directory
64 .. automethod:: add_message
66 .. automethod:: remove_message
68 .. automethod:: find_message
70 .. automethod:: find_message_by_filename
72 .. automethod:: get_all_tags
74 .. automethod:: create_query
76 .. note:: :meth:`create_query` was broken in release
77 0.1 and is fixed since 0.1.1.
79 .. attribute:: Database.MODE
81 Defines constants that are used as the mode in which to open a database.
84 Open the database in read-only mode
87 Open the database in read-write mode
89 .. autoattribute:: db_p
91 :class:`notmuch.Query` -- A search query
92 -------------------------------------------------
94 .. autoclass:: notmuch.Query
96 .. automethod:: create
98 .. attribute:: Query.SORT
100 Defines constants that are used as the mode in which to open a database.
103 Sort by message date, oldest first.
106 Sort by message date, newest first.
109 Sort by email message ID.
112 Do not apply a special sort order (returns results in document id
115 .. automethod:: set_sort
119 Instance attribute :attr:`sort` contains the sort order (see
120 :attr:`Query.SORT`) if explicitely specified via
121 :meth:`set_sort`. By default it is set to `None`.
123 .. automethod:: search_threads
125 .. automethod:: search_messages
127 .. automethod:: count_messages
130 :class:`Messages` -- A bunch of messages
131 ----------------------------------------
133 .. autoclass:: Messages
135 .. automethod:: collect_tags
137 .. method:: __len__()
139 .. warning:: :meth:`__len__` was removed in version 0.6 as it exhausted
140 the iterator and broke list(Messages()). Use the
141 :meth:`Query.count_messages` function or use
144 :class:`Message` -- A single message
145 ----------------------------------------
147 .. autoclass:: Message
149 .. automethod:: get_message_id
151 .. automethod:: get_thread_id
153 .. automethod:: get_replies
155 .. automethod:: get_filename
157 .. automethod:: get_filenames
162 This flag is automatically set by a
163 Query.search_threads on those messages that match the
164 query. This allows us to distinguish matches from the rest
165 of the messages in that thread.
167 .. automethod:: get_flag
169 .. automethod:: set_flag
171 .. automethod:: get_date
173 .. automethod:: get_header
175 .. automethod:: get_tags
177 .. automethod:: maildir_flags_to_tags
179 .. automethod:: tags_to_maildir_flags
181 .. automethod:: remove_tag
183 .. automethod:: add_tag
185 .. automethod:: remove_all_tags
187 .. automethod:: freeze
191 .. automethod:: format_message_as_json
193 .. automethod:: format_message_as_text
195 .. automethod:: __str__
198 :class:`Tags` -- Notmuch tags
199 -----------------------------
206 .. warning:: :meth:`__len__` was removed in version 0.6 as it
207 exhausted the iterator and broke list(Tags()). Use
208 :meth:`len(list(msgs))` instead if you need to know the
211 .. automethod:: __str__
214 :class:`notmuch.Threads` -- Threads iterator
215 -----------------------------------------------------
217 .. autoclass:: notmuch.Threads
219 .. automethod:: __len__
221 .. automethod:: __str__
223 :class:`Thread` -- A single thread
224 ------------------------------------
226 .. autoclass:: Thread
228 .. automethod:: get_thread_id
230 .. automethod:: get_total_messages
232 .. automethod:: get_toplevel_messages
234 .. automethod:: get_matched_messages
236 .. automethod:: get_authors
238 .. automethod:: get_subject
240 .. automethod:: get_oldest_date
242 .. automethod:: get_newest_date
244 .. automethod:: get_tags
246 .. automethod:: __str__
249 :class:`Filenames` -- An iterator over filenames
250 ------------------------------------------------
252 .. autoclass:: notmuch.database.Filenames
254 .. automethod:: notmuch.database.Filenames.__len__
256 :class:`notmuch.database.Directoy` -- A directory entry in the database
257 ------------------------------------------------------------------------
259 .. autoclass:: notmuch.database.Directory
261 .. automethod:: notmuch.database.Directory.get_child_files
263 .. automethod:: notmuch.database.Directory.get_child_directories
265 .. automethod:: notmuch.database.Directory.get_mtime
267 .. automethod:: notmuch.database.Directory.set_mtime
269 .. autoattribute:: notmuch.database.Directory.mtime
271 .. autoattribute:: notmuch.database.Directory.path
274 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.