diff options
author | Ilya Etingof <etingof@gmail.com> | 2019-07-13 11:09:28 +0200 |
---|---|---|
committer | Ilya Etingof <etingof@gmail.com> | 2019-07-13 11:09:28 +0200 |
commit | e1500c60c0a15a641d5ee834f792fd0f2167c8b8 (patch) | |
tree | 3b0330806b1b86f9d17ca0306f04b3e358bda68d | |
parent | 4b24fcb98a21a6259ab1b71cd46f382401fad508 (diff) | |
download | pyasn1-git-e1500c60c0a15a641d5ee834f792fd0f2167c8b8.tar.gz |
Add exception classes documentation
Also fix references to exception objects in other docstrings.
-rw-r--r-- | docs/source/pyasn1/contents.rst | 13 | ||||
-rw-r--r-- | docs/source/pyasn1/error/contents.rst | 60 | ||||
-rw-r--r-- | pyasn1/codec/ber/decoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/ber/encoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/cer/decoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/cer/encoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/der/decoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/der/encoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/native/decoder.py | 2 | ||||
-rw-r--r-- | pyasn1/codec/native/encoder.py | 2 | ||||
-rw-r--r-- | pyasn1/error.py | 32 | ||||
-rw-r--r-- | pyasn1/type/char.py | 2 | ||||
-rw-r--r-- | pyasn1/type/namedtype.py | 12 | ||||
-rw-r--r-- | pyasn1/type/univ.py | 20 |
14 files changed, 122 insertions, 33 deletions
diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst index 474bbff..554ebe9 100644 --- a/docs/source/pyasn1/contents.rst +++ b/docs/source/pyasn1/contents.rst @@ -212,3 +212,16 @@ implemented in pyasn1. /pyasn1/codec/cer/contents /pyasn1/codec/der/contents /pyasn1/codec/native/contents + +Exceptions +---------- + +Operations on PyASN1 schema and value objects might cause errors. These +errors are manifested to the caller in form of Python exceptions. + +The exception hierarchy is as follows (ordered from least specific). + +.. toctree:: + :maxdepth: 2 + + /pyasn1/error/contents diff --git a/docs/source/pyasn1/error/contents.rst b/docs/source/pyasn1/error/contents.rst new file mode 100644 index 0000000..be8a04c --- /dev/null +++ b/docs/source/pyasn1/error/contents.rst @@ -0,0 +1,60 @@ + +.. _error.PyAsn1Error: + +.. |PyAsn1Error| replace:: PyAsn1Error + +|PyAsn1Error| +------------- + +.. autoclass:: pyasn1.error.PyAsn1Error + :members: + +.. _error.ValueConstraintError: + +.. |ValueConstraintError| replace:: ValueConstraintError + +|ValueConstraintError| +---------------------- + +.. autoclass:: pyasn1.error.ValueConstraintError + :members: + +.. _error.SubstrateUnderrunError: + +.. |SubstrateUnderrunError| replace:: SubstrateUnderrunError + +|SubstrateUnderrunError| +------------------------ + +.. autoclass:: pyasn1.error.SubstrateUnderrunError + :members: + +.. _error.PyAsn1UnicodeError: + +.. |PyAsn1UnicodeError| replace:: PyAsn1UnicodeError + +|PyAsn1UnicodeError| +-------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeError + :members: + +.. _error.PyAsn1UnicodeDecodeError: + +.. |PyAsn1UnicodeDecodeError| replace:: PyAsn1UnicodeDecodeError + +|PyAsn1UnicodeDecodeError| +-------------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeDecodeError + :members: + +.. _error.PyAsn1UnicodeEncodeError: + +.. |PyAsn1UnicodeEncodeError| replace:: PyAsn1UnicodeEncodeError + +|PyAsn1UnicodeEncodeError| +-------------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeEncodeError + :members: diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py index ddd8f83..3f2d180 100644 --- a/pyasn1/codec/ber/decoder.py +++ b/pyasn1/codec/ber/decoder.py @@ -1620,7 +1620,7 @@ class Decoder(object): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError #: On decoding errors #: #: Examples diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py index fbad7e7..58e71e7 100644 --- a/pyasn1/codec/ber/encoder.py +++ b/pyasn1/codec/ber/encoder.py @@ -861,7 +861,7 @@ class Encoder(object): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error #: On encoding errors #: #: Examples diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py index 5099e3c..3e86fd0 100644 --- a/pyasn1/codec/cer/decoder.py +++ b/pyasn1/codec/cer/decoder.py @@ -87,7 +87,7 @@ class Decoder(decoder.Decoder): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError #: On decoding errors #: #: Examples diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py index d7a1dfe..6a9db97 100644 --- a/pyasn1/codec/cer/encoder.py +++ b/pyasn1/codec/cer/encoder.py @@ -284,7 +284,7 @@ class Encoder(encoder.Encoder): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error #: On encoding errors #: #: Examples diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py index 261bab8..1a13fdb 100644 --- a/pyasn1/codec/der/decoder.py +++ b/pyasn1/codec/der/decoder.py @@ -67,7 +67,7 @@ class Decoder(decoder.Decoder): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error, ~pyasn1.error.SubstrateUnderrunError #: On decoding errors #: #: Examples diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py index 5e3c571..90e982d 100644 --- a/pyasn1/codec/der/encoder.py +++ b/pyasn1/codec/der/encoder.py @@ -82,7 +82,7 @@ class Encoder(encoder.Encoder): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error #: On encoding errors #: #: Examples diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py index 10e2015..104b92e 100644 --- a/pyasn1/codec/native/decoder.py +++ b/pyasn1/codec/native/decoder.py @@ -195,7 +195,7 @@ class Decoder(object): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error #: On decoding errors #: #: Examples diff --git a/pyasn1/codec/native/encoder.py b/pyasn1/codec/native/encoder.py index 50caa53..4c5908d 100644 --- a/pyasn1/codec/native/encoder.py +++ b/pyasn1/codec/native/encoder.py @@ -235,7 +235,7 @@ class Encoder(object): #: #: Raises #: ------ -#: :py:class:`~pyasn1.error.PyAsn1Error` +#: ~pyasn1.error.PyAsn1Error #: On encoding errors #: #: Examples diff --git a/pyasn1/error.py b/pyasn1/error.py index cb30033..4f48db2 100644 --- a/pyasn1/error.py +++ b/pyasn1/error.py @@ -7,33 +7,41 @@ class PyAsn1Error(Exception): - """Create pyasn1 exception object + """Base pyasn1 exception - The `PyAsn1Error` exception represents generic, usually fatal, error. + `PyAsn1Error` is the base exception class (based on + :class:`Exception`) that represents all possible ASN.1 related + errors. """ class ValueConstraintError(PyAsn1Error): - """Create pyasn1 exception object + """ASN.1 type constraints violation exception The `ValueConstraintError` exception indicates an ASN.1 value constraint violation. + + It might happen on value object instantiation (for scalar types) or on + serialization (for constructed types). """ class SubstrateUnderrunError(PyAsn1Error): - """Create pyasn1 exception object + """ASN.1 data structure deserialization error The `SubstrateUnderrunError` exception indicates insufficient serialised - data on input of a de-serialization routine. + data on input of a de-serialization codec. """ class PyAsn1UnicodeError(PyAsn1Error, UnicodeError): - """Create pyasn1 exception object + """Unicode text processing error The `PyAsn1UnicodeError` exception is a base class for errors relating to unicode text de/serialization. + + Apart from inheriting from :class:`PyAsn1Error`, it also inherits from + :class:`UnicodeError` to help the caller catching unicode-related errors. """ def __init__(self, message, unicode_error=None): if isinstance(unicode_error, UnicodeError): @@ -42,18 +50,26 @@ class PyAsn1UnicodeError(PyAsn1Error, UnicodeError): class PyAsn1UnicodeDecodeError(PyAsn1UnicodeError, UnicodeDecodeError): - """Create pyasn1 exception object + """Unicode text decoding error The `PyAsn1UnicodeDecodeError` exception represents a failure to deserialize unicode text. + + Apart from inheriting from :class:`PyAsn1UnicodeError`, it also inherits + from :class:`UnicodeDecodeError` to help the caller catching unicode-related + errors. """ class PyAsn1UnicodeEncodeError(PyAsn1UnicodeError, UnicodeEncodeError): - """Create pyasn1 exception object + """Unicode text encoding error The `PyAsn1UnicodeEncodeError` exception represents a failure to serialize unicode text. + + Apart from inheriting from :class:`PyAsn1UnicodeError`, it also inherits + from :class:`UnicodeEncodeError` to help the caller catching + unicode-related errors. """ diff --git a/pyasn1/type/char.py b/pyasn1/type/char.py index 1b5daed..ce10599 100644 --- a/pyasn1/type/char.py +++ b/pyasn1/type/char.py @@ -44,7 +44,7 @@ class AbstractCharacterString(univ.OctetString): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. """ diff --git a/pyasn1/type/namedtype.py b/pyasn1/type/namedtype.py index 71f5f11..936c96c 100644 --- a/pyasn1/type/namedtype.py +++ b/pyasn1/type/namedtype.py @@ -293,7 +293,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If given position is out of fields range """ try: @@ -317,7 +317,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If *tagSet* is not present or ASN.1 types are not unique within callee *NamedTypes* """ try: @@ -341,7 +341,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If given field name is not present in callee *NamedTypes* """ try: @@ -365,7 +365,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If *name* is not present or not unique within callee *NamedTypes* """ try: @@ -394,7 +394,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If given position is out of fields range """ try: @@ -426,7 +426,7 @@ class NamedTypes(object): Raises ------ - : :class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error If *tagSet* is not present or not unique within callee *NamedTypes* or *idx* is out of fields range """ diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py index 93114d6..2a42fc7 100644 --- a/pyasn1/type/univ.py +++ b/pyasn1/type/univ.py @@ -52,7 +52,7 @@ class Integer(base.AbstractSimpleAsn1Item): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -296,7 +296,7 @@ class Boolean(Integer): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -386,7 +386,7 @@ class BitString(base.AbstractSimpleAsn1Item): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -754,7 +754,7 @@ class OctetString(base.AbstractSimpleAsn1Item): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -1047,7 +1047,7 @@ class Null(OctetString): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -1106,7 +1106,7 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -1242,7 +1242,7 @@ class Real(base.AbstractSimpleAsn1Item): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -1527,7 +1527,7 @@ class Enumerated(Integer): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples @@ -1827,7 +1827,7 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item): Raises ------ - IndexError: + IndexError When idx > len(self) """ if isinstance(idx, slice): @@ -3160,7 +3160,7 @@ class Any(OctetString): Raises ------ - :py:class:`~pyasn1.error.PyAsn1Error` + ~pyasn1.error.PyAsn1Error On constraint violation or bad initializer. Examples |