Metadata-Version: 2.1
Name: sureberus
Version: 0.5
Summary: Cerberus alternative
Home-page: http://github.com/radix/sureberus/
Author: Christopher Armstrong
License: MIT
Description: # Sureberus
        
        This is an implementation of the [Cerberus](https://github.com/pyeve/cerberus/)
        schema format. It doesn't implement all of the features of that library, and
        where it does implement a feature it doesn't always implement it in the exact
        same way.
        
        The main reason it exists is to support some of the things that Cerberus doesn't
        do.
        
        ## Schema selection based on dict keys
        
        Often times when `anyof` or `oneof` are used, what we really want to do is
        *select* a schema based on dict keys.
        
        There are two options for this, which should be used in preference to `anyof` or
        `oneof`, when possible, as they provide much better error messages.
        
        ### when_key_is
        
        Use this when you have dictionaries that have a fixed key, such as `"type"`,
        which specifies some specific format to use. For example, if you have data that
        can look like this:
        
        ```json
        {"type": "elephant", "trunk_length": 60}
        {"type": "eagle", "wingspan": 50}
        ```
        
        Then you would use `when_key_is`, like this:
        
        ```json
        {
            "type": "dict",
            "when_key_is": {
                "key": "type",
                "choices": {
                    "elephant": {
                        "schema": {"trunk_length": {"type": "integer"}}
                    },
                    "eagle": {
                        "schema": {"wingspan": {"type": "integer"}}
                    },
                }
            }
        }
        ```
        
        ### when_key_exists
        
        Use this when you have dictionaries where you must choose the schema based on
        keys that exist in the data exclusively for their type of data. For example, if
        you have data that can look like this:
        
        ```json
        {"image_url": "foo.jpg", "width": 30}
        {"color": "red"}
        ```
        
        Then you would use `when_key_exists`, like this:
        
        ```json
        {
            "type": "dict",
            "when_key_exists": {
                "image_url": {
                    "schema": {"image_url": {"type": "string"}, "width": {"type": "integer"}}
                },
                "color": {
                    "schema": {"color": {"type": "string"}}
                },
            }
        }
        ```
        
        
        ## normalization inside of *of-rules
        
        The primary important difference is that you can use sureberus if you want to
        use `default` or `coerce` inside of a
        [*of-rule](http://docs.python-cerberus.org/en/stable/validation-rules.html#of-rules).
        
        
        ## In-line schema registries
        
        Small, reusable "chunks" of schema can be defined in-line in the schema
        specification, instead of requiring Python code to be written which sets up
        registries. This allows for easy use of recursive schemas at any point in your
        schema, or just a way to conveniently reuse some subschema in multiple places.
        For example, here is a schema that validates any nested list of strings:
        
        ```json
        {
            "registry": {
                "nested_list": {
                    "type": "list",
                    "schema": {
                        "anyof": [
                            {"type": "string"},
                            "nested_list",
                        ],
                    }
                }
            },
            "type": "dict",
            "schema": {"things": "nested_list"},
        }
        ```
        
        This will validate data like `{"things": ["one", ["two", ["three"]]]}`.
        
        Typically any place you can specify a schema, you can instead specify a string
        which will be used to find a previously registered schema (references to
        registered schemas are resolved lexically).
        
        When you need to "merge in" a registered schema, you can use the `schema_ref`
        directive. This can be useful if you want to register a schema and use it at
        exactly the same level, for example:
        
        ```json
        {
            "registry": {
                "nested_list": {
                    "type": "list",
                    "schema": {"anyof": [{"type": "integer"}, "nested_list"]}
                }
            },
            "schema_ref": "nested_list",
        }
        ```
        
        This will validate data like `["one", ["two", ["three"]]]`.
        
        
        ## Nullable in the face of *of-rules
        
        Sureberus allows you to use `nullable` even if you have `*of-rules` that have
        `type` constraints. A nullable schema always allows `None`.
        
        ## A slightly nicer schema syntax
        
        If you want to construct a schema from Python code instead of storing it as
        JSON, sureberus provides a more terse syntax for it:
        
        Here's a standard dict-based schema, using an 80-character limit and strict
        newline/indent-based line wrapping:
        
        ```python
        myschema = {
            'type': 'dict',
            'anyof': [
                {'schema': {'gradient': {'type': 'string'}}},
                {
                    'schema': {
                        'image': {'type': 'string'},
                        'opacity': {'type': 'integer', 'default': 100},
                    }
                },
            ],
        }
        ```
        
        And here is a `sureberus.schema`-based schema, using the same line-wrapping
        rules:
        
        ```python
        from sureberus.schema import Dict, SubSchema, String, Integer
        myschema = Dict(
            anyof=[
                SubSchema(gradient=String()),
                SubSchema(image=String(), opacity=Integer(default=100))
            ]
        )
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown
