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