From 61bef71a126efb02b477209a02789cc194a5b784 Mon Sep 17 00:00:00 2001 From: Sebastian Spaeth Date: Wed, 17 Mar 2010 12:32:22 +0100 Subject: [PATCH] many doc improvements, fixed at least one bug due to parameter renaming --- cnotmuch/__init__.py | 3 -- cnotmuch/database.py | 72 +++++++++++++++++++------------------------ cnotmuch/notmuch.py | 44 +++++++++++++++++++++----- docs/source/index.rst | 21 +++++++------ 4 files changed, 80 insertions(+), 60 deletions(-) diff --git a/cnotmuch/__init__.py b/cnotmuch/__init__.py index e24dc966..e69de29b 100644 --- a/cnotmuch/__init__.py +++ b/cnotmuch/__init__.py @@ -1,3 +0,0 @@ -__version__=0.1 -__author__ ="Sebastian Spaeth " -#ctypes.util.find_library("notmuch") diff --git a/cnotmuch/database.py b/cnotmuch/database.py index eb54626d..2b51e5ea 100644 --- a/cnotmuch/database.py +++ b/cnotmuch/database.py @@ -7,31 +7,11 @@ from datetime import date class Database(object): """Represents a notmuch database (wraps notmuch_database_t) - .. note:: Do note that as soon as we tear down 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. - - We implement reference counting, so that parent objects can be - automatically freed when they are not needed anymore, for example:: - - db = Database('path',create=True) - msgs = Query(db,'from:myself').search_messages() - - This returns a :class:`Messages` which internally contains - a reference to the parent :class:`Query` object. Otherwise - the Query() would be immediately freed, taking our *msgs* - down with it. - - In this case, the above Query() object will be - automatically freed whenever we delete all derived objects, - ie in our case: `del (msgs)` would also delete the parent - Query (but not the parent Database() as that is still - referenced from the variable *db* in which it is stored. - - Pretty much the same is valid for all other objects in the hierarchy, - such as :class:`Query`, :class:`Messages`, :class:`Message`, - and :class:`Tags`. + .. note:: Do remember that as soon as we tear down 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. """ MODE = Enum(['READ_ONLY','READ_WRITE']) """Constants: Mode in which to open the database""" @@ -63,8 +43,7 @@ class Database(object): """If *path* is *None*, we will try to read a users notmuch configuration and use his default database. If *create* is `True`, the database will always be created in - :attr:`MODE.READ_WRITE` mode as creating an empty - database for reading only does not make a great deal of sense. + :attr:`MODE`.READ_WRITE mode. :param path: Directory to open/create the database in (see above for behavior if `None`) @@ -72,7 +51,7 @@ class Database(object): :param create: False to open an existing, True to create a new database. :type create: bool - :param mdoe: Mode to open a database in. Always + :param mode: Mode to open a database in. Always :attr:`MODE`.READ_WRITE when creating a new one. :type mode: :attr:`MODE` :returns: Nothing @@ -87,17 +66,19 @@ class Database(object): path = Database._std_db_path if create == False: - self.open(path, status) + self.open(path, mode) else: self.create(path) def create(self, path): """Creates a new notmuch database - This function wraps *notmuch_database_create(...)* 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 reading only does not make a great deal of sense. + This function is used by __init__() 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 + reading only does not make a great deal of sense. :param path: A directory in which we should create the database. :type path: str @@ -116,14 +97,21 @@ class Database(object): message="Could not create the specified database") self._db = res - def open(self, path, status= MODE.READ_ONLY): - """calls notmuch_database_open + def open(self, path, mode= MODE.READ_ONLY): + """Opens an existing database - :returns: Raises :exc:`notmuch.NotmuchError` in case - of any failure (after printing an error message on stderr). + This function is used by __init__() usually does not need + to be called directly. It wraps the underlying + *notmuch_database_open* function. + + :param status: Open the database in read-only or read-write mode + :type status: :attr:`MODE` + :returns: Nothing + :exception: Raises :exc:`notmuch.NotmuchError` in case + of any failure (after printing an error message on stderr). """ - res = Database._open(path, status) + res = Database._open(path, mode) if res is None: raise NotmuchError( @@ -131,11 +119,15 @@ class Database(object): self._db = res def get_path(self): - """notmuch_database_get_path (notmuch_database_t *database); """ + """Returns the file path of an open database + + Wraps notmuch_database_get_path""" return Database._get_path(self._db) def find_message(self, msgid): - """notmuch_database_find_message + """Returns a :class:`Message` as identified by its message ID + + wraps *notmuch_database_find_message* :param msgid: The message id :type msgid: string diff --git a/cnotmuch/notmuch.py b/cnotmuch/notmuch.py index 4bf593a7..e945d496 100644 --- a/cnotmuch/notmuch.py +++ b/cnotmuch/notmuch.py @@ -1,12 +1,42 @@ +"""The :mod:`notmuch` module provides most of the functionality that a user is likely to need. + +.. note:: The underlying notmuch library is build on a hierarchical + memory allocator called talloc. All objects derive from a + top-level :class:`Database` object. + + This means that as soon as an object is deleted, all underlying + derived objects such as Queries, Messages, Message, and Tags will + be freed by the underlying library as well. Accessing these + objects will then lead to segfaults and other unexpected behavior. + + We implement reference counting, so that parent objects can be + automatically freed when they are not needed anymore. For + example:: + + db = Database('path',create=True) + msgs = Query(db,'from:myself').search_messages() + + This returns a :class:`Messages` which internally contains a + reference to its parent :class:`Query` object. Otherwise the + Query() would be immediately freed, taking our *msgs* down with + it. + + In this case, the above Query() object will be automatically freed + whenever we delete all derived objects, ie in our case: + `del(msgs)` would also delete the parent Query (but not the parent + Database() as that is still referenced from the variable *db* in + which it is stored. + + Pretty much the same is valid for all other objects in the + hierarchy, such as :class:`Query`, :class:`Messages`, + :class:`Message`, and :class:`Tags`. + +""" import ctypes from ctypes import c_int, c_char_p from database import Database,Tags,Query,Messages,Message,Tags from cnotmuch.globals import nmlib,STATUS,NotmuchError +__LICENSE__="GPL v3+" +__VERSION__=0.1 +__AUTHOR__ ="Sebastian Spaeth " -# 114 typedef struct _notmuch_query notmuch_query_t; -# 115 typedef struct _notmuch_threads notmuch_threads_t; -# 116 typedef struct _notmuch_thread notmuch_thread_t; -# 117 typedef struct _notmuch_messages notmuch_messages_t; -# 118 typedef struct _notmuch_message notmuch_message_t; -# 120 typedef struct _notmuch_directory notmuch_directory_t; -# 121 typedef struct _notmuch_filenames notmuch_filenames_t; diff --git a/docs/source/index.rst b/docs/source/index.rst index 06f21422..d6f9411d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ .. cnotmuch documentation master file, created by sphinx-quickstart on Tue Feb 2 10:00:47 2010. -.. currentmodule:: cnotmuch.notmuch +.. currentmodule:: cnotmuch -Welcome to notmuch's documentation! -=================================== +Welcome to :mod:`cnotmuch`'s documentation +=========================================== The :mod:`cnotmuch` module provides an interface to the `notmuch `_ functionality, directly interfacing to a shared notmuch library. -The classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Messages` and :class:`Tags`. +The classes :class:`notmuch.Database`, :class:`notmuch.Query` provide most of the core functionality, returning :class:`notmuch.Messages` and :class:`notmuch.Tags`. .. moduleauthor:: Sebastian Spaeth @@ -15,11 +15,11 @@ The classes :class:`Database`, :class:`Query` provide most of the core functiona This page contains the main API overview. More information on specific topics can be found on the following pages: (none here yet) -Notmuch can be imported as: +Notmuch can be imported as:: from cnotmuch import notmuch -or: +or:: from cnotmuch.notmuch import Query,Database @@ -27,11 +27,12 @@ or: :maxdepth: 1 - :mod:`notmuch` -- The Notmuch interface ============================================= -Document from cnotmuch.globals import nmlib,STATUS +.. automodule:: cnotmuch.notmuch + +:todo: Document nmlib,STATUS :class:`Database` -- The underlying notmuch database ----------------------------------------------------- @@ -53,10 +54,10 @@ Document from cnotmuch.globals import nmlib,STATUS Defines constants that are used as the mode in which to open a database. - READ_ONLY + MODE.READ_ONLY Open the database in read-only mode - READ_WRITE + MODE.READ_WRITE Open the database in read-write mode .. autoattribute:: db_p