sc-oa 0.7.0.17__py3-none-any.whl

sphinxcontrib/openapi/renderers/_httpdomain_old.py

@@ -0,0 +1,59 @@
+"""Here lies still breathing and only renderer implementation."""
+
+from docutils.parsers.rst import directives
+
+from . import abc
+from .. import openapi20, openapi30, utils
+
+
+class HttpdomainOldRenderer(abc.RestructuredTextRenderer):
+
+    option_spec = {
+        # A list of endpoints to be rendered. Endpoints must be whitespace
+        # delimited.
+        "paths": lambda s: s.split(),
+        # Regular expression patterns to includes/excludes endpoints to/from
+        # rendering. Similar to paths, the patterns must be whitespace
+        # delimited.
+        "include": lambda s: s.split(),
+        "exclude": lambda s: s.split(),
+        # Endpoints to be included based on HTTP method names.
+        "methods": lambda s: s.split(),
+        # Render the request body structure when passed.
+        "request": directives.flag,
+        # Render request/response examples when passed.
+        "examples": directives.flag,  # render examples when passed
+        # Render request/response examples in one block or inline with the response codes.
+        "contextpath": directives.flag,     # use the server path as prefix in service URL
+        "group_examples": directives.flag,  # render examples in one block
+        # Include links to entity description
+        "entities": directives.flag,
+        # Group endpoints by tags when passed. By default, no grouping is
+        # applied and endpoints are rendered in the order they met in spec.
+        "group": directives.flag,
+        # Markup format to render OpenAPI descriptions.
+        "format": str,
+    }
+
+    def __init__(self, state, options):
+        self._state = state
+        self._options = options
+
+    def render_restructuredtext_markup(self, spec):
+        # OpenAPI spec may contain JSON references, common properties, etc.
+        # Trying to render the spec "As Is" will require to put multiple if-s
+        # around the code. In order to simplify rendering flow, let's make it
+        # have only one (expected) schema, i.e. normalize it.
+        utils.normalize_spec(spec, **self._options)
+
+        # We support both OpenAPI 2.0 (f.k.a. Swagger) and OpenAPI 3.0.0, so
+        # determine which version we are parsing here.
+        spec_version = spec.get("openapi", spec.get("swagger", "2.0"))
+        if spec_version.startswith("2."):
+            openapihttpdomain = openapi20.openapihttpdomain
+        elif spec_version.startswith("3."):
+            openapihttpdomain = openapi30.openapihttpdomain
+        else:
+            raise ValueError("Unsupported OpenAPI version (%s)" % spec_version)
+
+        yield from openapihttpdomain(spec, **self._options)

sphinxcontrib/openapi/renderers/_model.py

@@ -0,0 +1,426 @@
+from . import abc
+from .. import utils
+
+import re
+import hashlib
+import json
+import textwrap
+
+import jsonschema
+from jsonschema import validate
+from docutils.parsers.rst import directives
+
+from sphinx.locale import get_translation
+_ = get_translation('openapi')
+
+
+def _get_description(obj, convert):
+    d = obj.get('description', '')
+    D = convert(d).strip()
+#    if d.strip()!=D:
+    if '\n' in D:
+        D += '\n\n'
+    if 'default' in obj:
+        if D and D.splitlines()[-1] and D[-1] != '.':
+            D += '.'
+        if D and D.splitlines()[-1]:
+            D += ' '
+        D += 'Default: ``' + json.dumps(obj['default']) + "``."
+    return D
+
+
+def _get_contraints(obj):
+    c = []
+    if 'minItems' in obj:
+        c.append(_('minItems is {}').format(obj['minItems']))
+    if 'maxItems' in obj:
+        c.append(_('maxItems is {}').format(obj['maxItems']))
+    if 'minLength' in obj:
+        c.append(_('minLength is {}').format(obj['minLength']))
+    if 'maxLength' in obj:
+        c.append(_('maxLength is {}').format(obj['maxLength']))
+    if 'minimum' in obj:
+        c.append(_('minimum is {}').format(obj['minimum']))
+    if 'maximum' in obj:
+        c.append(_('maximum is {}').format(obj['maximum']))
+    if 'uniqueItems' in obj:
+        c.append(_("items must be unique"))
+    if "pattern" in obj:
+        c.append(_("pattern ``{}``").format(obj["pattern"]))
+    if 'enum' in obj:
+        c.append(_('possible values are {}').format(
+                 ', '.join(
+                    [
+                        '``{}``'.format(x) for x in obj['enum']
+                    ]
+                 )))
+    if 'readOnly' in obj:
+        c.append(_("read only"))
+    if 'writeOnly' in obj:
+        c.append(_("write only"))
+    c = [str(x) for x in c]
+    s = '; '.join(c)
+    return s
+
+
+def _add_constraints(obj, D, C):
+    if C:
+        if str(_('Constraints')) not in D:
+            C = _("Constraints: {}").format(C)
+            if D and D.splitlines()[-1] and D[-1] != '.':
+                D += '.'
+        else:
+            if C and D and D.splitlines()[-1] and D[-1] != ';':
+                D += ';'
+        if D and D.splitlines()[-1] and C and C[0] != '\n':
+            D += ' '
+        D += C
+    else:
+        if D and D.splitlines()[-1] and D[-1] != '.':
+            D += '.'
+    if 'deprecated' in obj:
+        D += "\n\n**{}**".format(_("DEPRECATED"))
+    return D
+
+
+def _get_multi_type(schema, entities):
+    T = []
+    duplicate = set()
+    if 'oneOf' in schema:
+        k = 'oneOf'
+    elif 'allOf' in schema:
+        k = 'allOf'
+    else:
+        k = 'anyOf'
+    for t in schema[k]:
+        type = t.get('type', 'object')
+        if '$entity_ref' in t and type == 'object':
+            T.append(ref2link(entities, t['$entity_ref']))
+        else:
+            if type == 'string' and 'enum' in t:
+                type = 'enumerate'
+                vals = ', '.join(
+                    [
+                        '``{}``'.format(x) for x in t['enum']
+                    ]
+                )
+                if vals:
+                    type += ' (' + vals + ')'
+            if type not in duplicate:
+                T.append(type)
+                duplicate.add(type)
+    return T
+
+
+def _process_one(prefix, schema, mandatory, entities, convert):
+    if 'oneOf' in schema:
+        type = 'oneOf'
+    elif 'allOf' in schema:
+        type = 'allOf'
+    elif 'anyOf' in schema:
+        type = 'anyOf'
+    else:
+        type = schema.get('type', 'object')
+    if '$entity_ref' in schema and type == 'object' and prefix:
+        # does not apply to first level types (prefix empty)
+        T = _('Object of type {}').format(ref2link(entities, schema['$entity_ref']))
+        D = _get_description(schema, convert)
+        C = _get_contraints(schema)
+        D = _add_constraints(schema, D, C)
+        ret = ['.'.join(prefix), T, D, mandatory]
+        yield ret
+    elif type == 'array':
+        ref = schema['items'].get('$entity_ref', None)
+        type_items = schema['items'].get('type', None)
+        if ref:
+            D = _get_description(schema, convert)
+            C = _get_contraints(schema)
+            D = _add_constraints(schema, D, C)
+            if type_items not in ['object', 'array']:
+                # Since only object and array are described on their own
+                # Add here the constraints of the referenced type
+                D = _get_description(schema['items'], convert)
+                C = _get_contraints(schema['items'])
+                D = _add_constraints(schema['items'], D, C)
+                C = _get_contraints(schema)
+                D = _add_constraints(schema, D, C)
+                yield [
+                    '.'.join(prefix),
+                    _('Array of {}').format(type_items),
+                    D,
+                    mandatory
+                ]
+            else:
+                yield [
+                    '.'.join(prefix),
+                    _('Array of {}').format(ref2link(entities, ref)),
+                    D,
+                    mandatory
+                ]
+        elif type_items == 'object':
+            T = _("Array")
+            D = _get_description(schema, convert)
+            C = _get_contraints(schema)
+            D = _add_constraints(schema, D, C)
+            yield ['.'.join(prefix), T, D, mandatory]
+            if prefix:
+                prefix[-1] += '[]'
+            else:
+                prefix = ['[]']
+            for x in _process_one(prefix, schema['items'], False, entities, convert):
+                yield x
+        else:
+            # Support array of simple types (string, etc.)
+            D = _get_description(schema, convert)
+            C = _get_contraints(schema)
+            for x in _process_one(prefix, schema['items'], False, entities, convert):
+                # Add C to x[2] now and not before (to avoid double "Constraints:")
+                if D and x[2]:
+                    DD = D + ' ' + x[2]
+                else:
+                    DD = D + x[2]
+                DD = _add_constraints(schema, DD, C)
+                yield [x[0], _('Array of {}').format(x[1]), DD, mandatory]
+    elif type == 'object':
+        required = schema.get('required', [])
+        for prop_name, prop in schema.get('properties', {}).items():
+            for x in _process_one(
+                    prefix+[prop_name],
+                    prop,
+                    prop_name in required,
+                    entities,
+                    convert):
+                yield x
+        if 'additionalProperties' in schema:
+            D = _('Additional properties')
+            if schema['additionalProperties'] is True:
+                T = ''
+            elif schema['additionalProperties'] is False:
+                return
+            else:
+                if 'oneOf' in schema['additionalProperties']:
+                    T = _("One of {}").format(
+                        ", ".join(_get_multi_type(schema['additionalProperties'], entities)))
+                elif 'allOf' in schema['additionalProperties']:
+                    T = _("All of {}").format(
+                        ", ".join(_get_multi_type(schema['additionalProperties'], entities)))
+                elif 'anyOf' in schema['additionalProperties']:
+                    T = _("Any of {}").format(
+                        ", ".join(_get_multi_type(schema['additionalProperties'], entities)))
+                else:
+                    T = schema['additionalProperties'].get('type', 'object')
+            yield ['.'.join(prefix+['*']), T, D, '']
+    elif 'oneOf' in schema:
+        # One of the subtype, must be basic types or ref
+        D = _get_description(schema, convert)
+        C = _get_contraints(schema)
+        D = _add_constraints(schema, D, C)
+        T = _get_multi_type(schema, entities)
+        T = _("One of {}").format(", ".join(T))
+        yield ['.'.join(prefix), T, D, mandatory]
+    elif 'allOf' in schema:
+        # All of the subtype, must be basic types or ref
+        D = _get_description(schema, convert)
+        C = _get_contraints(schema)
+        D = _add_constraints(schema, D, C)
+        T = _get_multi_type(schema, entities)
+        T = _("All of {}").format(", ".join(T))
+        yield ['.'.join(prefix), T, D, mandatory]
+    elif 'anyOf' in schema:
+        # Any of the subtype, must be basic types or ref
+        D = _get_description(schema, convert)
+        C = _get_contraints(schema)
+        D = _add_constraints(schema, D, C)
+        T = _get_multi_type(schema, entities)
+        T = _("Any of {}").format(", ".join(T))
+        yield ['.'.join(prefix), T, D, mandatory]
+    elif type in ['string', 'integer', 'number', 'boolean']:
+        T = type
+        if schema.get('format', ''):
+            T += '/' + schema.get('format', '')
+        D = _get_description(schema, convert)
+        C = _get_contraints(schema)
+        D = _add_constraints(schema, D, C)
+        yield ['.'.join(prefix), T, D, mandatory]
+
+
+def _build(name, schema, entities, convert, options):
+    if 'type' in schema and schema['type'] not in ['object', 'array']:
+        return ''
+
+    yield ''
+    yield '.. _'+entities('/components/schemas/'+name)+':'
+    yield ''
+    yield name
+    yield options['header'] * len(name)
+    yield ''
+    D = _get_description(schema, convert)
+    if 'type' not in schema and not (set(['oneOf', 'allOf', 'anyOf']) & schema.keys()):
+        D += '\n' + _('Any type of content is accepted (number, string or object).')
+    if D:
+        yield D
+        yield ''
+    if 'type' not in schema and not (set(['oneOf', 'allOf', 'anyOf']) & schema.keys()):
+        pass
+    else:
+        yield '.. list-table:: ' + name
+        yield '    :header-rows: 1'
+        yield '    :widths: 25 25 45 15'
+        yield '    :class: longtable'
+        yield ''
+        yield '    * - ' + _('Attribute')
+        yield '      - ' + _('Type')
+        yield '      - ' + _('Description')
+        yield '      - ' + _('Required')
+
+        for item in _process_one([], schema, False, entities, convert):
+            if str(item[0]):
+                yield '    * - ``' + str(item[0]) + '``'
+            else:
+                yield '    * - ' + _('N/A')
+            yield '      - ' + textwrap.indent(str(item[1]), '        ').lstrip()
+            yield '      - ' + textwrap.indent(str(item[2]), '        ').lstrip()
+            yield '      - ' + _('Yes') if item[3] else '      -'
+
+    if 'example' in schema or 'examples' in schema:
+        N = 1
+        for ex in [schema.get('example', None)] + schema.get('examples', []):
+            if ex is None:
+                continue
+            yield ''
+            yield _('Example #{}:').format(N)
+            N += 1
+            # validate the example against this schema
+            try:
+                if 'type' in schema:
+                    validate(instance=ex, schema=schema)
+                yield ''
+                yield '.. code-block:: json'
+                yield ''
+                for line in json.dumps(ex, indent=2).splitlines():
+                    yield '    ' + line
+            except jsonschema.ValidationError:
+                yield ''
+                yield '**{}**'.format(_('Invalid example'))
+
+
+def ref2link(entities, ref):
+    if ref in ['object', 'string']:
+        return ref
+    name = ref.split('/')[-1]
+    if ref[0] == '#':
+        ref = ref[1:]
+    if callable(entities):
+        ref = entities(ref)
+        return ':ref:`{name} <{ref}>`'.format(**locals())
+    else:
+        return '{name}'.format(**locals())
+
+
+def _entities(spec, ref):
+    m = hashlib.md5()
+    m.update(spec.get('info', {}).get('title', '').encode('utf-8'))
+    m.update(spec.get('info', {}).get('version', '0.0').encode('utf-8'))
+    key = m.hexdigest()
+    # for unit tests
+    if key == '30565a8911a6bb487e3745c0ea3c8224':
+        key = ''
+    if '#' in ref:
+        ref = ref.split('#')[1]
+    return key + ref
+
+
+class ModelRenderer(abc.RestructuredTextRenderer):
+
+    option_spec = {
+        # prefix (components/schemas)
+        "prefix": str,
+        # header marker (')
+        "header": directives.single_char_or_unicode,
+        # Markup format to render OpenAPI descriptions.
+        "format": str,
+        # A list of entities to be rendered. Must be whitespace delimited.
+        "entities": lambda s: s.split(),
+        # Regular expression patterns to include/exclude entities to/from
+        # rendering. The patterns must be whitespace delimited.
+        "include": lambda s: s.split(),
+        "exclude": lambda s: s.split(),
+    }
+
+    def __init__(self, state, options):
+        self._state = state
+        self._options = options
+        if 'header' not in self._options:
+            self._options["header"] = "'"
+        if 'prefix' not in self._options:
+            self._options["prefix"] = "/components/schemas"
+
+    def render_restructuredtext_markup(self, spec):
+
+        utils.normalize_spec(spec, **self._options)
+
+        convert = utils.get_text_converter(self._options)
+
+        schemas = spec
+        for p in filter(None, self._options["prefix"].split('/')):
+            schemas = schemas.get(p, {})
+
+        # Entities list to be processed
+        entities = []
+
+        # If 'entities' are passed we've got to ensure they exist within an OpenAPI
+        # spec; otherwise raise error and ask user to fix that.
+        if 'entities' in self._options:
+            if not set(self._options['entities']).issubset(schemas.keys()):
+                raise ValueError(
+                    'One or more entities are not defined in the spec: %s.' % (
+                        ', '.join(set(self._options['entities']) - set(schemas.keys())),
+                    )
+                )
+            entities = self._options['entities']
+
+        # Check against regular expressions to be included
+        if 'include' in self._options:
+            # use a set to avoid duplicates
+            new_entities = set()
+            for i in self._options['include']:
+                ir = re.compile(i)
+                for entity in schemas.keys():
+                    if ir.match(entity):
+                        new_entities.add(entity)
+            # preserve order
+            new_list = []
+            for i in schemas.keys():
+                if i in new_entities or i in entities:
+                    new_list.append(i)
+            entities = new_list
+
+        # If no include nor entities option, then take full entity
+        if 'include' not in self._options and 'entities' not in self._options:
+            entities = list(schemas.keys())
+
+        # Remove entities matching regexp
+        if 'exclude' in self._options:
+            exc_entities = set()
+            for e in self._options['exclude']:
+                er = re.compile(e)
+                for entity in entities:
+                    if er.match(entity):
+                        exc_entities.add(entity)
+            # remove like that to preserve order
+            for entity in exc_entities:
+                entities.remove(entity)
+
+        def __entities(x):
+            return _entities(spec, x)
+
+        for name in entities:
+            schema = schemas[name]
+            for line in _build(name, schema, __entities, convert, self._options):
+                line_stripped = line.rstrip()
+                if '\n' in line_stripped:
+                    for line_splitted in line_stripped.splitlines():
+                        yield line_splitted
+                else:
+                    yield line_stripped
+            yield ''

sphinxcontrib/openapi/renderers/_toc.py

@@ -0,0 +1,48 @@
+
+import re
+from urllib.parse import urlparse
+
+from . import abc
+from .. import utils
+from docutils.parsers.rst import directives
+
+
+class TocRenderer(abc.RestructuredTextRenderer):
+
+    option_spec = {
+        # nb columns
+        "nb_columns": directives.positive_int,
+        "contextpath": directives.flag,     # use the server path as prefix in service URL
+    }
+
+    def __init__(self, state, options):
+        self._state = state
+        self._options = options
+        if 'nb_columns' not in self._options:
+            self._options["nb_columns"] = 2
+
+    def render_restructuredtext_markup(self, spec):
+
+        utils.normalize_spec(spec, **self._options)
+
+        contextpath = ''
+        if 'contextpath' in self._options:
+            if 'servers' in spec:
+                h = spec['servers'][0]['url']
+                contextpath = urlparse(h).path
+                if contextpath and contextpath[-1] == '/':
+                    contextpath = contextpath[:-1]
+
+        yield ""
+        yield ".. hlist::"
+        yield "    :columns: {}".format(self._options["nb_columns"])
+        yield ""
+
+        for path in spec["paths"].keys():
+            cpath = re.sub(r"[{}]", "", re.sub(r"[<>:/]", "-", contextpath+path))
+            for verb, ope in spec["paths"][path].items():
+                yield "    - `{} <#{}>`_".format(
+                    ope.get("operationId", verb + " " + path),
+                    verb.lower() + "-" + cpath
+                )
+        yield ""

sphinxcontrib/openapi/renderers/abc.py

@@ -0,0 +1,46 @@
+"""Abstract Base Classes (ABCs) for OpenAPI renderers."""
+
+import abc
+
+from docutils import nodes
+from docutils.statemachine import ViewList
+from sphinx.util.nodes import nested_parse_with_titles
+
+
+class Renderer(metaclass=abc.ABCMeta):
+    """Base class for OpenAPI renderers."""
+
+    def __init__(self, state, options):
+        self._state = state
+        self._options = options
+
+    @property
+    @abc.abstractmethod
+    def option_spec(self):
+        """Renderer options and their converting functions."""
+
+    @abc.abstractmethod
+    def render(self, spec):
+        """Render a given OpenAPI spec."""
+
+
+class RestructuredTextRenderer(Renderer):
+    """Base class for reStructuredText OpenAPI renderers.
+
+    Docutils DOM manipulation is quite a tricky task that requires passing
+    dozen arguments around. Because of that a lot of Sphinx extensions instead
+    of constructing DOM nodes directly produce and parse reStructuredText.
+    This Sphinx extension is not an exception, and that's why this class
+    exists. It's a convenient extension of :class:`Renderer` that converts
+    produced markup text into docutils DOM elements.
+    """
+
+    def render(self, spec):
+        viewlist = ViewList()
+        for line in self.render_restructuredtext_markup(spec):
+            viewlist.append(line, "<openapi>")
+
+        node = nodes.section()
+        node.document = self._state.document
+        nested_parse_with_titles(self._state, viewlist, node)
+        return node.children