python: rename filename.py into filenames.py
[notmuch] / bindings / python / notmuch / __init__.py
1 """The :mod:`notmuch` module provides most of the functionality that a user is
2 likely to need.
3
4 .. note:: The underlying notmuch library is build on a hierarchical
5     memory allocator called talloc. All objects derive from a
6     top-level :class:`Database` object.
7
8     This means that as soon as an object is deleted, all underlying
9     derived objects such as Queries, Messages, Message, and Tags will
10     be freed by the underlying library as well. Accessing these
11     objects will then lead to segfaults and other unexpected behavior.
12
13     We implement reference counting, so that parent objects can be
14     automatically freed when they are not needed anymore. For
15     example::
16
17             db = Database('path',create=True)
18             msgs = Query(db,'from:myself').search_messages()
19
20     This returns :class:`Messages` which internally contains a
21     reference to its parent :class:`Query` object. Otherwise the
22     Query() would be immediately freed, taking our *msgs* down with
23     it.
24
25     In this case, the above Query() object will be automatically freed
26     whenever we delete all derived objects, ie in our case:
27     `del(msgs)` would also delete the parent Query. It would not
28     delete the parent Database() though, as that is still referenced
29     from the variable *db* in which it is stored.
30
31     Pretty much the same is valid for all other objects in the
32     hierarchy, such as :class:`Query`, :class:`Messages`,
33     :class:`Message`, and :class:`Tags`.
34 """
35
36 """
37 This file is part of notmuch.
38
39 Notmuch is free software: you can redistribute it and/or modify it
40 under the terms of the GNU General Public License as published by the
41 Free Software Foundation, either version 3 of the License, or (at your
42 option) any later version.
43
44 Notmuch is distributed in the hope that it will be useful, but WITHOUT
45 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
46 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
47 for more details.
48
49 You should have received a copy of the GNU General Public License
50 along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
51
52 Copyright 2010-2011 Sebastian Spaeth <Sebastian@SSpaeth.de>
53 """
54 from .database import Database
55 from .directory import Directory
56 from .filenames import Filenames
57 from .message import Message
58 from .messages import Messages
59 from .query import Query
60 from .tag import Tags
61 from .thread import Thread
62 from .threads import Threads
63 from .globals import (
64     nmlib,
65     STATUS,
66     NotmuchError,
67     OutOfMemoryError,
68     ReadOnlyDatabaseError,
69     XapianError,
70     FileError,
71     FileNotEmailError,
72     DuplicateMessageIdError,
73     NullPointerError,
74     TagTooLongError,
75     UnbalancedFreezeThawError,
76     UnbalancedAtomicError,
77     NotInitializedError,
78 )
79 from .version import __VERSION__
80 __LICENSE__ = "GPL v3+"
81 __AUTHOR__ = 'Sebastian Spaeth <Sebastian@SSpaeth.de>'