JSON utilities¶
JSON (de)serialization framework.
The framework presented here is somewhat based on Go’s “json” package
(especially the omitempty
functionality).
-
class
acme.jose.json_util.
Field
(json_name, default=None, omitempty=False, decoder=None, encoder=None)[source]¶ Bases:
object
JSON object field.
Field
is meant to be used together withJSONObjectWithFields
.encoder
(decoder
) is a callable that accepts a single parameter, i.e. a value to be encoded (decoded), and returns the serialized (deserialized) value. In case of errors it should raiseSerializationError
(DeserializationError
).Note, that
decoder
should perform partial serialization only.Variables: - json_name (str) – Name of the field when encoded to JSON.
- default – Default value (used when not present in JSON object).
- omitempty (bool) – If
True
and the field value is empty, then it will not be included in the serialized JSON object, anddefault
will be used for deserialization. Otherwise, ifFalse
, field is considered as required, value will always be included in the serialized JSON objected, and it must also be present when deserializing.
-
classmethod
_empty
(value)[source]¶ Is the provided value cosidered “empty” for this field?
This is useful for subclasses that might want to override the definition of being empty, e.g. for some more exotic data types.
-
classmethod
default_decoder
(value)[source]¶ Default decoder.
Recursively deserialize into immutable types (
acme.jose.util.frozendict
instead ofdict()
,tuple()
instead oflist()
).
-
class
acme.jose.json_util.
JSONObjectWithFieldsMeta
[source]¶ Bases:
abc.ABCMeta
Metaclass for
JSONObjectWithFields
and its subclasses.It makes sure that, for any class
cls
with__metaclass__
set toJSONObjectWithFieldsMeta
:- All fields (attributes of type
Field
) in the class definition are moved to thecls._fields
dictionary, where keys are field attribute names and values are fields themselves. cls.__slots__
is extended by all field attribute names (i.e. notField.json_name
). Originalcls.__slots__
are stored incls._orig_slots
.
In a consequence, for a field attribute name
some_field
,cls.some_field
will be a slot descriptor and not an instance ofField
. For example:some_field = Field('someField', default=()) class Foo(object): __metaclass__ = JSONObjectWithFieldsMeta __slots__ = ('baz',) some_field = some_field assert Foo.__slots__ == ('some_field', 'baz') assert Foo._orig_slots == () assert Foo.some_field is not Field assert Foo._fields.keys() == ['some_field'] assert Foo._fields['some_field'] is some_field
As an implementation note, this metaclass inherits from
abc.ABCMeta
(and not the usualtype
) to mitigate the metaclass conflict (ImmutableMap
andJSONDeSerializable
, parents ofJSONObjectWithFields
, useabc.ABCMeta
as its metaclass).- All fields (attributes of type
-
class
acme.jose.json_util.
JSONObjectWithFields
(**kwargs)[source]¶ Bases:
acme.jose.util.ImmutableMap
,acme.jose.interfaces.JSONDeSerializable
JSON object with fields.
Example:
class Foo(JSONObjectWithFields): bar = Field('Bar') empty = Field('Empty', omitempty=True) @bar.encoder def bar(value): return value + 'bar' @bar.decoder def bar(value): if not value.endswith('bar'): raise errors.DeserializationError('No bar suffix!') return value[:-3] assert Foo(bar='baz').to_partial_json() == {'Bar': 'bazbar'} assert Foo.from_json({'Bar': 'bazbar'}) == Foo(bar='baz') assert (Foo.from_json({'Bar': 'bazbar', 'Empty': '!'}) == Foo(bar='baz', empty='!')) assert Foo(bar='baz').bar == 'baz'
-
acme.jose.json_util.
encode_b64jose
(data)[source]¶ Encode JOSE Base-64 field.
Parameters: data (bytes) – Return type: unicode
-
acme.jose.json_util.
decode_b64jose
(data, size=None, minimum=False)[source]¶ Decode JOSE Base-64 field.
Parameters: - data (unicode) –
- size (int) – Required length (after decoding).
- minimum (bool) – If
True
, thensize
will be treated as minimum required length, as opposed to exact equality.
Return type: bytes
-
acme.jose.json_util.
encode_hex16
(value)[source]¶ Hexlify.
Parameters: value (bytes) – Return type: unicode
-
acme.jose.json_util.
decode_hex16
(value, size=None, minimum=False)[source]¶ Decode hexlified field.
Parameters: - value (unicode) –
- size (int) – Required length (after decoding).
- minimum (bool) – If
True
, thensize
will be treated as minimum required length, as opposed to exact equality.
Return type: bytes
-
acme.jose.json_util.
encode_cert
(cert)[source]¶ Encode certificate as JOSE Base-64 DER.
Return type: unicode
-
acme.jose.json_util.
decode_cert
(b64der)[source]¶ Decode JOSE Base-64 DER-encoded certificate.
Parameters: b64der (unicode) – Return type: OpenSSL.crypto.X509
wrapped inComparableX509
-
acme.jose.json_util.
decode_csr
(b64der)[source]¶ Decode JOSE Base-64 DER-encoded CSR.
Parameters: b64der (unicode) – Return type: OpenSSL.crypto.X509Req
wrapped inComparableX509
-
class
acme.jose.json_util.
TypedJSONObjectWithFields
(**kwargs)[source]¶ Bases:
acme.jose.json_util.JSONObjectWithFields
JSON object with type.
-
typ
= NotImplemented¶ Type of the object. Subclasses must override.
-
type_field_name
= 'type'¶ Field name used to distinguish different object types.
Subclasses will probably have to override this.
-
TYPES
= NotImplemented¶ Types registered for JSON deserialization
-