no changes to the code, only makes compiling the docs smoother
as some rsT syntax errors were fixed
- .. 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
----------------------------------------
:class:`Message` -- A single message
----------------------------------------
- .. 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.
:exc:`XapianError` as the underlying database has been
modified. Close and reopen the database to continue working with it.
: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"""
"""
_std_db_path = None
"""Class attribute to cache user's default database"""
neither begin nor end necessarily flush modifications to disk.
:returns: :attr:`STATUS`.SUCCESS or raises
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()
*Added in notmuch 0.9*"""
self._assert_db_is_initialized()
"""Returns a :class:`Directory` of path,
(creating it if it does not exist(?))
"""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
:param path: An unicode string containing the path relative to the path
of database (see :meth:`get_path`), or else should be an absolute
def find_message_by_filename(self, filename):
"""Find a message with the given filename
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
:returns: If the database contains a message with the given
filename, then a class:`Message:` is returned. This
and know that it only needs to add files if the mtime of the
directory and files are newer than the stored timestamp.
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.
:param mtime: A (time_t) timestamp
:returns: Nothing on success, raising an exception on failure.
def __len__(self):
"""len(:class:`Filenames`) returns the number of contained files
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()
#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:
for file in files: print file
"""
if self._files_p is None:
"""Return the unique :class:`Tags` in the contained messages
:returns: :class:`Tags`
"""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)
"""
if self._msgs is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
"""Gets all direct replies to this message as :class:`Messages`
iterator
"""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.
:returns: :class:`Messages` or `None` if there are no replies to
this message.
This means that changes to the message state, (via :meth:`add_tag`,
:meth:`remove_tag`, and :meth:`remove_all_tags`), will not be
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
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
def __str__(self):
"""The str() representation of Tags() is a space separated list of tags
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)
"""
return " ".join(self)