Skip to main content

Dictionary deserializer is a package that aides in the deserializing of JSON (or other structures) that are converted to dicts, into composite classes.

Project description

Dictionary deserializer

ReadTheDocs GitHub issues GitHub pull requests PyPI PyPI - Downloads GitHub

Dictionary deserializer is a project built to convert dictionaries into composite classes in an intuitive way. Special attention was also paid to being friendly to static type-checkers and IDE autocompletes.

It is expected that this library is used together with a JSON-to-dict deserializer like json.loads.


In order to use it, simply add the dependency dictionary-deserializer to your requirements file:


pipenv install dictionary-deserializer


pip install dictionary-deserializer
pip freeze > requirements.txt


This project was originally meant as a proof of concept, to be used to find other projects that would be able to replace this, with the required feature set. That project was not found, and therefore, this project was expanded.


  • Use type hints for type validation
  • Allow polymorphism
    • Through typing.Unions
    • Through subclassing
  • Support a large part of the typing module's types
  • Allow validations on values
  • Be able to validate and deserialize any compliant JSON structure
  • Be compatible with static type checkers and IDE hinting
  • Have a small impact on existing code starting to use this library


None of this code is actually useful if you don't understand how to use it. It is very simple. Here are some examples:

Specifying a structure

from typing import Optional

from dict_deserializer.deserializer import Deserializable

class User(Deserializable):
    email: str                  # Type must be a string
    username: str               # Type must be a string
    password: Optional[str]     # Type must either be a string or a None


from dict_deserializer.deserializer import deserialize, Rule

# Successful
deserialize(Rule(User), {
    'email': '',
    'username': 'rkleef',

# Fails because optional type is wrong
deserialize(Rule(User), {
    'email': '',
    'username': 'rkleef',
    'password': 9.78,

Polymorphic structures

from typing import Optional, Any, List

from dict_deserializer.deserializer import Deserializable
from dict_deserializer.annotations import abstract

class DirectoryObject(Deserializable):
    name: str
    meta: Any

class User(DirectoryObject):
    full_name: str
    first_name: Optional[str]

class Group(DirectoryObject):
    members: List[DirectoryObject]

If you deserialize into Rule(DirectoryObject), the matching class will automatically be selected. If none of the subclasses match, an error is thrown since the DirectoryObject is declared abstract.

If you want to discriminate not by field names or types, but by their values, one can choose to define a @discriminator annotation.

Value validations

The syntax for validating the value of a key is currently a bit weird. It is incompatible with existing syntax for defaults, but the type syntax is the same.


from typing import Optional

from dict_deserializer.deserializer import Deserializable
from dict_deserializer.annotations import validated

class Test(Deserializable):
    name: Optional[str]

    def name(self, value):
        if len(value) > 20:
            raise TypeError('Name may not be longer than 20 characters.')


This library uses the typing module extensively. It does, however, only support some of its types. This is a list of verified composite types:

  • Union (Including Optional)
  • Dict
  • List
  • Tuple
  • Any
  • dict_deserializer.deserializer.Deserializable
  • dict
  • list

It supports these types as terminal types:

  • int
  • float
  • str
  • NoneType
  • bool

Planned features

  • NamedTuples
    • The anonymous namedtuple and the class-namedtuples with (optionally) type annotations.
  • Dataclasses
  • A way to allow deserializing into a class not extending Deserializable
  • Enums
  • Sets
    • From lists

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Dictionary deserializer-0.0.6.tar.gz (7.5 kB view hashes)

Uploaded Source

Built Distribution

Dictionary_deserializer-0.0.6-py3-none-any.whl (9.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page