dec9697fd42f33d7d2e2b6b0cf9ebc0c00517de5
[notmuch] / bindings / python / docs / source / index.rst
1 .. notmuch documentation master file, created by
2    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
3
4 .. currentmodule:: notmuch
5
6 Welcome to :mod:`notmuch`'s documentation
7 ===========================================
8
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`.
11
12 .. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
13
14 :License: This module is covered under the GNU GPL v3 (or later).
15
16 This page contains the main API overview of notmuch |release|.
17
18
19 More information on specific topics can be found on the following pages:
20
21 .. toctree::
22    :maxdepth: 1
23
24    quickstart
25    status_and_errors
26    notmuch
27
28 :mod:`notmuch` -- The Notmuch interface
29 =================================================
30
31 .. automodule:: notmuch
32
33 :class:`Database` -- The underlying notmuch database
34 ---------------------------------------------------------------------
35
36 .. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
37
38    .. automethod:: create
39
40    .. automethod:: open(path, status=MODE.READ_ONLY)
41
42    .. automethod:: get_path
43
44    .. automethod:: get_version
45
46    .. automethod:: needs_upgrade
47
48    .. automethod:: upgrade
49
50    .. automethod:: begin_atomic
51
52    .. automethod:: end_atomic
53
54    .. automethod:: get_directory
55
56    .. automethod:: add_message
57
58    .. automethod:: remove_message
59
60    .. automethod:: find_message
61
62    .. automethod:: find_message_by_filename
63
64    .. automethod:: get_all_tags
65
66    .. automethod:: create_query
67
68    .. attribute:: Database.MODE
69
70      Defines constants that are used as the mode in which to open a database.
71
72      MODE.READ_ONLY
73        Open the database in read-only mode
74
75      MODE.READ_WRITE
76        Open the database in read-write mode
77
78    .. autoattribute:: db_p
79
80
81 :class:`Query` -- A search query
82 -------------------------------------------------
83
84 .. autoclass:: Query
85
86    .. automethod:: create
87
88    .. attribute:: Query.SORT
89
90      Defines constants that are used as the mode in which to open a database.
91
92      SORT.OLDEST_FIRST
93        Sort by message date, oldest first.
94
95      SORT.NEWEST_FIRST
96        Sort by message date, newest first.
97
98      SORT.MESSAGE_ID
99        Sort by email message ID.
100
101      SORT.UNSORTED
102        Do not apply a special sort order (returns results in document id
103        order).
104
105    .. automethod:: set_sort
106
107    .. attribute::  sort
108
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`.
112
113    .. automethod:: search_threads
114
115    .. automethod:: search_messages
116
117    .. automethod:: count_messages
118
119    .. automethod:: count_threads
120
121
122 :class:`Messages` -- A bunch of messages
123 ----------------------------------------
124
125 .. autoclass:: Messages
126
127    .. automethod:: collect_tags
128
129    .. method:: __len__()
130
131    .. warning::
132
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))`.
135
136 :class:`Message` -- A single message
137 ----------------------------------------
138
139 .. autoclass:: Message
140
141    .. automethod:: get_message_id
142
143    .. automethod:: get_thread_id
144
145    .. automethod:: get_replies
146
147    .. automethod:: get_filename
148
149    .. automethod:: get_filenames
150
151    .. attribute:: FLAG
152
153         FLAG.MATCH
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.
158
159    .. automethod:: get_flag
160
161    .. automethod:: set_flag
162
163    .. automethod:: get_date
164
165    .. automethod:: get_header
166
167    .. automethod:: get_tags
168
169    .. automethod:: maildir_flags_to_tags
170
171    .. automethod:: tags_to_maildir_flags
172
173    .. automethod:: remove_tag
174
175    .. automethod:: add_tag
176
177    .. automethod:: remove_all_tags
178
179    .. automethod:: freeze
180
181    .. automethod:: thaw
182
183    .. automethod:: format_message_as_json
184
185    .. automethod:: format_message_as_text
186
187    .. automethod:: __str__
188
189
190 :class:`Tags` -- Notmuch tags
191 -----------------------------
192
193 .. autoclass:: Tags
194    :members:
195
196    .. method:: __len__
197
198        .. warning::
199
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
202             tags.
203
204    .. automethod:: __str__
205
206
207 :class:`Threads` -- Threads iterator
208 -----------------------------------------------------
209
210 .. autoclass:: Threads
211
212    .. automethod:: __len__
213
214    .. automethod:: __str__
215
216 :class:`Thread` -- A single thread
217 ------------------------------------
218
219 .. autoclass:: Thread
220
221   .. automethod:: get_thread_id
222
223   .. automethod:: get_total_messages
224
225   .. automethod:: get_toplevel_messages
226
227   .. automethod:: get_matched_messages
228
229   .. automethod:: get_authors
230
231   .. automethod:: get_subject
232
233   .. automethod:: get_oldest_date
234
235   .. automethod:: get_newest_date
236
237   .. automethod:: get_tags
238
239   .. automethod:: __str__
240
241
242 :class:`Filenames` -- An iterator over filenames
243 ------------------------------------------------
244
245 .. autoclass:: Filenames
246
247    .. automethod:: Filenames.__len__
248
249    .. automethod:: Filenames.as_generator
250
251 :class:`Directoy` -- A directory entry in the database
252 ------------------------------------------------------------------------
253
254 .. autoclass:: Directory
255
256    .. automethod:: Directory.get_child_files
257
258    .. automethod:: Directory.get_child_directories
259
260    .. automethod:: Directory.get_mtime
261
262    .. automethod:: Directory.set_mtime
263
264    .. autoattribute:: Directory.mtime
265
266    .. autoattribute:: Directory.path
267
268
269 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
270
271 Indices and tables
272 ==================
273
274 * :ref:`genindex`
275 * :ref:`search`
276