python: Remove Messages().__len__
[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    .. method:: __len__()
131
132    .. note:: :meth:`__len__` was removed in version 0.6 as it exhausted
133        the iterator and broke list(Messages()). Use the
134        :meth:`Query.count_messages` function or use
135        `len(list(msgs))`.
136
137 :class:`Message` -- A single message
138 ----------------------------------------
139
140 .. autoclass:: Message
141
142    .. automethod:: get_message_id
143
144    .. automethod:: get_thread_id
145
146    .. automethod:: get_replies
147
148    .. automethod:: get_filename
149
150    .. automethod:: get_filenames
151
152    .. attribute:: FLAG
153
154         FLAG.MATCH 
155           This flag is automatically set by a
156           Query.search_threads on those messages that match the
157           query. This allows us to distinguish matches from the rest
158           of the messages in that thread.
159
160   .. automethod:: get_flag
161
162    .. automethod:: set_flag
163    
164    .. automethod:: get_date
165
166    .. automethod:: get_header
167
168    .. automethod:: get_tags
169
170    .. automethod:: remove_tag
171
172    .. automethod:: add_tag
173
174    .. automethod:: remove_all_tags
175
176    .. automethod:: freeze
177
178    .. automethod:: thaw
179
180    .. automethod:: format_as_text
181
182    .. automethod:: __str__
183
184
185 :class:`Tags` -- Notmuch tags
186 -----------------------------
187
188 .. autoclass:: Tags
189    :members:
190
191    .. automethod:: __len__
192
193    .. automethod:: __str__
194
195
196 :class:`notmuch.Threads` -- Threads iterator
197 -----------------------------------------------------
198
199 .. autoclass:: notmuch.Threads
200
201    .. automethod:: __len__
202
203    .. automethod:: __str__
204
205 :class:`Thread` -- A single thread
206 ------------------------------------
207
208 .. autoclass:: Thread
209
210   .. automethod:: get_thread_id
211
212   .. automethod:: get_total_messages
213
214   .. automethod:: get_toplevel_messages
215
216   .. automethod:: get_matched_messages
217
218   .. automethod:: get_authors
219
220   .. automethod:: get_subject
221
222   .. automethod:: get_oldest_date
223
224   .. automethod:: get_newest_date
225
226   .. automethod:: get_tags
227
228   .. automethod:: __str__
229
230
231 :class:`Filenames` -- An iterator over filenames
232 ------------------------------------------------
233
234 .. autoclass:: notmuch.database.Filenames
235
236    .. automethod:: notmuch.database.Filenames.__len__
237
238 :class:`notmuch.database.Directoy` -- A directory entry in the database
239 ------------------------------------------------------------------------
240
241 .. autoclass:: notmuch.database.Directory
242
243    .. automethod:: notmuch.database.Directory.get_child_files
244
245    .. automethod:: notmuch.database.Directory.get_child_directories
246
247    .. automethod:: notmuch.database.Directory.get_mtime
248
249    .. automethod:: notmuch.database.Directory.set_mtime
250
251    .. autoattribute:: notmuch.database.Directory.mtime
252
253    .. autoattribute:: notmuch.database.Directory.path
254
255 :exc:`NotmuchError` -- A Notmuch execution error
256 ------------------------------------------------
257 .. autoexception:: NotmuchError
258    :members:
259
260    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
261
262 :class:`STATUS` -- Notmuch operation return status
263 --------------------------------------------------
264
265 .. data:: STATUS
266
267   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.
268
269   * SUCCESS
270   * OUT_OF_MEMORY
271   * READ_ONLY_DATABASE
272   * XAPIAN_EXCEPTION
273   * FILE_ERROR
274   * FILE_NOT_EMAIL
275   * DUPLICATE_MESSAGE_ID
276   * NULL_POINTER
277   * TAG_TOO_LONG
278   * UNBALANCED_FREEZE_THAW
279   * NOT_INITIALIZED
280
281
282 Indices and tables
283 ==================
284
285 * :ref:`genindex`
286 * :ref:`search`
287