mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-22 19:08:09 +01:00
docs: Improve documentations
This commit is contained in:
parent
bef8bdbd04
commit
7390c869c7
2 changed files with 75 additions and 54 deletions
|
@ -24,7 +24,7 @@ class Database(object):
|
||||||
_get_directory = nmlib.notmuch_database_get_directory
|
_get_directory = nmlib.notmuch_database_get_directory
|
||||||
_get_directory.restype = c_void_p
|
_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 = nmlib.notmuch_database_get_path
|
||||||
_get_path.restype = c_char_p
|
_get_path.restype = c_char_p
|
||||||
|
|
||||||
|
@ -32,7 +32,7 @@ class Database(object):
|
||||||
_get_version = nmlib.notmuch_database_get_version
|
_get_version = nmlib.notmuch_database_get_version
|
||||||
_get_version.restype = c_uint
|
_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 = nmlib.notmuch_database_open
|
||||||
_open.restype = c_void_p
|
_open.restype = c_void_p
|
||||||
|
|
||||||
|
@ -44,16 +44,16 @@ class Database(object):
|
||||||
_find_message = nmlib.notmuch_database_find_message
|
_find_message = nmlib.notmuch_database_find_message
|
||||||
_find_message.restype = c_void_p
|
_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 = nmlib.notmuch_database_get_all_tags
|
||||||
_get_all_tags.restype = c_void_p
|
_get_all_tags.restype = c_void_p
|
||||||
|
|
||||||
""" notmuch_database_create(const char *path):"""
|
"""notmuch_database_create"""
|
||||||
_create = nmlib.notmuch_database_create
|
_create = nmlib.notmuch_database_create
|
||||||
_create.restype = c_void_p
|
_create.restype = c_void_p
|
||||||
|
|
||||||
def __init__(self, path=None, create=False, mode= 0):
|
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 and use his configured database. The location of the
|
||||||
configuration file can be specified through the environment variable
|
configuration file can be specified through the environment variable
|
||||||
*NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
|
*NOTMUCH_CONFIG*, falling back to the default `~/.notmuch-config`.
|
||||||
|
@ -97,8 +97,8 @@ class Database(object):
|
||||||
This function is used by __init__() and usually does not need
|
This function is used by __init__() and usually does not need
|
||||||
to be called directly. It wraps the underlying
|
to be called directly. It wraps the underlying
|
||||||
*notmuch_database_create* function and creates a new notmuch
|
*notmuch_database_create* function and creates a new notmuch
|
||||||
database at *path*. It will always return a database in
|
database at *path*. It will always return a database in :attr:`MODE`
|
||||||
:attr:`MODE`.READ_WRITE mode as creating an empty database for
|
.READ_WRITE mode as creating an empty database for
|
||||||
reading only does not make a great deal of sense.
|
reading only does not make a great deal of sense.
|
||||||
|
|
||||||
:param path: A directory in which we should create the database.
|
:param path: A directory in which we should create the database.
|
||||||
|
@ -142,7 +142,7 @@ class Database(object):
|
||||||
def get_path(self):
|
def get_path(self):
|
||||||
"""Returns the file path of an open database
|
"""Returns the file path of an open database
|
||||||
|
|
||||||
Wraps notmuch_database_get_path"""
|
Wraps *notmuch_database_get_path*."""
|
||||||
# Raise a NotmuchError if not initialized
|
# Raise a NotmuchError if not initialized
|
||||||
self._verify_initialized_db()
|
self._verify_initialized_db()
|
||||||
|
|
||||||
|
@ -163,10 +163,10 @@ class Database(object):
|
||||||
def needs_upgrade(self):
|
def needs_upgrade(self):
|
||||||
"""Does this database need to be upgraded before writing to it?
|
"""Does this database need to be upgraded before writing to it?
|
||||||
|
|
||||||
If this function returns True then no functions that modify the
|
If this function returns `True` then no functions that modify the
|
||||||
database (:meth:`add_message`, :meth:`add_tag`,
|
database (:meth:`add_message`,
|
||||||
:meth:`Directory.set_mtime`, etc.) will work unless :meth:`upgrade`
|
:meth:`Message.add_tag`, :meth:`Directory.set_mtime`,
|
||||||
is called successfully first.
|
etc.) will work unless :meth:`upgrade` is called successfully first.
|
||||||
|
|
||||||
:returns: `True` or `False`
|
:returns: `True` or `False`
|
||||||
:exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
|
:exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
|
||||||
|
@ -187,9 +187,10 @@ class Database(object):
|
||||||
NOT IMPLEMENTED: The optional progress_notify callback can be
|
NOT IMPLEMENTED: The optional progress_notify callback can be
|
||||||
used by the caller to provide progress indication to the
|
used by the caller to provide progress indication to the
|
||||||
user. If non-NULL it will be called periodically with
|
user. If non-NULL it will be called periodically with
|
||||||
'progress' as a floating-point value in the range of [0.0
|
'progress' as a floating-point value in the range of [0.0..1.0]
|
||||||
.. 1.0] indicating the progress made so far in the upgrade
|
indicating the progress made so far in the upgrade process.
|
||||||
process.
|
|
||||||
|
:TODO: catch exceptions, document return values and etc...
|
||||||
"""
|
"""
|
||||||
# Raise a NotmuchError if not initialized
|
# Raise a NotmuchError if not initialized
|
||||||
self._verify_initialized_db()
|
self._verify_initialized_db()
|
||||||
|
@ -209,7 +210,6 @@ class Database(object):
|
||||||
:param path: A str containing the path relative to the path of 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
|
(see :meth:`get_path`), or else should be an absolute path
|
||||||
with initial components that match the path of 'database'.
|
with initial components that match the path of 'database'.
|
||||||
|
|
||||||
:returns: :class:`Directory` or raises an exception.
|
:returns: :class:`Directory` or raises an exception.
|
||||||
:exception: :exc:`NotmuchError`
|
:exception: :exc:`NotmuchError`
|
||||||
|
|
||||||
|
@ -308,7 +308,7 @@ class Database(object):
|
||||||
is removed for a particular message, the database content for that
|
is removed for a particular message, the database content for that
|
||||||
message will be entirely removed.
|
message will be entirely removed.
|
||||||
|
|
||||||
:returns: A STATUS.* value with the following meaning:
|
:returns: A STATUS value with the following meaning:
|
||||||
|
|
||||||
STATUS.SUCCESS
|
STATUS.SUCCESS
|
||||||
The last filename was removed and the message was removed
|
The last filename was removed and the message was removed
|
||||||
|
@ -636,7 +636,7 @@ class Directory(object):
|
||||||
:param path: The absolute path of the directory object.
|
:param path: The absolute path of the directory object.
|
||||||
:param dir_p: The pointer to an internal notmuch_directory_t object.
|
:param dir_p: The pointer to an internal notmuch_directory_t object.
|
||||||
:param parent: The object this Directory is derived from
|
: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, but store a reference to it as long as
|
||||||
this Directory object lives. This keeps the
|
this Directory object lives. This keeps the
|
||||||
parent object alive.
|
parent object alive.
|
||||||
|
@ -710,10 +710,12 @@ class Directory(object):
|
||||||
|
|
||||||
return Directory._get_mtime (self._dir_p)
|
return Directory._get_mtime (self._dir_p)
|
||||||
|
|
||||||
|
|
||||||
# Make mtime attribute a property of Directory()
|
# Make mtime attribute a property of Directory()
|
||||||
mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
|
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):
|
def get_child_files(self):
|
||||||
"""Gets a Filenames iterator listing all the filenames of
|
"""Gets a Filenames iterator listing all the filenames of
|
||||||
|
@ -729,7 +731,7 @@ class Directory(object):
|
||||||
return Filenames(files_p, self)
|
return Filenames(files_p, self)
|
||||||
|
|
||||||
def get_child_directories(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
|
sub-directories in the database within the given directory
|
||||||
|
|
||||||
The returned filenames will be the basename-entries only (not
|
The returned filenames will be the basename-entries only (not
|
||||||
|
@ -743,7 +745,7 @@ class Directory(object):
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def path(self):
|
def path(self):
|
||||||
"""Returns the absolute path of this Directory"""
|
"""Returns the absolute path of this Directory (read-only)"""
|
||||||
return self._path
|
return self._path
|
||||||
|
|
||||||
def __repr__(self):
|
def __repr__(self):
|
||||||
|
@ -757,7 +759,7 @@ class Directory(object):
|
||||||
|
|
||||||
#------------------------------------------------------------------------------
|
#------------------------------------------------------------------------------
|
||||||
class Filenames(object):
|
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
|
#notmuch_filenames_get
|
||||||
|
|
|
@ -1,13 +1,13 @@
|
||||||
.. cnotmuch documentation master file, created by
|
.. cnotmuch documentation master file, created by
|
||||||
sphinx-quickstart on Tue Feb 2 10:00:47 2010.
|
sphinx-quickstart on Tue Feb 2 10:00:47 2010.
|
||||||
|
|
||||||
.. currentmodule:: cnotmuch
|
.. currentmodule:: cnotmuch.notmuch
|
||||||
|
|
||||||
Welcome to :mod:`cnotmuch`'s documentation
|
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 :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>
|
.. moduleauthor:: Sebastian Spaeth <Sebastian@SSpaeth.de>
|
||||||
|
|
||||||
|
@ -30,17 +30,17 @@ More information on specific topics can be found on the following pages:
|
||||||
|
|
||||||
notmuch
|
notmuch
|
||||||
|
|
||||||
:mod:`notmuch` -- The Notmuch interface
|
:mod:`cnotmuch.notmuch` -- The Notmuch interface
|
||||||
=============================================
|
=================================================
|
||||||
|
|
||||||
.. automodule:: cnotmuch.notmuch
|
.. automodule:: cnotmuch.notmuch
|
||||||
|
|
||||||
:todo: Document nmlib,STATUS
|
: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
|
.. automethod:: create
|
||||||
|
|
||||||
|
@ -81,10 +81,10 @@ More information on specific topics can be found on the following pages:
|
||||||
|
|
||||||
.. autoattribute:: db_p
|
.. autoattribute:: db_p
|
||||||
|
|
||||||
:class:`Query` -- A search query
|
:class:`cnotmuch.notmuch.Query` -- A search query
|
||||||
-----------------------------------------------
|
-------------------------------------------------
|
||||||
|
|
||||||
.. autoclass:: Query
|
.. autoclass:: cnotmuch.notmuch.Query
|
||||||
|
|
||||||
.. automethod:: create
|
.. automethod:: create
|
||||||
|
|
||||||
|
@ -115,8 +115,6 @@ More information on specific topics can be found on the following pages:
|
||||||
|
|
||||||
.. automethod:: count_messages
|
.. automethod:: count_messages
|
||||||
|
|
||||||
.. #############################################
|
|
||||||
.. currentmodule:: cnotmuch.message
|
|
||||||
|
|
||||||
:class:`Messages` -- A bunch of messages
|
:class:`Messages` -- A bunch of messages
|
||||||
----------------------------------------
|
----------------------------------------
|
||||||
|
@ -172,8 +170,6 @@ More information on specific topics can be found on the following pages:
|
||||||
|
|
||||||
.. automethod:: __str__
|
.. automethod:: __str__
|
||||||
|
|
||||||
.. #############################################
|
|
||||||
.. currentmodule:: cnotmuch.tag
|
|
||||||
|
|
||||||
:class:`Tags` -- Notmuch tags
|
:class:`Tags` -- Notmuch tags
|
||||||
-----------------------------
|
-----------------------------
|
||||||
|
@ -186,13 +182,10 @@ More information on specific topics can be found on the following pages:
|
||||||
.. automethod:: __str__
|
.. automethod:: __str__
|
||||||
|
|
||||||
|
|
||||||
.. #############################################
|
:class:`cnotmuch.notmuch.Threads` -- Threads iterator
|
||||||
.. currentmodule:: cnotmuch.thread
|
-----------------------------------------------------
|
||||||
|
|
||||||
:class:`Threads` -- Threads iterator
|
.. autoclass:: cnotmuch.notmuch.Threads
|
||||||
------------------------------------
|
|
||||||
|
|
||||||
.. autoclass:: Threads
|
|
||||||
|
|
||||||
.. automethod:: __len__
|
.. automethod:: __len__
|
||||||
|
|
||||||
|
@ -223,18 +216,30 @@ More information on specific topics can be found on the following pages:
|
||||||
|
|
||||||
.. automethod:: __str__
|
.. automethod:: __str__
|
||||||
|
|
||||||
.. #############################################
|
|
||||||
.. currentmodule:: cnotmuch.notmuch
|
|
||||||
|
|
||||||
:class:`Filenames` -- An iterator over filenames
|
:class:`Filenames` -- An iterator over filenames
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
|
||||||
To be implemented
|
.. autoclass:: cnotmuch.database.Filenames
|
||||||
|
|
||||||
:class:`Directoy` -- A directory entry in the database
|
.. automethod:: cnotmuch.database.Filenames.__len__
|
||||||
------------------------------------------------------
|
|
||||||
|
|
||||||
To be implemented
|
:class:`cnotmuch.database.Directoy` -- A directory entry in the database
|
||||||
|
------------------------------------------------------------------------
|
||||||
|
|
||||||
|
.. autoclass:: cnotmuch.database.Directory
|
||||||
|
|
||||||
|
.. 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
|
:exc:`NotmuchError` -- A Notmuch execution error
|
||||||
------------------------------------------------
|
------------------------------------------------
|
||||||
|
@ -245,9 +250,23 @@ To be implemented
|
||||||
|
|
||||||
:class:`STATUS` -- Notmuch operation return status
|
: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
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
Loading…
Reference in a new issue