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|.
19 More information on specific topics can be found on the following pages:
28 :mod:`notmuch` -- The Notmuch interface
29 =================================================
31 .. automodule:: notmuch
33 :class:`Database` -- The underlying notmuch database
34 ---------------------------------------------------------------------
36 .. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
38 .. automethod:: create
40 .. automethod:: open(path, status=MODE.READ_ONLY)
42 .. automethod:: get_path
44 .. automethod:: get_version
46 .. automethod:: needs_upgrade
48 .. automethod:: upgrade
50 .. automethod:: begin_atomic
52 .. automethod:: end_atomic
54 .. automethod:: get_directory
56 .. automethod:: add_message
58 .. automethod:: remove_message
60 .. automethod:: find_message
62 .. automethod:: find_message_by_filename
64 .. automethod:: get_all_tags
66 .. automethod:: create_query
68 .. attribute:: Database.MODE
70 Defines constants that are used as the mode in which to open a database.
73 Open the database in read-only mode
76 Open the database in read-write mode
78 .. autoattribute:: db_p
81 :class:`Query` -- A search query
82 -------------------------------------------------
86 .. automethod:: create
88 .. attribute:: Query.SORT
90 Defines constants that are used as the mode in which to open a database.
93 Sort by message date, oldest first.
96 Sort by message date, newest first.
99 Sort by email message ID.
102 Do not apply a special sort order (returns results in document id
105 .. automethod:: set_sort
109 Instance attribute :attr:`sort` contains the sort order (see
110 :attr:`Query.SORT`) if explicitely specified via
111 :meth:`set_sort`. By default it is set to `None`.
113 .. automethod:: search_threads
115 .. automethod:: search_messages
117 .. automethod:: count_messages
119 .. automethod:: count_threads
122 :class:`Messages` -- A bunch of messages
123 ----------------------------------------
125 .. autoclass:: Messages
127 .. automethod:: collect_tags
129 .. method:: __len__()
133 :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
134 list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.
136 :class:`Message` -- A single message
137 ----------------------------------------
139 .. autoclass:: Message
141 .. automethod:: get_message_id
143 .. automethod:: get_thread_id
145 .. automethod:: get_replies
147 .. automethod:: get_filename
149 .. automethod:: get_filenames
154 This flag is automatically set by a
155 Query.search_threads on those messages that match the
156 query. This allows us to distinguish matches from the rest
157 of the messages in that thread.
159 .. automethod:: get_flag
161 .. automethod:: set_flag
163 .. automethod:: get_date
165 .. automethod:: get_header
167 .. automethod:: get_tags
169 .. automethod:: maildir_flags_to_tags
171 .. automethod:: tags_to_maildir_flags
173 .. automethod:: remove_tag
175 .. automethod:: add_tag
177 .. automethod:: remove_all_tags
179 .. automethod:: freeze
183 .. automethod:: format_message_as_json
185 .. automethod:: format_message_as_text
187 .. automethod:: __str__
190 :class:`Tags` -- Notmuch tags
191 -----------------------------
200 :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
201 list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of
204 .. automethod:: __str__
207 :class:`Threads` -- Threads iterator
208 -----------------------------------------------------
210 .. autoclass:: Threads
212 .. automethod:: __len__
214 .. automethod:: __str__
216 :class:`Thread` -- A single thread
217 ------------------------------------
219 .. autoclass:: Thread
221 .. automethod:: get_thread_id
223 .. automethod:: get_total_messages
225 .. automethod:: get_toplevel_messages
227 .. automethod:: get_matched_messages
229 .. automethod:: get_authors
231 .. automethod:: get_subject
233 .. automethod:: get_oldest_date
235 .. automethod:: get_newest_date
237 .. automethod:: get_tags
239 .. automethod:: __str__
242 :class:`Filenames` -- An iterator over filenames
243 ------------------------------------------------
245 .. autoclass:: Filenames
247 .. automethod:: Filenames.__len__
249 .. automethod:: Filenames.as_generator
251 :class:`Directoy` -- A directory entry in the database
252 ------------------------------------------------------------------------
254 .. autoclass:: Directory
256 .. automethod:: Directory.get_child_files
258 .. automethod:: Directory.get_child_directories
260 .. automethod:: Directory.get_mtime
262 .. automethod:: Directory.set_mtime
264 .. autoattribute:: Directory.mtime
266 .. autoattribute:: Directory.path
269 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.