*************
Python module
*************

Synopsis
========

.. code:: python

    from sievemgr import SieveManager


Description
===========

.. autoclass:: sievemgr.SieveManager
    :inherited-members:
    :no-show-inheritance:

.. autoclass:: sievemgr.Atom

.. autoclass:: sievemgr.Line

.. autoclass:: sievemgr.Word

.. autoclass:: sievemgr.Capabilities

.. autoclass:: sievemgr.Response
    :special-members: __str__

.. autoclass:: sievemgr.URL
    :special-members: __str__


SASL
====

.. note::
    You need not read this section unless you want to implement an
    `authentication mechanism <SASL mechanisms_>`_.

.. warning::
   This API *will* change at some point in the future.

.. mermaid::
    :caption: Authentication architecture

    sequenceDiagram
        participant auth as authenticate()
        participant mech as :AbstractAuth
        participant conn as :AbstractSASLAdapter
        auth ->> mech: .__init__(conn, authcid, authzid, ...)
        activate auth
        activate mech
        mech ->> mech: Prepare credentials
        break Encoding invalid
            mech --) auth: ValueError
        end
        deactivate auth
        deactivate mech
        auth ->> mech: .__call__()
        activate auth
        activate mech
        mech ->> conn: .begin(name, ...)
        activate conn
        deactivate conn
        loop SASL exchange
            mech ->> conn: .receive()
            activate conn
            conn --) mech: Message
            deactivate conn
            mech ->> conn: .send(message)
            activate conn
            deactivate conn
        end
        mech ->> conn: .end()
        activate conn
        break Authentication failed
            conn --) auth: OperationError
        end
        conn --) mech: Capabilities
        deactivate conn
        mech --) auth: Capabilities
        deactivate mech
        auth ->> mech: .authcid
        mech --) auth: Authentication ID
        auth ->> mech: .authzid
        mech --) auth: Authorisation ID
        deactivate auth

.. autoclass:: sievemgr.AbstractAuth
    :special-members: __init__, __call__

.. autoclass:: sievemgr.AbstractSASLAdapter

.. autoclass:: sievemgr.BaseAuth
    :special-members: __init__, __call__

.. autoclass:: sievemgr.BasePwdAuth
    :special-members: __init__

.. autoclass:: sievemgr.BaseScramAuth

.. autoclass:: sievemgr.BaseScramPlusAuth

.. autoclass:: sievemgr.AuthzUnsupportedMixin

.. autoclass:: sievemgr.CramMD5Auth
    :members: exchange, name, order

.. autoclass:: sievemgr.ExternalAuth
    :members: exchange, name, order
    :special-members: __init__, __call__

.. autoclass:: sievemgr.LoginAuth
    :members: exchange, name, order

.. autoclass:: sievemgr.PlainAuth
    :members: exchange, name, order

.. autoclass:: sievemgr.ScramSHA1Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA1PlusAuth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA224Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA224PlusAuth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA256Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA256PlusAuth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA384Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA384PlusAuth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA512Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA512PlusAuth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA3_512Auth
    :members: name, digest, order

.. autoclass:: sievemgr.ScramSHA3_512PlusAuth
    :members: name, digest, order

.. autoenum:: sievemgr.AuthState
    :members: name, digest, order

.. autoenum:: sievemgr.SASLPrep


ERRORS
======

.. autoexception:: sievemgr.Error

.. autoexception:: sievemgr.ProtocolError

.. autoexception:: sievemgr.SecurityError

.. autoexception:: sievemgr.CapabilityError

.. autoexception:: sievemgr.ConfigError

.. autoexception:: sievemgr.DataError

.. autoexception:: sievemgr.OperationError

.. autoexception:: sievemgr.UsageError

.. autoexception:: sievemgr.AppError

.. autoexception:: sievemgr.AppConfigError

.. autoexception:: sievemgr.AppConnectionError

.. autoexception:: sievemgr.AppOperationError

.. autoexception:: sievemgr.AppSecurityError

.. autoexception:: sievemgr.OCSPError

.. autoexception:: sievemgr.OCSPDataError

.. autoexception:: sievemgr.OCSPOperationError

.. autoexception:: sievemgr.SASLError

.. autoexception:: sievemgr.SASLCapabilityError

.. autoexception:: sievemgr.SASLProtocolError

.. autoexception:: sievemgr.SASLSecurityError

.. autoexception:: sievemgr.SieveError

.. autoexception:: sievemgr.SieveCapabilityError

.. autoexception:: sievemgr.SieveConnectionError

.. autoexception:: sievemgr.SieveOperationError

.. autoexception:: sievemgr.SieveProtocolError

.. autoexception:: sievemgr.TLSError

.. autoexception:: sievemgr.TLSCapabilityError

.. autoexception:: sievemgr.TLSSecurityError


.. only:: unwritten

    Security
    ========

    Files
    =====

    Examples
    ========