API Reference

gnarl

Lightweight Annotated Schema Serializable Objects.

class gnarl.And(*args, error=None)

class gnarl.Enum(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Provides support for enumeration values as Gnarl schema objects.

The Enum class augments the standard enum.Enum, providing support to use it as a schema type:

class Tristate(gnarl.Enum):
    TRUE      = "#t"
    FALSE     = "#f"
    UNDEFINED = "#nil"

class Checkbox(gnarl.Schemed):
    __schema__ = { "state": Tristate, "label": str }

class gnarl.GnarlJSONEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

JSON encoder that can encode arbitrary types.

To make any type (class) serializable, it is enough that it provides a jsonable attribute which returns a primitive value that the JSON encoder from the Python standard library (json.JSONEncoder) can understand.

For example, the following defins a Timestamp class that wraps a datetime.datetime object to make it serializable:

class Timestamp(object):
    def __init__(self, dt):
        self.datetime = dt

    @property
    def jsonable(self):
        # Return a 'str'value
        return self.datetime.isoformat()

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

class gnarl.JSONable

Mix-in class which adds methods to serialize to/from JSON.

classmethod from_hipack(data, encoding=None)

Deserializes an object from HiPack and validates it.

Loads data from a HiPack string, decoding it with hipack.loads(), and the resulting value is passed to a .validate() class method. That method is responsible of validating the input date, and optionally returning an object which represents the deserialized data.

classmethod from_json(data, encoding=None)

Deserializes an object from JSON and validates it.

Loads data from a JSON string, decoding it with the json.loads() function from the Python standard library, and the resulting value is passed to a .validate() class method. This method is responsible to validate the input data, and optionally return an object which represents the deserialized data.

to_hipack(indent=False)

Serializes an object to HiPack.

The indent argument is passed to hipack.dumps().

to_json(*arg, **kw)

Serializes an object to JSON using GnarlJSONEncoder.

Positional and keyword arguments are passed down to the json.dump() function from the Python standard library.

class gnarl.Optional(schema, default=<object object>)

Marks an element in a dictionary schema as optional.

For example, the following creates a schema which validates a dictionary, where the name key is optional, and the ``

Schema({
    "login": str,
    "name": Optional(str),
    "age": Optional(int, default=0),
})

class gnarl.Or(*args, error=None)

exception gnarl.SchemaError

Error occured during schema validation.

property message

Error message.

class gnarl.Schemed(*arg, **kw)

class gnarl.StringMatch(pattern, error=None, *arg, **kw)

class gnarl.Timestamp(datetime=None, timezone=None)

class gnarl.UUID(hex=None, bytes=None, bytes_le=None, fields=None, int=None, version=None, *, is_safe=SafeUUID.unknown)

class gnarl.Use(func, error=None)