From c34f53e7ee787577482f9e1b67ea507299dd3be3 Mon Sep 17 00:00:00 2001 From: Ilya Etingof Date: Tue, 14 Nov 2017 11:12:09 +0100 Subject: added example code snippets to the docstrings (#101) --- pyasn1/codec/ber/decoder.py | 22 +++ pyasn1/codec/ber/encoder.py | 20 +++ pyasn1/codec/cer/decoder.py | 22 +++ pyasn1/codec/cer/encoder.py | 20 +++ pyasn1/codec/der/decoder.py | 22 +++ pyasn1/codec/der/encoder.py | 20 +++ pyasn1/codec/native/decoder.py | 13 ++ pyasn1/codec/native/encoder.py | 12 ++ pyasn1/type/base.py | 8 +- pyasn1/type/constraint.py | 32 ++-- pyasn1/type/namedtype.py | 27 +++- pyasn1/type/opentype.py | 3 +- pyasn1/type/tag.py | 17 +++ pyasn1/type/univ.py | 336 ++++++++++++++++++++++++++++++++++++++++- 14 files changed, 545 insertions(+), 29 deletions(-) (limited to 'pyasn1') diff --git a/pyasn1/codec/ber/decoder.py b/pyasn1/codec/ber/decoder.py index 725eaa3..3737742 100644 --- a/pyasn1/codec/ber/decoder.py +++ b/pyasn1/codec/ber/decoder.py @@ -1355,6 +1355,28 @@ class Decoder(object): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On decoding errors +#: +#: Examples +#: -------- +#: Decode BER serialisation without ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03') +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: +#: Decode BER serialisation with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03', asn1Spec=seq) +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: decode = Decoder(tagMap, typeMap) # XXX diff --git a/pyasn1/codec/ber/encoder.py b/pyasn1/codec/ber/encoder.py index c8eac34..a915f52 100644 --- a/pyasn1/codec/ber/encoder.py +++ b/pyasn1/codec/ber/encoder.py @@ -666,4 +666,24 @@ class Encoder(object): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On encoding errors +#: +#: Examples +#: -------- +#: Encode Python value into BER with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> encode([1, 2, 3], asn1Spec=seq) +#: b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03' +#: +#: Encode ASN.1 value object into BER +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> seq.extend([1, 2, 3]) +#: >>> encode(seq) +#: b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03' +#: encode = Encoder(tagMap, typeMap) diff --git a/pyasn1/codec/cer/decoder.py b/pyasn1/codec/cer/decoder.py index 3cc29c7..2a9d94f 100644 --- a/pyasn1/codec/cer/decoder.py +++ b/pyasn1/codec/cer/decoder.py @@ -89,4 +89,26 @@ class Decoder(decoder.Decoder): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On decoding errors +#: +#: Examples +#: -------- +#: Decode CER serialisation without ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> s, _ = decode(b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00') +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: +#: Decode CER serialisation with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> s, _ = decode(b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00', asn1Spec=seq) +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: decode = Decoder(tagMap, decoder.typeMap) diff --git a/pyasn1/codec/cer/encoder.py b/pyasn1/codec/cer/encoder.py index b4c68ec..80cdc35 100644 --- a/pyasn1/codec/cer/encoder.py +++ b/pyasn1/codec/cer/encoder.py @@ -271,6 +271,26 @@ class Encoder(encoder.Encoder): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On encoding errors +#: +#: Examples +#: -------- +#: Encode Python value into CER with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> encode([1, 2, 3], asn1Spec=seq) +#: b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00' +#: +#: Encode ASN.1 value object into CER +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> seq.extend([1, 2, 3]) +#: >>> encode(seq) +#: b'0\x80\x02\x01\x01\x02\x01\x02\x02\x01\x03\x00\x00' +#: encode = Encoder(tagMap, typeMap) # EncoderFactory queries class instance and builds a map of tags -> encoders diff --git a/pyasn1/codec/der/decoder.py b/pyasn1/codec/der/decoder.py index 1da37a0..e7956a4 100644 --- a/pyasn1/codec/der/decoder.py +++ b/pyasn1/codec/der/decoder.py @@ -69,4 +69,26 @@ class Decoder(decoder.Decoder): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On decoding errors +#: +#: Examples +#: -------- +#: Decode DER serialisation without ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03') +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: +#: Decode DER serialisation with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> s, _ = decode(b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03', asn1Spec=seq) +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: decode = Decoder(tagMap, typeMap) diff --git a/pyasn1/codec/der/encoder.py b/pyasn1/codec/der/encoder.py index 8496252..5d6c6c0 100644 --- a/pyasn1/codec/der/encoder.py +++ b/pyasn1/codec/der/encoder.py @@ -84,4 +84,24 @@ class Encoder(encoder.Encoder): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On encoding errors +#: +#: Examples +#: -------- +#: Encode Python value into DER with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> encode([1, 2, 3], asn1Spec=seq) +#: b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03' +#: +#: Encode ASN.1 value object into DER +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> seq.extend([1, 2, 3]) +#: >>> encode(seq) +#: b'0\t\x02\x01\x01\x02\x01\x02\x02\x01\x03' +#: encode = Encoder(tagMap, typeMap) diff --git a/pyasn1/codec/native/decoder.py b/pyasn1/codec/native/decoder.py index cd60649..55ccc3c 100644 --- a/pyasn1/codec/native/decoder.py +++ b/pyasn1/codec/native/decoder.py @@ -193,4 +193,17 @@ class Decoder(object): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On decoding errors +#: +#: Examples +#: -------- +#: Decode native Python object into ASN.1 objects with ASN.1 schema +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> s, _ = decode([1, 2, 3], asn1Spec=seq) +#: >>> print(s.prettyPrint()) +#: SequenceOf: +#: 1 2 3 +#: decode = Decoder(tagMap, typeMap) diff --git a/pyasn1/codec/native/encoder.py b/pyasn1/codec/native/encoder.py index 53d16fc..e99e1df 100644 --- a/pyasn1/codec/native/encoder.py +++ b/pyasn1/codec/native/encoder.py @@ -209,4 +209,16 @@ class Encoder(object): #: ------ #: :py:class:`~pyasn1.error.PyAsn1Error` #: On encoding errors +#: +#: Examples +#: -------- +#: Encode ASN.1 value object into native Python types +#: +#: .. code-block:: pycon +#: +#: >>> seq = SequenceOf(componentType=Integer()) +#: >>> seq.extend([1, 2, 3]) +#: >>> encode(seq) +#: [1, 2, 3] +#: encode = Encoder(tagMap, typeMap) diff --git a/pyasn1/type/base.py b/pyasn1/type/base.py index a20eff4..45b27e3 100644 --- a/pyasn1/type/base.py +++ b/pyasn1/type/base.py @@ -354,8 +354,8 @@ class AbstractSimpleAsn1Item(Asn1ItemBase): The following arguments to `subtype()` create a ASN.1 subtype out of |ASN.1| type: - Parameters - ---------- + Other 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 @@ -559,8 +559,8 @@ class AbstractConstructedAsn1Item(Asn1ItemBase): The following arguments to `subtype()` create a ASN.1 subtype out of |ASN.1| type. - Parameters - ---------- + Other 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 diff --git a/pyasn1/type/constraint.py b/pyasn1/type/constraint.py index c4f4238..7299ccd 100644 --- a/pyasn1/type/constraint.py +++ b/pyasn1/type/constraint.py @@ -105,8 +105,8 @@ class SingleValueConstraint(AbstractConstraint): \*values: :class:`int` Full set of values permitted by this constraint object. - Example - ------- + Examples + -------- .. code-block:: python class DivisorOfSix(Integer): @@ -148,8 +148,8 @@ class ContainedSubtypeConstraint(AbstractConstraint): Full set of values and constraint objects permitted by this constraint object. - Example - ------- + Examples + -------- .. code-block:: python class DivisorOfEighteen(Integer): @@ -194,8 +194,8 @@ class ValueRangeConstraint(AbstractConstraint): end: :class:`int` Maximum permitted value in the range (inclusive) - Example - ------- + Examples + -------- .. code-block:: python class TeenAgeYears(Integer): @@ -254,8 +254,8 @@ class ValueSizeConstraint(ValueRangeConstraint): maximum: :class:`int` Maximum permitted size of the value (inclusive) - Example - ------- + Examples + -------- .. code-block:: python class BaseballTeamRoster(SetOf): @@ -308,8 +308,8 @@ class PermittedAlphabetConstraint(SingleValueConstraint): \*alphabet: :class:`str` Full set of characters permitted by this constraint object. - Example - ------- + Examples + -------- .. code-block:: python class BooleanValue(IA5String): @@ -378,8 +378,8 @@ class ConstraintsExclusion(AbstractConstraint): constraint: Constraint or logic operator object. - Example - ------- + Examples + -------- .. code-block:: python class Lipogramme(IA5STRING): @@ -465,8 +465,8 @@ class ConstraintsIntersection(AbstractConstraintSet): \*constraints: Constraint or logic operator objects. - Example - ------- + Examples + -------- .. code-block:: python class CapitalAndSmall(IA5String): @@ -509,8 +509,8 @@ class ConstraintsUnion(AbstractConstraintSet): \*constraints: Constraint or logic operator objects. - Example - ------- + Examples + -------- .. code-block:: python class CapitalOrSmall(IA5String): diff --git a/pyasn1/type/namedtype.py b/pyasn1/type/namedtype.py index 256ba56..bf650c8 100644 --- a/pyasn1/type/namedtype.py +++ b/pyasn1/type/namedtype.py @@ -116,6 +116,31 @@ class NamedTypes(object): Parameters ---------- *namedTypes: :class:`~pyasn1.type.namedtype.NamedType` + + Examples + -------- + + .. code-block:: python + + class Description(Sequence): + ''' + ASN.1 specification: + + Description ::= SEQUENCE { + surname IA5String, + first-name IA5String OPTIONAL, + age INTEGER DEFAULT 40 + } + ''' + componentType = NamedTypes( + NamedType('surname', IA5String()), + OptionalNamedType('first-name', IA5String()), + DefaultedNamedType('age', Integer(40)) + ) + + descr = Description() + descr['surname'] = 'Smith' + descr['first-name'] = 'John' """ def __init__(self, *namedTypes, **kwargs): self.__namedTypes = namedTypes @@ -466,7 +491,6 @@ class NamedTypes(object): Example ------- - .. code-block:: python OuterType ::= CHOICE { @@ -491,7 +515,6 @@ class NamedTypes(object): Example ------- - .. code-block:: python OuterType ::= CHOICE { diff --git a/pyasn1/type/opentype.py b/pyasn1/type/opentype.py index 2f692d5..ae27ffe 100644 --- a/pyasn1/type/opentype.py +++ b/pyasn1/type/opentype.py @@ -22,13 +22,12 @@ class OpenType(object): name: :py:class:`str` Field name - typeMap: :py:class:`dict`: + typeMap: :py:class:`dict` A map of value->ASN.1 type. It's stored by reference and can be mutated later to register new mappings. Examples -------- - .. code-block:: python openType = OpenType( diff --git a/pyasn1/type/tag.py b/pyasn1/type/tag.py index 6c0e2c1..44d6c4e 100644 --- a/pyasn1/type/tag.py +++ b/pyasn1/type/tag.py @@ -168,6 +168,23 @@ class TagSet(object): *superTags: :class:`~pyasn1.type.tag.Tag` Additional *Tag* objects taking part in subtyping. + + Examples + -------- + .. code-block:: python + + class OrderNumber(NumericString): + ''' + ASN.1 specification + + Order-number ::= + [APPLICATION 5] IMPLICIT NumericString + ''' + tagSet = NumericString.tagSet.tagImplicitly( + Tag(tagClassApplication, tagFormatSimple, 5) + ) + + orderNumber = OrderNumber('1234') """ def __init__(self, baseTag=(), *superTags): self.__baseTag = baseTag diff --git a/pyasn1/type/univ.py b/pyasn1/type/univ.py index 9d16b05..1ff079b 100644 --- a/pyasn1/type/univ.py +++ b/pyasn1/type/univ.py @@ -45,6 +45,28 @@ class Integer(base.AbstractSimpleAsn1Item): ------ :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + + Examples + -------- + + .. code-block:: python + + class ErrorCode(Integer): + ''' + ASN.1 specification: + + ErrorCode ::= + INTEGER { disk-full(1), no-disk(-1), + disk-not-formatted(2) } + + error ErrorCode ::= disk-full + ''' + namedValues = NamedValues( + ('disk-full', 1), ('no-disk', -1), + ('disk-not-formatted', 2) + ) + + error = ErrorCode('disk-full') """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) @@ -251,8 +273,45 @@ class Integer(base.AbstractSimpleAsn1Item): class Boolean(Integer): - __doc__ = Integer.__doc__ + """Create |ASN.1| type or object. + + |ASN.1| objects are immutable and duck-type Python :class:`int` objects. + + Keyword Args + ------------ + value: :class:`int`, :class:`str` or |ASN.1| object + Python integer or boolean or string literal 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) + + namedValues: :py:class:`~pyasn1.type.namedval.NamedValues` + Object representing non-default symbolic aliases for numbers + + Raises + ------ + :py:class:`~pyasn1.error.PyAsn1Error` + On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class RoundResult(Boolean): + ''' + ASN.1 specification: + RoundResult ::= BOOLEAN + + ok RoundResult ::= TRUE + ko RoundResult ::= FALSE + ''' + ok = RoundResult(True) + ko = RoundResult(False) + """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) #: associated with |ASN.1| type. @@ -326,6 +385,32 @@ class BitString(base.AbstractSimpleAsn1Item): ------ :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class Rights(BitString): + ''' + ASN.1 specification: + + Rights ::= BIT STRING { user-read(0), user-write(1), + group-read(2), group-write(3), + other-read(4), other-write(5) } + + group1 Rights ::= { group-read, group-write } + group2 Rights ::= '0011'B + group3 Rights ::= '3'H + ''' + namedValues = NamedValues( + ('user-read', 0), ('user-write', 1), + ('group-read', 2), ('group-write', 3), + ('other-read', 4), ('other-write', 5) + ) + + group1 = Rights(('group-read', 'group-write')) + group2 = Rights('0011') + group3 = Rights(0x3) """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) @@ -671,6 +756,22 @@ class OctetString(base.AbstractSimpleAsn1Item): ------ :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class Icon(OctetString): + ''' + ASN.1 specification: + + Icon ::= OCTET STRING + + icon1 Icon ::= '001100010011001000110011'B + icon2 Icon ::= '313233'H + ''' + icon1 = Icon.fromBinaryString('001100010011001000110011') + icon2 = Icon.fromHexString('313233') """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) @@ -940,6 +1041,18 @@ class Null(OctetString): ------ :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class Ack(Null): + ''' + ASN.1 specification: + + Ack ::= NULL + ''' + ack = Ack('') """ #: Set (on class, not on instance) or return a @@ -987,6 +1100,22 @@ class ObjectIdentifier(base.AbstractSimpleAsn1Item): ------ :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class ID(ObjectIdentifier): + ''' + ASN.1 specification: + + ID ::= OBJECT IDENTIFIER + + id-edims ID ::= { joint-iso-itu-t mhs-motif(6) edims(7) } + id-bp ID ::= { id-edims 11 } + ''' + id_edims = ID('2.6.7') + id_bp = id_edims + (11,) """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) @@ -1114,6 +1243,20 @@ class Real(base.AbstractSimpleAsn1Item): :py:class:`~pyasn1.error.PyAsn1Error` On constraint violation or bad initializer. + Examples + -------- + .. code-block:: python + + class Pi(Real): + ''' + ASN.1 specification: + + Pi ::= REAL + + pi Pi ::= { mantissa 314159, base 10, exponent -5 } + + ''' + pi = Pi((314159, 10, -5)) """ binEncBase = None # binEncBase = 16 is recommended for large numbers @@ -1373,8 +1516,50 @@ class Real(base.AbstractSimpleAsn1Item): class Enumerated(Integer): - __doc__ = Integer.__doc__ + """Create |ASN.1| type or object. + + |ASN.1| objects are immutable and duck-type Python :class:`int` objects. + + Keyword Args + ------------ + value: :class:`int`, :class:`str` or |ASN.1| object + Python integer or string literal 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) + + namedValues: :py:class:`~pyasn1.type.namedval.NamedValues` + Object representing non-default symbolic aliases for numbers + + Raises + ------ + :py:class:`~pyasn1.error.PyAsn1Error` + On constraint violation or bad initializer. + Examples + -------- + + .. code-block:: python + + class RadioButton(Enumerated): + ''' + ASN.1 specification: + + RadioButton ::= ENUMERATED { button1(0), button2(1), + button3(2) } + + selected-by-default RadioButton ::= button1 + ''' + namedValues = NamedValues( + ('button1', 0), ('button2', 1), + ('button3', 2) + ) + + selected_by_default = RadioButton('button1') + """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) #: associated with |ASN.1| type. @@ -1415,8 +1600,23 @@ class SequenceOfAndSetOfBase(base.AbstractConstructedAsn1Item): sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection` Object representing collection size constraint - """ + Examples + -------- + + .. code-block:: python + + class LotteryDraw(SequenceOf): # SetOf is similar + ''' + ASN.1 specification: + + LotteryDraw ::= SEQUENCE OF INTEGER + ''' + componentType = Integer() + + lotteryDraw = LotteryDraw() + lotteryDraw.extend([123, 456, 789]) + """ def __init__(self, *args, **kwargs): # support positional params for backward compatibility if args: @@ -1768,6 +1968,31 @@ class SequenceAndSetBase(base.AbstractConstructedAsn1Item): sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection` Object representing collection size constraint + + Examples + -------- + + .. code-block:: python + + class Description(Sequence): # Set is similar + ''' + ASN.1 specification: + + Description ::= SEQUENCE { + surname IA5String, + first-name IA5String OPTIONAL, + age INTEGER DEFAULT 40 + } + ''' + componentType = NamedTypes( + NamedType('surname', IA5String()), + OptionalNamedType('first-name', IA5String()), + DefaultedNamedType('age', Integer(40)) + ) + + descr = Description() + descr['surname'] = 'Smith' + descr['first-name'] = 'John' """ #: Default :py:class:`~pyasn1.type.namedtype.NamedTypes` #: object representing named ASN.1 types allowed within |ASN.1| type @@ -2390,8 +2615,50 @@ class Set(SequenceAndSetBase): class Choice(Set): - __doc__ = Set.__doc__ + """Create |ASN.1| type. + + |ASN.1| objects are mutable and duck-type Python :class:`dict` objects. + Keyword Args + ------------ + componentType: :py:class:`~pyasn1.type.namedtype.NamedType` + Object holding named ASN.1 types allowed within this collection + + 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) + + sizeSpec: :py:class:`~pyasn1.type.constraint.ConstraintsIntersection` + Object representing collection size constraint + + Examples + -------- + + .. code-block:: python + + class Afters(Choice): + ''' + ASN.1 specification: + + Afters ::= CHOICE { + cheese [0] IA5String, + dessert [1] IA5String + } + ''' + componentType = NamedTypes( + NamedType('cheese', IA5String().subtype( + implicitTag=Tag(tagClassContext, tagFormatSimple, 0) + ), + NamedType('dessert', IA5String().subtype( + implicitTag=Tag(tagClassContext, tagFormatSimple, 1) + ) + ) + + afters = Afters() + afters['cheese'] = 'Mascarpone' + """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) #: associated with |ASN.1| type. @@ -2649,8 +2916,67 @@ class Choice(Set): class Any(OctetString): - __doc__ = OctetString.__doc__ + """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. + + Keyword Args + ------------ + value: :class:`str`, :class:`bytes` or |ASN.1| object + string (Python 2) or bytes (Python 3), alternatively unicode object + (Python 2) or string (Python 3) representing character string to be + serialized into octets (note `encoding` parameter) or |ASN.1| object. + + 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 :class:`unicode` (Python 2) or + :class:`str` (Python 3) the payload when |ASN.1| object is used + in text string context. + + 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'. + Raises + ------ + :py:class:`~pyasn1.error.PyAsn1Error` + On constraint violation or bad initializer. + + Examples + -------- + .. code-block:: python + + class Error(Sequence): + ''' + ASN.1 specification: + + Error ::= SEQUENCE { + code INTEGER, + parameter ANY DEFINED BY code -- Either INTEGER or REAL + } + ''' + componentType=NamedTypes( + NamedType('code', Integer()), + NamedType('parameter', Any(), + openType=OpenType('code', {1: Integer(), + 2: Real()})) + ) + + error = Error() + error['code'] = 1 + error['parameter'] = Integer(1234) + """ #: Set (on class, not on instance) or return a #: :py:class:`~pyasn1.type.tag.TagSet` object representing ASN.1 tag(s) #: associated with |ASN.1| type. -- cgit v1.2.3