From ff8f864245c3ac54cc23aa47af09c95cde484abb Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Sat, 18 Feb 2012 01:32:21 +0100 Subject: python: wrap notmuch_query_count_threads as Query.count_threads Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index f7d3d60..5405de8 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -128,6 +128,8 @@ More information on specific topics can be found on the following pages: .. automethod:: count_messages + .. automethod:: count_threads + :class:`Messages` -- A bunch of messages ---------------------------------------- -- cgit v1.2.3 From ab2f9fd828058d281480e9947ea346e382a7f3c8 Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Sat, 18 Feb 2012 01:41:23 +0100 Subject: python: remove trailing whitespace within the documentation source files Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 14 +++++++------- bindings/python/docs/source/notmuch.rst | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index 5405de8..25eb146 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -13,7 +13,7 @@ Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide mos :License: This module is covered under the GNU GPL v3 (or later). -This page contains the main API overview of notmuch |release|. +This page contains the main API overview of notmuch |release|. Notmuch can be imported as:: @@ -35,7 +35,7 @@ More information on specific topics can be found on the following pages: :maxdepth: 1 status_and_errors - notmuch + notmuch :mod:`notmuch` -- The Notmuch interface ================================================= @@ -111,8 +111,8 @@ More information on specific topics can be found on the following pages: Sort by email message ID. SORT.UNSORTED - Do not apply a special sort order (returns results in document id - order). + Do not apply a special sort order (returns results in document id + order). .. automethod:: set_sort @@ -141,7 +141,7 @@ More information on specific topics can be found on the following pages: .. method:: __len__() .. warning:: - + :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`. @@ -162,7 +162,7 @@ More information on specific topics can be found on the following pages: .. attribute:: FLAG - FLAG.MATCH + FLAG.MATCH This flag is automatically set by a Query.search_threads on those messages that match the query. This allows us to distinguish matches from the rest @@ -171,7 +171,7 @@ More information on specific topics can be found on the following pages: .. automethod:: get_flag .. automethod:: set_flag - + .. automethod:: get_date .. automethod:: get_header diff --git a/bindings/python/docs/source/notmuch.rst b/bindings/python/docs/source/notmuch.rst index 32e1783..bf68f33 100644 --- a/bindings/python/docs/source/notmuch.rst +++ b/bindings/python/docs/source/notmuch.rst @@ -29,7 +29,7 @@ Where and [args...] are as follows: **show** [...] Show all messages matching the search terms. - This has been partially implemented, we show a stub for each + This has been partially implemented, we show a stub for each found message, but do not output the full message body yet. **count** [...] -- cgit v1.2.3 From ba95980cf1a5e2b32104611ccdf2e9c43bf3305a Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Wed, 22 Feb 2012 21:55:59 +0100 Subject: python: refactor the python bindings Move the Directory class into its own file, merge the two Filenames classes into one, deprecate Filenames.as_iterator, update the documentation accordingly. Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 20 +-- bindings/python/notmuch/__init__.py | 15 ++- bindings/python/notmuch/database.py | 239 +--------------------------------- bindings/python/notmuch/directory.py | 183 ++++++++++++++++++++++++++ bindings/python/notmuch/filename.py | 62 +++++++-- 5 files changed, 256 insertions(+), 263 deletions(-) create mode 100644 bindings/python/notmuch/directory.py (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index 25eb146..e87a865 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -254,26 +254,28 @@ More information on specific topics can be found on the following pages: :class:`Filenames` -- An iterator over filenames ------------------------------------------------ -.. autoclass:: notmuch.database.Filenames +.. autoclass:: notmuch.Filenames - .. automethod:: notmuch.database.Filenames.__len__ + .. automethod:: notmuch.Filenames.__len__ + + .. automethod:: notmuch.Filenames.as_generator :class:`notmuch.database.Directoy` -- A directory entry in the database ------------------------------------------------------------------------ -.. autoclass:: notmuch.database.Directory +.. autoclass:: notmuch.Directory - .. automethod:: notmuch.database.Directory.get_child_files + .. automethod:: notmuch.Directory.get_child_files - .. automethod:: notmuch.database.Directory.get_child_directories + .. automethod:: notmuch.Directory.get_child_directories - .. automethod:: notmuch.database.Directory.get_mtime + .. automethod:: notmuch.Directory.get_mtime - .. automethod:: notmuch.database.Directory.set_mtime + .. automethod:: notmuch.Directory.set_mtime - .. autoattribute:: notmuch.database.Directory.mtime + .. autoattribute:: notmuch.Directory.mtime - .. autoattribute:: notmuch.database.Directory.path + .. autoattribute:: notmuch.Directory.path The `next page `_ contains information on possible Status and Error values. diff --git a/bindings/python/notmuch/__init__.py b/bindings/python/notmuch/__init__.py index f3ff987..8de73d5 100644 --- a/bindings/python/notmuch/__init__.py +++ b/bindings/python/notmuch/__init__.py @@ -51,11 +51,14 @@ along with notmuch. If not, see . Copyright 2010-2011 Sebastian Spaeth """ -from notmuch.database import Database, Query -from notmuch.message import Messages, Message -from notmuch.thread import Threads, Thread -from notmuch.tag import Tags -from notmuch.globals import ( +from .database import Database +from .directory import Directory +from .filename import Filenames +from .message import Messages, Message +from .query import Query +from .tag import Tags +from .thread import Threads, Thread +from .globals import ( nmlib, STATUS, NotmuchError, @@ -71,6 +74,6 @@ from notmuch.globals import ( UnbalancedAtomicError, NotInitializedError, ) -from notmuch.version import __VERSION__ +from .version import __VERSION__ __LICENSE__ = "GPL v3+" __AUTHOR__ = 'Sebastian Spaeth ' diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py index a054be7..800264b 100644 --- a/bindings/python/notmuch/database.py +++ b/bindings/python/notmuch/database.py @@ -19,7 +19,7 @@ Copyright 2010 Sebastian Spaeth ' import os import codecs -from ctypes import c_char_p, c_void_p, c_uint, c_long, byref, POINTER +from ctypes import c_char_p, c_void_p, c_uint, byref, POINTER from notmuch.globals import ( nmlib, STATUS, @@ -34,11 +34,11 @@ from notmuch.globals import ( NotmuchDirectoryP, NotmuchMessageP, NotmuchTagsP, - NotmuchFilenamesP ) from notmuch.message import Message from notmuch.tag import Tags from .query import Query +from .directory import Directory class Database(object): """The :class:`Database` is the highest-level object that notmuch @@ -603,238 +603,3 @@ class Database(object): guaranteed to remain stable in future versions). """ return self._db - - -class Directory(object): - """Represents a directory entry in the notmuch directory - - Modifying attributes of this object will modify the - database, not the real directory attributes. - - The Directory object is usually derived from another object - e.g. via :meth:`Database.get_directory`, and will automatically be - become invalid whenever that parent is deleted. You should - therefore initialized this object handing it a reference to the - parent, preventing the parent from automatically being garbage - collected. - """ - - """notmuch_directory_get_mtime""" - _get_mtime = nmlib.notmuch_directory_get_mtime - _get_mtime.argtypes = [NotmuchDirectoryP] - _get_mtime.restype = c_long - - """notmuch_directory_set_mtime""" - _set_mtime = nmlib.notmuch_directory_set_mtime - _set_mtime.argtypes = [NotmuchDirectoryP, c_long] - _set_mtime.restype = c_uint - - """notmuch_directory_get_child_files""" - _get_child_files = nmlib.notmuch_directory_get_child_files - _get_child_files.argtypes = [NotmuchDirectoryP] - _get_child_files.restype = NotmuchFilenamesP - - """notmuch_directory_get_child_directories""" - _get_child_directories = nmlib.notmuch_directory_get_child_directories - _get_child_directories.argtypes = [NotmuchDirectoryP] - _get_child_directories.restype = NotmuchFilenamesP - - def _assert_dir_is_initialized(self): - """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) - if dir_p is None""" - if not self._dir_p: - raise NotInitializedError() - - def __init__(self, path, dir_p, parent): - """ - :param path: The absolute path of the directory object. - :param dir_p: The pointer to an internal notmuch_directory_t object. - :param parent: The object this Directory is derived from - (usually a :class:`Database`). We do not directly use - this, but store a reference to it as long as - this Directory object lives. This keeps the - parent object alive. - """ - self._path = path - self._dir_p = dir_p - self._parent = parent - - def set_mtime(self, mtime): - """Sets the mtime value of this directory in the database - - The intention is for the caller to use the mtime to allow efficient - identification of new messages to be added to the database. The - recommended usage is as follows: - - * Read the mtime of a directory from the filesystem - - * Call :meth:`Database.add_message` for all mail files in - the directory - - * Call notmuch_directory_set_mtime with the mtime read from the - filesystem. Then, when wanting to check for updates to the - directory in the future, the client can call :meth:`get_mtime` - and know that it only needs to add files if the mtime of the - directory and files are newer than the stored timestamp. - - .. note:: - - :meth:`get_mtime` function does not allow the caller to - distinguish a timestamp of 0 from a non-existent timestamp. So - don't store a timestamp of 0 unless you are comfortable with - that. - - :param mtime: A (time_t) timestamp - :raises: :exc:`XapianError` a Xapian exception occurred, mtime - not stored - :raises: :exc:`ReadOnlyDatabaseError` the database was opened - in read-only mode so directory mtime cannot be modified - :raises: :exc:`NotInitializedError` the directory object has not - been initialized - """ - self._assert_dir_is_initialized() - status = Directory._set_mtime(self._dir_p, mtime) - - if status != STATUS.SUCCESS: - raise NotmuchError(status) - - def get_mtime(self): - """Gets the mtime value of this directory in the database - - Retrieves a previously stored mtime for this directory. - - :param mtime: A (time_t) timestamp - :raises: :exc:`NotmuchError`: - - :attr:`STATUS`.NOT_INITIALIZED - The directory has not been initialized - """ - self._assert_dir_is_initialized() - return Directory._get_mtime(self._dir_p) - - # Make mtime attribute a property of Directory() - mtime = property(get_mtime, set_mtime, doc="""Property that allows getting - and setting of the Directory *mtime* (read-write) - - See :meth:`get_mtime` and :meth:`set_mtime` for usage and - possible exceptions.""") - - def get_child_files(self): - """Gets a Filenames iterator listing all the filenames of - messages in the database within the given directory. - - The returned filenames will be the basename-entries only (not - complete paths. - """ - self._assert_dir_is_initialized() - files_p = Directory._get_child_files(self._dir_p) - return Filenames(files_p, self) - - def get_child_directories(self): - """Gets a :class:`Filenames` iterator listing all the filenames of - sub-directories in the database within the given directory - - The returned filenames will be the basename-entries only (not - complete paths. - """ - self._assert_dir_is_initialized() - files_p = Directory._get_child_directories(self._dir_p) - return Filenames(files_p, self) - - @property - def path(self): - """Returns the absolute path of this Directory (read-only)""" - return self._path - - def __repr__(self): - """Object representation""" - return "" % self._path - - _destroy = nmlib.notmuch_directory_destroy - _destroy.argtypes = [NotmuchDirectoryP] - _destroy.argtypes = None - - def __del__(self): - """Close and free the Directory""" - if self._dir_p is not None: - self._destroy(self._dir_p) - - -class Filenames(object): - """An iterator over File- or Directory names stored in the database""" - - #notmuch_filenames_get - _get = nmlib.notmuch_filenames_get - _get.argtypes = [NotmuchFilenamesP] - _get.restype = c_char_p - - def __init__(self, files_p, parent): - """ - :param files_p: The pointer to an internal notmuch_filenames_t object. - :param parent: The object this Directory is derived from - (usually a Directory()). We do not directly use - this, but store a reference to it as long as - this Directory object lives. This keeps the - parent object alive. - """ - self._files_p = files_p - self._parent = parent - - def __iter__(self): - """ Make Filenames an iterator """ - return self - - _valid = nmlib.notmuch_filenames_valid - _valid.argtypes = [NotmuchFilenamesP] - _valid.restype = bool - - _move_to_next = nmlib.notmuch_filenames_move_to_next - _move_to_next.argtypes = [NotmuchFilenamesP] - _move_to_next.restype = None - - def __next__(self): - if not self._files_p: - raise NotInitializedError() - - if not self._valid(self._files_p): - self._files_p = None - raise StopIteration - - file_ = Filenames._get(self._files_p) - self._move_to_next(self._files_p) - return file_.decode('utf-8', 'ignore') - next = __next__ # python2.x iterator protocol compatibility - - def __len__(self): - """len(:class:`Filenames`) returns the number of contained files - - .. note:: - - As this iterates over the files, we will not be able to - iterate over them again! So this will fail:: - - #THIS FAILS - files = Database().get_directory('').get_child_files() - if len(files) > 0: # this 'exhausts' msgs - # next line raises - # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) - for file in files: print file - """ - if not self._files_p: - raise NotInitializedError() - - i = 0 - while self._valid(self._files_p): - self._move_to_next(self._files_p) - i += 1 - self._files_p = None - return i - - _destroy = nmlib.notmuch_filenames_destroy - _destroy.argtypes = [NotmuchFilenamesP] - _destroy.restype = None - - def __del__(self): - """Close and free Filenames""" - if self._files_p is not None: - self._destroy(self._files_p) diff --git a/bindings/python/notmuch/directory.py b/bindings/python/notmuch/directory.py new file mode 100644 index 0000000..3e0763f --- /dev/null +++ b/bindings/python/notmuch/directory.py @@ -0,0 +1,183 @@ +""" +This file is part of notmuch. + +Notmuch is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation, either version 3 of the License, or (at your +option) any later version. + +Notmuch is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for more details. + +You should have received a copy of the GNU General Public License +along with notmuch. If not, see . + +Copyright 2010 Sebastian Spaeth ' +""" + +from ctypes import c_uint, c_long +from notmuch.globals import ( + nmlib, + STATUS, + NotmuchError, + NotInitializedError, + NotmuchDirectoryP, + NotmuchFilenamesP +) +from .filename import Filenames + +class Directory(object): + """Represents a directory entry in the notmuch directory + + Modifying attributes of this object will modify the + database, not the real directory attributes. + + The Directory object is usually derived from another object + e.g. via :meth:`Database.get_directory`, and will automatically be + become invalid whenever that parent is deleted. You should + therefore initialized this object handing it a reference to the + parent, preventing the parent from automatically being garbage + collected. + """ + + """notmuch_directory_get_mtime""" + _get_mtime = nmlib.notmuch_directory_get_mtime + _get_mtime.argtypes = [NotmuchDirectoryP] + _get_mtime.restype = c_long + + """notmuch_directory_set_mtime""" + _set_mtime = nmlib.notmuch_directory_set_mtime + _set_mtime.argtypes = [NotmuchDirectoryP, c_long] + _set_mtime.restype = c_uint + + """notmuch_directory_get_child_files""" + _get_child_files = nmlib.notmuch_directory_get_child_files + _get_child_files.argtypes = [NotmuchDirectoryP] + _get_child_files.restype = NotmuchFilenamesP + + """notmuch_directory_get_child_directories""" + _get_child_directories = nmlib.notmuch_directory_get_child_directories + _get_child_directories.argtypes = [NotmuchDirectoryP] + _get_child_directories.restype = NotmuchFilenamesP + + def _assert_dir_is_initialized(self): + """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) + if dir_p is None""" + if not self._dir_p: + raise NotInitializedError() + + def __init__(self, path, dir_p, parent): + """ + :param path: The absolute path of the directory object. + :param dir_p: The pointer to an internal notmuch_directory_t object. + :param parent: The object this Directory is derived from + (usually a :class:`Database`). We do not directly use + this, but store a reference to it as long as + this Directory object lives. This keeps the + parent object alive. + """ + self._path = path + self._dir_p = dir_p + self._parent = parent + + def set_mtime(self, mtime): + """Sets the mtime value of this directory in the database + + The intention is for the caller to use the mtime to allow efficient + identification of new messages to be added to the database. The + recommended usage is as follows: + + * Read the mtime of a directory from the filesystem + + * Call :meth:`Database.add_message` for all mail files in + the directory + + * Call notmuch_directory_set_mtime with the mtime read from the + filesystem. Then, when wanting to check for updates to the + directory in the future, the client can call :meth:`get_mtime` + and know that it only needs to add files if the mtime of the + directory and files are newer than the stored timestamp. + + .. note:: + + :meth:`get_mtime` function does not allow the caller to + distinguish a timestamp of 0 from a non-existent timestamp. So + don't store a timestamp of 0 unless you are comfortable with + that. + + :param mtime: A (time_t) timestamp + :raises: :exc:`XapianError` a Xapian exception occurred, mtime + not stored + :raises: :exc:`ReadOnlyDatabaseError` the database was opened + in read-only mode so directory mtime cannot be modified + :raises: :exc:`NotInitializedError` the directory object has not + been initialized + """ + self._assert_dir_is_initialized() + status = Directory._set_mtime(self._dir_p, mtime) + + if status != STATUS.SUCCESS: + raise NotmuchError(status) + + def get_mtime(self): + """Gets the mtime value of this directory in the database + + Retrieves a previously stored mtime for this directory. + + :param mtime: A (time_t) timestamp + :raises: :exc:`NotmuchError`: + + :attr:`STATUS`.NOT_INITIALIZED + The directory has not been initialized + """ + self._assert_dir_is_initialized() + return Directory._get_mtime(self._dir_p) + + # Make mtime attribute a property of Directory() + mtime = property(get_mtime, set_mtime, doc="""Property that allows getting + and setting of the Directory *mtime* (read-write) + + See :meth:`get_mtime` and :meth:`set_mtime` for usage and + possible exceptions.""") + + def get_child_files(self): + """Gets a Filenames iterator listing all the filenames of + messages in the database within the given directory. + + The returned filenames will be the basename-entries only (not + complete paths. + """ + self._assert_dir_is_initialized() + files_p = Directory._get_child_files(self._dir_p) + return Filenames(files_p, self) + + def get_child_directories(self): + """Gets a :class:`Filenames` iterator listing all the filenames of + sub-directories in the database within the given directory + + The returned filenames will be the basename-entries only (not + complete paths. + """ + self._assert_dir_is_initialized() + files_p = Directory._get_child_directories(self._dir_p) + return Filenames(files_p, self) + + @property + def path(self): + """Returns the absolute path of this Directory (read-only)""" + return self._path + + def __repr__(self): + """Object representation""" + return "" % self._path + + _destroy = nmlib.notmuch_directory_destroy + _destroy.argtypes = [NotmuchDirectoryP] + _destroy.argtypes = None + + def __del__(self): + """Close and free the Directory""" + if self._dir_p is not None: + self._destroy(self._dir_p) diff --git a/bindings/python/notmuch/filename.py b/bindings/python/notmuch/filename.py index 353eb76..232a9ed 100644 --- a/bindings/python/notmuch/filename.py +++ b/bindings/python/notmuch/filename.py @@ -78,10 +78,14 @@ class Filenames(Python3StringMixIn): if not files_p: raise NullPointerError() - self._files = files_p + self._files_p = files_p #save reference to parent object so we keep it alive self._parent = parent + def __iter__(self): + """ Make Filenames an iterator """ + return self + _valid = nmlib.notmuch_filenames_valid _valid.argtypes = [NotmuchFilenamesP] _valid.restype = bool @@ -90,19 +94,30 @@ class Filenames(Python3StringMixIn): _move_to_next.argtypes = [NotmuchFilenamesP] _move_to_next.restype = None + def __next__(self): + if not self._files_p: + raise NotInitializedError() + + if not self._valid(self._files_p): + self._files_p = None + raise StopIteration + + file_ = Filenames._get(self._files_p) + self._move_to_next(self._files_p) + return file_.decode('utf-8', 'ignore') + next = __next__ # python2.x iterator protocol compatibility + def as_generator(self): """Return generator of Filenames This is the main function that will usually be used by the - user.""" - if not self._files: - raise NotInitializedError() + user. - while self._valid(self._files): - yield Filenames._get(self._files).decode('utf-8', 'ignore') - self._move_to_next(self._files) - - self._files = None + .. deprecated:: 0.12 + :class:`Filenames` objects implement the + iterator protocol. + """ + return self def __unicode__(self): """Represent Filenames() as newline-separated list of full paths @@ -123,5 +138,30 @@ class Filenames(Python3StringMixIn): def __del__(self): """Close and free the notmuch filenames""" - if self._files is not None: - self._destroy(self._files) + if self._files_p is not None: + self._destroy(self._files_p) + + def __len__(self): + """len(:class:`Filenames`) returns the number of contained files + + .. note:: + + As this iterates over the files, we will not be able to + iterate over them again! So this will fail:: + + #THIS FAILS + files = Database().get_directory('').get_child_files() + if len(files) > 0: # this 'exhausts' msgs + # next line raises + # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED) + for file in files: print file + """ + if not self._files_p: + raise NotInitializedError() + + i = 0 + while self._valid(self._files_p): + self._move_to_next(self._files_p) + i += 1 + self._files_p = None + return i -- cgit v1.2.3 From fb52083bf7eff44f27b2f2fffcbfbcb4faaeda3c Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Fri, 24 Feb 2012 00:38:47 +0100 Subject: python: strip module prefix in the sphinx documentation Remove the notmuch prefix from classes in the documentation. This change makes the table of contents look much nicer. Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index e87a865..fc3179b 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -42,10 +42,10 @@ More information on specific topics can be found on the following pages: .. automodule:: notmuch -:class:`notmuch.Database` -- The underlying notmuch database +:class:`Database` -- The underlying notmuch database --------------------------------------------------------------------- -.. autoclass:: notmuch.Database([path=None[, create=False[, mode=MODE.READ_ONLY]]]) +.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]]) .. automethod:: create @@ -90,10 +90,10 @@ More information on specific topics can be found on the following pages: .. autoattribute:: db_p -:class:`notmuch.Query` -- A search query +:class:`Query` -- A search query ------------------------------------------------- -.. autoclass:: notmuch.Query +.. autoclass:: Query .. automethod:: create @@ -216,10 +216,10 @@ More information on specific topics can be found on the following pages: .. automethod:: __str__ -:class:`notmuch.Threads` -- Threads iterator +:class:`Threads` -- Threads iterator ----------------------------------------------------- -.. autoclass:: notmuch.Threads +.. autoclass:: Threads .. automethod:: __len__ @@ -254,28 +254,28 @@ More information on specific topics can be found on the following pages: :class:`Filenames` -- An iterator over filenames ------------------------------------------------ -.. autoclass:: notmuch.Filenames +.. autoclass:: Filenames - .. automethod:: notmuch.Filenames.__len__ + .. automethod:: Filenames.__len__ - .. automethod:: notmuch.Filenames.as_generator + .. automethod:: Filenames.as_generator -:class:`notmuch.database.Directoy` -- A directory entry in the database +:class:`Directoy` -- A directory entry in the database ------------------------------------------------------------------------ -.. autoclass:: notmuch.Directory +.. autoclass:: Directory - .. automethod:: notmuch.Directory.get_child_files + .. automethod:: Directory.get_child_files - .. automethod:: notmuch.Directory.get_child_directories + .. automethod:: Directory.get_child_directories - .. automethod:: notmuch.Directory.get_mtime + .. automethod:: Directory.get_mtime - .. automethod:: notmuch.Directory.set_mtime + .. automethod:: Directory.set_mtime - .. autoattribute:: notmuch.Directory.mtime + .. autoattribute:: Directory.mtime - .. autoattribute:: notmuch.Directory.path + .. autoattribute:: Directory.path The `next page `_ contains information on possible Status and Error values. -- cgit v1.2.3 From 8dfbba05fa43013e9c97d94246c167c3d64a9d50 Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Fri, 24 Feb 2012 01:18:54 +0100 Subject: python: move the usage example to quickstart.rst Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 14 +------------- bindings/python/docs/source/quickstart.rst | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 13 deletions(-) create mode 100644 bindings/python/docs/source/quickstart.rst (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index fc3179b..dec9697 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -15,25 +15,13 @@ Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide mos This page contains the main API overview of notmuch |release|. -Notmuch can be imported as:: - - import notmuch - -or:: - - 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: .. toctree:: :maxdepth: 1 + quickstart status_and_errors notmuch diff --git a/bindings/python/docs/source/quickstart.rst b/bindings/python/docs/source/quickstart.rst new file mode 100644 index 0000000..609f42e --- /dev/null +++ b/bindings/python/docs/source/quickstart.rst @@ -0,0 +1,19 @@ +Quickstart and examples +======================= + +.. todo:: write a nice introduction +.. todo:: improve the examples + +Notmuch can be imported as:: + + import notmuch + +or:: + + from notmuch import Query, Database + + db = Database('path', create=True) + msgs = Query(db, 'from:myself').search_messages() + + for msg in msgs: + print(msg) -- cgit v1.2.3 From 594dbb62432bd7f92d1e121145b80628eb8aad2a Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Fri, 24 Feb 2012 01:30:04 +0100 Subject: python: move the notmuch module section to notes.rst Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 6 +----- bindings/python/docs/source/notes.rst | 6 ++++++ 2 files changed, 7 insertions(+), 5 deletions(-) create mode 100644 bindings/python/docs/source/notes.rst (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index dec9697..a2b42aa 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -22,14 +22,10 @@ More information on specific topics can be found on the following pages: :maxdepth: 1 quickstart + notes status_and_errors notmuch -:mod:`notmuch` -- The Notmuch interface -================================================= - -.. automodule:: notmuch - :class:`Database` -- The underlying notmuch database --------------------------------------------------------------------- diff --git a/bindings/python/docs/source/notes.rst b/bindings/python/docs/source/notes.rst new file mode 100644 index 0000000..a792748 --- /dev/null +++ b/bindings/python/docs/source/notes.rst @@ -0,0 +1,6 @@ +Interfacing with notmuch +======================== + +.. todo:: move the note about talloc out of the code + +.. automodule:: notmuch -- cgit v1.2.3 From d50171d1cc575a41bf620c55853ade65d0edfad8 Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Fri, 24 Feb 2012 01:34:15 +0100 Subject: python: split the documentation Move each classes documentation into its own file and thus into its own page in the generated documentation. Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/database.rst | 48 ++++++ bindings/python/docs/source/filesystem.rst | 30 ++++ bindings/python/docs/source/index.rst | 267 ++--------------------------- bindings/python/docs/source/message.rst | 54 ++++++ bindings/python/docs/source/messages.rst | 15 ++ bindings/python/docs/source/query.rst | 41 +++++ bindings/python/docs/source/tags.rst | 17 ++ bindings/python/docs/source/thread.rst | 26 +++ bindings/python/docs/source/threads.rst | 10 ++ 9 files changed, 257 insertions(+), 251 deletions(-) create mode 100644 bindings/python/docs/source/database.rst create mode 100644 bindings/python/docs/source/filesystem.rst create mode 100644 bindings/python/docs/source/message.rst create mode 100644 bindings/python/docs/source/messages.rst create mode 100644 bindings/python/docs/source/query.rst create mode 100644 bindings/python/docs/source/tags.rst create mode 100644 bindings/python/docs/source/thread.rst create mode 100644 bindings/python/docs/source/threads.rst (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/database.rst b/bindings/python/docs/source/database.rst new file mode 100644 index 0000000..ee71085 --- /dev/null +++ b/bindings/python/docs/source/database.rst @@ -0,0 +1,48 @@ +:class:`Database` -- The underlying notmuch database +==================================================== + +.. currentmodule:: notmuch + +.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]]) + + .. automethod:: create + + .. automethod:: open(path, status=MODE.READ_ONLY) + + .. automethod:: get_path + + .. automethod:: get_version + + .. automethod:: needs_upgrade + + .. automethod:: upgrade + + .. automethod:: begin_atomic + + .. automethod:: end_atomic + + .. automethod:: get_directory + + .. automethod:: add_message + + .. automethod:: remove_message + + .. automethod:: find_message + + .. automethod:: find_message_by_filename + + .. automethod:: get_all_tags + + .. automethod:: create_query + + .. attribute:: Database.MODE + + Defines constants that are used as the mode in which to open a database. + + MODE.READ_ONLY + Open the database in read-only mode + + MODE.READ_WRITE + Open the database in read-write mode + + .. autoattribute:: db_p diff --git a/bindings/python/docs/source/filesystem.rst b/bindings/python/docs/source/filesystem.rst new file mode 100644 index 0000000..685dc4d --- /dev/null +++ b/bindings/python/docs/source/filesystem.rst @@ -0,0 +1,30 @@ +Files and directories +===================== + +.. currentmodule:: notmuch + +:class:`Filenames` -- An iterator over filenames +------------------------------------------------ + +.. autoclass:: Filenames + + .. automethod:: Filenames.__len__ + + .. automethod:: Filenames.as_generator + +:class:`Directoy` -- A directory entry in the database +------------------------------------------------------ + +.. autoclass:: Directory + + .. automethod:: Directory.get_child_files + + .. automethod:: Directory.get_child_directories + + .. automethod:: Directory.get_mtime + + .. automethod:: Directory.set_mtime + + .. autoattribute:: Directory.mtime + + .. autoattribute:: Directory.path diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index a2b42aa..9ad5fa9 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -1,272 +1,37 @@ -.. notmuch documentation master file, created by - sphinx-quickstart on Tue Feb 2 10:00:47 2010. +Welcome to :mod:`notmuch`'s documentation +========================================= .. currentmodule:: notmuch -Welcome to :mod:`notmuch`'s documentation -=========================================== - -The :mod:`notmuch` module provides an interface to the `notmuch `_ functionality, directly interfacing to a shared notmuch library. -Within :mod:`notmuch`, the classes :class:`Database`, :class:`Query` provide most of the core functionality, returning :class:`Threads`, :class:`Messages` and :class:`Tags`. +The :mod:`notmuch` module provides an interface to the `notmuch +`_ functionality, directly interfacing to a +shared notmuch library. Within :mod:`notmuch`, the classes +:class:`Database`, :class:`Query` provide most of the core +functionality, returning :class:`Threads`, :class:`Messages` and +:class:`Tags`. .. moduleauthor:: Sebastian Spaeth :License: This module is covered under the GNU GPL v3 (or later). -This page contains the main API overview of notmuch |release|. - - -More information on specific topics can be found on the following pages: - .. toctree:: :maxdepth: 1 quickstart notes status_and_errors + database + query + messages + message + tags + threads + thread + filesystem notmuch -:class:`Database` -- The underlying notmuch database ---------------------------------------------------------------------- - -.. autoclass:: Database([path=None[, create=False[, mode=MODE.READ_ONLY]]]) - - .. automethod:: create - - .. automethod:: open(path, status=MODE.READ_ONLY) - - .. automethod:: get_path - - .. automethod:: get_version - - .. automethod:: needs_upgrade - - .. automethod:: upgrade - - .. automethod:: begin_atomic - - .. automethod:: end_atomic - - .. automethod:: get_directory - - .. automethod:: add_message - - .. automethod:: remove_message - - .. automethod:: find_message - - .. automethod:: find_message_by_filename - - .. automethod:: get_all_tags - - .. automethod:: create_query - - .. attribute:: Database.MODE - - Defines constants that are used as the mode in which to open a database. - - MODE.READ_ONLY - Open the database in read-only mode - - MODE.READ_WRITE - Open the database in read-write mode - - .. autoattribute:: db_p - - -:class:`Query` -- A search query -------------------------------------------------- - -.. autoclass:: Query - - .. automethod:: create - - .. attribute:: Query.SORT - - Defines constants that are used as the mode in which to open a database. - - SORT.OLDEST_FIRST - Sort by message date, oldest first. - - SORT.NEWEST_FIRST - Sort by message date, newest first. - - SORT.MESSAGE_ID - Sort by email message ID. - - SORT.UNSORTED - Do not apply a special sort order (returns results in document id - order). - - .. automethod:: set_sort - - .. attribute:: sort - - Instance attribute :attr:`sort` contains the sort order (see - :attr:`Query.SORT`) if explicitely specified via - :meth:`set_sort`. By default it is set to `None`. - - .. automethod:: search_threads - - .. automethod:: search_messages - - .. automethod:: count_messages - - .. automethod:: count_threads - - -:class:`Messages` -- A bunch of messages ----------------------------------------- - -.. autoclass:: Messages - - .. automethod:: collect_tags - - .. method:: __len__() - - .. warning:: - - :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke - list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`. - -:class:`Message` -- A single message ----------------------------------------- - -.. autoclass:: Message - - .. automethod:: get_message_id - - .. automethod:: get_thread_id - - .. automethod:: get_replies - - .. automethod:: get_filename - - .. automethod:: get_filenames - - .. attribute:: FLAG - - FLAG.MATCH - This flag is automatically set by a - Query.search_threads on those messages that match the - query. This allows us to distinguish matches from the rest - of the messages in that thread. - - .. automethod:: get_flag - - .. automethod:: set_flag - - .. automethod:: get_date - - .. automethod:: get_header - - .. automethod:: get_tags - - .. automethod:: maildir_flags_to_tags - - .. automethod:: tags_to_maildir_flags - - .. automethod:: remove_tag - - .. automethod:: add_tag - - .. automethod:: remove_all_tags - - .. automethod:: freeze - - .. automethod:: thaw - - .. automethod:: format_message_as_json - - .. automethod:: format_message_as_text - - .. automethod:: __str__ - - -:class:`Tags` -- Notmuch tags ------------------------------ - -.. autoclass:: Tags - :members: - - .. method:: __len__ - - .. warning:: - - :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke - list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of - tags. - - .. automethod:: __str__ - - -:class:`Threads` -- Threads iterator ------------------------------------------------------ - -.. autoclass:: Threads - - .. automethod:: __len__ - - .. automethod:: __str__ - -:class:`Thread` -- A single thread ------------------------------------- - -.. autoclass:: Thread - - .. automethod:: get_thread_id - - .. automethod:: get_total_messages - - .. automethod:: get_toplevel_messages - - .. automethod:: get_matched_messages - - .. automethod:: get_authors - - .. automethod:: get_subject - - .. automethod:: get_oldest_date - - .. automethod:: get_newest_date - - .. automethod:: get_tags - - .. automethod:: __str__ - - -:class:`Filenames` -- An iterator over filenames ------------------------------------------------- - -.. autoclass:: Filenames - - .. automethod:: Filenames.__len__ - - .. automethod:: Filenames.as_generator - -:class:`Directoy` -- A directory entry in the database ------------------------------------------------------------------------- - -.. autoclass:: Directory - - .. automethod:: Directory.get_child_files - - .. automethod:: Directory.get_child_directories - - .. automethod:: Directory.get_mtime - - .. automethod:: Directory.set_mtime - - .. autoattribute:: Directory.mtime - - .. autoattribute:: Directory.path - - -The `next page `_ contains information on possible Status and Error values. - Indices and tables ================== * :ref:`genindex` * :ref:`search` - diff --git a/bindings/python/docs/source/message.rst b/bindings/python/docs/source/message.rst new file mode 100644 index 0000000..2ae280e --- /dev/null +++ b/bindings/python/docs/source/message.rst @@ -0,0 +1,54 @@ +:class:`Message` -- A single message +==================================== + +.. currentmodule:: notmuch + +.. autoclass:: Message + + .. automethod:: get_message_id + + .. automethod:: get_thread_id + + .. automethod:: get_replies + + .. automethod:: get_filename + + .. automethod:: get_filenames + + .. attribute:: FLAG + + FLAG.MATCH + This flag is automatically set by a + Query.search_threads on those messages that match the + query. This allows us to distinguish matches from the rest + of the messages in that thread. + + .. automethod:: get_flag + + .. automethod:: set_flag + + .. automethod:: get_date + + .. automethod:: get_header + + .. automethod:: get_tags + + .. automethod:: maildir_flags_to_tags + + .. automethod:: tags_to_maildir_flags + + .. automethod:: remove_tag + + .. automethod:: add_tag + + .. automethod:: remove_all_tags + + .. automethod:: freeze + + .. automethod:: thaw + + .. automethod:: format_message_as_json + + .. automethod:: format_message_as_text + + .. automethod:: __str__ diff --git a/bindings/python/docs/source/messages.rst b/bindings/python/docs/source/messages.rst new file mode 100644 index 0000000..3ccf505 --- /dev/null +++ b/bindings/python/docs/source/messages.rst @@ -0,0 +1,15 @@ +:class:`Messages` -- A bunch of messages +======================================== + +.. currentmodule:: notmuch + +.. autoclass:: Messages + + .. automethod:: collect_tags + + .. method:: __len__() + + .. warning:: + + :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke + list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`. diff --git a/bindings/python/docs/source/query.rst b/bindings/python/docs/source/query.rst new file mode 100644 index 0000000..ddfc348 --- /dev/null +++ b/bindings/python/docs/source/query.rst @@ -0,0 +1,41 @@ +:class:`Query` -- A search query +================================ + +.. currentmodule:: notmuch + +.. autoclass:: Query + + .. automethod:: create + + .. attribute:: Query.SORT + + Defines constants that are used as the mode in which to open a database. + + SORT.OLDEST_FIRST + Sort by message date, oldest first. + + SORT.NEWEST_FIRST + Sort by message date, newest first. + + SORT.MESSAGE_ID + Sort by email message ID. + + SORT.UNSORTED + Do not apply a special sort order (returns results in document id + order). + + .. automethod:: set_sort + + .. attribute:: sort + + Instance attribute :attr:`sort` contains the sort order (see + :attr:`Query.SORT`) if explicitely specified via + :meth:`set_sort`. By default it is set to `None`. + + .. automethod:: search_threads + + .. automethod:: search_messages + + .. automethod:: count_messages + + .. automethod:: count_threads diff --git a/bindings/python/docs/source/tags.rst b/bindings/python/docs/source/tags.rst new file mode 100644 index 0000000..31527d4 --- /dev/null +++ b/bindings/python/docs/source/tags.rst @@ -0,0 +1,17 @@ +:class:`Tags` -- Notmuch tags +----------------------------- + +.. currentmodule:: notmuch + +.. autoclass:: Tags + :members: + + .. method:: __len__ + + .. warning:: + + :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke + list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of + tags. + + .. automethod:: __str__ diff --git a/bindings/python/docs/source/thread.rst b/bindings/python/docs/source/thread.rst new file mode 100644 index 0000000..4067872 --- /dev/null +++ b/bindings/python/docs/source/thread.rst @@ -0,0 +1,26 @@ +:class:`Thread` -- A single thread +================================== + +.. currentmodule:: notmuch + +.. autoclass:: Thread + + .. automethod:: get_thread_id + + .. automethod:: get_total_messages + + .. automethod:: get_toplevel_messages + + .. automethod:: get_matched_messages + + .. automethod:: get_authors + + .. automethod:: get_subject + + .. automethod:: get_oldest_date + + .. automethod:: get_newest_date + + .. automethod:: get_tags + + .. automethod:: __str__ diff --git a/bindings/python/docs/source/threads.rst b/bindings/python/docs/source/threads.rst new file mode 100644 index 0000000..e5a8c8a --- /dev/null +++ b/bindings/python/docs/source/threads.rst @@ -0,0 +1,10 @@ +:class:`Threads` -- Threads iterator +==================================== + +.. currentmodule:: notmuch + +.. autoclass:: Threads + + .. automethod:: __len__ + + .. automethod:: __str__ -- cgit v1.2.3 From 643719dfce3bc1c9fa3a0d861076069d08d7bbbc Mon Sep 17 00:00:00 2001 From: Justus Winter <4winter@informatik.uni-hamburg.de> Date: Thu, 17 May 2012 17:47:49 +0200 Subject: python: remove the "notmuch binary" section from the docs Signed-off-by: Justus Winter <4winter@informatik.uni-hamburg.de> --- bindings/python/docs/source/index.rst | 1 - bindings/python/docs/source/notmuch.rst | 68 --------------------------------- 2 files changed, 69 deletions(-) delete mode 100644 bindings/python/docs/source/notmuch.rst (limited to 'bindings/python/docs/source/index.rst') diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index 9ad5fa9..1cece5f 100644 --- a/bindings/python/docs/source/index.rst +++ b/bindings/python/docs/source/index.rst @@ -28,7 +28,6 @@ functionality, returning :class:`Threads`, :class:`Messages` and threads thread filesystem - notmuch Indices and tables ================== diff --git a/bindings/python/docs/source/notmuch.rst b/bindings/python/docs/source/notmuch.rst deleted file mode 100644 index bf68f33..0000000 --- a/bindings/python/docs/source/notmuch.rst +++ /dev/null @@ -1,68 +0,0 @@ -The notmuch 'binary' -==================== - -The cnotmuch module provides *notmuch*, a python reimplementation of the standard notmuch binary for two purposes: first, to allow running the standard notmuch testsuite over the cnotmuch bindings (for correctness and performance testing) and second, to give some examples as to how to use cnotmuch. 'Notmuch' provides a command line interface to your mail database. - -A standard install via `easy_install cnotmuch` will not install the notmuch binary, however it is available in the `cnotmuch source code repository `_. - - -It is invoked with the following pattern: `notmuch [args...]`. - -Where and [args...] are as follows: - - **setup** Interactively setup notmuch for first use. - This has not yet been implemented, and will probably not be - implemented unless someone puts in the effort. - - **new** [--verbose] - Find and import new messages to the notmuch database. - - This has not been implemented yet. We cheat by calling - the regular "notmuch" binary (which must be in your path - somewhere). - - **search** [options...] [...] Search for messages matching the given search terms. - - This has been implemented but for the `--format` and - `--sort` options. - - **show** [...] - Show all messages matching the search terms. - - This has been partially implemented, we show a stub for each - found message, but do not output the full message body yet. - - **count** [...] - Count messages matching the search terms. - - This has been fully implemented. - - **reply** [options...] [...] - Construct a reply template for a set of messages. - - This has not been implemented yet. - - **tag** +|- [...] [--] [...] - Add/remove tags for all messages matching the search terms. - - This has been fully implemented. - - **dump** [] - Create a plain-text dump of the tags for each message. - - This has been fully implemented. - **restore** - Restore the tags from the given dump file (see 'dump'). - - This has been fully implemented. - - **search-tags** [ [...] ] - List all tags found in the database or matching messages. - - This has been fully implemented. - - **help** [] - This message, or more detailed help for the named command. - - The 'help' page has been implemented, help for single - commands are missing though. Patches are welcome. -- cgit v1.2.3