bf0cfd280eb1f27b96ece1ffa4027b5f440522b1
[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 More information on specific topics can be found on the following pages:
27
28 .. toctree::
29    :maxdepth: 1
30
31    notmuch   
32
33 :mod:`notmuch` -- The Notmuch interface
34 =================================================
35
36 .. automodule:: notmuch
37
38 :todo: Document nmlib,STATUS
39
40 :class:`notmuch.Database` -- The underlying notmuch database
41 ---------------------------------------------------------------------
42
43 .. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
44
45    .. automethod:: create
46
47    .. automethod:: open(path, status=MODE.READ_ONLY)
48
49    .. automethod:: get_path
50
51    .. automethod:: get_version
52
53    .. automethod:: needs_upgrade
54
55    .. automethod:: upgrade
56
57    .. automethod:: get_directory
58
59    .. automethod:: add_message
60
61    .. automethod:: remove_message
62
63    .. automethod:: find_message
64
65    .. automethod:: get_all_tags
66
67    .. automethod:: create_query
68
69    .. note:: :meth:`create_query` was broken in release
70              0.1 and is fixed since 0.1.1.
71
72    .. attribute:: Database.MODE
73
74      Defines constants that are used as the mode in which to open a database.
75
76      MODE.READ_ONLY
77        Open the database in read-only mode
78
79      MODE.READ_WRITE
80        Open the database in read-write mode
81
82    .. autoattribute:: db_p
83
84 :class:`notmuch.Query` -- A search query
85 -------------------------------------------------
86
87 .. autoclass:: notmuch.Query
88
89    .. automethod:: create
90
91    .. attribute:: Query.SORT
92
93      Defines constants that are used as the mode in which to open a database.
94
95      SORT.OLDEST_FIRST
96        Sort by message date, oldest first.
97
98      SORT.NEWEST_FIRST
99        Sort by message date, newest first.
100
101      SORT.MESSAGE_ID
102        Sort by email message ID.
103
104      SORT.UNSORTED
105        Do not apply a special sort order (returns results in document id     
106        order). 
107
108    .. automethod:: set_sort
109
110    .. attribute::  sort
111
112       Instance attribute :attr:`sort` contains the sort order (see
113       :attr:`Query.SORT`) if explicitely specified via
114       :meth:`set_sort`. By default it is set to `None`.
115
116    .. automethod:: search_threads
117
118    .. automethod:: search_messages
119
120    .. automethod:: count_messages
121
122
123 :class:`Messages` -- A bunch of messages
124 ----------------------------------------
125
126 .. autoclass:: Messages
127
128    .. automethod:: collect_tags
129
130    .. automethod:: __len__
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:: remove_tag
166
167    .. automethod:: add_tag
168
169    .. automethod:: remove_all_tags
170
171    .. automethod:: freeze
172
173    .. automethod:: thaw
174
175    .. automethod:: format_as_text
176
177    .. automethod:: __str__
178
179
180 :class:`Tags` -- Notmuch tags
181 -----------------------------
182
183 .. autoclass:: Tags
184    :members:
185
186    .. automethod:: __len__
187
188    .. automethod:: __str__
189
190
191 :class:`notmuch.Threads` -- Threads iterator
192 -----------------------------------------------------
193
194 .. autoclass:: notmuch.Threads
195
196    .. automethod:: __len__
197
198    .. automethod:: __str__
199
200 :class:`Thread` -- A single thread
201 ------------------------------------
202
203 .. autoclass:: Thread
204
205   .. automethod:: get_thread_id
206
207   .. automethod:: get_total_messages
208
209   .. automethod:: get_toplevel_messages
210
211   .. automethod:: get_matched_messages
212
213   .. automethod:: get_authors
214
215   .. automethod:: get_subject
216
217   .. automethod:: get_oldest_date
218
219   .. automethod:: get_newest_date
220
221   .. automethod:: get_tags
222
223   .. automethod:: __str__
224
225
226 :class:`Filenames` -- An iterator over filenames
227 ------------------------------------------------
228
229 .. autoclass:: notmuch.database.Filenames
230
231    .. automethod:: notmuch.database.Filenames.__len__
232
233 :class:`notmuch.database.Directoy` -- A directory entry in the database
234 ------------------------------------------------------------------------
235
236 .. autoclass:: notmuch.database.Directory
237
238    .. automethod:: notmuch.database.Directory.get_child_files
239
240    .. automethod:: notmuch.database.Directory.get_child_directories
241
242    .. automethod:: notmuch.database.Directory.get_mtime
243
244    .. automethod:: notmuch.database.Directory.set_mtime
245
246    .. autoattribute:: notmuch.database.Directory.mtime
247
248    .. autoattribute:: notmuch.database.Directory.path
249
250 :exc:`NotmuchError` -- A Notmuch execution error
251 ------------------------------------------------
252 .. autoexception:: NotmuchError
253    :members:
254
255    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
256
257 :class:`STATUS` -- Notmuch operation return status
258 --------------------------------------------------
259
260 .. data:: STATUS
261
262   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.
263
264   * SUCCESS
265   * OUT_OF_MEMORY
266   * READ_ONLY_DATABASE
267   * XAPIAN_EXCEPTION
268   * FILE_ERROR
269   * FILE_NOT_EMAIL
270   * DUPLICATE_MESSAGE_ID
271   * NULL_POINTER
272   * TAG_TOO_LONG
273   * UNBALANCED_FREEZE_THAW
274   * NOT_INITIALIZED
275
276
277 Indices and tables
278 ==================
279
280 * :ref:`genindex`
281 * :ref:`search`
282