Metadata-Version: 1.1
Name: schema-resource
Version: 0.0.1
Summary: Schema Resources
Home-page: https://github.com/klmitch/schema-resource
Author: Kevin L. Mitchell
Author-email: klmitch@mit.edu
License: UNKNOWN
Description: ================
        Schema Resources
        ================
        
        .. image:: https://travis-ci.org/klmitch/schema-resource.svg?branch=master
            :target: https://travis-ci.org/klmitch/schema-resource
        
        The ``schema-resource`` package is a simple library for loading
        ``jsonschema`` schemas using ``pkg_resources``.  This means that
        Python packages utilizing the ``schema-resource`` package can bundle
        schemas for validating API or user configuration as separate files
        with the package source.  Further, those schemas may then reference
        other schema files within the package.
        
        Simple Usage
        ============
        
        The simplest way to use ``schema-resource`` begins by understanding
        the resource URI.  A resource URI is a URI with the scheme "res".  The
        "network location"--the part that appears after the "//" in a URI--is
        the package name, as understood by ``pkg_resources``.  The path is
        then interpreted relative to the root directory of the package.  For
        instance, if the package "spam" has a schema named "schema.yaml", the
        resource URI would be "res://spam/schema.yaml".  This schema can then
        be loaded using ``schema_res.load_schema()``, which takes the resource
        URI as its first argument; the result will be an object conforming to
        the ``jsonschema.IValidator`` interface documented in the
        ``jsonschema`` documentation.
        
        This schema could, of course, be loaded by using a combination of
        ``jsonschema`` and ``pkg_resources`` directly; however,
        ``schema-resource`` creates the schema with a special
        ``jsonschema.RefResolver`` that understands these resource URIs; this
        enhancement allows one schema to refer to another, or part of another,
        resource schema directly.
        
        Class Attributes
        ================
        
        Often, a class needs to use a particular schema in order to validate
        input, often from an API or a configuration file.  This can be
        simplified through the use of ``schema_res.SchemaDescriptor``.  This
        class implements the Python "descriptor" protocol, meaning that, when
        assigned to a class attribute, references to the value of the
        attribute will cause a method of ``schema_res.SchemaDescriptor`` to be
        called.  That method implements an on-demand loading of a schema
        resource, constructing the resource URI if needed from the class's
        ``__module__`` attribute.  For instance, assume that the ``Spam``
        class below needs to validate data fed to a class method::
        
            class Spam(object):
                schema = schema_res.SchemaDescriptor("spam.yaml")
        
                @classmethod
                def from_data(cls, data):
                    cls.schema.validate(data)
        
                    return cls(**data)
        
                ...
        
        This class first validates the data against the schema loaded from the
        "spam.yaml" file bundled with the package sources, loading the schema
        the first time the method is called.  (The
        ``jsonschema.IValidator.validate()`` method raises a
        ``jsonschema.ValidationError`` exception if the ``data`` doesn't match
        the requirements of the schema.)
        
        Validating Schemas
        ==================
        
        It is a good idea for the test suite for a package to verify that the
        schemas it bundles are valid.  This could be done by simply using the
        ``schema_res.load_schema()`` function, calling it for each resource
        URI and passing ``validate=True``, within the package's test suite.
        However, there's also a simple helper: ``schema_res.validate()`` takes
        one or more resource URIs and calls ``schema_res.load_schema()`` on
        each, passing ``validate=True``.  This means that this entire test can
        be written as a single function call, like so::
        
            class TestSchemas(object):
                def test_valid(self):
                    schema_res.validate(
                        "res://spam/schema1.yaml",
                        "res://spam/schema2.yaml",
                        "res://spam/schema3.yaml",
                    )
        
        Schema Format
        =============
        
        In all the examples so far, the schema filenames have had the ".yaml"
        extension.  There is no specific need to use this extension, nor even
        for the files to be in YAML format: JSON is a subset of YAML, so the
        schema files can be written in regular JSON.  However, by using a YAML
        parser to load the schema files, they may be expressed in YAML format,
        which this programmer finds easier to write and to read than strict
        JSON syntax.
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
