Documentation of prance 0.21.8.0

Swagger/OpenAPI 2.0 Parser for Python

License PyPI Python Versions Package Format Package Status

Logo

Prance provides parsers for Swagger/OpenAPI 2.0 and 3.0 API specifications in Python. It uses openapi_spec_validator, swagger_spec_validator or flex to validate specifications, but additionally resolves JSON references in accordance with the OpenAPI spec.

Mostly the latter involves handling non-URI references; OpenAPI is fine with providing relative file paths, whereas JSON references require URIs at this point in time.

Usage

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:

$ sudo apt-get install libicu-dev python3-dev # Ubuntu/Debian
$ sudo dnf install libicu-devel python3-devel # Fedora

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.

Backend

Python Version

OpenAPI Version

Strict Mode

Notes

Available From

Link

swagger-spec-validator

2 and 3

2.0 only

yes

Slow; does not accept integer keys (see strict mode).

prance 0.1

swagger_spec_validator

flex

2 and 3

2.0 only

n/a

Fastest; unfortunately deprecated.

prance 0.8

flex

openapi-spec-validator

2 and 3

2.0 and 3.0

yes

Slow; does not accept integer keys (see strict mode).

prance 0.11

openapi_spec_validator

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 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.

Compatibility

See COMPATIBILITY.rst for a list of known issues.

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

Contributing

See CONTRIBUTING.md for details.

Professional support is available through finkhaeuser consulting.

License

Licensed under MIT. See the LICENSE.txt file for details.

“Prancing unicorn” logo image Copyright (c) Jens Finkhaeuser. Made by Moreven B. Use of the logo is permitted under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license.

API/Modules

prance

Prance implements parsers for Swagger/OpenAPI 2.0 and 3.0.0 API specs.

prance.mixins

Defines Mixins for parsers.

prance.convert

Functionality for converting from Swagger/OpenAPI 2.0 to OpenAPI 3.0.0.

prance.util.formats

This submodule contains file format related utility code for Prance.

prance.util.fs

This submodule contains file system utilities for Prance.

prance.util.iterators

This submodule contains specialty iterators over specs.

prance.util.resolver

This submodule contains a JSON inlining reference resolver.

prance.util.url

This submodule contains code for fetching/parsing URLs.

prance.util.exceptions

This submodule contains helpers for exception handling.

prance.util.path

This module contains code for accessing values in nested data structures.

Changes

Prance 0.21.8.0 (2021-08-06)

Features

  • Initial translating parser to inline other specs to new names. (#101)

  • replace pyyaml with ruamel.yaml for modern yaml support (#110)

  • Adopt black as code formatter. (#113)

Bugfixes

  • RefResolver will again accept and if instructed resolve references using the “python” URL scheme. (#104)

Prance 0.21.2 (2021-05-18)

Bugfixes

  • widen chardet pin to ease dependency hell for when others haven’t updated to >4 (#98)

v0.21.1 (2021-05-18)

  • quickfix for a missed rst issue in readme

v0.21.0 (2021-05-18)

Features

  • Implement initial part of maintainer switch (#93)

    • @RonnyPfannschmidt is the new maintainer, plans to move to jazzband

    • License is now MIT after coordination with Jens

    • begin to use pre-commit + pyupgrade

    • set up for setuptools_scm as bumpversion breaks with normalized configfiles

    • github actions

    • modernize setup.py/cfg

  • return to towncrier default templates

v0.20.2

  • #83: Properly propagate strict mode down to nested resolvers.

v0.20.1

Bugfix release:

  • #85: Update dependencies, in particular chardet

  • Miscellaneous: #86

v0.20.0

  • #77: Translate local references in external files by injecting them into the main specification.

  • #78: Fix issue in RESOLVE_INTERNAL handling

v0.19.0

  • #72: Fix behaviour when attempting to resolve nonexistent local references: raise ResolutionError instead of what the OS provides.

  • #69: Improve documenation with regards to JSON Schema and OpenAPI interoperability; some things are just not very well defined, and we make some strict assumptions in prance.

  • Miscellaneous: #71

v0.18.3

Bugfix release:

  • #67: fix syntax warning.

  • #69: when resolving references, if URL parsing fails, provide context on which URL was being parsed in error message.

v0.18.2

Bugfix release:

  • #65: fix error in resolving files only with ResolvingParser.

v0.18.1

Maintenance release, focusing on change requests from users.

  • #23: Add support for partial resolution, i.e. resolving only internal references, local files, HTTP URLs, or any combination thereof.

  • #36: Improve error handling by mentioning strict mode when openapi-spec-validator raises TypeError with very little context.

  • #46: Reduce reliance on network in tests. Tests that require a network connection can now be skipped via “-m ‘not requires_network’”. Other tests have mocked connections.

  • #55: RefResolver could set recursion limits, but the ResolvingParser did not pass related options on to the resolver. Fixed that. Also create & use reference cache in ResolvingParser.

  • #60: Improve output when resolving references, by indicating the type of problem (missing key, index out of bounds) in the object or sequence where the error occurred.

v0.17.0

  • #51: Try a lot more bytes when detecting file encoding. The new value is meant to be a multiple of sector/cluster size that’s still reasonable on most OSes and volumes.

  • #49: Remove Python 2.7 from supported/built versions. The CI vendors also don’t love 3.4 any longer. Instead, we’ve added 3.7 and 3.8 where available.

  • Miscellaneous: #53

v0.16.2

  • #47: Fix deprecation warning by always preferring collections.abc over collections.

v0.16.1

  • #44: Add changelog generation via towncrier