From a7d88710444459a9b634a9a0735221b80ceb68c3 Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Wed, 11 Oct 2017 22:09:14 +0200 Subject: Docs rearrangement (#88) Docs rearranged, simplified and reworded, Sphinx theme changed. --- pyasn1/type/base.py | 60 +++++++++++++++----------- pyasn1/type/char.py | 6 +-- pyasn1/type/univ.py | 122 +++++++++++++++++++++++++++++----------------------- 3 files changed, 105 insertions(+), 83 deletions(-) (limited to 'pyasn1/type') diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py index 1b54d8d..4dd6a21 100644 --- a/pyasn1/type/base.py +++ b/pyasn1/type/base.py @@ -75,7 +75,7 @@ class Asn1ItemBase(Asn1Item): (:py:mod:`~pyasn1.type.constraint`) are examined when carrying out ASN.1 types comparison. - No Python inheritance relationship between PyASN1 objects is considered. + Python class inheritance relationship is NOT considered. Parameters ---------- @@ -99,8 +99,7 @@ class Asn1ItemBase(Asn1Item): (:py:mod:`~pyasn1.type.constraint`) are examined when carrying out ASN.1 types comparison. - No Python inheritance relationship between PyASN1 objects is considered. - + Python class inheritance relationship is NOT considered. Parameters ---------- @@ -145,11 +144,16 @@ class Asn1ItemBase(Asn1Item): class NoValue(object): """Create a singleton instance of NoValue class. - NoValue object can be used as an initializer on PyASN1 type class - instantiation to represent ASN.1 type rather than ASN.1 data value. + The *NoValue* sentinel object represents an instance of ASN.1 schema + object as opposed to ASN.1 value object. - No operations other than type comparison can be performed on - a PyASN1 type object. + Only ASN.1 schema-related operations can be performed on ASN.1 + schema objects. + + Warning + ------- + Any operation attempted on the *noValue* object will raise the + *PyAsn1Error* exception. """ skipMethods = ('__getattribute__', '__getattr__', '__setattr__', '__delattr__', '__class__', '__init__', '__del__', '__new__', '__repr__', @@ -161,7 +165,7 @@ class NoValue(object): if cls._instance is None: def getPlug(name): def plug(self, *args, **kw): - raise error.PyAsn1Error('Uninitialized ASN.1 value ("%s" attribute looked up)' % name) + raise error.PyAsn1Error('Attempted "%s" operation on ASN.1 schema object' % name) return plug op_names = [name @@ -253,31 +257,35 @@ class AbstractSimpleAsn1Item(Asn1ItemBase): @property def isValue(self): - """Indicate if |ASN.1| object represents ASN.1 type or ASN.1 value. + """Indicate that |ASN.1| object represents ASN.1 value. - In other words, if *isValue* is `True`, then the ASN.1 object is - initialized. + If *isValue* is `False` then this object represents just ASN.1 schema. + + If *isValue* is `True` then, in addition to its ASN.1 schema features, + this object can also be used like a Python built-in object (e.g. `int`, + `str`, `dict` etc.). Returns ------- : :class:`bool` - :class:`True` if object represents ASN.1 value and type, - :class:`False` if object represents just ASN.1 type. + :class:`False` if object represents just ASN.1 schema. + :class:`True` if object represents ASN.1 schema and can be used as a normal value. Note ---- - There is an important distinction between PyASN1 type and value objects. - The PyASN1 type objects can only participate in ASN.1 type - operations (subtyping, comparison etc) and serve as a - blueprint for serialization codecs to resolve ambiguous types. - - The PyASN1 value objects can additionally participate in most - of built-in Python operations. + There is an important distinction between PyASN1 schema and value objects. + The PyASN1 schema objects can only participate in ASN.1 schema-related + operations (e.g. defining or testing the structure of the data). Most + obvious uses of ASN.1 schema is to guide serialization codecs whilst + encoding/decoding serialised ASN.1 contents. + + The PyASN1 value objects can **additionally** participate in many operations + involving regular Python objects (e.g. arithmetic, comprehension etc). """ return self._value is not noValue def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -311,7 +319,7 @@ class AbstractSimpleAsn1Item(Asn1ItemBase): return self.__class__(value, **initilaizers) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -369,7 +377,7 @@ class AbstractSimpleAsn1Item(Asn1ItemBase): return str(value) def prettyPrint(self, scope=0): - """Provide human-friendly printable object representation. + """Return human-friendly object representation as a text. Returns ------- @@ -408,6 +416,8 @@ class AbstractSimpleAsn1Item(Asn1ItemBase): # of types for Sequence/Set/Choice. # +# TODO: remove + def setupComponent(): """Returns a sentinel value. @@ -490,7 +500,7 @@ class AbstractConstructedAsn1Item(Asn1ItemBase): pass def clone(self, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -525,7 +535,7 @@ class AbstractConstructedAsn1Item(Asn1ItemBase): return clone def subtype(self, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. diff --git a/pyasn1/type/char.py b/pyasn1/type/char.py index 60f9d97..d430bd8 100644 --- a/pyasn1/type/char.py +++ b/pyasn1/type/char.py @@ -18,7 +18,7 @@ noValue = univ.noValue class AbstractCharacterString(univ.OctetString): - """Creates |ASN.1| type or object. + """Creates |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type Python 2 :class:`unicode` or Python 3 :class:`str`. When used in octet-stream context, |ASN.1| type assumes "|encoding|" encoding. @@ -126,7 +126,7 @@ class AbstractCharacterString(univ.OctetString): return reversed(self._value) def clone(self, value=noValue, **kwargs): - """Creates a copy of a |ASN.1| type or object. + """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. @@ -158,7 +158,7 @@ class AbstractCharacterString(univ.OctetString): return univ.OctetString.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Creates a copy of a |ASN.1| type or object. + """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. diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py index a0d0e01..8e78f77 100644 --- a/pyasn1/type/univ.py +++ b/pyasn1/type/univ.py @@ -245,7 +245,7 @@ class Integer(base.AbstractSimpleAsn1Item): return str(value) def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -273,7 +273,7 @@ class Integer(base.AbstractSimpleAsn1Item): return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -340,7 +340,7 @@ class Boolean(Integer): class BitString(base.AbstractSimpleAsn1Item): - """Create |ASN.1| type or object. + """Create |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type both Python :class:`tuple` (as a tuple of bits) and :class:`int` objects. @@ -441,7 +441,7 @@ class BitString(base.AbstractSimpleAsn1Item): base.AbstractSimpleAsn1Item.__init__(self, value, **kwargs) def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -477,7 +477,7 @@ class BitString(base.AbstractSimpleAsn1Item): return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -783,7 +783,7 @@ except NameError: # Python 2.4 class OctetString(base.AbstractSimpleAsn1Item): - """Create |ASN.1| type or object. + """Create |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type Python 2 :class:`str` or Python 3 :class:`bytes`. When used in Unicode context, |ASN.1| type assumes "|encoding|" serialization. @@ -865,7 +865,7 @@ class OctetString(base.AbstractSimpleAsn1Item): base.AbstractSimpleAsn1Item.__init__(self, value, **kwargs) def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -901,7 +901,7 @@ class OctetString(base.AbstractSimpleAsn1Item): return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -1151,7 +1151,7 @@ class OctetString(base.AbstractSimpleAsn1Item): class Null(OctetString): - """Create |ASN.1| type or object. + """Create |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type Python :class:`str` objects (always empty). @@ -1182,7 +1182,7 @@ class Null(OctetString): typeId = OctetString.getTypeId() def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -1204,7 +1204,7 @@ class Null(OctetString): return OctetString.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -1242,7 +1242,7 @@ numericTypes = intTypes + (float,) class ObjectIdentifier(base.AbstractSimpleAsn1Item): - """Create |ASN.1| type or object. + """Create |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type Python :class:`tuple` objects (tuple of non-negative integers). @@ -1365,7 +1365,7 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item): class Real(base.AbstractSimpleAsn1Item): - """Create |ASN.1| type or object. + """Create |ASN.1| schema or value object. |ASN.1| objects are immutable and duck-type Python :class:`float` objects. Additionally, |ASN.1| objects behave like a :class:`tuple` in which case its @@ -1416,7 +1416,7 @@ class Real(base.AbstractSimpleAsn1Item): typeId = base.AbstractSimpleAsn1Item.getTypeId() def clone(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -1441,7 +1441,7 @@ class Real(base.AbstractSimpleAsn1Item): return base.AbstractSimpleAsn1Item.clone(self, value, **kwargs) def subtype(self, value=noValue, **kwargs): - """Create a copy of a |ASN.1| type or object. + """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. @@ -1955,29 +1955,30 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item): @property def isValue(self): - """Indicate if |ASN.1| object represents ASN.1 type or ASN.1 value. - - In other words, if *isValue* is `True`, then the ASN.1 object is - initialized. + """Indicate that |ASN.1| object represents ASN.1 value. - For the purpose of this check, empty |ASN.1| object is considered - as initialized. + If *isValue* is `False` then this object represents just ASN.1 schema. + + If *isValue* is `True` then, in addition to its ASN.1 schema features, + this object can also be used like a Python built-in object (e.g. `int`, + `str`, `dict` etc.). Returns ------- : :class:`bool` - :class:`True` if object represents ASN.1 value and type, - :class:`False` if object represents just ASN.1 type. + :class:`False` if object represents just ASN.1 schema. + :class:`True` if object represents ASN.1 schema and can be used as a normal value. Note ---- - There is an important distinction between PyASN1 type and value objects. - The PyASN1 type objects can only participate in ASN.1 type - operations (subtyping, comparison etc) and serve as a - blueprint for serialization codecs to resolve ambiguous types. - - The PyASN1 value objects can additionally participate in most - of built-in Python operations. + There is an important distinction between PyASN1 schema and value objects. + The PyASN1 schema objects can only participate in ASN.1 schema-related + operations (e.g. defining or testing the structure of the data). Most + obvious uses of ASN.1 schema is to guide serialization codecs whilst + encoding/decoding serialised ASN.1 contents. + + The PyASN1 value objects can **additionally** participate in many operations + involving regular Python objects (e.g. arithmetic, comprehension etc). """ for componentValue in self._componentValues: if not componentValue.isValue: @@ -2267,7 +2268,7 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item): ---------- idx : :class:`int` Component index (zero-based). Must either refer to an existing - component or (if *componentType* is set) new ASN.1 type object gets + component or (if *componentType* is set) new ASN.1 schema object gets instantiated. Returns @@ -2379,29 +2380,30 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item): @property def isValue(self): - """Indicate if |ASN.1| object represents ASN.1 type or ASN.1 value. + """Indicate that |ASN.1| object represents ASN.1 value. - In other words, if *isValue* is `True`, then the ASN.1 object is - initialized. - - For the purpose of check, the *OPTIONAL* and *DEFAULT* fields are - unconditionally considered as initialized. + If *isValue* is `False` then this object represents just ASN.1 schema. + + If *isValue* is `True` then, in addition to its ASN.1 schema features, + this object can also be used like a Python built-in object (e.g. `int`, + `str`, `dict` etc.). Returns ------- : :class:`bool` - :class:`True` if object represents ASN.1 value and type, - :class:`False` if object represents just ASN.1 type. + :class:`False` if object represents just ASN.1 schema. + :class:`True` if object represents ASN.1 schema and can be used as a normal value. Note ---- - There is an important distinction between PyASN1 type and value objects. - The PyASN1 type objects can only participate in ASN.1 type - operations (subtyping, comparison etc) and serve as a - blueprint for serialization codecs to resolve ambiguous types. - - The PyASN1 value objects can additionally participate in most - of built-in Python operations. + There is an important distinction between PyASN1 schema and value objects. + The PyASN1 schema objects can only participate in ASN.1 schema-related + operations (e.g. defining or testing the structure of the data). Most + obvious uses of ASN.1 schema is to guide serialization codecs whilst + encoding/decoding serialised ASN.1 contents. + + The PyASN1 value objects can **additionally** participate in many operations + involving regular Python objects (e.g. arithmetic, comprehension etc). """ componentType = self.componentType @@ -2837,20 +2839,30 @@ class Choice(Set): @property def isValue(self): - """Indicate if |ASN.1| component is set and represents ASN.1 type or ASN.1 value. - - The PyASN1 type objects can only participate in types comparison - and serve as a blueprint for serialization codecs to resolve - ambiguous types. + """Indicate that |ASN.1| object represents ASN.1 value. - The PyASN1 value objects can additionally participate in most - of built-in Python operations. + If *isValue* is `False` then this object represents just ASN.1 schema. + + If *isValue* is `True` then, in addition to its ASN.1 schema features, + this object can also be used like a Python built-in object (e.g. `int`, + `str`, `dict` etc.). Returns ------- : :class:`bool` - :class:`True` if |ASN.1| component is set and represent value and type, - :class:`False` if |ASN.1| component is not set or it represents just ASN.1 type. + :class:`False` if object represents just ASN.1 schema. + :class:`True` if object represents ASN.1 schema and can be used as a normal value. + + Note + ---- + There is an important distinction between PyASN1 schema and value objects. + The PyASN1 schema objects can only participate in ASN.1 schema-related + operations (e.g. defining or testing the structure of the data). Most + obvious uses of ASN.1 schema is to guide serialization codecs whilst + encoding/decoding serialised ASN.1 contents. + + The PyASN1 value objects can **additionally** participate in many operations + involving regular Python objects (e.g. arithmetic, comprehension etc). """ if self._currentIdx is None: return False -- cgit v1.2.3