Make BER/CER/DER decodersstreaming and suspendible (#176)

The goal of this change is to make the decoder yielding on input
data starvation and resuming from where it stopped whenever the
caller decides to try again (hopefully making sure that some more
input becomes available).

This change makes it possible for the decoder to operate on streams
of data (meaning that the entire DER blob might not be immediately
available on input).

On top of that, the decoder yields partially reconstructed ASN.1
object on input starvation making it possible for the caller to
inspect what has been decoded so far and possibly consume partial
ASN.1 data.

All these new feature are natively available through
`StreamingDecoder` class. Previously published API is implemented
as a thin wrapper on top of that ensuring backward compatibility.

1 files changed, 41 insertions, 0 deletions

diff --git a/pyasn1/error.py b/pyasn1/error.py
index 4f48db2..08ec1b3 100644
--- a/pyasn1/error.py
+++ b/pyasn1/error.py
@@ -12,7 +12,36 @@ class PyAsn1Error(Exception):
     `PyAsn1Error` is the base exception class (based on
     :class:`Exception`) that represents all possible ASN.1 related
     errors.
+
+    Parameters
+    ----------
+    args:
+        Opaque positional parameters
+
+    Keyword Args
+    ------------
+    kwargs:
+        Opaque keyword parameters
+
     """
+    def __init__(self, *args, **kwargs):
+        self._args = args
+        self._kwargs = kwargs
+
+    @property
+    def context(self):
+        """Return exception context
+
+        When exception object is created, the caller can supply some opaque
+        context for the upper layers to better understand the cause of the
+        exception.
+
+        Returns
+        -------
+        : :py:class:`dict`
+            Dict holding context specific data
+        """
+        return self._kwargs.get('context', {})
 
 
 class ValueConstraintError(PyAsn1Error):
@@ -34,6 +63,18 @@ class SubstrateUnderrunError(PyAsn1Error):
     """
 
 
+class EndOfStreamError(SubstrateUnderrunError):
+    """ASN.1 data structure deserialization error
+
+    The `EndOfStreamError` exception indicates the condition of the input
+    stream has been closed.
+    """
+
+
+class UnsupportedSubstrateError(PyAsn1Error):
+    """Unsupported substrate type to parse as ASN.1 data."""
+
+
 class PyAsn1UnicodeError(PyAsn1Error, UnicodeError):
     """Unicode text processing error