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