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    .. 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