docs: Improve documentations
[notmuch] / docs / source / index.rst
1 .. cnotmuch documentation master file, created by
2    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
3
4 .. currentmodule:: cnotmuch.notmuch
5
6 Welcome to :mod:`cnotmuch`'s documentation
7 ===========================================
8
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`.
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 cnotmuch |release|. 
17
18 Notmuch can be imported as::
19
20  from cnotmuch import notmuch
21
22 or::
23
24  from cnotmuch.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:`cnotmuch.notmuch` -- The Notmuch interface
34 =================================================
35
36 .. automodule:: cnotmuch.notmuch
37
38 :todo: Document nmlib,STATUS
39
40 :class:`cnotmuch.notmuch.Database` -- The underlying notmuch database
41 ---------------------------------------------------------------------
42
43 .. autoclass:: cnotmuch.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:`cnotmuch.notmuch.Query` -- A search query
85 -------------------------------------------------
86
87 .. autoclass:: cnotmuch.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    .. automethod:: set_sort
105
106    .. attribute::  sort
107
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`.
111
112    .. automethod:: search_threads
113
114    .. automethod:: search_messages
115
116    .. automethod:: count_messages
117
118
119 :class:`Messages` -- A bunch of messages
120 ----------------------------------------
121
122 .. autoclass:: Messages
123
124    .. automethod:: collect_tags
125
126    .. automethod:: __len__
127
128 :class:`Message` -- A single message
129 ----------------------------------------
130
131 .. autoclass:: Message
132
133    .. automethod:: get_message_id
134
135    .. automethod:: get_thread_id
136
137    .. automethod:: get_replies
138
139    .. automethod:: get_filename
140
141    .. attribute:: FLAG
142
143         FLAG.MATCH 
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.
148
149   .. automethod:: get_flag
150
151    .. automethod:: set_flag
152    
153    .. automethod:: get_date
154
155    .. automethod:: get_header
156
157    .. automethod:: get_tags
158
159    .. automethod:: remove_tag
160
161    .. automethod:: add_tag
162
163    .. automethod:: remove_all_tags
164
165    .. automethod:: freeze
166
167    .. automethod:: thaw
168
169    .. automethod:: format_as_text
170
171    .. automethod:: __str__
172
173
174 :class:`Tags` -- Notmuch tags
175 -----------------------------
176
177 .. autoclass:: Tags
178    :members:
179
180    .. automethod:: __len__
181
182    .. automethod:: __str__
183
184
185 :class:`cnotmuch.notmuch.Threads` -- Threads iterator
186 -----------------------------------------------------
187
188 .. autoclass:: cnotmuch.notmuch.Threads
189
190    .. automethod:: __len__
191
192    .. automethod:: __str__
193
194 :class:`Thread` -- A single thread
195 ------------------------------------
196
197 .. autoclass:: Thread
198
199   .. automethod:: get_thread_id
200
201   .. automethod:: get_total_messages
202
203   .. automethod:: get_toplevel_messages
204
205   .. automethod:: get_matched_messages
206
207   .. automethod:: get_authors
208
209   .. automethod:: get_subject
210
211   .. automethod:: get_oldest_date
212
213   .. automethod:: get_newest_date
214
215   .. automethod:: get_tags
216
217   .. automethod:: __str__
218
219
220 :class:`Filenames` -- An iterator over filenames
221 ------------------------------------------------
222
223 .. autoclass:: cnotmuch.database.Filenames
224
225    .. automethod:: cnotmuch.database.Filenames.__len__
226
227 :class:`cnotmuch.database.Directoy` -- A directory entry in the database
228 ------------------------------------------------------------------------
229
230 .. autoclass:: cnotmuch.database.Directory
231
232    .. automethod:: cnotmuch.database.Directory.get_child_files
233
234    .. automethod:: cnotmuch.database.Directory.get_child_directories
235
236    .. automethod:: cnotmuch.database.Directory.get_mtime
237
238    .. automethod:: cnotmuch.database.Directory.set_mtime
239
240    .. autoattribute:: cnotmuch.database.Directory.mtime
241
242    .. autoattribute:: cnotmuch.database.Directory.path
243
244 :exc:`NotmuchError` -- A Notmuch execution error
245 ------------------------------------------------
246 .. autoexception:: NotmuchError
247    :members:
248
249    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
250
251 :class:`STATUS` -- Notmuch operation return status
252 --------------------------------------------------
253
254 .. data:: STATUS
255
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.
257
258   * SUCCESS
259   * OUT_OF_MEMORY
260   * READ_ONLY_DATABASE
261   * XAPIAN_EXCEPTION
262   * FILE_ERROR
263   * FILE_NOT_EMAIL
264   * DUPLICATE_MESSAGE_ID
265   * NULL_POINTER
266   * TAG_TOO_LONG
267   * UNBALANCED_FREEZE_THAW
268   * NOT_INITIALIZED
269
270
271 Indices and tables
272 ==================
273
274 * :ref:`genindex`
275 * :ref:`search`
276