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
  19 More information on specific topics can be found on the following pages:
  20
  21 .. toctree::
  22    :maxdepth: 1
  23
  24    quickstart
  25    notes
  26    status_and_errors
  27    notmuch
  28
  29 :class:`Database` -- The underlying notmuch database
  30 ---------------------------------------------------------------------
  31
  32 .. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
  33
  34    .. automethod:: create
  35
  36    .. automethod:: open(path, status=MODE.READ_ONLY)
  37
  38    .. automethod:: get_path
  39
  40    .. automethod:: get_version
  41
  42    .. automethod:: needs_upgrade
  43
  44    .. automethod:: upgrade
  45
  46    .. automethod:: begin_atomic
  47
  48    .. automethod:: end_atomic
  49
  50    .. automethod:: get_directory
  51
  52    .. automethod:: add_message
  53
  54    .. automethod:: remove_message
  55
  56    .. automethod:: find_message
  57
  58    .. automethod:: find_message_by_filename
  59
  60    .. automethod:: get_all_tags
  61
  62    .. automethod:: create_query
  63
  64    .. attribute:: Database.MODE
  65
  66      Defines constants that are used as the mode in which to open a database.
  67
  68      MODE.READ_ONLY
  69        Open the database in read-only mode
  70
  71      MODE.READ_WRITE
  72        Open the database in read-write mode
  73
  74    .. autoattribute:: db_p
  75
  76
  77 :class:`Query` -- A search query
  78 -------------------------------------------------
  79
  80 .. autoclass:: Query
  81
  82    .. automethod:: create
  83
  84    .. attribute:: Query.SORT
  85
  86      Defines constants that are used as the mode in which to open a database.
  87
  88      SORT.OLDEST_FIRST
  89        Sort by message date, oldest first.
  90
  91      SORT.NEWEST_FIRST
  92        Sort by message date, newest first.
  93
  94      SORT.MESSAGE_ID
  95        Sort by email message ID.
  96
  97      SORT.UNSORTED
  98        Do not apply a special sort order (returns results in document id
  99        order).
 100
 101    .. automethod:: set_sort
 102
 103    .. attribute::  sort
 104
 105       Instance attribute :attr:`sort` contains the sort order (see
 106       :attr:`Query.SORT`) if explicitely specified via
 107       :meth:`set_sort`. By default it is set to `None`.
 108
 109    .. automethod:: search_threads
 110
 111    .. automethod:: search_messages
 112
 113    .. automethod:: count_messages
 114
 115    .. automethod:: count_threads
 116
 117
 118 :class:`Messages` -- A bunch of messages
 119 ----------------------------------------
 120
 121 .. autoclass:: Messages
 122
 123    .. automethod:: collect_tags
 124
 125    .. method:: __len__()
 126
 127    .. warning::
 128
 129       :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
 130       list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.
 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:: maildir_flags_to_tags
 166
 167    .. automethod:: tags_to_maildir_flags
 168
 169    .. automethod:: remove_tag
 170
 171    .. automethod:: add_tag
 172
 173    .. automethod:: remove_all_tags
 174
 175    .. automethod:: freeze
 176
 177    .. automethod:: thaw
 178
 179    .. automethod:: format_message_as_json
 180
 181    .. automethod:: format_message_as_text
 182
 183    .. automethod:: __str__
 184
 185
 186 :class:`Tags` -- Notmuch tags
 187 -----------------------------
 188
 189 .. autoclass:: Tags
 190    :members:
 191
 192    .. method:: __len__
 193
 194        .. warning::
 195
 196             :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
 197             list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of
 198             tags.
 199
 200    .. automethod:: __str__
 201
 202
 203 :class:`Threads` -- Threads iterator
 204 -----------------------------------------------------
 205
 206 .. autoclass:: Threads
 207
 208    .. automethod:: __len__
 209
 210    .. automethod:: __str__
 211
 212 :class:`Thread` -- A single thread
 213 ------------------------------------
 214
 215 .. autoclass:: Thread
 216
 217   .. automethod:: get_thread_id
 218
 219   .. automethod:: get_total_messages
 220
 221   .. automethod:: get_toplevel_messages
 222
 223   .. automethod:: get_matched_messages
 224
 225   .. automethod:: get_authors
 226
 227   .. automethod:: get_subject
 228
 229   .. automethod:: get_oldest_date
 230
 231   .. automethod:: get_newest_date
 232
 233   .. automethod:: get_tags
 234
 235   .. automethod:: __str__
 236
 237
 238 :class:`Filenames` -- An iterator over filenames
 239 ------------------------------------------------
 240
 241 .. autoclass:: Filenames
 242
 243    .. automethod:: Filenames.__len__
 244
 245    .. automethod:: Filenames.as_generator
 246
 247 :class:`Directoy` -- A directory entry in the database
 248 ------------------------------------------------------------------------
 249
 250 .. autoclass:: Directory
 251
 252    .. automethod:: Directory.get_child_files
 253
 254    .. automethod:: Directory.get_child_directories
 255
 256    .. automethod:: Directory.get_mtime
 257
 258    .. automethod:: Directory.set_mtime
 259
 260    .. autoattribute:: Directory.mtime
 261
 262    .. autoattribute:: Directory.path
 263
 264
 265 The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
 266
 267 Indices and tables
 268 ==================
 269
 270 * :ref:`genindex`
 271 * :ref:`search`
 272