mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-25 04:18:08 +01:00
fix sphinx compile-time warnings
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
Sebastian Spaeth
parent
4292b1197d
commit
12ebf87947
4 changed files with 67 additions and 53 deletions
|
|
@ -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__
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue