a2b42aae6b686ccd5da1357010a861de819c08f3
[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    notes
26    status_and_errors
27    notmuch
28
29 :class:`Database` -- The underlying notmuch database
30 ---------------------------------------------------------------------
31
32 .. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
33
34    .. automethod:: create
35
36    .. automethod:: open(path, status=MODE.READ_ONLY)
37
38    .. automethod:: get_path
39
40    .. automethod:: get_version
41
42    .. automethod:: needs_upgrade
43
44    .. automethod:: upgrade
45
46    .. automethod:: begin_atomic
47
48    .. automethod:: end_atomic
49
50    .. automethod:: get_directory
51
52    .. automethod:: add_message
53
54    .. automethod:: remove_message
55
56    .. automethod:: find_message
57
58    .. automethod:: find_message_by_filename
59
60    .. automethod:: get_all_tags
61
62    .. automethod:: create_query
63
64    .. attribute:: Database.MODE
65
66      Defines constants that are used as the mode in which to open a database.
67
68      MODE.READ_ONLY
69        Open the database in read-only mode
70
71      MODE.READ_WRITE
72        Open the database in read-write mode
73
74    .. autoattribute:: db_p
75
76
77 :class:`Query` -- A search query
78 -------------------------------------------------
79
80 .. autoclass:: Query
81
82    .. automethod:: create
83
84    .. attribute:: Query.SORT
85
86      Defines constants that are used as the mode in which to open a database.
87
88      SORT.OLDEST_FIRST
89        Sort by message date, oldest first.
90
91      SORT.NEWEST_FIRST
92        Sort by message date, newest first.
93
94      SORT.MESSAGE_ID
95        Sort by email message ID.
96
97      SORT.UNSORTED
98        Do not apply a special sort order (returns results in document id
99        order).
100
101    .. automethod:: set_sort
102
103    .. attribute::  sort
104
105       Instance attribute :attr:`sort` contains the sort order (see
106       :attr:`Query.SORT`) if explicitely specified via
107       :meth:`set_sort`. By default it is set to `None`.
108
109    .. automethod:: search_threads
110
111    .. automethod:: search_messages
112
113    .. automethod:: count_messages
114
115    .. automethod:: count_threads
116
117
118 :class:`Messages` -- A bunch of messages
119 ----------------------------------------
120
121 .. autoclass:: Messages
122
123    .. automethod:: collect_tags
124
125    .. method:: __len__()
126
127    .. warning::
128
129       :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
130       list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.
131
132 :class:`Message` -- A single message
133 ----------------------------------------
134
135 .. autoclass:: Message
136
137    .. automethod:: get_message_id
138
139    .. automethod:: get_thread_id
140
141    .. automethod:: get_replies
142
143    .. automethod:: get_filename
144
145    .. automethod:: get_filenames
146
147    .. attribute:: FLAG
148
149         FLAG.MATCH
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.
154
155    .. automethod:: get_flag
156
157    .. automethod:: set_flag
158
159    .. automethod:: get_date
160
161    .. automethod:: get_header
162
163    .. automethod:: get_tags
164
165    .. automethod:: maildir_flags_to_tags
166
167    .. automethod:: tags_to_maildir_flags
168
169    .. automethod:: remove_tag
170
171    .. automethod:: add_tag
172
173    .. automethod:: remove_all_tags
174
175    .. automethod:: freeze
176
177    .. automethod:: thaw
178
179    .. automethod:: format_message_as_json
180
181    .. automethod:: format_message_as_text
182
183    .. automethod:: __str__
184
185
186 :class:`Tags` -- Notmuch tags
187 -----------------------------
188
189 .. autoclass:: Tags
190    :members:
191
192    .. method:: __len__
193
194        .. warning::
195
196             :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
197             list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of
198             tags.
199
200    .. automethod:: __str__
201
202
203 :class:`Threads` -- Threads iterator
204 -----------------------------------------------------
205
206 .. autoclass:: Threads
207
208    .. automethod:: __len__
209
210    .. automethod:: __str__
211
212 :class:`Thread` -- A single thread
213 ------------------------------------
214
215 .. autoclass:: Thread
216
217   .. automethod:: get_thread_id
218
219   .. automethod:: get_total_messages
220
221   .. automethod:: get_toplevel_messages
222
223   .. automethod:: get_matched_messages
224
225   .. automethod:: get_authors
226
227   .. automethod:: get_subject
228
229   .. automethod:: get_oldest_date
230
231   .. automethod:: get_newest_date
232
233   .. automethod:: get_tags
234
235   .. automethod:: __str__
236
237
238 :class:`Filenames` -- An iterator over filenames
239 ------------------------------------------------
240
241 .. autoclass:: Filenames
242
243    .. automethod:: Filenames.__len__
244
245    .. automethod:: Filenames.as_generator
246
247 :class:`Directoy` -- A directory entry in the database
248 ------------------------------------------------------------------------
249
250 .. autoclass:: Directory
251
252    .. automethod:: Directory.get_child_files
253
254    .. automethod:: Directory.get_child_directories
255
256    .. automethod:: Directory.get_mtime
257
258    .. automethod:: Directory.set_mtime
259
260    .. autoattribute:: Directory.mtime
261
262    .. autoattribute:: Directory.path
263
264
265 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
266
267 Indices and tables
268 ==================
269
270 * :ref:`genindex`
271 * :ref:`search`
272