1 .. cnotmuch documentation master file, created by
2 sphinx-quickstart on Tue Feb 2 10:00:47 2010.
4 .. currentmodule:: cnotmuch.notmuch
6 Welcome to :mod:`cnotmuch`'s documentation
7 ===========================================
9 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
10 Within :mod:`cnotmuch.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 cnotmuch |release|.
18 Notmuch can be imported as::
20 from cnotmuch import notmuch
24 from cnotmuch.notmuch import Query,Database
26 More information on specific topics can be found on the following pages:
33 :mod:`cnotmuch.notmuch` -- The Notmuch interface
34 =================================================
36 .. automodule:: cnotmuch.notmuch
38 :todo: Document nmlib,STATUS
40 :class:`cnotmuch.notmuch.Database` -- The underlying notmuch database
41 ---------------------------------------------------------------------
43 .. autoclass:: cnotmuch.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:`cnotmuch.notmuch.Query` -- A search query
85 -------------------------------------------------
87 .. autoclass:: cnotmuch.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
104 .. automethod:: set_sort
108 Instance attribute :attr:`sort` contains the sort order (see
109 :attr:`Query.SORT`) if explicitely specified via
110 :meth:`set_sort`. By default it is set to `None`.
112 .. automethod:: search_threads
114 .. automethod:: search_messages
116 .. automethod:: count_messages
119 :class:`Messages` -- A bunch of messages
120 ----------------------------------------
122 .. autoclass:: Messages
124 .. automethod:: collect_tags
126 .. automethod:: __len__
128 :class:`Message` -- A single message
129 ----------------------------------------
131 .. autoclass:: Message
133 .. automethod:: get_message_id
135 .. automethod:: get_thread_id
137 .. automethod:: get_replies
139 .. automethod:: get_filename
144 This flag is automatically set by a
145 Query.search_threads on those messages that match the
146 query. This allows us to distinguish matches from the rest
147 of the messages in that thread.
149 .. automethod:: get_flag
151 .. automethod:: set_flag
153 .. automethod:: get_date
155 .. automethod:: get_header
157 .. automethod:: get_tags
159 .. automethod:: remove_tag
161 .. automethod:: add_tag
163 .. automethod:: remove_all_tags
165 .. automethod:: freeze
169 .. automethod:: format_as_text
171 .. automethod:: __str__
174 :class:`Tags` -- Notmuch tags
175 -----------------------------
180 .. automethod:: __len__
182 .. automethod:: __str__
185 :class:`cnotmuch.notmuch.Threads` -- Threads iterator
186 -----------------------------------------------------
188 .. autoclass:: cnotmuch.notmuch.Threads
190 .. automethod:: __len__
192 .. automethod:: __str__
194 :class:`Thread` -- A single thread
195 ------------------------------------
197 .. autoclass:: Thread
199 .. automethod:: get_thread_id
201 .. automethod:: get_total_messages
203 .. automethod:: get_toplevel_messages
205 .. automethod:: get_matched_messages
207 .. automethod:: get_authors
209 .. automethod:: get_subject
211 .. automethod:: get_oldest_date
213 .. automethod:: get_newest_date
215 .. automethod:: get_tags
217 .. automethod:: __str__
220 :class:`Filenames` -- An iterator over filenames
221 ------------------------------------------------
223 .. autoclass:: cnotmuch.database.Filenames
225 .. automethod:: cnotmuch.database.Filenames.__len__
227 :class:`cnotmuch.database.Directoy` -- A directory entry in the database
228 ------------------------------------------------------------------------
230 .. autoclass:: cnotmuch.database.Directory
232 .. automethod:: cnotmuch.database.Directory.get_child_files
234 .. automethod:: cnotmuch.database.Directory.get_child_directories
236 .. automethod:: cnotmuch.database.Directory.get_mtime
238 .. automethod:: cnotmuch.database.Directory.set_mtime
240 .. autoattribute:: cnotmuch.database.Directory.mtime
242 .. autoattribute:: cnotmuch.database.Directory.path
244 :exc:`NotmuchError` -- A Notmuch execution error
245 ------------------------------------------------
246 .. autoexception:: NotmuchError
249 This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
251 :class:`STATUS` -- Notmuch operation return status
252 --------------------------------------------------
256 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.
264 * DUPLICATE_MESSAGE_ID
267 * UNBALANCED_FREEZE_THAW