From 12ebf879476ba60389c9310327b8a271f1f7eb5e Mon Sep 17 00:00:00 2001 From: Patrick Totzke Date: Mon, 5 Dec 2011 21:12:35 +0000 Subject: [PATCH] fix sphinx compile-time warnings 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 | 65 +++++++++++++++------------ bindings/python/notmuch/message.py | 27 ++++++----- bindings/python/notmuch/tag.py | 11 ++--- 4 files changed, 67 insertions(+), 53 deletions(-) diff --git a/bindings/python/docs/source/index.rst b/bindings/python/docs/source/index.rst index 73d2a3b0..f7d3d605 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 ca172738..f1795151 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:: - .. 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. + 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 e0c7eda2..7bc7798c 100644 --- a/bindings/python/notmuch/message.py +++ b/bindings/python/notmuch/message.py @@ -128,10 +128,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) @@ -359,14 +361,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. @@ -647,7 +650,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 f3a3d27e..a77b68d7 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)