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

fix sphinx compile-time warnings

Browse source 
no changes to the code, only makes compiling the docs smoother
as some rsT syntax errors were fixed
This commit is contained in:
Patrick Totzke 2011-12-05 21:12:35 +00:00 committed by Sebastian Spaeth
parent 4292b1197d
commit 12ebf87947
4 changed files with 67 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
bindings/python/docs/source/index.rst
View file

@ -138,10 +138,10 @@ More information on specific topics can be found on the following pages:
.. method:: __len__() .. method:: __len__()
.. warning:: :meth:`__len__` was removed in version 0.6 as it exhausted .. warning::
the iterator and broke list(Messages()). Use the
:meth:`Query.count_messages` function or use :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
`len(list(msgs))`. list(Messages()). Use the :meth:`Query.count_messages` function or use `len(list(msgs))`.
:class:`Message` -- A single message :class:`Message` -- A single message
---------------------------------------- ----------------------------------------
@ -205,10 +205,11 @@ More information on specific topics can be found on the following pages:
.. method:: __len__ .. method:: __len__
.. warning:: :meth:`__len__` was removed in version 0.6 as it .. warning::
exhausted the iterator and broke list(Tags()). Use
:meth:`len(list(msgs))` instead if you need to know the :meth:`__len__` was removed in version 0.6 as it exhausted the iterator and broke
number of tags. list(Tags()). Use :meth:`len(list(msgs))` instead if you need to know the number of
tags.
.. automethod:: __str__ .. automethod:: __str__

65
bindings/python/notmuch/database.py
View file

@ -40,16 +40,19 @@ class Database(object):
:exc:`XapianError` as the underlying database has been :exc:`XapianError` as the underlying database has been
modified. Close and reopen the database to continue working with it. modified. Close and reopen the database to continue working with it.
.. note:: Any function in this class can and will throw an .. note::
:exc:`NotInitializedError` if the database was not
intitialized properly.
.. note:: Do remember that as soon as we tear down (e.g. via `del Any function in this class can and will throw an
db`) this object, all underlying derived objects such as :exc:`NotInitializedError` if the database was not intitialized
queries, threads, messages, tags etc will be freed by the properly.
underlying library as well. Accessing these objects will lead
to segfaults and other unexpected behavior. See above for .. note::
more details.
Do remember that as soon as we tear down (e.g. via `del db`) 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.
""" """
_std_db_path = None _std_db_path = None
"""Class attribute to cache user's default database""" """Class attribute to cache user's default database"""
@ -253,10 +256,8 @@ class Database(object):
neither begin nor end necessarily flush modifications to disk. neither begin nor end necessarily flush modifications to disk.
:returns: :attr:`STATUS`.SUCCESS or raises :returns: :attr:`STATUS`.SUCCESS or raises
:exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
:exception: :exc:`NotmuchError`: Xapian exception occurred; atomic section not entered.
:attr:`STATUS`.XAPIAN_EXCEPTION
Xapian exception occurred; atomic section not entered.
*Added in notmuch 0.9*""" *Added in notmuch 0.9*"""
self._assert_db_is_initialized() self._assert_db_is_initialized()
@ -295,9 +296,11 @@ class Database(object):
"""Returns a :class:`Directory` of path, """Returns a :class:`Directory` of path,
(creating it if it does not exist(?)) (creating it if it does not exist(?))
.. warning:: This call needs a writeable database in .. warning::
:attr:`Database.MODE`.READ_WRITE mode. The underlying library will
exit the program if this method is used on a read-only database! This call needs a writeable database in
:attr:`Database.MODE`.READ_WRITE mode. The underlying library will
exit the program if this method is used on a read-only database!
:param path: An unicode string containing the path relative to the path :param path: An unicode string containing the path relative to the path
of database (see :meth:`get_path`), or else should be an absolute of database (see :meth:`get_path`), or else should be an absolute
@ -459,10 +462,11 @@ class Database(object):
def find_message_by_filename(self, filename): def find_message_by_filename(self, filename):
"""Find a message with the given filename """Find a message with the given filename
.. warning:: This call needs a writeable database in .. warning::
:attr:`Database.MODE`.READ_WRITE mode. The underlying library will
exit the program if this method is used on a read-only This call needs a writeable database in
database! :attr:`Database.MODE`.READ_WRITE mode. The underlying library will
exit the program if this method is used on a read-only database!
:returns: If the database contains a message with the given :returns: If the database contains a message with the given
filename, then a class:`Message:` is returned. This filename, then a class:`Message:` is returned. This
@ -791,10 +795,12 @@ class Directory(object):
and know that it only needs to add files if the mtime of the and know that it only needs to add files if the mtime of the
directory and files are newer than the stored timestamp. directory and files are newer than the stored timestamp.
.. note:: :meth:`get_mtime` function does not allow the caller .. note::
to distinguish a timestamp of 0 from a non-existent
timestamp. So don't store a timestamp of 0 unless you are :meth:`get_mtime` function does not allow the caller to
comfortable with that. 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 :param mtime: A (time_t) timestamp
:returns: Nothing on success, raising an exception on failure. :returns: Nothing on success, raising an exception on failure.
@ -928,13 +934,16 @@ class Filenames(object):
def __len__(self): def __len__(self):
"""len(:class:`Filenames`) returns the number of contained files """len(:class:`Filenames`) returns the number of contained files
.. note:: As this iterates over the files, we will not be able to .. note::
iterate over them again! So this will fail::
As this iterates over the files, we will not be able to
iterate over them again! So this will fail::
#THIS FAILS #THIS FAILS
files = Database().get_directory('').get_child_files() files = Database().get_directory('').get_child_files()
if len(files) > 0: #this 'exhausts' msgs if len(files) > 0: # this 'exhausts' msgs
# next line raises NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)!!! # next line raises
# NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
for file in files: print file for file in files: print file
""" """
if self._files_p is None: if self._files_p is None:

27
bindings/python/notmuch/message.py
View file

@ -128,10 +128,12 @@ class Messages(object):
"""Return the unique :class:`Tags` in the contained messages """Return the unique :class:`Tags` in the contained messages
:returns: :class:`Tags` :returns: :class:`Tags`
:exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not inited :exceptions: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if not init'ed
.. note:: :meth:`collect_tags` will iterate over the messages and .. note::
therefore will not allow further iterations.
:meth:`collect_tags` will iterate over the messages and therefore
will not allow further iterations.
""" """
if self._msgs is None: if self._msgs is None:
raise NotmuchError(STATUS.NOT_INITIALIZED) raise NotmuchError(STATUS.NOT_INITIALIZED)
@ -359,14 +361,15 @@ class Message(object):
"""Gets all direct replies to this message as :class:`Messages` """Gets all direct replies to this message as :class:`Messages`
iterator iterator
.. note:: This call only makes sense if 'message' was .. note::
ultimately obtained from a :class:`Thread` object, (such as
by coming directly from the result of calling This call only makes sense if 'message' was ultimately obtained from
:meth:`Thread.get_toplevel_messages` or by any number of a :class:`Thread` object, (such as by coming directly from the
subsequent calls to :meth:`get_replies`). If this message was result of calling :meth:`Thread.get_toplevel_messages` or by any
obtained through some non-thread means, (such as by a call number of subsequent calls to :meth:`get_replies`). If this message
to :meth:`Query.search_messages`), then this function will was obtained through some non-thread means, (such as by a call to
return `None`. :meth:`Query.search_messages`), then this function will return
`None`.
:returns: :class:`Messages` or `None` if there are no replies to :returns: :class:`Messages` or `None` if there are no replies to
this message. this message.
@ -647,7 +650,7 @@ class Message(object):
This means that changes to the message state, (via :meth:`add_tag`, This means that changes to the message state, (via :meth:`add_tag`,
:meth:`remove_tag`, and :meth:`remove_all_tags`), will not be :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be
committed to the database until the message is :meth:`thaw`ed. committed to the database until the message is :meth:`thaw` ed.
Multiple calls to freeze/thaw are valid and these calls will Multiple calls to freeze/thaw are valid and these calls will
"stack". That is there must be as many calls to thaw as to freeze "stack". That is there must be as many calls to thaw as to freeze

11
bindings/python/notmuch/tag.py
View file

@ -113,11 +113,12 @@ class Tags(object):
def __str__(self): def __str__(self):
"""The str() representation of Tags() is a space separated list of tags """The str() representation of Tags() is a space separated list of tags
.. note:: As this iterates over the tags, we will not be able .. note::
to iterate over them again (as in retrieve them)! If
the tags have been exhausted already, this will raise a As this iterates over the tags, we will not be able to iterate over
:exc:`NotmuchError` STATUS.NOT_INITIALIZED on them again (as in retrieve them)! If the tags have been exhausted
subsequent attempts. already, this will raise a :exc:`NotmuchError`
STATUS.NOT_INITIALIZED on subsequent attempts.
""" """
return " ".join(self) return " ".join(self)