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    status_and_errors
  32    notmuch
  33
  34 :mod:`notmuch` -- The Notmuch interface
  35 =================================================
  36
  37 .. automodule:: notmuch
  38
  39 :todo: Document nmlib,STATUS
  40
  41 :class:`notmuch.Database` -- The underlying notmuch database
  42 ---------------------------------------------------------------------
  43
  44 .. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
  45
  46    .. automethod:: create
  47
  48    .. automethod:: open(path, status=MODE.READ_ONLY)
  49
  50    .. automethod:: get_path
  51
  52    .. automethod:: get_version
  53
  54    .. automethod:: needs_upgrade
  55
  56    .. automethod:: upgrade
  57
  58    .. automethod:: begin_atomic
  59
  60    .. automethod:: end_atomic
  61
  62    .. automethod:: get_directory
  63
  64    .. automethod:: add_message
  65
  66    .. automethod:: remove_message
  67
  68    .. automethod:: find_message
  69
  70    .. automethod:: find_message_by_filename
  71
  72    .. automethod:: get_all_tags
  73
  74    .. automethod:: create_query
  75
  76    .. note:: :meth:`create_query` was broken in release
  77              0.1 and is fixed since 0.1.1.
  78
  79    .. attribute:: Database.MODE
  80
  81      Defines constants that are used as the mode in which to open a database.
  82
  83      MODE.READ_ONLY
  84        Open the database in read-only mode
  85
  86      MODE.READ_WRITE
  87        Open the database in read-write mode
  88
  89    .. autoattribute:: db_p
  90
  91 :class:`notmuch.Query` -- A search query
  92 -------------------------------------------------
  93
  94 .. autoclass:: notmuch.Query
  95
  96    .. automethod:: create
  97
  98    .. attribute:: Query.SORT
  99
 100      Defines constants that are used as the mode in which to open a database.
 101
 102      SORT.OLDEST_FIRST
 103        Sort by message date, oldest first.
 104
 105      SORT.NEWEST_FIRST
 106        Sort by message date, newest first.
 107
 108      SORT.MESSAGE_ID
 109        Sort by email message ID.
 110
 111      SORT.UNSORTED
 112        Do not apply a special sort order (returns results in document id
 113        order).
 114
 115    .. automethod:: set_sort
 116
 117    .. attribute::  sort
 118
 119       Instance attribute :attr:`sort` contains the sort order (see
 120       :attr:`Query.SORT`) if explicitely specified via
 121       :meth:`set_sort`. By default it is set to `None`.
 122
 123    .. automethod:: search_threads
 124
 125    .. automethod:: search_messages
 126
 127    .. automethod:: count_messages
 128
 129
 130 :class:`Messages` -- A bunch of messages
 131 ----------------------------------------
 132
 133 .. autoclass:: Messages
 134
 135    .. automethod:: collect_tags
 136
 137    .. method:: __len__()
 138
 139    .. warning:: :meth:`__len__` was removed in version 0.6 as it exhausted
 140        the iterator and broke list(Messages()). Use the
 141        :meth:`Query.count_messages` function or use
 142        `len(list(msgs))`.
 143
 144 :class:`Message` -- A single message
 145 ----------------------------------------
 146
 147 .. autoclass:: Message
 148
 149    .. automethod:: get_message_id
 150
 151    .. automethod:: get_thread_id
 152
 153    .. automethod:: get_replies
 154
 155    .. automethod:: get_filename
 156
 157    .. automethod:: get_filenames
 158
 159    .. attribute:: FLAG
 160
 161         FLAG.MATCH
 162           This flag is automatically set by a
 163           Query.search_threads on those messages that match the
 164           query. This allows us to distinguish matches from the rest
 165           of the messages in that thread.
 166
 167    .. automethod:: get_flag
 168
 169    .. automethod:: set_flag
 170
 171    .. automethod:: get_date
 172
 173    .. automethod:: get_header
 174
 175    .. automethod:: get_tags
 176
 177    .. automethod:: maildir_flags_to_tags
 178
 179    .. automethod:: tags_to_maildir_flags
 180
 181    .. automethod:: remove_tag
 182
 183    .. automethod:: add_tag
 184
 185    .. automethod:: remove_all_tags
 186
 187    .. automethod:: freeze
 188
 189    .. automethod:: thaw
 190
 191    .. automethod:: format_message_as_json
 192
 193    .. automethod:: format_message_as_text
 194
 195    .. automethod:: __str__
 196
 197
 198 :class:`Tags` -- Notmuch tags
 199 -----------------------------
 200
 201 .. autoclass:: Tags
 202    :members:
 203
 204    .. method:: __len__
 205
 206        .. warning:: :meth:`__len__` was removed in version 0.6 as it
 207            exhausted the iterator and broke list(Tags()). Use
 208            :meth:`len(list(msgs))` instead if you need to know the
 209            number of tags.
 210
 211    .. automethod:: __str__
 212
 213
 214 :class:`notmuch.Threads` -- Threads iterator
 215 -----------------------------------------------------
 216
 217 .. autoclass:: notmuch.Threads
 218
 219    .. automethod:: __len__
 220
 221    .. automethod:: __str__
 222
 223 :class:`Thread` -- A single thread
 224 ------------------------------------
 225
 226 .. autoclass:: Thread
 227
 228   .. automethod:: get_thread_id
 229
 230   .. automethod:: get_total_messages
 231
 232   .. automethod:: get_toplevel_messages
 233
 234   .. automethod:: get_matched_messages
 235
 236   .. automethod:: get_authors
 237
 238   .. automethod:: get_subject
 239
 240   .. automethod:: get_oldest_date
 241
 242   .. automethod:: get_newest_date
 243
 244   .. automethod:: get_tags
 245
 246   .. automethod:: __str__
 247
 248
 249 :class:`Filenames` -- An iterator over filenames
 250 ------------------------------------------------
 251
 252 .. autoclass:: notmuch.database.Filenames
 253
 254    .. automethod:: notmuch.database.Filenames.__len__
 255
 256 :class:`notmuch.database.Directoy` -- A directory entry in the database
 257 ------------------------------------------------------------------------
 258
 259 .. autoclass:: notmuch.database.Directory
 260
 261    .. automethod:: notmuch.database.Directory.get_child_files
 262
 263    .. automethod:: notmuch.database.Directory.get_child_directories
 264
 265    .. automethod:: notmuch.database.Directory.get_mtime
 266
 267    .. automethod:: notmuch.database.Directory.set_mtime
 268
 269    .. autoattribute:: notmuch.database.Directory.mtime
 270
 271    .. autoattribute:: notmuch.database.Directory.path
 272
 273
 274 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
 275
 276 Indices and tables
 277 ==================
 278
 279 * :ref:`genindex`
 280 * :ref:`search`
 281