mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-12-22 17:34:54 +01:00
python: Improve API documentation
Various API doc cleanups and improvements. No code change. Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
This commit is contained in:
Sebastian Spaeth
parent
d8c0e0c72d
commit
0817f0e168
4 changed files with 56 additions and 35 deletions
|
|
@ -28,6 +28,7 @@ More information on specific topics can be found on the following pages:
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
status_and_errors
|
||||
notmuch
|
||||
|
||||
:mod:`notmuch` -- The Notmuch interface
|
||||
|
|
@ -157,7 +158,7 @@ More information on specific topics can be found on the following pages:
|
|||
query. This allows us to distinguish matches from the rest
|
||||
of the messages in that thread.
|
||||
|
||||
.. automethod:: get_flag
|
||||
.. automethod:: get_flag
|
||||
|
||||
.. automethod:: set_flag
|
||||
|
||||
|
|
@ -167,6 +168,10 @@ More information on specific topics can be found on the following pages:
|
|||
|
||||
.. automethod:: get_tags
|
||||
|
||||
.. automethod:: maildir_flags_to_tags
|
||||
|
||||
.. automethod:: tags_to_maildir_flags
|
||||
|
||||
.. automethod:: remove_tag
|
||||
|
||||
.. automethod:: add_tag
|
||||
|
|
@ -177,7 +182,9 @@ More information on specific topics can be found on the following pages:
|
|||
|
||||
.. automethod:: thaw
|
||||
|
||||
.. automethod:: format_as_text
|
||||
.. automethod:: format_message_as_json
|
||||
|
||||
.. automethod:: format_message_as_text
|
||||
|
||||
.. automethod:: __str__
|
||||
|
||||
|
|
@ -252,32 +259,8 @@ More information on specific topics can be found on the following pages:
|
|||
|
||||
.. autoattribute:: notmuch.database.Directory.path
|
||||
|
||||
:exc:`NotmuchError` -- A Notmuch execution error
|
||||
------------------------------------------------
|
||||
.. autoexception:: NotmuchError
|
||||
:members:
|
||||
|
||||
This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
|
||||
|
||||
:class:`STATUS` -- Notmuch operation return status
|
||||
--------------------------------------------------
|
||||
|
||||
.. data:: STATUS
|
||||
|
||||
STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.
|
||||
|
||||
* SUCCESS
|
||||
* OUT_OF_MEMORY
|
||||
* READ_ONLY_DATABASE
|
||||
* XAPIAN_EXCEPTION
|
||||
* FILE_ERROR
|
||||
* FILE_NOT_EMAIL
|
||||
* DUPLICATE_MESSAGE_ID
|
||||
* NULL_POINTER
|
||||
* TAG_TOO_LONG
|
||||
* UNBALANCED_FREEZE_THAW
|
||||
* NOT_INITIALIZED
|
||||
|
||||
The `next page <status_and_errors.html>`_ contains information on possible Status and Error values.
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
|
|
|||
23
bindings/python/docs/source/status_and_errors.rst
Normal file
23
bindings/python/docs/source/status_and_errors.rst
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
.. currentmodule:: notmuch
|
||||
|
||||
Status and Errors
|
||||
=================
|
||||
|
||||
Some methods return a status, indicating if an operation was successful and what the error was. Most of these status codes are expressed as a specific value, the :class:`notmuch.STATUS`.
|
||||
|
||||
:class:`STATUS` -- Notmuch operation return value
|
||||
--------------------------------------------------
|
||||
|
||||
.. autoclass:: notmuch.STATUS
|
||||
:inherited-members:
|
||||
|
||||
.. automethod:: notmuch.STATUS.status2str
|
||||
|
||||
:exc:`NotmuchError` -- A Notmuch execution error
|
||||
------------------------------------------------
|
||||
Whenever an error occurs, we throw a special Exception:
|
||||
|
||||
.. autoexception:: NotmuchError
|
||||
:members:
|
||||
|
||||
This execption inherits directly from :exc:`Exception` and is raised on errors during the notmuch execution.
|
||||
|
|
@ -37,7 +37,6 @@ class Enum(object):
|
|||
#-----------------------------------------------------------------------------
|
||||
class Status(Enum):
|
||||
"""Enum with a string representation of a notmuch_status_t value."""
|
||||
__name__="foo"
|
||||
_status2str = nmlib.notmuch_status_to_string
|
||||
_status2str.restype = c_char_p
|
||||
_status2str.argtypes = [c_int]
|
||||
|
|
@ -67,7 +66,22 @@ STATUS = Status(['SUCCESS',
|
|||
'TAG_TOO_LONG',
|
||||
'UNBALANCED_FREEZE_THAW',
|
||||
'NOT_INITIALIZED'])
|
||||
"""STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.
|
||||
|
||||
* SUCCESS
|
||||
* OUT_OF_MEMORY
|
||||
* READ_ONLY_DATABASE
|
||||
* XAPIAN_EXCEPTION
|
||||
* FILE_ERROR
|
||||
* FILE_NOT_EMAIL
|
||||
* DUPLICATE_MESSAGE_ID
|
||||
* NULL_POINTER
|
||||
* TAG_TOO_LONG
|
||||
* UNBALANCED_FREEZE_THAW
|
||||
* NOT_INITIALIZED
|
||||
|
||||
Invoke the class method `notmuch.STATUS.status2str` with a status value as argument to receive a human readable string"""
|
||||
STATUS.__name__ = 'STATUS'
|
||||
|
||||
class NotmuchError(Exception):
|
||||
def __init__(self, status=None, message=None):
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ class Messages(object):
|
|||
of messages, and a subsequent iteration attempt will raise a
|
||||
:exc:`NotmuchError` STATUS.NOT_INITIALIZED. If you need to
|
||||
re-iterate over a list of messages you will need to retrieve a new
|
||||
:class:`Messages` object or cache your :class:`Message`s in a list
|
||||
:class:`Messages` object or cache your :class:`Message`\s in a list
|
||||
via::
|
||||
|
||||
msglist = list(msgs)
|
||||
|
|
@ -226,12 +226,12 @@ class Messages(object):
|
|||
class Message(object):
|
||||
"""Represents a single Email message
|
||||
|
||||
Technically, this wraps the underlying *notmuch_message_t* structure.
|
||||
Technically, this wraps the underlying *notmuch_message_t*
|
||||
structure. A user will usually not create these objects themselves
|
||||
but get them as search results.
|
||||
|
||||
As this implements __cmp__() it is possible to compare 2
|
||||
:class:`Message`s with::
|
||||
|
||||
if msg1 == msg2:
|
||||
As it implements :meth:`__cmp__`, it is possible to compare two
|
||||
:class:`Message`\s using `if msg1 == msg2: ...`.
|
||||
"""
|
||||
|
||||
"""notmuch_message_get_filename (notmuch_message_t *message)"""
|
||||
|
|
@ -284,6 +284,7 @@ class Message(object):
|
|||
:param msg_p: A pointer to an internal notmuch_message_t
|
||||
Structure. If it is `None`, we will raise an :exc:`NotmuchError`
|
||||
STATUS.NULL_POINTER.
|
||||
|
||||
:param parent: A 'parent' object is passed which this message is
|
||||
derived from. We save a reference to it, so we can
|
||||
automatically delete the parent object once all derived
|
||||
|
|
@ -313,7 +314,7 @@ class Message(object):
|
|||
The returned string belongs to 'message' will only be valid for as
|
||||
long as the message is valid.
|
||||
|
||||
This function will not return None since Notmuch ensures that every
|
||||
This function will not return `None` since Notmuch ensures that every
|
||||
message belongs to a single thread.
|
||||
|
||||
:returns: String with a thread ID
|
||||
|
|
|
|||
Loading…
Reference in a new issue