git.notmuchmail.org Git - notmuch/blob - 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