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