Metadata-Version: 1.2
Name: dacite
Version: 0.0.9
Summary: Simple creation of data classes from dictionaries.
Home-page: https://github.com/konradhalas/dacite
Author: Konrad Hałas
Author-email: halas.konrad@gmail.com
License: MIT
Description-Content-Type: UNKNOWN
Description: dacite
        ======
        
        |Build Status| |License| |Version| |Python versions|
        
        This module simplify creation of data classes (`PEP
        557 <https://www.python.org/dev/peps/pep-0557/>`__) from dictionaries.
        
        Installation
        ------------
        
        To install dacite, simply use ``pip`` (or ``pipenv``):
        
        ::
        
            $ pip install dacite
        
        Requirements
        ------------
        
        Minimum Python version supported by ``dacite`` is 3.6.
        
        Data classes will be available in Python 3.7 as a part of the standard
        library, but you can use ``dataclasses`` module now - it's available as
        an external package from PyPI. It will be installed automatically as a
        ``dacite`` dependence.
        
        Quick start
        -----------
        
        .. code:: python
        
            from dataclasses import dataclass
            from dacite import make
        
        
            @dataclass
            class User:
                name: str
                age: int
                is_active: bool
        
        
            data = {
                'name': 'john',
                'age': 30,
                'is_active': True,
            }
        
            user = make(data_class=User, data=data)
        
            assert user == User(name='john', age=30, is_active=True)
        
        Features
        --------
        
        Dacite supports following features:
        
        -  nested structures
        -  types checking
        -  optional fields (i.e. ``typing.Optional``)
        -  values casting and transformation
        -  remapping of fields names
        
        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. 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.
        
        Usage
        -----
        
        Dacite is based on a single function - ``dacite.make``. 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:
        
        -  ``rename``
        -  ``flattened``
        -  ``prefixed``
        -  ``cast``
        -  ``transform``
        
        The examples below show all features of ``make`` function and usage of
        all ``Config`` parameters.
        
        Nested structures
        ~~~~~~~~~~~~~~~~~
        
        You can pass a data with nested dictionaries and it will create a proper
        result.
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
                y: int
        
        
            @dataclass
            class B:
                a: A
        
        
            data = {
                'a': {
                    'x': 'test',
                    'y': 1,
                }
            }
        
            result = make(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.
        
        .. code:: python
        
            from typing import Optional
        
            @dataclass
            class A:
                x: str
                y: Optional[int]
        
        
            data = {
                'x': 'test',
            }
        
            result = make(data_class=A, data=data)
        
            assert result == A(x='test', y=None)
        
        Collections
        ~~~~~~~~~~~
        
        Dacite supports fields defined as collection. It works for both - basic
        types and data classes.
        
        .. code:: python
        
            @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 = make(data_class=B, data=data)
        
            assert result == B(a_list=[A(x='test1', y=1), A(x='test2', y=2)])
        
        Multiple inputs
        ~~~~~~~~~~~~~~~
        
        If you have multiple input dicts, you can pass a list of dictionaries
        instead of a single one as a value of ``data`` argument.
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
                y: int
        
        
            data_1 = {
                'x': 'test',
            }
        
            data_2 = {
                'y': 1,
            }
        
            result = make(data_class=A, data=[data_1, data_2])
        
            assert result == A(x='test', y=1)
        
        Rename
        ~~~~~~
        
        If you want to change the name of your input field, you can use
        ``Config.rename`` argument. You have to pass dictionary with a following
        mapping: ``{'data_class_field': 'input_field'}``
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
        
        
            data = {
                'y': 'test',
            }
        
            result = make(data_class=A, data=data, config=Config(rename={'x': 'y'}))
        
            assert result == A(x='test')
        
        Flattened
        ~~~~~~~~~
        
        You often receive a flat structure which you want to convert to
        something more sophisticated. In this case you can use
        ``Config.flattened`` argument. You have to pass list of flattened
        fields.
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
                y: int
        
        
            @dataclass
            class B:
                a: A
                z: float
        
        
            data = {
                'x': 'test',
                'y': 1,
                'z': 2.0,
            }
        
            result = make(data_class=B, data=data, config=Config(flattened=['a']))
        
            assert result == B(a=A(x='test', y=1), z=2.0)
        
        Prefixed
        ~~~~~~~~
        
        Sometimes your data are prefixed instead of nested. To handle this case,
        you have to use ``Config.prefixed`` argument, just pass a following
        mapping: ``{'data_class_field': 'prefix'}``
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
                y: int
        
        
            @dataclass
            class B:
                a: A
                z: float
        
        
            data = {
                'a_x': 'test',
                'a_y': 1,
                'z': 2.0,
            }
        
            result = make(data_class=B, data=data, config=Config(prefixed={'a': 'a_'}))
        
            assert result == B(a=A(x='test', y=1), z=2.0)
        
        Casting
        ~~~~~~~
        
        Input values are not casted by default. If you want to use field type
        information to transform input value from one type to another, you have
        to pass given field name as an element of the ``Config.cast`` argument
        list.
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
        
        
            data = {
                'x': 1,
            }
        
            result = make(data_class=A, data=data, config=Config(cast=['x']))
        
            assert result == A(x='1')
        
        Transformation
        ~~~~~~~~~~~~~~
        
        You can use ``Config.transform`` argument if you want to transform the
        input data into the new value. You have to pass a following mapping:
        ``{'data_class_field': callable}``, where ``callable`` is a
        ``Callable[[Any], Any]``.
        
        .. code:: python
        
            @dataclass
            class A:
                x: str
        
        
            data = {
                'x': 'TEST',
            }
        
            result = make(data_class=A, data=data, config=Config(transform={'x': str.lower}))
        
            assert result == A(x='test')
        
        .. |Build Status| image:: https://travis-ci.org/konradhalas/dacite.svg?branch=master
           :target: https://travis-ci.org/konradhalas/dacite
        .. |License| image:: https://img.shields.io/pypi/l/dacite.svg
           :target: https://pypi.python.org/pypi/dacite/
        .. |Version| image:: https://img.shields.io/pypi/v/dacite.svg
           :target: https://pypi.python.org/pypi/dacite/
        .. |Python versions| image:: https://img.shields.io/pypi/pyversions/dacite.svg
           :target: https://pypi.python.org/pypi/dacite/
        
Keywords: dataclasses
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.6
