debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-22 19:08:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

many doc improvements, fixed at least one bug due to parameter renaming

Browse source
This commit is contained in:
Sebastian Spaeth 2010-03-17 12:32:22 +01:00
parent 06f627df92
commit 61bef71a12
4 changed files with 80 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
cnotmuch/__init__.py
View file

@ -1,3 +0,0 @@
__version__=0.1
__author__ ="Sebastian Spaeth <Sebastian@SSpaeth.de>"
#ctypes.util.find_library("notmuch")

70
cnotmuch/database.py
View file

@ -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
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

44
cnotmuch/notmuch.py
View file

@ -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 <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;

21
docs/source/index.rst
View file

@ -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 <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>
@ -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