debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-28 21:54:10 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

python: clean up docstrings and API documentation

Browse source 
Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
This commit is contained in:
Sebastian Spaeth 2011-10-05 17:54:09 +02:00
parent a8db280f58
commit 42f184c236
3 changed files with 41 additions and 69 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
bindings/python/docs/source/index.rst
View file

@ -23,6 +23,12 @@ or::
from notmuch import Query, Database from notmuch import Query, Database
db = Database('path',create=True)
msgs = Query(db,'from:myself').search_messages()
for msg in msgs:
print (msg)
More information on specific topics can be found on the following pages: More information on specific topics can be found on the following pages:
.. toctree:: .. toctree::
@ -36,8 +42,6 @@ More information on specific topics can be found on the following pages:
.. automodule:: notmuch .. automodule:: notmuch
:todo: Document nmlib,STATUS
:class:`notmuch.Database` -- The underlying notmuch database :class:`notmuch.Database` -- The underlying notmuch database
--------------------------------------------------------------------- ---------------------------------------------------------------------
@ -73,9 +77,6 @@ More information on specific topics can be found on the following pages:
.. automethod:: create_query .. automethod:: create_query
.. note:: :meth:`create_query` was broken in release
0.1 and is fixed since 0.1.1.
.. attribute:: Database.MODE .. attribute:: Database.MODE
Defines constants that are used as the mode in which to open a database. Defines constants that are used as the mode in which to open a database.
@ -88,6 +89,7 @@ More information on specific topics can be found on the following pages:
.. autoattribute:: db_p .. autoattribute:: db_p
:class:`notmuch.Query` -- A search query :class:`notmuch.Query` -- A search query
------------------------------------------------- -------------------------------------------------

3
bindings/python/notmuch/__init__.py
View file

@ -17,7 +17,7 @@ likely to need.
db = Database('path',create=True) db = Database('path',create=True)
msgs = Query(db,'from:myself').search_messages() msgs = Query(db,'from:myself').search_messages()
This returns a :class:`Messages` which internally contains a This returns :class:`Messages` which internally contains a
reference to its parent :class:`Query` object. Otherwise the reference to its parent :class:`Query` object. Otherwise the
Query() would be immediately freed, taking our *msgs* down with Query() would be immediately freed, taking our *msgs* down with
it. it.
@ -31,7 +31,6 @@ likely to need.
Pretty much the same is valid for all other objects in the Pretty much the same is valid for all other objects in the
hierarchy, such as :class:`Query`, :class:`Messages`, hierarchy, such as :class:`Query`, :class:`Messages`,
:class:`Message`, and :class:`Tags`. :class:`Message`, and :class:`Tags`.
""" """
""" """

93
bindings/python/notmuch/database.py
View file

@ -26,13 +26,27 @@ from notmuch.message import Messages, Message
from notmuch.tag import Tags from notmuch.tag import Tags
class Database(object): class Database(object):
"""Represents a notmuch database (wraps notmuch_database_t) """The :class:`Database` is the highest-level object that notmuch
provides. It references a notmuch database, and can be opened in
read-only or read-write mode. A :class:`Query` can be derived from
or be applied to a specific database to find messages. Also adding
and removing messages to the database happens via this
object. Modifications to the database are not atmic by default (see
:meth:`begin_atomic`) and once a database has been modified, all
other database objects pointing to the same data-base will throw an
:exc:`XapianError` as the underlying database has been
modified. Close and reopen the database to continue working with it.
.. note:: Do remember that as soon as we tear down this object, .. note:: Any function in this class can and will throw an
all underlying derived objects such as queries, threads, :exc:`NotInitializedError` if the database was not
messages, tags etc will be freed by the underlying library intitialized properly.
as well. Accessing these objects will lead to segfaults and
other unexpected behavior. See above for more details. .. note:: Do remember that as soon as we tear down (e.g. via `del
db`) this object, all underlying derived objects such as
queries, threads, messages, tags etc will be freed by the
underlying library as well. Accessing these objects will lead
to segfaults and other unexpected behavior. See above for
more details.
""" """
_std_db_path = None _std_db_path = None
"""Class attribute to cache user's default database""" """Class attribute to cache user's default database"""
@ -151,7 +165,7 @@ class Database(object):
:type status: :attr:`MODE` :type status: :attr:`MODE`
:returns: Nothing :returns: Nothing
:exception: Raises :exc:`NotmuchError` in case :exception: Raises :exc:`NotmuchError` in case
of any failure (after printing an error message on stderr). of any failure (possibly after printing an error message on stderr).
""" """
res = Database._open(_str(path), mode) res = Database._open(_str(path), mode)
@ -160,9 +174,7 @@ class Database(object):
self._db = res self._db = res
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 underlying `notmuch_database_get_path`"""
self._assert_db_is_initialized() self._assert_db_is_initialized()
return Database._get_path(self._db).decode('utf-8') return Database._get_path(self._db).decode('utf-8')
@ -170,8 +182,6 @@ class Database(object):
"""Returns the database format version """Returns the database format version
:returns: The database version as positive integer :returns: The database version as positive integer
:exception: :exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
return Database._get_version(self._db) return Database._get_version(self._db)
@ -185,8 +195,6 @@ class Database(object):
etc.) will work unless :meth:`upgrade` is called successfully first. etc.) will work unless :meth:`upgrade` is called successfully first.
:returns: `True` or `False` :returns: `True` or `False`
:exception: :exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
return nmlib.notmuch_database_needs_upgrade(self._db) return nmlib.notmuch_database_needs_upgrade(self._db)
@ -205,9 +213,6 @@ class Database(object):
indicating the progress made so far in the upgrade process. indicating the progress made so far in the upgrade process.
:TODO: catch exceptions, document return values and etc... :TODO: catch exceptions, document return values and etc...
:exception: :exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
status = Database._upgrade(self._db, None, None) status = Database._upgrade(self._db, None, None)
@ -229,9 +234,6 @@ class Database(object):
:attr:`STATUS`.XAPIAN_EXCEPTION :attr:`STATUS`.XAPIAN_EXCEPTION
Xapian exception occurred; atomic section not entered. Xapian exception occurred; atomic section not entered.
:exc:`NotInitializedError` if
the database was not intitialized.
*Added in notmuch 0.9*""" *Added in notmuch 0.9*"""
self._assert_db_is_initialized() self._assert_db_is_initialized()
status = nmlib.notmuch_database_begin_atomic(self._db) status = nmlib.notmuch_database_begin_atomic(self._db)
@ -254,9 +256,6 @@ class Database(object):
:attr:`STATUS`.UNBALANCED_ATOMIC: :attr:`STATUS`.UNBALANCED_ATOMIC:
end_atomic has been called more times than begin_atomic. end_atomic has been called more times than begin_atomic.
:exc:`NotInitializedError` if
the database was not intitialized.
*Added in notmuch 0.9*""" *Added in notmuch 0.9*"""
self._assert_db_is_initialized() self._assert_db_is_initialized()
status = nmlib.notmuch_database_end_atomic(self._db) status = nmlib.notmuch_database_end_atomic(self._db)
@ -280,9 +279,6 @@ class Database(object):
:exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR :exc:`NotmuchError` with :attr:`STATUS`.FILE_ERROR
If path is not relative database or absolute with initial If path is not relative database or absolute with initial
components same as database. components same as database.
:exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
# sanity checking if path is valid, and make path absolute # sanity checking if path is valid, and make path absolute
@ -351,9 +347,6 @@ class Database(object):
:attr:`STATUS`.READ_ONLY_DATABASE :attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can Database was opened in read-only mode so no message can
be added. be added.
:exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
msg_p = c_void_p() msg_p = c_void_p()
@ -397,9 +390,6 @@ class Database(object):
:attr:`STATUS`.READ_ONLY_DATABASE :attr:`STATUS`.READ_ONLY_DATABASE
Database was opened in read-only mode so no message can be Database was opened in read-only mode so no message can be
removed. removed.
:exc:`NotInitializedError` if
the database was not intitialized.
""" """
self._assert_db_is_initialized() self._assert_db_is_initialized()
return nmlib.notmuch_database_remove_message(self._db, return nmlib.notmuch_database_remove_message(self._db,
@ -537,11 +527,12 @@ class Query(object):
A query selects and filters a subset of messages from the notmuch A query selects and filters a subset of messages from the notmuch
database we derive from. database we derive from.
Query() provides an instance attribute :attr:`sort`, which :class:`Query` provides an instance attribute :attr:`sort`, which
contains the sort order (if specified via :meth:`set_sort`) or contains the sort order (if specified via :meth:`set_sort`) or
`None`. `None`.
Technically, it wraps the underlying *notmuch_query_t* struct. Any function in this class may throw an :exc:`NotInitializedError`
in case the underlying query object was not set up correctly.
.. note:: Do remember that as soon as we tear down this object, .. note:: Do remember that as soon as we tear down this object,
all underlying derived objects such as threads, all underlying derived objects such as threads,
@ -592,11 +583,11 @@ class Query(object):
:param querystr: The query string :param querystr: The query string
:type querystr: utf-8 encoded str or unicode :type querystr: utf-8 encoded str or unicode
:returns: Nothing :returns: Nothing
:exception: :exc:`NotmuchError` :exception:
:exc:`NullPointerError` if the query creation failed
* :attr:`STATUS`.NOT_INITIALIZED if db is not inited (e.g. too little memory).
* :attr:`STATUS`.NULL_POINTER if the query creation failed :exc:`NotInitializedError` if the underlying db was not
(too little memory) intitialized.
""" """
if db.db_p is None: if db.db_p is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)
@ -611,12 +602,7 @@ class Query(object):
def set_sort(self, sort): def set_sort(self, sort):
"""Set the sort order future results will be delivered in """Set the sort order future results will be delivered in
Wraps the underlying *notmuch_query_set_sort* function.
:param sort: Sort order (see :attr:`Query.SORT`) :param sort: Sort order (see :attr:`Query.SORT`)
:returns: Nothing
:exception: :exc:`NotmuchError` :attr:`STATUS`.NOT_INITIALIZED if query has not
been initialized.
""" """
if self._query is None: if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)
@ -635,14 +621,8 @@ class Query(object):
match the query. The method :meth:`Message.get_flag` allows us match the query. The method :meth:`Message.get_flag` allows us
to get the value of this flag. to get the value of this flag.
Technically, it wraps the underlying
*notmuch_query_search_threads* function.
:returns: :class:`Threads` :returns: :class:`Threads`
:exception: :exc:`NotmuchError` :exception: :exc:`NullPointerError` if search_threads failed
* :attr:`STATUS`.NOT_INITIALIZED if query is not inited
* :attr:`STATUS`.NULL_POINTER if search_threads failed
""" """
if self._query is None: if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)
@ -658,14 +638,8 @@ class Query(object):
"""Filter messages according to the query and return """Filter messages according to the query and return
:class:`Messages` in the defined sort order :class:`Messages` in the defined sort order
Technically, it wraps the underlying
*notmuch_query_search_messages* function.
:returns: :class:`Messages` :returns: :class:`Messages`
:exception: :exc:`NotmuchError` :exception: :exc:`NullPointerError` if search_messages failed
* :attr:`STATUS`.NOT_INITIALIZED if query is not inited
* :attr:`STATUS`.NULL_POINTER if search_messages failed
""" """
if self._query is None: if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)
@ -688,9 +662,6 @@ class Query(object):
*notmuch_query_count_messages* function. *notmuch_query_count_messages* function.
:returns: :class:`Messages` :returns: :class:`Messages`
:exception: :exc:`NotmuchError`
* :attr:`STATUS`.NOT_INITIALIZED if query is not inited
""" """
if self._query is None: if self._query is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)