prance 0.18.2

Installation

Prance is available from PyPI, and can be installed via pip:

$ pip install prance

Note that this will install the code, but additional subpackages must be specified to unlock various pieces of functionality. At minimum, a parsing backend must be installed. For the CLI functionality, you need further dependencies.

The recommended installation installs the CLI, uses ICU and installs one validation backend:

$ pip install prance[osv,icu,cli]

Make sure you have ICU Unicode Library installed, as well as Python dev library before running the commands above. If not, use the following commands:

Ubuntu

$ sudo apt-get install libicu-dev
$ sudo apt-get install python3-dev

Command Line Interface

After installing prance, a CLI is available for validating (and resolving external references in) specs:

# Validates with resolving
$ prance validate path/to/swagger.yml

# Validates without resolving
$ prance validate --no-resolve path/to/swagger.yml

# Fetch URL, validate and resolve.
$ prance validate http://petstore.swagger.io/v2/swagger.json
Processing "http://petstore.swagger.io/v2/swagger.json"...
 -> Resolving external references.
Validates OK as Swagger/OpenAPI 2.0!

Validation is not the only feature of prance. One of the side effects of resolving is that from a spec with references, one can create a fully resolved output spec. In the past, this was done via options to the validate command, but now there’s a specific command just for this purpose:

# Compile spec
$ prance compile path/to/input.yml path/to/output.yml

Lastly, with the arrival of OpenAPI 3.0.0, it becomes useful for tooling to convert older specs to the new standard. Instead of re-inventing the wheel, prance just provides a CLI command for passing specs to the web API of swagger2openapi - a working internet connection is therefore required for this command:

# Convert spec
$ prance convert path/to/swagger.yml path/to/openapi.yml

Code

Most likely you have spec file and want to parse it:

from prance import ResolvingParser
parser = ResolvingParser('path/to/my/swagger.yaml')
parser.specification  # contains fully resolved specs as a dict

Prance also includes a non-resolving parser that does not follow JSON references, in case you prefer that.

from prance import BaseParser
parser = BaseParser('path/to/my/swagger.yaml')
parser.specification  # contains specs as a dict still containing JSON references

On Windows, the code reacts correctly if you pass posix-like paths (/c:/swagger) or if the path is relative. If you pass absolute windows path (like c:\swagger.yaml), you can use prance.util.fs.abspath to convert them.

URLs can also be parsed:

parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')

Largely, that’s it. There is a whole slew of utility code that you may or may not find useful, too. Look at the full documentation for details.

Compatibility

Python Versions

Version 0.16.2 is the last version supporting Python 2. It was released on Nov 12th, 2019. Python 2 reaches end of life at the end of 2019. If you wish for updates to the Python 2 supported packages, please contact the maintainer directly.

Until fairly recently, we also tested with PyPy. Unfortunately, Travis isn’t very good at supporting this. So in the absence of spare time, they’re disabled. Issue 50 tracks progress on that.

Similarly, but less critically, Python 3.4 is no longer receiving a lot of love from CI vendors, so automated builds on that version are no longer supported.

Backends

Different validation backends support different features.

You can select the backend in the constructor of the parser(s):

parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json', backend = 'openapi-spec-validator')

No backend is included in the dependencies; they are detected at run-time. If you install them, they can be used:

$ pip install openapi-spec-validator
$ pip install prance
$ prance validate --backend=openapi-spec-validator path/to/spec.yml

A note on strict mode: The OpenAPI specs are a little ambiguous. On the one hand, they use JSON references and JSON schema a fair bit. But on the other hand, what they specify as examples does not always match the JSON specs.

Most notably, JSON only accepts string keys in objects. However, some keys in the specs tend to be integer values, most notably the status codes for responses. Strict mode rejects non-string keys; the default lenient mode accepts them.

Since the flex validator is not based on JSON, it does not have this issue. The strict option therefore does not apply here.

A note on flex usage: While flex is the fastest validation backend, unfortunately it is no longer maintained and there are issues with its dependencies. For one thing, it depends on a version of PyYAML that contains security flaws. For another, it depends explicitly on older versions of click.

If you use the flex subpackage, therefore, you do so at your own risk.

A Note on JSON References

The relevant parts of the RFC for JSON references can be condensed like this:

A JSON Reference is a JSON object, which contains a member named “$ref”, which has a JSON string value. Example:

{ “$ref”: “http://example.com/example.json#/foo/bar” }

(…)

Any members other than “$ref” in a JSON Reference object SHALL be ignored.

(…)

Resolution of a JSON Reference object SHOULD yield the referenced JSON value. Implementations MAY choose to replace the reference with the referenced value.

Prance is strict about ignoring additional keys, and does so by replacing the reference with the referenced value.

In practice, that means that given such a reference:

# main file
---
foo: bar
$ref: /path/to/ref

# and at /path/to/ref
---
baz: quux

Then, after resolution, the result is the following:

# resolved
---
baz: quux

That is, the key foo is ignored as the specs require. That is the reason the OpenAPI specs tend to use JSON references within schema objects, and place any other parameters as siblings of the schema object.

Recursion Limits

Since JSON references can reference an object that references the first object, we can create recursive references. By default, when a recursion is detected, an exception is raised. There are two ways you can modify this behaviour:

1. Increase the recursion_limit from it’s default value of 1 to some higher number. This doesn’t actually help much on its own.

2. Set the recursion_limit_handler parameter to a callable. It accepts the recursion limit, the reference URL of the element being resolved, and the currently known recursions.

prance.util.resolver.default_reclimit_handler is the default handler, and will always raise an exception.

If the handler you set does not raise an exception, its return value is used as the “resolved” value. To simply ignore recursions, use a handler that returns None - this will translate to the null value in the specs.

Partial Reference Resolution

It’s possible to instruct the parser to only resolve some kinds of references. This allows e.g. resolving references from external URLs, whilst keeping local references (i.e. to local files, or file internal) intact.

from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP

parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP)

Multiple types can be specified by OR-ing constants together:

from prance import ResolvingParser
from prance.util.resolver import RESOLVE_HTTP, RESOLVE_FILES

parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP | RESOLVE_FILES)

Extensions

Prance includes the ability to reference outside swagger definitions in outside Python packages. Such a package must already be importable (i.e. installed), and be accessible via the ResourceManager API (some more info here).

For example, you might create a package common_swag with the file base.yaml containing the definition

definitions:
  Severity:
    type: string
    enum:
    - INFO
    - WARN
    - ERROR
    - FATAL

In the setup.py for common_swag you would add lines such as

packages=find_packages('src'),
package_dir={'': 'src'},
package_data={
    '': '*.yaml'
}

Then, having installed common_swag into some application, you could now write

definitions:
  Message:
    type: object
    properties:
      severity:
        $ref: 'python://common_swag/base.yaml#/definitions/Severity'
      code:
        type: string
      summary:
        type: string
      description:
        type: string
    required:
    - severity
    - summary