dacite

by konradhalas

konradhalas / dacite

Simple creation of data classes from dictionaries.

565 Stars 41 Forks Last release: Not found MIT License 142 Commits 35 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

dacite

Build Status Coverage Status License Version Python versions Code style: black

This module simplifies creation of data classes (PEP 557) from dictionaries.

Installation

To install dacite, simply use

pip
:
$ pip install dacite

Requirements

Minimum Python version supported by

dacite
is 3.6.

Quick start

from dataclasses import dataclass
from dacite import from_dict


@dataclass class User: name: str age: int is_active: bool

data = { 'name': 'John', 'age': 30, 'is_active': True, }

user = from_dict(data_class=User, data=data)

assert user == User(name='John', age=30, is_active=True)

Features

Dacite supports following features:

  • nested structures
  • (basic) types checking
  • optional fields (i.e.
    typing.Optional
    )
  • unions
  • forward references
  • collections
  • custom type hooks

Motivation

Passing plain dictionaries as a data container between your functions or methods isn't a good practice. Of course you can always create your custom class instead, but this solution is an overkill if you only want to merge a few fields within a single object.

Fortunately Python has a good solution to this problem - data classes. Thanks to

@dataclass
decorator you can easily create a new custom type with a list of given fields in a declarative manner. Data classes support type hints by design.

However, even if you are using data classes, you have to create their instances somehow. In many such cases, your input is a dictionary - it can be a payload from a HTTP request or a raw data from a database. If you want to convert those dictionaries into data classes,

dacite
is your best friend.

This library was originally created to simplify creation of type hinted data transfer objects (DTO) which can cross the boundaries in the application architecture.

It's important to mention that

dacite
is not a data validation library. There are dozens of awesome data validation projects and it doesn't make sense to duplicate this functionality within
dacite
. If you want to validate your data first, you should combine
dacite
with one of data validation library.

Please check Use Case section for a real-life example.

Usage

Dacite is based on a single function -

dacite.from_dict
. This function takes 3 parameters:
  • data_class
    - data class type
  • data
    - dictionary of input data
  • config
    (optional) - configuration of the creation process, instance of
    dacite.Config
    class

Configuration is a (data) class with following fields:

  • type_hooks
  • cast
  • forward_references
  • check_types
  • strict
  • strict_unions_match

The examples below show all features of

from_dict
function and usage of all
Config
parameters.

Nested structures

You can pass a data with nested dictionaries and it will create a proper result.

@dataclass
class A:
    x: str
    y: int


@dataclass class B: a: A

data = { 'a': { 'x': 'test', 'y': 1, } }

result = from_dict(data_class=B, data=data)

assert result == B(a=A(x='test', y=1))

Optional fields

Whenever your data class has a

Optional
field and you will not provide input data for this field, it will take the
None
value.
from typing import Optional

@dataclass class A: x: str y: Optional[int]

data = { 'x': 'test', }

result = from_dict(data_class=A, data=data)

assert result == A(x='test', y=None)

Unions

If your field can accept multiple types, you should use

Union
. Dacite will try to match data with provided types one by one. If none will match, it will raise
UnionMatchError
exception.
from typing import Union

@dataclass class A: x: str

@dataclass class B: y: int

@dataclass class C: u: Union[A, B]

data = { 'u': { 'y': 1, }, }

result = from_dict(data_class=C, data=data)

assert result == C(u=B(y=1))

Collections

Dacite supports fields defined as collections. It works for both - basic types and data classes.

@dataclass
class A:
    x: str
    y: int


@dataclass class B: a_list: List[A]

data = { 'a_list': [ { 'x': 'test1', 'y': 1, }, { 'x': 'test2', 'y': 2, } ], }

result = from_dict(data_class=B, data=data)

assert result == B(a_list=[A(x='test1', y=1), A(x='test2', y=2)])

Type hooks

You can use

Config.type_hooks
argument if you want to transform the input data of a data class field with given type into the new value. You have to pass a following mapping:
{Type: callable}
, where
callable
is a
Callable[[Any], Any]
.
@dataclass
class A:
    x: str


data = { 'x': 'TEST', }

result = from_dict(data_class=A, data=data, config=Config(type_hooks={str: str.lower}))

assert result == A(x='test')

If a data class field type is a

Optional[T]
you can pass both -
Optional[T]
or just
T
- as a key in
type_hooks
. The same with generic collections, e.g. when a field has type
List[T]
you can use
List[T]
to transform whole collection or
T
to transform each item.

Casting

It's a very common case that you want to create an instance of a field type from the input data with just calling your type with the input value. Of course you can use

type_hooks={T: T}
to achieve this goal but
cast=[T]
is an easier and more expressive way. It also works with base classes - if
T
is a base class of type
S
, all fields of type
S
will be also "casted".
from enum import Enum

class E(Enum): X = 'x' Y = 'y' Z = 'z'

@dataclass class A: e: E

data = { 'e': 'x', }

result = from_dict(data_class=A, data=data, config=Config(cast=[E]))

or

result = from_dict(data_class=A, data=data, config=Config(cast=[Enum]))

assert result == A(e=E.X)

Forward References

Definition of forward references can be passed as a

{'name': Type}
mapping to
Config.forward_references
. This dict is passed to
typing.get_type_hints()
as the
globalns
param when evaluating each field's type.
@dataclass
class X:
    y: "Y"

@dataclass class Y: s: str

data = from_dict(X, {"y": {"s": "text"}}, Config(forward_references={"Y": Y})) assert data == X(Y("text"))

Types checking

There are rare cases when

dacite
built-in type checker can not validate your types (e.g. custom generic class) or you have such functionality covered by other library and you don't want to validate your types twice. In such case you can disable type checking with
Config(check_types=False)
. By default types checking is enabled.
T = TypeVar('T')


class X(Generic[T]): pass

@dataclass class A: x: X[str]

x = Xstr

assert from_dict(A, {'x': x}, config=Config(check_types=False)) == A(x=x)

Strict mode

By default

from_dict
ignores additional keys (not matching data class field) in the input data. If you want change this behaviour set
Config.strict
to
True
. In case of unexpected key
from_dict
will raise
UnexpectedDataError
exception.

Strict unions match

Union
allows to define multiple possible types for a given field. By default
dacite
is trying to find the first matching type for a provided data and it returns instance of this type. It means that it's possible that there are other matching types further on the
Union
types list. With
strict_unions_match
only a single match is allowed, otherwise
dacite
raises
StrictUnionMatchError
.

Exceptions

Whenever something goes wrong,

from_dict
will raise adequate exception. There are a few of them:
  • WrongTypeError
    - raised when a type of a input value does not match with a type of a data class field
  • MissingValueError
    - raised when you don't provide a value for a required field
  • UnionMatchError
    - raised when provided data does not match any type of
    Union
  • ForwardReferenceError
    - raised when undefined forward reference encountered in dataclass
  • UnexpectedDataError
    - raised when
    strict
    mode is enabled and the input data has not matching keys
  • StrictUnionMatchError
    - raised when
    strict_unions_match
    mode is enabled and the input data has ambiguous
    Union
    match

Development

First of all - if you want to submit your pull request, thank you very much! I really appreciate your support.

Please remember that every new feature, bug fix or improvement should be tested. 100% code coverage is a must have.

We are using a few static code analysis tools to increase the code quality (

black
,
mypy
,
pylint
). Please make sure that you are not generating any errors/warnings before you submit your PR. You can find current configuration in
.travis.yml
file.

Last but not least, if you want to introduce new feature, please discuss it first within an issue.

How to start

Clone

dacite
repository:
$ git clone [email protected]:konradhalas/dacite.git

Create and activate virtualenv in the way you like:

$ python3 -m venv dacite-env
$ source dacite-env/bin/activate

Install all

dacite
dependencies:
$ pip install -e .[dev]

To run tests you just have to fire:

$ pytest

Use case

There are many cases when we receive "raw" data (Python dicts) as a input to our system. HTTP request payload is a very common use case. In most web frameworks we receive request data as a simple dictionary. Instead of passing this dict down to your "business" code, it's a good idea to create something more "robust".

Following example is a simple

flask
app - it has single
/products
endpoint. You can use this endpoint to "create" product in your system. Our core
create_product
function expects data class as a parameter. Thanks to
dacite
we can easily build such data class from
POST
request payload.
from dataclasses import dataclass
from typing import List

from flask import Flask, request, Response

import dacite

app = Flask(name)

@dataclass class ProductVariantData: code: str description: str = '' stock: int = 0

@dataclass class ProductData: name: str price: float variants: List[ProductVariantData]

def create_product(product_data: ProductData) -> None: pass # your business logic here

@app.route("/products", methods=['POST']) def products(): product_data = dacite.from_dict( data_class=ProductData, data=request.get_json(), ) create_product(product_data=product_data) return Response(status=201)

What if we want to validate our data (e.g. check if

code
has 6 characters)? Such features are out of scope of
dacite
but we can easily combine it with one of data validation library. Let's try with marshmallow.

First of all we have to define our data validation schemas:

from marshmallow import Schema, fields, ValidationError


def validate_code(code): if len(code) != 6: raise ValidationError('Code must have 6 characters.')

class ProductVariantDataSchema(Schema): code = fields.Str(required=True, validate=validate_code) description = fields.Str(required=False) stock = fields.Int(required=False)

class ProductDataSchema(Schema): name = fields.Str(required=True) price = fields.Decimal(required=True) variants = fields.Nested(ProductVariantDataSchema(many=True))

And use them within our endpoint:

@app.route("/products", methods=['POST'])
def products():
    schema = ProductDataSchema()
    result, errors = schema.load(request.get_json())
    if errors:
        return Response(
            response=json.dumps(errors), 
            status=400, 
            mimetype='application/json',
        )
    product_data = dacite.from_dict(
        data_class=ProductData,
        data=result,
    )
    create_product(product_data=product_data)
    return Response(status=201)

Still

dacite
helps us to create data class from "raw" dict with validated data.

Changelog

Follow

dacite
updates in CHANGELOG.

Authors

Created by Konrad Hałas.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.