docs: Update documentation
[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
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 The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Messages` and :class:`notmuch.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:`notmuch` -- The Notmuch interface
34 =============================================
35
36 .. automodule:: cnotmuch.notmuch
37
38 :todo: Document nmlib,STATUS
39
40 :class:`Database` -- The underlying notmuch database
41 -----------------------------------------------------
42
43 .. autoclass:: 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:`Query` -- A search query
85 -----------------------------------------------
86
87 .. autoclass:: 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 :class:`Messages` -- A bunch of messages
119 ----------------------------------------
120
121 .. autoclass:: Messages
122
123    .. automethod:: collect_tags
124
125    .. automethod:: __len__
126
127 :class:`Message` -- A single message
128 ----------------------------------------
129
130 .. autoclass:: Message
131
132    .. automethod:: get_message_id
133
134    .. automethod:: get_thread_id
135
136    .. automethod:: get_replies
137
138    .. automethod:: get_filename
139
140    .. automethod:: get_flag
141
142    .. automethod:: set_flag
143    
144    .. automethod:: get_date
145
146    .. automethod:: get_header
147
148    .. automethod:: get_tags
149
150    .. automethod:: remove_tag
151
152    .. automethod:: add_tag
153
154    .. automethod:: remove_all_tags
155
156    .. automethod:: freeze
157
158    .. automethod:: thaw
159
160    .. automethod:: format_as_text
161
162    .. automethod:: __str__
163
164 :class:`Tags` -- Notmuch tags
165 -----------------------------
166
167 .. autoclass:: Tags
168    :members:
169
170    .. automethod:: __len__
171
172    .. automethod:: __str__
173
174
175 .. -----------------------------------------------------------------
176 .. currentmodule:: cnotmuch.thread
177
178 :class:`Threads` -- Threads iterator
179 ------------------------------------
180
181 .. autoclass:: Threads
182
183    .. automethod:: __len__
184
185    .. automethod:: __str__
186
187 :class:`Thread` -- A single thread
188 ------------------------------------
189
190 .. autoclass:: Thread
191
192   .. automethod:: get_thread_id
193
194   .. automethod:: get_total_messages
195
196   .. automethod:: get_toplevel_messages
197
198   .. automethod:: get_matched_messages
199
200   .. automethod:: get_authors
201
202   .. automethod:: get_subject
203
204   .. automethod:: get_oldest_date
205
206   .. automethod:: get_newest_date
207
208   .. automethod:: get_tags
209
210   .. automethod:: __str__
211
212 :class:`Filenames` -- An iterator over filenames
213 ------------------------------------------------
214
215 To be implemented
216
217 :class:`Directoy` -- A directory entry in the database
218 ------------------------------------------------------
219
220 To be implemented
221
222 :exc:`NotmuchError` -- A Notmuch execution error
223 ------------------------------------------------
224 .. autoexception:: NotmuchError
225    :members:
226
227    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
228
229 :class:`STATUS` -- Notmuch operation return status
230 --------------------------------------------------
231 .. autoclass:: STATUS
232
233    To be documented
234
235 Indices and tables
236 ==================
237
238 * :ref:`genindex`
239 * :ref:`search`
240