Metadata-Version: 1.1
Name: schemalite
Version: 0.2.1
Summary: A minimal, yet powerful schema validation library for python
Home-page: https://github.com/SuryaSankar/schemalite
Author: Surya Sankar
Author-email: suryashankar.m@gmail.com
License: MIT license
Description: ==========
        Schemalite
        ==========
        
        
        .. image:: https://img.shields.io/pypi/v/schemalite.svg
                :target: https://pypi.python.org/pypi/schemalite
        
        .. image:: https://img.shields.io/travis/SuryaSankar/schemalite.svg
                :target: https://travis-ci.org/SuryaSankar/schemalite
        
        .. image:: https://readthedocs.org/projects/schemalite/badge/?version=latest
                :target: https://schemalite.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        
        
        
        A minimal, yet powerful schema validation library for python
        
        
        * Free software: MIT license
        * Documentation: https://schemalite.readthedocs.io.
        
        
        Features
        --------
        
        Because I started writing it before I came across Cerberus, Marshmallow and
        Schema.
        
        While the other schema validation libraries have powerful DSLs, they also have
        too big an API for simple needs. This library has only one concept I need to
        keep in mind - A validator is a function that will return a tuple like (False,
        "Some error message") or (True, None). Thats all.
        
        A schema is a `dict` with 2 keys - "fields" and "validators"
        
        `validators` is a list of validator functions to apply on the input data as a
        whole instead of at field level. It should again be a function which returns a
        tuple as output, while accepting a single dictionary as input ( corresponding to
        the whole input data )
        
        `fields` - is a dict with keys corresponding to the names of the keys of the
        dictionary which is being validated. Each field is in turn a dict, which has one
        or more of the following optional keys
        
        1. `required` - True/False. Alternatively it can also be a function which
           accepts the input dictionary and outputs True/False as output. If not
           specified, field is assumed to be not required.
        
        2. `type` - The type of the data the field is expecting. It can be any valid
           pythonic type - int / str / unicode / date / datetime / Decimal / list / dict
           ( or anything else which is a python `type`). It can also be a list of types
           in which case the data should be of any one of those types.
        
        3. `validators` - A list of validator functions. The function should accept 2
           arguments - The value of the particular key being processed and the whole
           dictionary itself (in case the validator needs access to the whole data
           instead of that field alone to decide whether the value is valid). It has to
           return a tuple. Either (True, None) or (False, "some error message") ( The
           error need not be a string. It can be any valid json serializable data
           structure - a list or dict also)
        
        4. `permitted_values` - A list of permitted values for the field.
        
        5. If `type` is list, you can send the following fields also
        
            i. `list_item_type` - Tells the type of each item in the list. It can also
            be any Python type or a list of types. ii. `list_item_schema` - If
            `list_item_type` is dict, then you can optionally provide `list_item_schema`
            also - to validate each dict in the list against another schema
        
        6. If `type` is dict, then you can send the following field `dict_schema` - The
           schema to validate the dict against.
        
        At both field and schema level, all validators will be applied one after another
        and their errors will be collected together in the output.
        
        To apply the validator, you can call `validate_dict(dictionary, schema)` ( or
        `validate_list_of_dicts(list_of_dicts, dict_schema)`)
        
        The output itself will be tuple of the same format as what we defined above for
        validators.
        
        Example:
        
        Lets define 2 schemas
        
        .. code-block:: python
            
            person_schema = {
                "fields": {
                    "name": {
                        "required": True,
                        "type": (str, unicode)
                    },
                    "gender": {
                        "required": True,
                        "type": (str, unicode),
                        "permitted_values": ("Male", "Female")
                    },
                    "age": {
                        "required": func_and_desc(
                            lambda person: person['gender']=='Female',
                            "Required if gender is female"),
                        "type": int,
                        "validators": [
                            func_and_desc(
                                lambda age, person: (False, "Too old")
                                if age > 40 else (True, None),
                                "Has to be less than 40")
                        ]
                    },
                    "access_levels": {
                        "type": list,
                        "list_item_type": int,
                        "permitted_values_for_list_items": range(1, 10)
                    }
                },
            }
        
            org_schema = {
                "fields": {
                    "name": {
                        "required": True,
                        "type": (str, unicode)
        
                    },
                    "ceo": {
                        "required": True,
                        "type": dict,
                        "dict_schema": person_schema
                    },
                    "members": {
                        "required": True,
                        "type": list,
                        "list_item_type": dict,
                        "list_item_schema": person_schema
                    }
                },
                "validators": [
                    func_and_desc(
                        lambda org: (False, "Non member cannot be CEO")
                        if org["ceo"] not in org["members"] else (True, None),
                        "Non member cannot be CEO")
                ],
                "allow_unknown_fields": True
            }
        
        
        And some data to validate against the schema
        
        .. code-block:: python
            
            isaac = {"gender": "Male", "name": "Isaac", "age": "new", "access_levels": [1,4,60]}
            surya = {"gender": "Male", "name": "Surya", "age": "h", "city": "Chennai"}
            senthil = {"gender": "Male", "name": "Senthil"}
            mrx = {"gender": "m", "name": "x"}
            sharanya = {
                "gender": "Female", "name": "Sharanya",
                "access_levels": [4, 5, 60]}
        
        
        Lets first validate some persons
        
        .. code-block:: python
            
            validate_dict(mrx, person_schema)
        
        
        Output is
        
        .. code-block:: python
            
            (False,
            {
                'FIELD_LEVEL_ERRORS': {
                    'gender': {
                        'PERMITTED_VALUES_ERROR': 'Field data can be one of the following only: Male/Female'
                    }
                }
            })
        
        
        Another person
        
        .. code-block:: python
            
            validate_dict(surya, person_schema)
        
        
        Output
        
        .. code-block:: python
            
            (False,
            {
                'FIELD_LEVEL_ERRORS': {
                    'age': {
                        'HAS_TO_BE_LESS_THAN_40': 'Too old',
                        'TYPE_ERROR': 'Field data should be of type int'
                    }
                },
            'UNKNOWN_FIELDS': ['city']
            })
        
        
        Now validating the same person, but allowing unknown fields
        
        .. code-block:: python
            
            validate_dict(surya, person_schema, allow_unknown_fields=True)
        
        
        Output
        
        .. code-block:: python
            
            (False,
            {
                'FIELD_LEVEL_ERRORS': {
                    'age': {
                        'HAS_TO_BE_LESS_THAN_40': 'Too old',
                        'TYPE_ERROR': 'Field data should be of type int'
                    }
                }
            })
        
        
        Finally lets create an organization and validate it
        
        .. code-block:: python
            
            inkmonk = {
                "name": "Inkmonk",
                "ceo": isaac,
                "members": [surya, senthil, sharanya],
                "city": "Chennai"
            }
            validate_dict(inkmonk, org_schema)
        
        
        Output
        
        .. code-block:: json
            
            (False,
            {
                'FIELD_LEVEL_ERRORS': {
                    'ceo': {
                        'VALIDATION_ERRORS_FOR_OBJECT': {
                            'FIELD_LEVEL_ERRORS': {
                                'access_levels': {
                                    'VALIDATION_ERRORS_FOR_OBJECTS_IN_LIST': [
                                        None,
                                        None,
                                        {
                                            'PERMITTED_VALUES_ERROR': 'Field data can be one of the following only: 1/2/3/4/5/6/7/8/9'
                                        }
                                    ]
                                },
                                'age': {
                                    'HAS_TO_BE_LESS_THAN_40': 'Too old',
                                    'TYPE_ERROR': 'Field data should be of type int'
                                }
                            }
                        }
                    },
                    'members': {
                        'VALIDATION_ERRORS_FOR_OBJECTS_IN_LIST': [
                            {
                                'FIELD_LEVEL_ERRORS': {
                                    'age': {
                                        'HAS_TO_BE_LESS_THAN_40': 'Too old',
                                        'TYPE_ERROR': 'Field data should be of type int'
                                    }
                                },
                                'UNKNOWN_FIELDS': ['city']
                            },
                            None,
                            {
                                'FIELD_LEVEL_ERRORS': {
                                    'access_levels': {
                                        'VALIDATION_ERRORS_FOR_OBJECTS_IN_LIST': [
                                            None,
                                            None,
                                            {
                                                'PERMITTED_VALUES_ERROR': 'Field data can be one of the following only: 1/2/3/4/5/6/7/8/9'
                                            }
                                        ]
                                    },
                                    'age': {
                                        'MISSING_FIELD_ERROR': 'Required if gender is female'
                                    }
                                },
                                'MISSING_FIELDS': ['age']
                            }
                        ]
                    }
                },
            'SCHEMA_LEVEL_ERRORS': ['Non member cannot be CEO'],
            'UNKNOWN_FIELDS': ['city']
            })
        
        
        ###Understanding the errors output
        
        The library is structured to provide an error output to any nested level of
        granularity.
        
        At the outer most level, there are the following keys
        
        "FIELD_LEVEL_ERRORS" - Contains the errors mapped to each field
        
        "SCHEMA_LEVEL_ERRORS" - A list of errors found for the schema as a whole
        
        "UNKNOWN_FIELDS" - If the validation is configured to not allow unknown fields
        and if the data had any, they will be listed here
        
        "MISSING_FIELDS" - List of all missing required fields.
        
        Inside 'FIELD_LEVEL_ERRORS', each field will have a dict of errors mapped to it.
        The keys of the dict are the names of the errors and values are the error
        strings. Example for an error dict for a field would be
        `{'TYPE_ERROR': "This field should have type int only"}` or
        `{"PERMITTED_VALUES_ERROR": "The object should have value high/low only"}`
        
        If a particular field is of type `dict`, and if `dict_schema` is defined, then
        you can also expect to see a key named `VALIDATION_ERRORS_FOR_OBJECT` inside
        `errors['FIELD_LEVEL_ERRORS']['particular_field_name']`. In that case
        `errors['FIELD_LEVEL_ERRORS']['particular_field_name']['VALIDATION_ERRORS_FOR_OBJECT']`
        will contain another errors object obtained by matching the data in this field
        alone against another schema ( So that errors object will in turn have
        FIELD_LEVEL_ERRORS, SCHEMA_LEVEL_ERRORS etc)
        
        If a particular field is of type `list` and if `list_type` is defined, then if
        there are validation errors for the objects in the list, you can expect to see
        `errors['FIELD_LEVEL_ERRORS']['particular_field_name']['VALIDATION_ERRORS_FOR_OBJECTS_IN_LIST']`.
        This will be a list of error objects. If the field is a list of primitive types,
        then you can expect each error object to have fields like `TYPE_ERROR` or
        `PERMITTED_VALUES_ERROR`. If it is a list of objects of another schema ( defined
        by `list_item_schema`), then each item in the errors list would be an error
        object got by validating against that schema - so it will have
        `FIELD_LEVEL_ERRORS`, `SCHEMA_LEVEL_ERRORS` etc. ( While iterating, if one item
        has no error, then instead of error object, it will have a null in the errors
        list at that index.)
        
        Credits
        -------
        
        This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
        
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
        
Keywords: schemalite
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
