14 files changed, 232 insertions, 36 deletions
diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst
index 474bbff..eaa7835 100644
--- a/docs/source/pyasn1/contents.rst
+++ b/docs/source/pyasn1/contents.rst
@@ -139,6 +139,7 @@ type's values.
 .. toctree::
    :maxdepth: 2
 
+   /pyasn1/type/base/contents
    /pyasn1/type/univ/contents
    /pyasn1/type/char/contents
    /pyasn1/type/useful/contents
@@ -212,3 +213,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/docs/source/pyasn1/type/base/asn1type.rst b/docs/source/pyasn1/type/base/asn1type.rst
new file mode 100644
index 0000000..94fe04d
--- /dev/null
+++ b/docs/source/pyasn1/type/base/asn1type.rst
@@ -0,0 +1,10 @@
+
+.. _base.Asn1Type:
+
+.. |ASN.1| replace:: Asn1Type
+
+|ASN.1| type
+------------
+
+.. autoclass:: pyasn1.type.base.Asn1Type(tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
+   :members: isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec
diff --git a/docs/source/pyasn1/type/base/constructedasn1type.rst b/docs/source/pyasn1/type/base/constructedasn1type.rst
new file mode 100644
index 0000000..54d828f
--- /dev/null
+++ b/docs/source/pyasn1/type/base/constructedasn1type.rst
@@ -0,0 +1,10 @@
+
+.. _base.ConstructedAsn1Type:
+
+.. |ASN.1| replace:: ConstructedAsn1Type
+
+|ASN.1| type
+------------
+
+.. autoclass:: pyasn1.type.base.ConstructedAsn1Type(tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection(), componentType=None)
+   :members: isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec
diff --git a/docs/source/pyasn1/type/base/contents.rst b/docs/source/pyasn1/type/base/contents.rst
new file mode 100644
index 0000000..ffb325c
--- /dev/null
+++ b/docs/source/pyasn1/type/base/contents.rst
@@ -0,0 +1,20 @@
+
+.. _type.base:
+
+ASN.1 type system
+-----------------
+
+The ASN.1 language defines a collection of data types such as *INTEGER*
+or *SET*. With pyasn1, ASN.1 types are represented by Python classes.
+The base classes are described in this part of the documentation.
+
+User code might not need to use them directly, except for figuring out
+if given object belongs to ASN.1 type or not.
+
+.. toctree::
+   :maxdepth: 2
+
+   /pyasn1/type/base/asn1type
+   /pyasn1/type/base/simpleasn1type
+   /pyasn1/type/base/constructedasn1type
+   /pyasn1/type/base/novalue
diff --git a/docs/source/pyasn1/type/base/novalue.rst b/docs/source/pyasn1/type/base/novalue.rst
new file mode 100644
index 0000000..6e34792
--- /dev/null
+++ b/docs/source/pyasn1/type/base/novalue.rst
@@ -0,0 +1,6 @@
+.. _type.base.NoValue:
+
+NoValue sentinel
+----------------
+
+.. autoclass:: pyasn1.type.base.NoValue()
diff --git a/docs/source/pyasn1/type/base/simpleasn1type.rst b/docs/source/pyasn1/type/base/simpleasn1type.rst
new file mode 100644
index 0000000..03a960d
--- /dev/null
+++ b/docs/source/pyasn1/type/base/simpleasn1type.rst
@@ -0,0 +1,10 @@
+
+.. _base.SimpleAsn1Type:
+
+.. |ASN.1| replace:: SimpleAsn1Type
+
+|ASN.1| type
+------------
+
+.. autoclass:: pyasn1.type.base.SimpleAsn1Type(value=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
+   :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec
diff --git a/docs/source/pyasn1/type/opentype/contents.rst b/docs/source/pyasn1/type/opentype/contents.rst
index 9ae10d0..034870b 100644
--- a/docs/source/pyasn1/type/opentype/contents.rst
+++ b/docs/source/pyasn1/type/opentype/contents.rst
@@ -1,16 +1,67 @@
 
 .. _type.opentype:
 
-Untyped fields of constructed types
------------------------------------
+Dynamic or open type
+--------------------
 
-To aid data structures flexibility, ASN.1 allows the designer to
-leave incomplete field type specification in the
-:ref:`Sequence <univ.Sequence>` and :ref:`Set <univ.Set>` types.
+ASN.1 allows data structure designer to leave "holes" in field type
+specification of :ref:`Sequence <univ.Sequence>` or
+:ref:`Set <univ.Set>` types.
 
-To figure out field's type at the run time, a type selector field
-must accompany the open type field. The open type situation can
-be captured by the :ref:`OpenType <opentype.OpenType>` object.
+The idea behind that feature is that there can be times, when the
+exact field type is not known at the design time, or it is anticipated
+that new field types may come up in the future.
+
+This "hole" type is manifested in the data structure by :ref:`Any <univ.Any>`
+type. Technically, the actual type is serialized into an octet stream
+and then put into :ref:`Any <univ.Any>` "container", which is in fact an
+(untagged, by default) specialization of ASN.1
+:ref:`OctetString <univ.OctetString>` type.
+
+.. code-block:: bash
+
+       Algorithm ::= SEQUENCE {
+               algorithm OBJECT IDENTIFIER,
+               parameters ANY DEFINED BY algorithm OPTIONAL
+       }
+
+On the receiving end, to know how to interpret the open type
+serialization, the receiver can rely on the supplied value in
+the other field of the data structure. That other field is
+semantically linked with the open type field. This link
+is expressed in ASN.1 by the *DEFINE BY* clause.
+
+From ASN.1 perspective, it is not an error if the decoder does
+not know a type selector value it receives. In that case pyasn1 decoder
+just leaves serialized blob in the open type field.
+
+.. note::
+
+   By default, ASN.1 ANY type has no tag. That makes it an
+   "invisible" in serialization. However, like any other ASN.1 type,
+   ANY type can be subtyped by :ref:`tagging <type.tag>`.
+
+Besides scalar open type fields, ASN.1 allows using *SET OF*
+or *SEQUENCE OF* containers holding zero or more of *ANY*
+scalars.
+
+.. code-block:: bash
+
+   AttributeTypeAndValues ::= SEQUENCE {
+      type OBJECT IDENTIFIER,
+      values SET OF ANY DEFINED BY type
+   }
+
+.. note::
+
+   A single type selector field is used to guide the decoder
+   of potentially many elements of a *SET OF* or *SEQUENCE OF* container
+   all at once. That implies that all *ANY* elements must be of the same
+   type in any given instance of a data structure.
+
+When expressing ASN.1 type "holes" in pyasn1, the
+:ref:`OpenType <opentype.OpenType>` object should be used to establish
+a semantic link between type selector field and open type field.
 
 .. code-block:: python
 
@@ -24,15 +75,38 @@ be captured by the :ref:`OpenType <opentype.OpenType>` object.
        """
        Algorithm ::= SEQUENCE {
                algorithm OBJECT IDENTIFIER,
-               parameters ANY DEFINED BY algorithm OPTIONAL
+               parameters ANY DEFINED BY algorithm
        }
        """
        componentType = NamedTypes(
            NamedType('algorithm', ObjectIdentifier()),
-           OptionalNamedType('parameters', Any(),
+           NamedType('parameters', Any(),
                      openType=OpenType('algorithm', algo_map))
        )
 
+Similarly for `SET OF ANY DEFINED BY` or `SEQUENCE OF ANY DEFINED BY`
+constructs:
+
+.. code-block:: python
+
+   algo_map = {
+       ObjectIdentifier('1.2.840.113549.1.1.1'): rsaEncryption(),
+       ObjectIdentifier('1.2.840.113549.1.1.2'): md2WithRSAEncryption()
+   }
+
+
+   class Algorithm(Sequence):
+       """
+       Algorithm ::= SEQUENCE {
+               algorithm OBJECT IDENTIFIER,
+               parameters SET OF ANY DEFINED BY algorithm
+       }
+       """
+       componentType = NamedTypes(
+           NamedType('algorithm', ObjectIdentifier()),
+           NamedType('parameters', SetOf(componentType=Any()),
+                     openType=OpenType('algorithm', algo_map))
+       )
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/source/pyasn1/type/opentype/opentype.rst b/docs/source/pyasn1/type/opentype/opentype.rst
index dc2fa47..8ce9303 100644
--- a/docs/source/pyasn1/type/opentype/opentype.rst
+++ b/docs/source/pyasn1/type/opentype/opentype.rst
@@ -9,9 +9,4 @@
 .. autoclass:: pyasn1.type.opentype.OpenType
    :members:
 
-   .. note::
-
-        The |OpenType| class models an untyped field of a constructed ASN.1
-        type. In ASN.1 syntax it is usually represented by the
-        `ANY DEFINED BY` clause. Typically used with :ref:`Any <univ.Any>`
-        type.
+More information on open type use can be found :ref:`here <type.opentype>`.
+\ No newline at end of file
diff --git a/docs/source/pyasn1/type/univ/contents.rst b/docs/source/pyasn1/type/univ/contents.rst
index 2a5ba25..d546e1c 100644
--- a/docs/source/pyasn1/type/univ/contents.rst
+++ b/docs/source/pyasn1/type/univ/contents.rst
@@ -32,7 +32,3 @@ and constructed.
    /pyasn1/type/univ/set
    /pyasn1/type/univ/sequence
    /pyasn1/type/univ/choice
-
-.. _univ.noValue:
-
-.. autoclass:: pyasn1.type.univ.NoValue()
diff --git a/docs/source/pyasn1/type/univ/sequence.rst b/docs/source/pyasn1/type/univ/sequence.rst
index 6d2c6b5..0988004 100644
--- a/docs/source/pyasn1/type/univ/sequence.rst
+++ b/docs/source/pyasn1/type/univ/sequence.rst
@@ -6,14 +6,15 @@
 |ASN.1| type
 ------------
 
-.. autoclass:: pyasn1.type.univ.Sequence(componentType=None, tagSet=tagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
+.. autoclass:: pyasn1.type.univ.Sequence(componentType=NamedTypes(), tagSet=tagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, getComponentByPosition,
-             setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents
+             setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents,
+             clear, reset
 
    .. note::
 
         The |ASN.1| type models a collection of named ASN.1 components.
         Ordering of the components **is** preserved upon de/serialisation.
 
-   .. automethod:: pyasn1.type.univ.Sequence.clone(componentType=None, tagSet=tagSet(), subtypeSpec=ConstraintsIntersection())
-   .. automethod:: pyasn1.type.univ.Sequence.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.Sequence.clone(componentType=NamedTypes(), tagSet=tagSet(), subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.Sequence.subtype(componentType=NamedTypes(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
diff --git a/docs/source/pyasn1/type/univ/sequenceof.rst b/docs/source/pyasn1/type/univ/sequenceof.rst
index dadef67..6a09b92 100644
--- a/docs/source/pyasn1/type/univ/sequenceof.rst
+++ b/docs/source/pyasn1/type/univ/sequenceof.rst
@@ -6,14 +6,14 @@
 |ASN.1| type
 ------------
 
-.. autoclass:: pyasn1.type.univ.SequenceOf(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
+.. autoclass:: pyasn1.type.univ.SequenceOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
-             getComponentByPosition, setComponentByPosition
+             getComponentByPosition, setComponentByPosition, clear, reset
 
    .. note::
 
        The |ASN.1| type models a collection of elements of a single ASN.1 type.
        Ordering of the components **is** preserved upon de/serialisation.
         
-   .. automethod:: pyasn1.type.univ.SequenceOf.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
-   .. automethod:: pyasn1.type.univ.SequenceOf.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.SequenceOf.clone(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.SequenceOf.subtype(componentType=NoValue(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
diff --git a/docs/source/pyasn1/type/univ/set.rst b/docs/source/pyasn1/type/univ/set.rst
index 5c75938..792d2e9 100644
--- a/docs/source/pyasn1/type/univ/set.rst
+++ b/docs/source/pyasn1/type/univ/set.rst
@@ -6,15 +6,15 @@
 |ASN.1| type
 ------------
 
-.. autoclass:: pyasn1.type.univ.Set(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
+.. autoclass:: pyasn1.type.univ.Set(componentType=NamedTypes(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
              getComponentByPosition, setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents,
-             getComponentByType, setComponentByType
+             getComponentByType, setComponentByType, clear, reset
 
    .. note::
 
         The |ASN.1| type models a collection of named ASN.1 components.
         Ordering of the components **is not** preserved upon de/serialisation.
 
-   .. automethod:: pyasn1.type.univ.Set.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
-   .. automethod:: pyasn1.type.univ.Set.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.Set.clone(componentType=NamedTypes(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.Set.subtype(componentType=NamedTypes(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
diff --git a/docs/source/pyasn1/type/univ/setof.rst b/docs/source/pyasn1/type/univ/setof.rst
index 0317f4a..67ef92f 100644
--- a/docs/source/pyasn1/type/univ/setof.rst
+++ b/docs/source/pyasn1/type/univ/setof.rst
@@ -6,14 +6,14 @@
 |ASN.1| type
 ------------
 
-.. autoclass:: pyasn1.type.univ.SetOf(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
+.. autoclass:: pyasn1.type.univ.SetOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection())
    :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec,
-             getComponentByPosition, setComponentByPosition
+             getComponentByPosition, setComponentByPosition, clear, reset
 
    .. note::
 
         The |ASN.1| type models a collection of elements of a single ASN.1 type.
         Ordering of the components **is not** preserved upon de/serialisation.
 
-   .. automethod:: pyasn1.type.univ.SetOf.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
-   .. automethod:: pyasn1.type.univ.SetOf.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.SetOf.clone(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection())
+   .. automethod:: pyasn1.type.univ.SetOf.subtype(componentType=NoValue(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection())