git.notmuchmail.org Git - notmuch/blob - docs/source/index.rst

   1 .. cnotmuch documentation master file, created by
   2    sphinx-quickstart on Tue Feb  2 10:00:47 2010.
   3
   4 .. currentmodule:: cnotmuch
   5
   6 Welcome to :mod:`cnotmuch`'s documentation
   7 ===========================================
   8
   9 The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
  10 The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Threads`, :class:`notmuch.Messages` and :class:`notmuch.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 cnotmuch |release|.
  17
  18 Notmuch can be imported as::
  19
  20  from cnotmuch import notmuch
  21
  22 or::
  23
  24  from cnotmuch.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:: cnotmuch.notmuch
  37
  38 :todo: Document nmlib,STATUS
  39
  40 :class:`Database` -- The underlying notmuch database
  41 -----------------------------------------------------
  42
  43 .. autoclass:: 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:`Query` -- A search query
  85 -----------------------------------------------
  86
  87 .. autoclass:: 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 .. currentmodule:: cnotmuch.message
 120
 121 :class:`Messages` -- A bunch of messages
 122 ----------------------------------------
 123
 124 .. autoclass:: Messages
 125
 126    .. automethod:: collect_tags
 127
 128    .. automethod:: __len__
 129
 130 :class:`Message` -- A single message
 131 ----------------------------------------
 132
 133 .. autoclass:: Message
 134
 135    .. automethod:: get_message_id
 136
 137    .. automethod:: get_thread_id
 138
 139    .. automethod:: get_replies
 140
 141    .. automethod:: get_filename
 142
 143    .. attribute:: FLAG
 144
 145         FLAG.MATCH
 146           This flag is automatically set by a
 147           Query.search_threads on those messages that match the
 148           query. This allows us to distinguish matches from the rest
 149           of the messages in that thread.
 150
 151   .. automethod:: get_flag
 152
 153    .. automethod:: set_flag
 154
 155    .. automethod:: get_date
 156
 157    .. automethod:: get_header
 158
 159    .. automethod:: get_tags
 160
 161    .. automethod:: remove_tag
 162
 163    .. automethod:: add_tag
 164
 165    .. automethod:: remove_all_tags
 166
 167    .. automethod:: freeze
 168
 169    .. automethod:: thaw
 170
 171    .. automethod:: format_as_text
 172
 173    .. automethod:: __str__
 174
 175 .. #############################################
 176 .. currentmodule:: cnotmuch.tag
 177
 178 :class:`Tags` -- Notmuch tags
 179 -----------------------------
 180
 181 .. autoclass:: Tags
 182    :members:
 183
 184    .. automethod:: __len__
 185
 186    .. automethod:: __str__
 187
 188
 189 .. #############################################
 190 .. currentmodule:: cnotmuch.thread
 191
 192 :class:`Threads` -- Threads iterator
 193 ------------------------------------
 194
 195 .. autoclass:: Threads
 196
 197    .. automethod:: __len__
 198
 199    .. automethod:: __str__
 200
 201 :class:`Thread` -- A single thread
 202 ------------------------------------
 203
 204 .. autoclass:: Thread
 205
 206   .. automethod:: get_thread_id
 207
 208   .. automethod:: get_total_messages
 209
 210   .. automethod:: get_toplevel_messages
 211
 212   .. automethod:: get_matched_messages
 213
 214   .. automethod:: get_authors
 215
 216   .. automethod:: get_subject
 217
 218   .. automethod:: get_oldest_date
 219
 220   .. automethod:: get_newest_date
 221
 222   .. automethod:: get_tags
 223
 224   .. automethod:: __str__
 225
 226 .. #############################################
 227 .. currentmodule:: cnotmuch.notmuch
 228
 229 :class:`Filenames` -- An iterator over filenames
 230 ------------------------------------------------
 231
 232 To be implemented
 233
 234 :class:`Directoy` -- A directory entry in the database
 235 ------------------------------------------------------
 236
 237 To be implemented
 238
 239 :exc:`NotmuchError` -- A Notmuch execution error
 240 ------------------------------------------------
 241 .. autoexception:: NotmuchError
 242    :members:
 243
 244    This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
 245
 246 :class:`STATUS` -- Notmuch operation return status
 247 --------------------------------------------------
 248 .. autoclass:: STATUS
 249
 250    To be documented
 251
 252 Indices and tables
 253 ==================
 254
 255 * :ref:`genindex`
 256 * :ref:`search`
 257