File: exceptions.rst

package info (click to toggle)
python-nacl 1.5.0-8
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid
  • size: 14,772 kB
  • sloc: ansic: 45,889; python: 7,249; sh: 6,752; asm: 2,974; makefile: 1,010; cs: 35; xml: 30; pascal: 11
file content (99 lines) | stat: -rw-r--r-- 2,535 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
Exceptions
==========

.. currentmodule:: nacl.exceptions

All of the exceptions raised from PyNaCl-exposed methods/functions
are subclasses of :py:exc:`nacl.exceptions.CryptoError`. This means
downstream users can just wrap cryptographic operations inside a

.. code-block:: python

    try:
        # cryptographic operations
    except nacl.exceptions.CryptoError:
        # cleanup after any kind of exception
        # raised from cryptographic-related operations

These are the exceptions implemented in :py:mod:`nacl.exceptions`:

PyNaCl specific exceptions
--------------------------

.. class:: CryptoError

    Base exception for all nacl related errors


.. class:: BadSignatureError

    Raised when the signature was forged or otherwise corrupt.


.. class:: InvalidkeyError

    Raised on password/key verification mismatch


.. class:: UnavailableError

    is a subclass of :class:`~nacl.exceptions.RuntimeError`, raised when
    trying to call functions not available in a minimal build of
    libsodium.


PyNaCl exceptions mixing-in standard library ones
-------------------------------------------------

Both for clarity and for compatibility with previous releases
of the PyNaCl, the following exceptions mix-in the same-named
standard library exception to :py:class:`~nacl.exceptions.CryptoError`.

.. class:: RuntimeError

    is a subclass of both CryptoError and standard library's
    RuntimeError, raised for internal library errors


.. class:: AssertionError

    is a subclass of both CryptoError and standard library's
    AssertionError, raised by default from
    :py:func:`~nacl.utils.ensure` when the checked condition is `False`


.. class:: TypeError

    is a subclass of both CryptoError and standard library's
    TypeError


.. class:: ValueError

    is a subclass of both CryptoError and standard library's
    ValueError


Utility functions for exception handling
----------------------------------------

.. function:: ensure(cond, *args, raising=nacl.exceptions.AssertionError)

    Returns if a condition is true, otherwise raise a caller-configurable
    :py:class:`Exception`

    :param cond: the condition to be checked
    :type cond: bool
    :param sequence args: the arguments to be passed to the exception's
                          constructor
    :param raising: the exception to be raised if `cond` is `False`
    :type raising: exception

Example usage:

.. code-block:: python

    nacl.exceptions.ensure(
        a == 1 or a == 2,
        "a must be either 1 or 2"
    )