sc-oa 0.7.0.17__py3-none-any.whl

sphinxcontrib/openapi/schema_utils.py

@@ -0,0 +1,137 @@
+"""OpenAPI schema utility functions."""
+
+from io import StringIO
+
+
+_DEFAULT_EXAMPLES = {
+    "string": "string",
+    "integer": 1,
+    "number": 1.0,
+    "boolean": True,
+    "array": [],
+}
+
+
+_DEFAULT_STRING_EXAMPLES = {
+    "date": "2020-01-01",
+    "date-time": "2020-01-01T01:01:01Z",
+    "password": "********",
+    "byte": "QG1pY2hhZWxncmFoYW1ldmFucw==",
+    "ipv4": "127.0.0.1",
+    "ipv6": "::1",
+}
+
+
+def example_from_schema(schema):
+    """
+    Generates an example request/response body from the provided schema.
+
+    >>> schema = {
+    ...     "type": "object",
+    ...     "required": ["id", "name"],
+    ...     "properties": {
+    ...         "id": {
+    ...             "type": "integer",
+    ...             "format": "int64"
+    ...         },
+    ...         "name": {
+    ...             "type": "string",
+    ...             "example": "John Smith"
+    ...         },
+    ...         "tag": {
+    ...             "type": "string"
+    ...         }
+    ...     }
+    ... }
+    >>> example = example_from_schema(schema)
+    >>> assert example == {
+    ...     "id": 1,
+    ...     "name": "John Smith",
+    ...     "tag": "string"
+    ... }
+    """
+    # If an example was provided then we use that
+    if "example" in schema:
+        return schema["example"]
+
+    elif "oneOf" in schema:
+        return example_from_schema(schema["oneOf"][0])
+
+    elif "anyOf" in schema:
+        return example_from_schema(schema["anyOf"][0])
+
+    elif "allOf" in schema:
+        # Combine schema examples
+        example = {}
+        for sub_schema in schema["allOf"]:
+            example.update(example_from_schema(sub_schema))
+        return example
+
+    elif "enum" in schema:
+        return schema["enum"][0]
+
+    elif "type" not in schema:
+        # Any type
+        return _DEFAULT_EXAMPLES["integer"]
+
+    elif schema["type"] == "object" or "properties" in schema:
+        example = {}
+        for prop, prop_schema in schema.get("properties", {}).items():
+            example[prop] = example_from_schema(prop_schema)
+        return example
+
+    elif schema["type"] == "array":
+        items = schema["items"]
+        min_length = schema.get("minItems", 0)
+        max_length = schema.get("maxItems", max(min_length, 2))
+        assert min_length <= max_length
+        # Try generate at least 2 example array items
+        gen_length = min(2, max_length) if min_length <= 2 else min_length
+
+        example_items = []
+        if items == {}:
+            # Any-type arrays
+            example_items.extend(_DEFAULT_EXAMPLES.values())
+        elif isinstance(items, dict) and "oneOf" in items:
+            # Mixed-type arrays
+            example_items.append(_DEFAULT_EXAMPLES[sorted(items["oneOf"])[0]])
+        else:
+            example_items.append(example_from_schema(items))
+
+        # Generate array containing example_items and satisfying min_length and max_length
+        return [example_items[i % len(example_items)] for i in range(gen_length)]
+
+    elif schema["type"] == "string":
+        example_string = _DEFAULT_STRING_EXAMPLES.get(
+            schema.get("format", None), _DEFAULT_EXAMPLES["string"]
+        )
+        min_length = schema.get("minLength", 0)
+        max_length = schema.get("maxLength", max(min_length, len(example_string)))
+        gen_length = (
+            min(len(example_string), max_length)
+            if min_length <= len(example_string)
+            else min_length
+        )
+        assert 0 <= min_length <= max_length
+        if min_length <= len(example_string) <= max_length:
+            return example_string
+        else:
+            example_builder = StringIO()
+            for i in range(gen_length):
+                example_builder.write(example_string[i % len(example_string)])
+            example_builder.seek(0)
+            return example_builder.read()
+
+    elif schema["type"] in ("integer", "number"):
+        example = _DEFAULT_EXAMPLES[schema["type"]]
+        if "minimum" in schema and "maximum" in schema:
+            # Take average
+            example = schema["minimum"] + (schema["maximum"] - schema["minimum"]) / 2
+        elif "minimum" in schema and example <= schema["minimum"]:
+            example = schema["minimum"] + 1
+        elif "maximum" in schema and example >= schema["maximum"]:
+            example = schema["maximum"] - 1
+        return float(example) if schema["type"] == "number" else int(example)
+
+    else:
+        return _DEFAULT_EXAMPLES[schema["type"]]

sphinxcontrib/openapi/utils.py

@@ -0,0 +1,137 @@
+"""
+    sphinxcontrib.openapi.utils
+    ---------------------------
+
+    Common functionality shared across the various renderers.
+
+    :copyright: (c) 2016, Ihor Kalnytskyi.
+    :license: BSD, see LICENSE for details.
+"""
+
+from __future__ import unicode_literals
+
+import collections
+import collections.abc
+
+from contextlib import closing
+import jsonschema
+import yaml
+try:
+    from m2r2 import convert as convert_markdown
+except ImportError:
+    convert_markdown = None
+
+from urllib.parse import urlsplit
+from urllib.request import urlopen
+
+import os.path
+
+
+class OpenApiRefResolver(jsonschema.RefResolver):
+    """
+    Overrides resolve_remote to support both YAML and JSON
+    OpenAPI schemas.
+    """
+
+    try:
+        import requests
+        _requests = requests
+    except ImportError:
+        _requests = None
+
+    def resolve_remote(self, uri):
+        scheme, _, path, _, _ = urlsplit(uri)
+        _, extension = os.path.splitext(path)
+
+        if extension not in [".yml", ".yaml"] or scheme in self.handlers:
+            return super(OpenApiRefResolver, self).resolve_remote(uri)
+
+        if scheme in [u"http", u"https"] and self._requests:
+            response = self._requests.get(uri)
+            result = yaml.safe_load(response)
+        else:
+            # Otherwise, pass off to urllib and assume utf-8
+            with closing(urlopen(uri)) as url:
+                response = url.read().decode("utf-8")
+                result = yaml.safe_load(response)
+
+        if self.cache_remote:
+            self.store[uri] = result
+        return result
+
+
+def _resolve_refs(uri, spec):
+    """Resolve JSON references in a given dictionary.
+
+    OpenAPI spec may contain JSON references to its nodes or external
+    sources, so any attempt to rely that there's some expected attribute
+    in the spec may fail. So we need to resolve JSON references before
+    we use it (i.e. replace with referenced object). For details see:
+
+        https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-02
+
+    The input spec is modified in-place despite being returned from
+    the function.
+    """
+
+    resolver = OpenApiRefResolver(uri, spec)
+
+    def _do_resolve(node):
+        if isinstance(node, collections.abc.Mapping) and '$ref' in node:
+            ref = node['$ref']
+            with resolver.resolving(node['$ref']) as resolved:
+                ret = _do_resolve(resolved)  # might have recursive references
+            # Restore the $ref in case we want to
+            # separate the entities in the document
+            if isinstance(ret, collections.abc.Mapping):
+                ret['$entity_ref'] = ref
+            return ret
+        elif isinstance(node, collections.abc.Mapping):
+            for k, v in node.items():
+                node[k] = _do_resolve(v)
+        elif isinstance(node, (list, tuple)):
+            for i in range(len(node)):
+                node[i] = _do_resolve(node[i])
+        return node
+
+    return _do_resolve(spec)
+
+
+def normalize_spec(spec, **options):
+    # OpenAPI spec may contain JSON references, so we need resolve them
+    # before we access the actual values trying to build an httpdomain
+    # markup. Since JSON references may be relative, it's crucial to
+    # pass a document URI in order to properly resolve them.
+    spec = _resolve_refs(options.get('uri', ''), spec)
+
+    # OpenAPI spec may contain common endpoint's parameters top-level.
+    # In order to do not place if-s around the code to handle special
+    # cases, let's normalize the spec and push common parameters inside
+    # endpoints definitions.
+    for endpoint in spec['paths'].values():
+        parameters = endpoint.pop('parameters', [])
+        for method in endpoint.values():
+            method.setdefault('parameters', [])
+            method['parameters'].extend(parameters)
+
+
+def _conv_md(s):
+    try:
+        return convert_markdown(s)
+    except Exception:
+        return s
+
+
+def get_text_converter(options):
+    """Decide on a text converter for prose."""
+    if 'format' in options:
+        if options['format'] == 'markdown':
+            if convert_markdown is None:
+                raise ValueError(
+                    "Markdown conversion isn't available, "
+                    "install the [markdown] extra."
+                )
+            return _conv_md
+
+    # No conversion needed.
+    return lambda s: s