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