Merge branch 'devel-0.4.1' of github.com:etingof/pyasn1 into devel-0.4.1

12 files changed, 126 insertions, 492 deletions

diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py
index b02aeec..8bdffcf 100644
--- a/pyasn1/codec/ber/decoder.py
+++ b/pyasn1/codec/ber/decoder.py
@@ -1351,7 +1351,7 @@ class Decoder(object):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
 decode = Decoder(tagMap, typeMap)
 
diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py
index 97a1390..3f19c8a 100644
--- a/pyasn1/codec/ber/encoder.py
+++ b/pyasn1/codec/ber/encoder.py
@@ -662,6 +662,6 @@ class Encoder(object):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py
index a9dd7e8..a93b9a6 100644
--- a/pyasn1/codec/cer/decoder.py
+++ b/pyasn1/codec/cer/decoder.py
@@ -85,6 +85,6 @@ class Decoder(decoder.Decoder):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
 decode = Decoder(tagMap, decoder.typeMap)
diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py
index 52216fe..8acd580 100644
--- a/pyasn1/codec/cer/encoder.py
+++ b/pyasn1/codec/cer/encoder.py
@@ -267,7 +267,7 @@ class Encoder(encoder.Encoder):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
 encode = Encoder(tagMap, typeMap)
 
diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py
index 77b1cec..4977a05 100644
--- a/pyasn1/codec/der/decoder.py
+++ b/pyasn1/codec/der/decoder.py
@@ -65,6 +65,6 @@ class Decoder(decoder.Decoder):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
 decode = Decoder(tagMap, typeMap)
diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py
index 14ae2c9..0a39e71 100644
--- a/pyasn1/codec/der/encoder.py
+++ b/pyasn1/codec/der/encoder.py
@@ -80,6 +80,6 @@ class Encoder(encoder.Encoder):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py
index 70b22a8..e5d0a53 100644
--- a/pyasn1/codec/native/decoder.py
+++ b/pyasn1/codec/native/decoder.py
@@ -189,6 +189,6 @@ class Decoder(object):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On decoding errors
 decode = Decoder(tagMap, typeMap)
diff --git a/pyasn1/codec/native/encoder.py b/pyasn1/codec/native/encoder.py
index 3d23d60..53d16fc 100644
--- a/pyasn1/codec/native/encoder.py
+++ b/pyasn1/codec/native/encoder.py
@@ -207,6 +207,6 @@ class Encoder(object):
 #:
 #: Raises
 #: ------
-#: : :py:class:`pyasn1.error.PyAsn1Error`
+#: :py:class:`~pyasn1.error.PyAsn1Error`
 #:     On encoding errors
 encode = Encoder(tagMap, typeMap)
diff --git a/pyasn1/error.py b/pyasn1/error.py
index 8530855..5eadfac 100644
--- a/pyasn1/error.py
+++ b/pyasn1/error.py
@@ -7,12 +7,23 @@
 
 
 class PyAsn1Error(Exception):
-    pass
+    """Create pyasn1 exception object
+
+    The `PyAsn1Error` exception represents generic, usually fatal, error.
+    """
 
 
 class ValueConstraintError(PyAsn1Error):
-    pass
+    """Create pyasn1 exception object
+    
+    The `ValueConstraintError` exception indicates an ASN.1 value 
+    constraint violation.
+    """
 
 
 class SubstrateUnderrunError(PyAsn1Error):
-    pass
+    """Create pyasn1 exception object
+
+    The `SubstrateUnderrunError` exception indicates insufficient serialised
+    data on input of a deserialisation routine.
+    """
diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py
index a3ca9fb..f22823b 100644
--- a/pyasn1/type/base.py
+++ b/pyasn1/type/base.py
@@ -286,27 +286,20 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         return self._value is not noValue
 
     def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
+        """Create a modified version of |ASN.1| schema or value object.
 
-          Any parameters to the *clone()* method will replace corresponding
-          properties of the |ASN.1| object.
+        The `clone()` method accepts the same set arguments as |ASN.1|
+        class takes on instantiation except that all arguments
+        of the `clone()` method are optional.
 
-          Parameters
-          ----------
-          value: :class:`tuple`, :class:`str` or |ASN.1| object
-              Initialization value to pass to new ASN.1 object instead of
-              inheriting one from the caller.
+        Whatever arguments are supplied, they are used to create a copy
+        of `self` taking precedence over the ones used to instantiate `self`.
 
-          tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-              Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-          subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-              Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-          Returns
-          -------
-          :
-              new instance of |ASN.1| type/value
+        Note
+        ----
+        Due to the immutable nature of the |ASN.1| object, if no arguments
+        are supplied, no new |ASN.1| object will be created and `self` will
+        be returned instead.
         """
         if value is noValue:
             if not kwargs:
@@ -320,35 +313,51 @@ class AbstractSimpleAsn1Item(Asn1ItemBase):
         return self.__class__(value, **initilaizers)
 
     def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-         Any parameters to the *subtype()* method will be added to the corresponding
-         properties of the |ASN.1| object.
-
-         Parameters
-         ----------
-         value: :class:`tuple`, :class:`str` or |ASN.1| object
-             Initialization value to pass to new ASN.1 object instead of
-             inheriting one from the caller.
-
-         implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-             Implicitly apply given ASN.1 tag object to caller's
-             :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-             new object's ASN.1 tag(s).
-
-         explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-             Explicitly apply given ASN.1 tag object to caller's
-             :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-             new object's ASN.1 tag(s).
-
-         subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-             Add ASN.1 constraints object to one of the caller, then
-             use the result as new object's ASN.1 constraints.
-
-         Returns
-         -------
-         :
-             new instance of |ASN.1| type/value
+        """Create a specialization of |ASN.1| schema or value object.
+
+        The subtype relationship between ASN.1 types has no correlation with
+        subtype relationship between Python types. ASN.1 type is mainly identified
+        by its tag(s) (:py:class:`~pyasn1.type.tag.TagSet`) and value range
+        constraints (:py:class:`~pyasn1.type.constraint.ConstraintsIntersection`).
+        These ASN.1 type properties are implemented as |ASN.1| attributes.  
+
+        The `subtype()` method accepts the same set arguments as |ASN.1|
+        class takes on instantiation except that all parameters
+        of the `subtype()` method are optional.
+
+        With the exception of the arguments described below, the rest of
+        supplied arguments they are used to create a copy of `self` taking
+        precedence over the ones used to instantiate `self`.
+
+        The following arguments to `subtype()` create a ASN.1 subtype out of
+        |ASN.1| type:
+
+        Parameters
+        ----------
+        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
+            Implicitly apply given ASN.1 tag object to `self`'s
+            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
+            new object's ASN.1 tag(s).
+
+        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
+            Explicitly apply given ASN.1 tag object to `self`'s
+            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
+            new object's ASN.1 tag(s).
+
+        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+            Add ASN.1 constraints object to one of the `self`'s, then
+            use the result as new object's ASN.1 constraints.
+
+        Returns
+        -------
+        :
+            new instance of |ASN.1| schema or value object 
+
+        Note
+        ----
+        Due to the immutable nature of the |ASN.1| object, if no arguments
+        are supplied, no new |ASN.1| object will be created and `self` will
+        be returned instead.
         """
         if value is noValue:
             if not kwargs:
@@ -479,27 +488,28 @@ class AbstractConstructedAsn1Item(Asn1ItemBase):
         pass
 
     def clone(self, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
+        """Create a modified version of |ASN.1| schema object.
 
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
+        The `clone()` method accepts the same set arguments as |ASN.1|
+        class takes on instantiation except that all arguments
+        of the `clone()` method are optional.
 
-        Parameters
-        ----------
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing non-default ASN.1 tag(s)
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 subtype constraint(s)
+        Whatever arguments are supplied, they are used to create a copy
+        of `self` taking precedence over the ones used to instantiate `self`.
 
-        sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 size constraint(s)
+        Possible values of `self` are never copied over thus `clone()` can
+        only create a new schema object.
 
         Returns
         -------
         :
             new instance of |ASN.1| type/value
 
+        Note
+        ----
+        Due to the mutable nature of the |ASN.1| object, even if no arguments
+        are supplied, new |ASN.1| object will always be created as a shallow
+        copy of `self`.
         """
         cloneValueFlag = kwargs.pop('cloneValueFlag', False)
 
@@ -514,27 +524,46 @@ class AbstractConstructedAsn1Item(Asn1ItemBase):
         return clone
 
     def subtype(self, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
+        """Create a specialization of |ASN.1| schema object.
+
+        The `subtype()` method accepts the same set arguments as |ASN.1|
+        class takes on instantiation except that all parameters
+        of the `subtype()` method are optional.
 
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
+        With the exception of the arguments described below, the rest of
+        supplied arguments they are used to create a copy of `self` taking
+        precedence over the ones used to instantiate `self`.
+
+        The following arguments to `subtype()` create a ASN.1 subtype out of
+        |ASN.1| type.
 
         Parameters
         ----------
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing non-default ASN.1 tag(s)
+        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
+            Implicitly apply given ASN.1 tag object to `self`'s
+            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
+            new object's ASN.1 tag(s).
 
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 subtype constraint(s)
+        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
+            Explicitly apply given ASN.1 tag object to `self`'s
+            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
+            new object's ASN.1 tag(s).
 
-        sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 size constraint(s)
+        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
+            Add ASN.1 constraints object to one of the `self`'s, then
+            use the result as new object's ASN.1 constraints.
 
+        
         Returns
         -------
         :
             new instance of |ASN.1| type/value
 
+        Note
+        ----
+        Due to the immutable nature of the |ASN.1| object, if no arguments
+        are supplied, no new |ASN.1| object will be created and `self` will
+        be returned instead.
         """
 
         initializers = self.readOnly.copy()
diff --git a/pyasn1/type/char.py b/pyasn1/type/char.py
index d430bd8..2a04bd1 100644
--- a/pyasn1/type/char.py
+++ b/pyasn1/type/char.py
@@ -43,7 +43,7 @@ class AbstractCharacterString(univ.OctetString):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
 
@@ -125,76 +125,6 @@ class AbstractCharacterString(univ.OctetString):
     def __reversed__(self):
         return reversed(self._value)
 
-    def clone(self, value=noValue, **kwargs):
-        """Creates a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`unicode`, :class:`str`, :class:`bytes` or |ASN.1| object
-            unicode object (Python 2) or string (Python 3), alternatively string
-            (Python 2) or bytes (Python 3) representing octet-stream of serialized
-            unicode string (note `encoding` parameter) or |ASN.1| class instance.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing non-default ASN.1 tag(s)
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 subtype constraint(s)
-
-        encoding: :py:class:`str`
-            Unicode codec ID to encode/decode :py:class:`unicode` (Python 2) or
-            :py:class:`str` (Python 3) the payload when |ASN.1| object is used
-            in octet-stream context.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-
-        """
-        return univ.OctetString.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Creates a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`unicode`, :class:`str`, :class:`bytes` or |ASN.1| object
-            unicode object (Python 2) or string (Python 3), alternatively string
-            (Python 2) or bytes (Python 3) representing octet-stream of serialized
-            unicode string (note `encoding` parameter) or |ASN.1| class instance.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to caller's
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to caller's
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing non-default ASN.1 subtype constraint(s)
-
-        encoding: :py:class:`str`
-            Unicode codec ID to encode/decode :py:class:`unicode` (Python 2) or
-            :py:class:`str` (Python 3) the payload when |ASN.1| object is used
-            in octet-stream context.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-
-        """
-        return univ.OctetString.subtype(self, value, **kwargs)
 
 class NumericString(AbstractCharacterString):
     __doc__ = AbstractCharacterString.__doc__
diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py
index f30e631..4ce03ce 100644
--- a/pyasn1/type/univ.py
+++ b/pyasn1/type/univ.py
@@ -43,7 +43,7 @@ class Integer(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
     #: Set (on class, not on instance) or return a
@@ -244,72 +244,6 @@ class Integer(base.AbstractSimpleAsn1Item):
         except KeyError:
             return str(value)
 
-    def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`int`, :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-        namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
-            Object representing symbolic aliases for numbers to use instead of inheriting from caller
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`int`, :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of 
-            inheriting one from the caller.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Add ASN.1 constraints object to one of the caller, then
-            use the result as new object's ASN.1 constraints.
-
-        namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
-            Add given object representing symbolic aliases for numbers
-            to one of the caller, then use the result as new object's
-            named numbers.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.subtype(self, value, **kwargs)
-
     # backward compatibility
 
     def getNamedValues(self):
@@ -370,7 +304,7 @@ class BitString(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
     #: Set (on class, not on instance) or return a
@@ -440,88 +374,6 @@ class BitString(base.AbstractSimpleAsn1Item):
 
         base.AbstractSimpleAsn1Item.__init__(self, value, **kwargs)
 
-    def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value : :class:`int`, :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-        namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
-            Class instance representing BitString type enumerations
-
-        binValue: :py:class:`str`
-            Binary string initializer to use instead of the *value*.
-            Example: '10110011'.
-
-        hexValue: :py:class:`str`
-            Hexadecimal string initializer to use instead of the *value*.
-            Example: 'DEADBEEF'.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`int`, :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Add ASN.1 constraints object to one of the caller, then
-            use the result as new object's ASN.1 constraints.
-
-        namedValues: :py:class:`~pyasn1.type.namedval.NamedValues`
-            Add given object representing symbolic aliases for numbers
-            to one of the caller, then use the result as new object's
-            named numbers.
-
-        binValue: :py:class:`str`
-            Binary string initializer to use instead of the *value*.
-            Example: '10110011'.
-
-        hexValue: :py:class:`str`
-            Hexadecimal string initializer to use instead of the *value*.
-            Example: 'DEADBEEF'.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.subtype(self, value, **kwargs)
-
     def __str__(self):
         return self.asBinary()
 
@@ -816,7 +668,7 @@ class OctetString(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
     #: Set (on class, not on instance) or return a
@@ -864,86 +716,6 @@ class OctetString(base.AbstractSimpleAsn1Item):
 
         base.AbstractSimpleAsn1Item.__init__(self, value, **kwargs)
 
-    def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value : :class:`str`, :class:`bytes` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-        encoding: :py:class:`str`
-            Unicode codec ID to encode/decode :class:`unicode` (Python 2)
-            or :class:`str` (Python 3) the payload when |ASN.1|
-            object is used in string context.
-
-        binValue: :py:class:`str`
-            Binary string initializer. Example: '10110011'.
-        
-        hexValue: :py:class:`str`
-            Hexadecimal string initializer. Example: 'DEADBEEF'.
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value : :class:`str`, :class:`bytes` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to |ASN.1| object tag set
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to |ASN.1| object tag set
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Add ASN.1 constraints object to one of the caller, then
-            use the result as new object's ASN.1 constraints.
-
-        encoding: :py:class:`str`
-            Unicode codec ID to encode/decode :class:`unicode` (Python 2)
-            or :class:`str` (Python 3) the payload when *OctetString*
-            object is used in string context.
-
-        binValue: :py:class:`str`
-            Binary string initializer. Example: '10110011'.
-        
-        hexValue: :py:class:`str`
-            Hexadecimal string initializer. Example: 'DEADBEEF'.
-
-        Returns
-        -------
-        :
-             new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.subtype(self, value, **kwargs)
-
     if sys.version_info[0] <= 2:
         def prettyIn(self, value):
             if isinstance(value, str):
@@ -1165,7 +937,7 @@ class Null(OctetString):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
 
@@ -1180,57 +952,6 @@ class Null(OctetString):
     # Optimization for faster codec lookup
     typeId = OctetString.getTypeId()
 
-    def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of 
-            inheriting one from the caller.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-        Returns
-        -------
-        : :py:class:`~pyasn1.type.univ.Null`
-            new instance of NULL type/value
-        """
-        return OctetString.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`int`, :class:`str` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        Returns
-        -------
-        : :py:class:`~pyasn1.type.univ.Null`
-            new instance of NULL type/value
-        """
-        return OctetString.subtype(self, value, **kwargs)
-
     def prettyIn(self, value):
         if value:
             return value
@@ -1263,7 +984,7 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
     """
     #: Set (on class, not on instance) or return a
@@ -1389,7 +1110,7 @@ class Real(base.AbstractSimpleAsn1Item):
 
     Raises
     ------
-    : :py:class:`pyasn1.error.PyAsn1Error`
+    :py:class:`~pyasn1.error.PyAsn1Error`
         On constraint violation or bad initializer.
 
     """
@@ -1419,63 +1140,6 @@ class Real(base.AbstractSimpleAsn1Item):
     # Optimization for faster codec lookup
     typeId = base.AbstractSimpleAsn1Item.getTypeId()
 
-    def clone(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *clone()* method will replace corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`tuple`, :class:`float` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        tagSet: :py:class:`~pyasn1.type.tag.TagSet`
-            Object representing ASN.1 tag(s) to use in new object instead of inheriting from the caller
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-            Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs)
-
-    def subtype(self, value=noValue, **kwargs):
-        """Create a copy of a |ASN.1| schema or value object.
-
-        Any parameters to the *subtype()* method will be added to the corresponding
-        properties of the |ASN.1| object.
-
-        Parameters
-        ----------
-        value: :class:`tuple`, :class:`float` or |ASN.1| object
-            Initialization value to pass to new ASN.1 object instead of
-            inheriting one from the caller.
-
-        implicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Implicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        explicitTag: :py:class:`~pyasn1.type.tag.Tag`
-            Explicitly apply given ASN.1 tag object to caller's 
-            :py:class:`~pyasn1.type.tag.TagSet`, then use the result as
-            new object's ASN.1 tag(s).
-
-        subtypeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection`
-             Object representing ASN.1 subtype constraint(s) to use in new object instead of inheriting from the caller
-
-        Returns
-        -------
-        :
-            new instance of |ASN.1| type/value
-        """
-        return base.AbstractSimpleAsn1Item.subtype(self, value, **kwargs)
-
     @staticmethod
     def __normalizeBase10(value):
         m, b, e = value