_get_directory = nmlib.notmuch_database_get_directory
_get_directory.restype = c_void_p
- """notmuch_database_get_path (notmuch_database_t *database)"""
+ """notmuch_database_get_path"""
_get_path = nmlib.notmuch_database_get_path
_get_path.restype = c_char_p
_get_version = nmlib.notmuch_database_get_version
_get_version.restype = c_uint
- """notmuch_database_open (const char *path, notmuch_database_mode_t mode)"""
+ """notmuch_database_open"""
_open = nmlib.notmuch_database_open
_open.restype = c_void_p
_upgrade = nmlib.notmuch_database_upgrade
_upgrade.argtypes = [c_void_p, c_void_p, c_void_p]
- """ notmuch_database_find_message """
+ """ notmuch_database_find_message"""
_find_message = nmlib.notmuch_database_find_message
_find_message.restype = c_void_p
- """notmuch_database_get_all_tags (notmuch_database_t *database)"""
+ """notmuch_database_get_all_tags"""
_get_all_tags = nmlib.notmuch_database_get_all_tags
_get_all_tags.restype = c_void_p
- """ notmuch_database_create(const char *path):"""
+ """notmuch_database_create"""
_create = nmlib.notmuch_database_create
_create.restype = c_void_p
def __init__(self, path=None, create=False, mode= 0):
- """If *path* is *None*, we will try to read a users notmuch
+ """If *path* is `None`, we will try to read a users notmuch
configuration and use his configured database. The location of the
configuration file can be specified through the environment variable
*NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
This function is used by __init__() and usually does not need
to be called directly. It wraps the underlying
*notmuch_database_create* function and creates a new notmuch
- database at *path*. It will always return a database in
- :attr:`MODE`.READ_WRITE mode as creating an empty database for
+ database at *path*. It will always return a database in :attr:`MODE`
+ .READ_WRITE mode as creating an empty database for
reading only does not make a great deal of sense.
:param path: A directory in which we should create the database.
def get_path(self):
"""Returns the file path of an open database
- Wraps notmuch_database_get_path"""
+ Wraps *notmuch_database_get_path*."""
# Raise a NotmuchError if not initialized
self._verify_initialized_db()
def needs_upgrade(self):
"""Does this database need to be upgraded before writing to it?
- If this function returns True then no functions that modify the
- database (:meth:`add_message`, :meth:`add_tag`,
- :meth:`Directory.set_mtime`, etc.) will work unless :meth:`upgrade`
- is called successfully first.
+ If this function returns `True` then no functions that modify the
+ database (:meth:`add_message`,
+ :meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
+ etc.) will work unless :meth:`upgrade` is called successfully first.
:returns: `True` or `False`
:exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
NOT IMPLEMENTED: The optional progress_notify callback can be
used by the caller to provide progress indication to the
user. If non-NULL it will be called periodically with
- 'progress' as a floating-point value in the range of [0.0
- .. 1.0] indicating the progress made so far in the upgrade
- process.
+ 'progress' as a floating-point value in the range of [0.0..1.0]
+ indicating the progress made so far in the upgrade process.
+
+ :TODO: catch exceptions, document return values and etc...
"""
# Raise a NotmuchError if not initialized
self._verify_initialized_db()
program if this method is used on a read-only database!
:param path: A str containing the path relative to the path of database
- (see :meth:`get_path`), or else should be an absolute path
- with initial components that match the path of 'database'.
-
+ (see :meth:`get_path`), or else should be an absolute path
+ with initial components that match the path of 'database'.
:returns: :class:`Directory` or raises an exception.
:exception: :exc:`NotmuchError`
is removed for a particular message, the database content for that
message will be entirely removed.
- :returns: A STATUS.* value with the following meaning:
+ :returns: A STATUS value with the following meaning:
STATUS.SUCCESS
The last filename was removed and the message was removed
:param path: The absolute path of the directory object.
:param dir_p: The pointer to an internal notmuch_directory_t object.
:param parent: The object this Directory is derived from
- (usually a Database()). We do not directly use
+ (usually a :class:`Database`). We do not directly use
this, but store a reference to it as long as
this Directory object lives. This keeps the
parent object alive.
return Directory._get_mtime (self._dir_p)
-
# Make mtime attribute a property of Directory()
mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
- and setting of the Directory *mtime*""")
+ and setting of the Directory *mtime* (read-write)
+
+ See :meth:`get_mtime` and :meth:`set_mtime` for usage and
+ possible exceptions.""")
def get_child_files(self):
"""Gets a Filenames iterator listing all the filenames of
return Filenames(files_p, self)
def get_child_directories(self):
- """Gets a Filenams iterator listing all the filenames of
+ """Gets a :class:`Filenames` iterator listing all the filenames of
sub-directories in the database within the given directory
The returned filenames will be the basename-entries only (not
@property
def path(self):
- """Returns the absolute path of this Directory"""
+ """Returns the absolute path of this Directory (read-only)"""
return self._path
def __repr__(self):
#------------------------------------------------------------------------------
class Filenames(object):
- """An iterator over File- or Directory names that are stored in the notmuch database
+ """An iterator over File- or Directory names that are stored in the database
"""
#notmuch_filenames_get
.. cnotmuch documentation master file, created by
sphinx-quickstart on Tue Feb 2 10:00:47 2010.
-.. currentmodule:: cnotmuch
+.. currentmodule:: cnotmuch.notmuch
Welcome to :mod:`cnotmuch`'s documentation
===========================================
The :mod:`cnotmuch` module provides an interface to the `notmuch <http://notmuchmail.org>`_ functionality, directly interfacing to a shared notmuch library.
-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`.
+Within :mod:`cnotmuch.notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`.
.. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
notmuch
-:mod:`notmuch` -- The Notmuch interface
-=============================================
+:mod:`cnotmuch.notmuch` -- The Notmuch interface
+=================================================
.. automodule:: cnotmuch.notmuch
:todo: Document nmlib,STATUS
-:class:`Database` -- The underlying notmuch database
------------------------------------------------------
+:class:`cnotmuch.notmuch.Database` -- The underlying notmuch database
+---------------------------------------------------------------------
-.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
+.. autoclass:: cnotmuch.notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]])
.. automethod:: create
.. autoattribute:: db_p
-:class:`Query` -- A search query
------------------------------------------------
+:class:`cnotmuch.notmuch.Query` -- A search query
+-------------------------------------------------
-.. autoclass:: Query
+.. autoclass:: cnotmuch.notmuch.Query
.. automethod:: create
.. automethod:: count_messages
-.. #############################################
-.. currentmodule:: cnotmuch.message
:class:`Messages` -- A bunch of messages
----------------------------------------
.. automethod:: __str__
-.. #############################################
-.. currentmodule:: cnotmuch.tag
:class:`Tags` -- Notmuch tags
-----------------------------
.. automethod:: __str__
-.. #############################################
-.. currentmodule:: cnotmuch.thread
-
-:class:`Threads` -- Threads iterator
-------------------------------------
+:class:`cnotmuch.notmuch.Threads` -- Threads iterator
+-----------------------------------------------------
-.. autoclass:: Threads
+.. autoclass:: cnotmuch.notmuch.Threads
.. automethod:: __len__
.. automethod:: __str__
-.. #############################################
-.. currentmodule:: cnotmuch.notmuch
:class:`Filenames` -- An iterator over filenames
------------------------------------------------
-To be implemented
+.. autoclass:: cnotmuch.database.Filenames
+
+ .. automethod:: cnotmuch.database.Filenames.__len__
+
+:class:`cnotmuch.database.Directoy` -- A directory entry in the database
+------------------------------------------------------------------------
-:class:`Directoy` -- A directory entry in the database
-------------------------------------------------------
+.. autoclass:: cnotmuch.database.Directory
-To be implemented
+ .. automethod:: cnotmuch.database.Directory.get_child_files
+
+ .. automethod:: cnotmuch.database.Directory.get_child_directories
+
+ .. automethod:: cnotmuch.database.Directory.get_mtime
+
+ .. automethod:: cnotmuch.database.Directory.set_mtime
+
+ .. autoattribute:: cnotmuch.database.Directory.mtime
+
+ .. autoattribute:: cnotmuch.database.Directory.path
:exc:`NotmuchError` -- A Notmuch execution error
------------------------------------------------
:class:`STATUS` -- Notmuch operation return status
--------------------------------------------------
-.. autoclass:: STATUS
- To be documented
+.. data:: STATUS
+
+ 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.
+
+ * SUCCESS
+ * OUT_OF_MEMORY
+ * READ_ONLY_DATABASE
+ * XAPIAN_EXCEPTION
+ * FILE_ERROR
+ * FILE_NOT_EMAIL
+ * DUPLICATE_MESSAGE_ID
+ * NULL_POINTER
+ * TAG_TOO_LONG
+ * UNBALANCED_FREEZE_THAW
+ * NOT_INITIALIZED
+
Indices and tables
==================
projects / notmuch / commitdiff