[PATCH 3/3] fix sphinx compile-time warnings
Patrick Totzke
patricktotzke at googlemail.com
Mon Dec 5 13:12:35 PST 2011
no changes to the code, only makes compiling the docs smoother
as some rsT syntax errors were fixed
---
bindings/python/docs/source/index.rst | 17 ++++----
bindings/python/notmuch/database.py | 67 ++++++++++++++++++--------------
bindings/python/notmuch/message.py | 27 +++++++------
bindings/python/notmuch/tag.py | 11 +++--
4 files changed, 68 insertions(+), 54 deletions(-)
diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst
index 73d2a3b..f7d3d60 100644
--- a/bindings/python/docs/source/index.rst
+++ b/bindings/python/docs/source/index.rst
@@ -138,10 +138,10 @@ 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))`.
+ .. 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
----------------------------------------
@@ -205,10 +205,11 @@ 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(Tags()). Use
- :meth:`len(list(msgs))` instead if you need to know the
- number of tags.
+ .. 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/notmuch/database.py b/bindings/python/notmuch/database.py
index 706e8c8..471adaa 100644
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -40,16 +40,19 @@ class Database(object):
:exc:`XapianError` as the underlying database has been
modified. Close and reopen the database to continue working with it.
- .. note:: Any function in this class can and will throw an
- :exc:`NotInitializedError` if the database was not
- intitialized properly.
-
- .. note:: 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.
+ .. note::
+
+ Any function in this class can and will throw an
+ :exc:`NotInitializedError` if the database was not intitialized
+ properly.
+
+ .. note::
+
+ 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
"""Class attribute to cache user's default database"""
@@ -253,10 +256,8 @@ class Database(object):
neither begin nor end necessarily flush modifications to disk.
:returns: :attr:`STATUS`.SUCCESS or raises
-
- :exception: :exc:`NotmuchError`:
- :attr:`STATUS`.XAPIAN_EXCEPTION
- Xapian exception occurred; atomic section not entered.
+ :exception: :exc:`NotmuchError`: :attr:`STATUS`.XAPIAN_EXCEPTION
+ Xapian exception occurred; atomic section not entered.
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
@@ -295,9 +296,11 @@ class Database(object):
"""Returns a :class:`Directory` of path,
(creating it if it does not exist(?))
- .. warning:: 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!
+ .. warning::
+
+ 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
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):
"""Find a message with the given filename
- .. warning:: 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!
+ .. warning::
+
+ 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!
:returns: If the database contains a message with the given
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
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.
+ .. 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
:returns: Nothing on success, raising an exception on failure.
@@ -928,13 +934,16 @@ class Filenames(object):
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::
+ .. 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)!!!
+ if len(files) > 0: # this 'exhausts' msgs
+ # next line raises
+ # NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
for file in files: print file
"""
if self._files_p is None:
diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py
index 2534742..2f0fd92 100644
--- a/bindings/python/notmuch/message.py
+++ b/bindings/python/notmuch/message.py
@@ -127,10 +127,12 @@ class Messages(object):
"""Return the unique :class:`Tags` in the contained messages
: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
- therefore will not allow further iterations.
+ .. note::
+
+ :meth:`collect_tags` will iterate over the messages and therefore
+ will not allow further iterations.
"""
if self._msgs is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
@@ -358,14 +360,15 @@ class Message(object):
"""Gets all direct replies to this message as :class:`Messages`
iterator
- .. note:: This call only makes sense if 'message' was
- ultimately obtained from a :class:`Thread` object, (such as
- by coming directly from the result of calling
- :meth:`Thread.get_toplevel_messages` or by any number of
- subsequent calls to :meth:`get_replies`). If this message was
- obtained through some non-thread means, (such as by a call
- to :meth:`Query.search_messages`), then this function will
- return `None`.
+ .. note::
+
+ This call only makes sense if 'message' was ultimately obtained from
+ a :class:`Thread` object, (such as by coming directly from the
+ result of calling :meth:`Thread.get_toplevel_messages` or by any
+ number of subsequent calls to :meth:`get_replies`). If this message
+ was obtained through some non-thread means, (such as by a call to
+ :meth:`Query.search_messages`), then this function will return
+ `None`.
:returns: :class:`Messages` or `None` if there are no replies to
this message.
@@ -646,7 +649,7 @@ class Message(object):
This means that changes to the message state, (via :meth:`add_tag`,
: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
"stack". That is there must be as many calls to thaw as to freeze
diff --git a/bindings/python/notmuch/tag.py b/bindings/python/notmuch/tag.py
index f3a3d27..a77b68d 100644
--- a/bindings/python/notmuch/tag.py
+++ b/bindings/python/notmuch/tag.py
@@ -113,11 +113,12 @@ class Tags(object):
def __str__(self):
"""The str() representation of Tags() is a space separated list of tags
- .. note:: As this iterates over the tags, we will not be able
- to iterate over them again (as in retrieve them)! If
- the tags have been exhausted already, this will raise a
- :exc:`NotmuchError` STATUS.NOT_INITIALIZED on
- subsequent attempts.
+ .. note::
+
+ As this iterates over the tags, we will not be able to iterate over
+ them again (as in retrieve them)! If the tags have been exhausted
+ already, this will raise a :exc:`NotmuchError`
+ STATUS.NOT_INITIALIZED on subsequent attempts.
"""
return " ".join(self)
--
1.7.4.1
More information about the notmuch
mailing list