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"""
"""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`)
: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
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
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(
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
+"""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 <Sebastian@SSpaeth.de>"
-# 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;
.. 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 <http://notmuchmail.org>`_ 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 <Sebastian@SSpaeth.de>
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
: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
-----------------------------------------------------
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
projects / notmuch.git / commitdiff