============ Simple Model

.. image:: https://badge.fury.io/py/pysimplemodel.svg :target: https://pypi.org/project/pysimplemodel/

.. image:: https://img.shields.io/badge/python-3.6,3.7-blue.svg :target: https://github.com/lamenezes/simple-model

.. image:: https://img.shields.io/github/license/lamenezes/simple-model.svg :target: https://github.com/lamenezes/simple-model/blob/master/LICENSE

.. image:: https://circleci.com/gh/lamenezes/simple-model.svg?style=shield :target: https://circleci.com/gh/lamenezes/simple-model

.. image:: https://codecov.io/gh/lamenezes/simple-model/branch/master/graph/badge.svg :target: https://codecov.io/gh/lamenezes/simple-model

SimpleModel offers a simple way to handle data using classes instead of a plenty of lists and dicts.

It has simple objectives:

• Define models and its fields easily using class attributes, type annotations or tuples (whatever suits your needs)
• Support for field validation, cleaning and type conversion
• Easy model conversion to dict

Quickstart

Installing

Open your favorite shell and run the following command:

.. code:: shell

pip install pysimplemodel

Example

Define your models using type annotations:

.. code:: python

from simple_model import Model


class Person(Model):
    age: int
    height: float
    is_active: bool = True
    name: str

Simple model automatically creates an initializer for your model and you all set to create instances:

.. code:: python

>> person = Person(age=18, height=1.67, name='John Doe')
>> person.name
'John Doe'

As you have noticed we haven't informed a value for field is_active, but the model was still created. That's because we've set a default value of True for it and the model takes care of assigning it automatically to the field:

.. code:: python

>> person.is_active
True

Simple model also offers model validation. Empty fields are considered invalid and will raise errors upon validation. Let's perform some tests using the previous Person model:

.. code:: python

>> person = Person()
>> print(person.name)
None
>> person.validate()
Traceback (most recent call last):
    ...
EmptyField: 'height' field cannot be empty

Let's say we want the height and age fields to be optional, that can be achieved with the following piece of code:

.. code:: python

from simple_model import Model


class Person(Model):
    age: int = None
    height: float = None
    is_active: bool = True
    name: str

Now let's test it:

.. code:: python

>> person = Person(name='Jane Doe', is_active=False)
>> person.is_active
False
>> person.validate()
True

The last line won't raise an exception which means the model instance is valid! In case you need the validation to return True or False instead of raising an exception that's possible by doing the following:

.. code:: python

>> person.validate(raise_exception=False)
True

You can also add custom validations by writing class methods prefixed by validate followed by the attribute name, e.g.

.. code:: python

class Person:
    age: int
    height: float
    name: str

    def validate_age(self, age):
        if age < 0 or age > 150:
            raise ValidationError('Invalid value for age {!r}'.format(age))
        
        return age

    def validate_height(self, height):
        if height <= 0:
           raise ValidationError('Invalid value for height {!r}'.format(age))
        
        return height

Let's test it:

.. code:: python

>> person = Person(name='John Doe', age=190)
>> person.validate()
Traceback (most recent call last):
    ...
ValidationError: Invalid value for age 190
>> other_person = Person(name='Jane Doe', height=-1.67)
>> other_person.validate()
Traceback (most recent call last):
    ...
ValidationError: Invalid value for height -1.67

It is important to note that models don't validate types. Currently types are used for field value conversion.

The validate method also supports cleaning the field values by defining custom transformations in the validate_ methods:

.. code:: python

class Person:
    age: int
    name: str

    def validate_name(self, name):
        return name.strip()

>>> person = Person(age=18.0, name='John Doe ')
>>> person.name
'John Doe '
>> person.age
18.0
>>> person.validate()
>>> person.name
'John Doe'
>>> person.age  # all attributes are converted to its type before cleaning
18  # converted from float (18.0) to int (18)

Finally, simple model allows you to easily convert your model to dict type using the function to_dict():

.. code:: python

>>> to_dict(person)
{
    'age': 18,
    'name': 'John Doe'
}

Documentation

Docs on simple-model.rtfd.io_

.. _simple-model.rtfd.io: https://simple-model.readthedocs.io/en/latest/