:py:mod:`kwcoco.util.jsonschema_elements`
=========================================

.. py:module:: kwcoco.util.jsonschema_elements

.. autoapi-nested-parse::

   Functional interface into defining jsonschema structures.

   See mixin classes for details.

   .. rubric:: Example

   >>> from kwcoco.util.jsonschema_elements import *  # NOQA
   >>> elem = SchemaElements()
   >>> for base in SchemaElements.__bases__:
   >>>     print('\n\n====\nbase = {!r}'.format(base))
   >>>     attrs = [key for key in dir(base) if not key.startswith('_')]
   >>>     for key in attrs:
   >>>         value = getattr(elem, key)
   >>>         print('{} = {}'.format(key, value))



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   kwcoco.util.jsonschema_elements.Element
   kwcoco.util.jsonschema_elements.ScalarElements
   kwcoco.util.jsonschema_elements.QuantifierElements
   kwcoco.util.jsonschema_elements.ContainerElements
   kwcoco.util.jsonschema_elements.SchemaElements




Attributes
~~~~~~~~~~

.. autoapisummary::

   kwcoco.util.jsonschema_elements.elem
   kwcoco.util.jsonschema_elements.ALLOF
   kwcoco.util.jsonschema_elements.ANY
   kwcoco.util.jsonschema_elements.ANYOF
   kwcoco.util.jsonschema_elements.ARRAY
   kwcoco.util.jsonschema_elements.BOOLEAN
   kwcoco.util.jsonschema_elements.INTEGER
   kwcoco.util.jsonschema_elements.NOT
   kwcoco.util.jsonschema_elements.NULL
   kwcoco.util.jsonschema_elements.NUMBER
   kwcoco.util.jsonschema_elements.OBJECT
   kwcoco.util.jsonschema_elements.ONEOF
   kwcoco.util.jsonschema_elements.STRING


.. py:class:: Element(base, options={}, _magic=None)

   Bases: :py:obj:`dict`

   A dictionary used to define an element of a JSON Schema.

   The exact keys/values for the element will depend on the type of element
   being described. The :class:`SchemaElements` defines exactly what these are
   for the core elements. (e.g. OBJECT, INTEGER, NULL, ARRAY, ANYOF)

   .. rubric:: Example

   >>> from kwcoco.coco_schema import *  # NOQA
   >>> self = Element(base={'type': 'demo'}, options={'opt1', 'opt2'})
   >>> new = self(opt1=3)
   >>> print('self = {}'.format(ub.repr2(self, nl=1, sort=1)))
   >>> print('new = {}'.format(ub.repr2(new, nl=1, sort=1)))
   >>> print('new2 = {}'.format(ub.repr2(new(), nl=1, sort=1)))
   >>> print('new3 = {}'.format(ub.repr2(new(title='myvar'), nl=1, sort=1)))
   >>> print('new4 = {}'.format(ub.repr2(new(title='myvar')(examples=['']), nl=1, sort=1)))
   >>> print('new5 = {}'.format(ub.repr2(new(badattr=True), nl=1, sort=1)))
   self = {
       'type': 'demo',
   }
   new = {
       'opt1': 3,
       'type': 'demo',
   }
   new2 = {
       'opt1': 3,
       'type': 'demo',
   }
   new3 = {
       'opt1': 3,
       'title': 'myvar',
       'type': 'demo',
   }
   new4 = {
       'examples': [''],
       'opt1': 3,
       'title': 'myvar',
       'type': 'demo',
   }
   new5 = {
       'opt1': 3,
       'type': 'demo',
   }

   .. py:attribute:: __generics__
      

      

   .. py:method:: __call__(self, *args, **kw)


   .. py:method:: validate(self, instance=ub.NoParam)

      If ``instance`` is given, validates that that dictionary conforms to
      this schema. Otherwise validates that this is a valid schema element.

      :Parameters: **instance** (*dict*) -- a dictionary to validate


   .. py:method:: __or__(self, other)

      Syntax for making an anyOf relationship

      .. rubric:: Example

      >>> from kwcoco.util.jsonschema_elements import *  # NOQA
      >>> obj1 = OBJECT(dict(opt1=NUMBER()))
      >>> obj2 = OBJECT(dict(opt2=STRING()))
      >>> obj3 = OBJECT(dict(opt3=ANY()))
      >>> any_v1 = obj1 | obj2
      >>> any_v2 = ANYOF(obj1, obj2)
      >>> assert any_v1 == any_v2
      >>> any_v3 = any_v1 | obj3
      >>> any_v4 = ANYOF(obj1, obj2, obj3)
      >>> assert any_v3 == any_v4



.. py:class:: ScalarElements

   Bases: :py:obj:`object`

   Single-valued elements

   .. py:method:: NULL(self)
      :property:

      https://json-schema.org/understanding-json-schema/reference/null.html


   .. py:method:: BOOLEAN(self)
      :property:

      https://json-schema.org/understanding-json-schema/reference/null.html


   .. py:method:: STRING(self)
      :property:

      https://json-schema.org/understanding-json-schema/reference/string.html


   .. py:method:: NUMBER(self)
      :property:

      https://json-schema.org/understanding-json-schema/reference/numeric.html#number


   .. py:method:: INTEGER(self)
      :property:

      https://json-schema.org/understanding-json-schema/reference/numeric.html#integer



.. py:class:: QuantifierElements

   Bases: :py:obj:`object`

   Quantifier types

   https://json-schema.org/understanding-json-schema/reference/combining.html#allof

   .. rubric:: Example

   >>> from kwcoco.util.jsonschema_elements import *  # NOQA
   >>> elem.ANYOF(elem.STRING, elem.NUMBER).validate()
   >>> elem.ONEOF(elem.STRING, elem.NUMBER).validate()
   >>> elem.NOT(elem.NULL).validate()
   >>> elem.NOT(elem.ANY).validate()
   >>> elem.ANY.validate()

   .. py:method:: ANY(self)
      :property:


   .. py:method:: ALLOF(self, *TYPES)


   .. py:method:: ANYOF(self, *TYPES)


   .. py:method:: ONEOF(self, *TYPES)


   .. py:method:: NOT(self, TYPE)



.. py:class:: ContainerElements

   Types that contain other types

   .. rubric:: Example

   >>> from kwcoco.util.jsonschema_elements import *  # NOQA
   >>> print(elem.ARRAY().validate())
   >>> print(elem.OBJECT().validate())
   >>> print(elem.OBJECT().validate())
   {'type': 'array', 'items': {}}
   {'type': 'object', 'properties': {}}
   {'type': 'object', 'properties': {}}

   .. py:method:: ARRAY(self, TYPE={}, **kw)

      https://json-schema.org/understanding-json-schema/reference/array.html

      .. rubric:: Example

      >>> from kwcoco.util.jsonschema_elements import *  # NOQA
      >>> ARRAY(numItems=3)
      >>> schema = ARRAY(minItems=3)
      >>> schema.validate()
      {'type': 'array', 'items': {}, 'minItems': 3}


   .. py:method:: OBJECT(self, PROPERTIES={}, **kw)

      https://json-schema.org/understanding-json-schema/reference/object.html


      .. rubric:: Example

      >>> import jsonschema
      >>> schema = elem.OBJECT()
      >>> jsonschema.validate({}, schema)
      >>> #
      >>> import jsonschema
      >>> schema = elem.OBJECT({
      >>>     'key1': elem.ANY(),
      >>>     'key2': elem.ANY(),
      >>> }, required=['key1'])
      >>> jsonschema.validate({'key1': None}, schema)
      >>> #
      >>> import jsonschema
      >>> schema = elem.OBJECT({
      >>>     'key1': elem.OBJECT({'arr': elem.ARRAY()}),
      >>>     'key2': elem.ANY(),
      >>> }, required=['key1'], title='a title')
      >>> schema.validate()
      >>> print('schema = {}'.format(ub.repr2(schema, sort=1, nl=-1)))
      >>> jsonschema.validate({'key1': {'arr': []}}, schema)
      schema = {
          'properties': {
              'key1': {
                  'properties': {
                      'arr': {'items': {}, 'type': 'array'}
                  },
                  'type': 'object'
              },
              'key2': {}
          },
          'required': ['key1'],
          'title': 'a title',
          'type': 'object'
      }



.. py:class:: SchemaElements

   Bases: :py:obj:`ScalarElements`, :py:obj:`QuantifierElements`, :py:obj:`ContainerElements`

   Functional interface into defining jsonschema structures.

   See mixin classes for details.

   .. rubric:: References

   https://json-schema.org/understanding-json-schema/

   .. todo:: - [ ] Generics: title, description, default, examples

   .. rubric:: CommandLine

   .. code-block:: bash

       xdoctest -m /home/joncrall/code/kwcoco/kwcoco/util/jsonschema_elements.py SchemaElements

   .. rubric:: Example

   >>> from kwcoco.util.jsonschema_elements import *  # NOQA
   >>> elem = SchemaElements()
   >>> elem.ARRAY(elem.ANY())
   >>> schema = OBJECT({
   >>>     'prop1': ARRAY(INTEGER, minItems=3),
   >>>     'prop2': ARRAY(STRING, numItems=2),
   >>>     'prop3': ARRAY(OBJECT({
   >>>         'subprob1': NUMBER,
   >>>         'subprob2': NUMBER,
   >>>     }))
   >>> })
   >>> print('schema = {}'.format(ub.repr2(schema, nl=2, sort=1)))
   schema = {
       'properties': {
           'prop1': {'items': {'type': 'integer'}, 'minItems': 3, 'type': 'array'},
           'prop2': {'items': {'type': 'string'}, 'maxItems': 2, 'minItems': 2, 'type': 'array'},
           'prop3': {'items': {'properties': {'subprob1': {'type': 'number'}, 'subprob2': {'type': 'number'}}, 'type': 'object'}, 'type': 'array'},
       },
       'type': 'object',
   }

   >>> TYPE = elem.OBJECT({
   >>>     'p1': ANY,
   >>>     'p2': ANY,
   >>> }, required=['p1'])
   >>> import jsonschema
   >>> inst = {'p1': None}
   >>> jsonschema.validate(inst, schema=TYPE)
   >>> #jsonschema.validate({'p2': None}, schema=TYPE)


.. py:data:: elem
   

   

.. py:data:: ALLOF
   

   

.. py:data:: ANY
   

   

.. py:data:: ANYOF
   

   

.. py:data:: ARRAY
   

   

.. py:data:: BOOLEAN
   

   

.. py:data:: INTEGER
   

   

.. py:data:: NOT
   

   

.. py:data:: NULL
   

   

.. py:data:: NUMBER
   

   

.. py:data:: OBJECT
   

   

.. py:data:: ONEOF
   

   

.. py:data:: STRING