Package: prance
Prance provides parsers forSwagger/OpenAPI
2.0 and 3.0API specifications in Python.
It usesopenapi_spec_validator,swagger_spec_validatororflexto validate specifications, but additionally resolvesJSON
referencesin 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.UsageInstallationPrance is available from PyPI, and can be installed via pip:$pipinstallpranceNote 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:$pipinstallprance[osv,icu,cli]Make sure you haveICU Unicode Libraryinstalled,
as well as Python dev library before running the commands above. If not, use the
following commands:$sudoapt-getinstalllibicu-devpython3-dev# Ubuntu/Debian$sudodnfinstalllibicu-develpython3-devel# FedoraCommand Line InterfaceAfter installing prance, a CLI is available for validating (and resolving
external references in) specs:# Validates with resolving$prancevalidatepath/to/swagger.yml# Validates without resolving$prancevalidate--no-resolvepath/to/swagger.yml# Fetch URL, validate and resolve.$prancevalidatehttp://petstore.swagger.io/v2/swagger.jsonProcessing"http://petstore.swagger.io/v2/swagger.json"...->Resolvingexternalreferences.ValidatesOKasSwagger/OpenAPI2.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 thevalidatecommand,
but now there’s a specific command just for this purpose:# Compile spec$prancecompilepath/to/input.ymlpath/to/output.ymlLastly, 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 ofswagger2openapi- a working
internet connection is therefore required for this command:# Convert spec$pranceconvertpath/to/swagger.ymlpath/to/openapi.ymlCodeMost likely you have spec file and want to parse it:frompranceimportResolvingParserparser=ResolvingParser('path/to/my/swagger.yaml')parser.specification# contains fully resolved specs as a dictPrance also includes a non-resolving parser that does not follow JSON
references, in case you prefer that.frompranceimportBaseParserparser=BaseParser('path/to/my/swagger.yaml')parser.specification# contains specs as a dict still containing JSON referencesOn 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 (likec:\swagger.yaml), you can useprance.util.fs.abspathto 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 thefull documentationfor details.CompatibilityPython VersionsVersion 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 withPyPy.
Unfortunately, Travis isn’t very good at supporting this. So in the absence
of spare time, they’re disabled.Issue 50tracks 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.BackendsDifferent validation backends support different features.BackendPython VersionOpenAPI VersionStrict ModeNotesAvailable FromLinkswagger-spec-validator2 and 32.0 onlyyesSlow; does not accept integer keys (see strict mode).prance 0.1swagger_spec_validatorflex2 and 32.0 onlyn/aFastest; unfortunately deprecated.prance 0.8flexopenapi-spec-validator2 and 32.0 and 3.0yesSlow; does not accept integer keys (see strict mode).prance 0.11openapi_spec_validatorYou 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:$pipinstallopenapi-spec-validator$pipinstallprance$prancevalidate--backend=openapi-spec-validatorpath/to/spec.ymlA 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 ofPyYAMLthat contains security flaws. For another, it depends explicitly on older versions ofclick.If you use the flex subpackage, therefore, you do so at your own risk.CompatibilitySeeCOMPATIBILITY.rstfor a list of known issues.Partial Reference ResolutionIt’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.frompranceimportResolvingParserfromprance.util.resolverimportRESOLVE_HTTPparser=ResolvingParser('/path/to/spec',resolve_types=RESOLVE_HTTP)Multiple types can be specified by OR-ing constants together:frompranceimportResolvingParserfromprance.util.resolverimportRESOLVE_HTTP,RESOLVE_FILESparser=ResolvingParser('/path/to/spec',resolve_types=RESOLVE_HTTP|RESOLVE_FILES)ExtensionsPrance 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 theResourceManager API(some more infohere).For example, you might create a packagecommon_swagwith the filebase.yamlcontaining the definitiondefinitions:Severity:type:stringenum:-INFO-WARN-ERROR-FATALIn thesetup.pyforcommon_swagyou would add lines such aspackages=find_packages('src'),package_dir={'':'src'},package_data={'':'*.yaml'}Then, having installedcommon_swaginto some application, you could
now writedefinitions:Message:type:objectproperties:severity:$ref:'python://common_swag/base.yaml#/definitions/Severity'code:type:stringsummary:type:stringdescription:type:stringrequired:-severity-summaryContributingSeeCONTRIBUTING.mdfor details.Professional support is available throughfinkhaeuser consulting.LicenseLicensed under MIT. See theLICENSE.txtfile for details.“Prancing unicorn” logo image Copyright (c) Jens Finkhaeuser.
Made byMoreven B. Use of the logo is permitted under
theCreative Commons Attribution-NonCommercial-ShareAlike 4.0 International license.