{"id":15008858,"url":"https://github.com/ronnypfannschmidt/prance","last_synced_at":"2026-04-02T02:07:56.939Z","repository":{"id":41936022,"uuid":"67692955","full_name":"RonnyPfannschmidt/prance","owner":"RonnyPfannschmidt","description":"Resolving Swagger/OpenAPI 2.0 and 3.0 Parser","archived":false,"fork":false,"pushed_at":"2025-04-07T22:26:19.000Z","size":4085,"stargazers_count":233,"open_issues_count":29,"forks_count":46,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-13T13:57:13.711Z","etag":null,"topics":["compiler","converter","openapi","openapi2","openapi3","parser","python","python2","python3","resolver","swagger","validator"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RonnyPfannschmidt.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-08T10:23:39.000Z","updated_at":"2025-04-08T13:26:48.000Z","dependencies_parsed_at":"2023-02-07T02:15:23.236Z","dependency_job_id":"7d61492a-a4f5-4447-9fc1-2e82e3a59708","html_url":"https://github.com/RonnyPfannschmidt/prance","commit_stats":{"total_commits":585,"total_committers":29,"mean_commits":20.17241379310345,"dds":0.1777777777777778,"last_synced_commit":"2b91d0776630512843ca7d2975f963080a5c3bb6"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonnyPfannschmidt%2Fprance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonnyPfannschmidt%2Fprance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonnyPfannschmidt%2Fprance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonnyPfannschmidt%2Fprance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RonnyPfannschmidt","download_url":"https://codeload.github.com/RonnyPfannschmidt/prance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724587,"owners_count":21151559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compiler","converter","openapi","openapi2","openapi3","parser","python","python2","python3","resolver","swagger","validator"],"created_at":"2024-09-24T19:21:06.296Z","updated_at":"2025-12-12T00:40:18.035Z","avatar_url":"https://github.com/RonnyPfannschmidt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"|License| |PyPI| |Python Versions| |Package Format| |Package Status|\n\n|Logo|\n\nPrance provides parsers for `Swagger/OpenAPI\n2.0 and 3.0 \u003chttp://swagger.io/specification/\u003e`__ API specifications in Python.\nIt uses `openapi\\_spec\\_validator \u003chttps://github.com/p1c2u/openapi-spec-validator\u003e`__,\n`swagger\\_spec\\_validator \u003chttps://github.com/Yelp/swagger_spec_validator\u003e`__ or\n`flex \u003chttps://github.com/pipermerriam/flex\u003e`__\nto validate specifications, but additionally resolves `JSON\nreferences \u003chttps://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03\u003e`__\nin accordance with the OpenAPI spec.\n\nMostly the latter involves handling non-URI references; OpenAPI is fine\nwith providing relative file paths, whereas JSON references require URIs\nat this point in time.\n\nUsage\n=====\n\nInstallation\n------------\n\nPrance is available from PyPI, and can be installed via pip:\n\n.. code:: bash\n\n    $ pip install prance\n\nNote that this will install the code, but additional subpackages must be specified\nto unlock various pieces of functionality. At minimum, a parsing backend must be\ninstalled. For the CLI functionality, you need further dependencies.\n\nThe recommended installation installs the CLI, uses ICU and installs one validation\nbackend:\n\n.. code:: bash\n\n    $ pip install prance[osv,icu,cli]\n\nMake sure you have `ICU Unicode Library \u003chttp://site.icu-project.org/home\u003e`__ installed,\nas well as Python dev library before running the commands above. If not, use the\nfollowing commands:\n\n.. code:: bash\n\n    $ sudo apt-get install libicu-dev python3-dev # Ubuntu/Debian\n    $ sudo dnf install libicu-devel python3-devel # Fedora\n\n\nCommand Line Interface\n----------------------\n\nAfter installing prance, a CLI is available for validating (and resolving\nexternal references in) specs:\n\n.. code:: bash\n\n    # Validates with resolving\n    $ prance validate path/to/swagger.yml\n\n    # Validates without resolving\n    $ prance validate --no-resolve path/to/swagger.yml\n\n    # Fetch URL, validate and resolve.\n    $ prance validate http://petstore.swagger.io/v2/swagger.json\n    Processing \"http://petstore.swagger.io/v2/swagger.json\"...\n     -\u003e Resolving external references.\n    Validates OK as Swagger/OpenAPI 2.0!\n\nValidation is not the only feature of prance. One of the side effects of\nresolving is that from a spec with references, one can create a fully resolved\noutput spec. In the past, this was done via options to the ``validate`` command,\nbut now there's a specific command just for this purpose:\n\n.. code:: bash\n\n    # Compile spec\n    $ prance compile path/to/input.yml path/to/output.yml\n\n\nLastly, with the arrival of OpenAPI 3.0.0, it becomes useful for tooling to\nconvert older specs to the new standard. Instead of re-inventing the wheel,\nprance just provides a CLI command for passing specs to the web API of\n`swagger2openapi \u003chttps://github.com/Mermade/swagger2openapi\u003e`__ - a working\ninternet connection is therefore required for this command:\n\n.. code:: bash\n\n    # Convert spec\n    $ prance convert path/to/swagger.yml path/to/openapi.yml\n\n\nCode\n----\n\nMost likely you have spec file and want to parse it:\n\n.. code:: python\n\n    from prance import ResolvingParser\n    parser = ResolvingParser('path/to/my/swagger.yaml')\n    parser.specification  # contains fully resolved specs as a dict\n\nPrance also includes a non-resolving parser that does not follow JSON\nreferences, in case you prefer that.\n\n.. code:: python\n\n    from prance import BaseParser\n    parser = BaseParser('path/to/my/swagger.yaml')\n    parser.specification  # contains specs as a dict still containing JSON references\n\nOn Windows, the code reacts correctly if you pass posix-like paths\n(``/c:/swagger``) or if the path is relative.  If you pass absolute\nwindows path (like ``c:\\swagger.yaml``), you can use\n``prance.util.fs.abspath`` to convert them.\n\nURLs can also be parsed:\n\n.. code:: python\n\n    parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')\n\nLargely, that's it. There is a whole slew of utility code that you may\nor may not find useful, too. Look at the `full documentation\n\u003chttps://prance.readthedocs.io/en/latest/#api-modules\u003e`__ for details.\n\n\nCompatibility\n-------------\n\n*Python Versions*\n\nVersion 0.16.2 is the last version supporting Python 2. It was released on\nNov 12th, 2019. Python 2 reaches end of life at the end of 2019. If you wish\nfor updates to the Python 2 supported packages, please contact the maintainer\ndirectly.\n\nUntil fairly recently, we also tested with `PyPy \u003chttps://www.pypy.org/\u003e`__.\nUnfortunately, Travis isn't very good at supporting this. So in the absence\nof spare time, they're disabled. `Issue 50 \u003chttps://github.com/jfinkhaeuser/prance/issues/50\u003e`__\ntracks progress on that.\n\nSimilarly, but less critically, Python 3.4 is no longer receiving a lot of\nlove from CI vendors, so automated builds on that version are no longer\nsupported.\n\n*Backends*\n\nDifferent validation backends support different features.\n\n+------------------------+----------------+-----------------+-------------+-------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+\n| Backend                | Python Version | OpenAPI Version | Strict Mode | Notes                                                 | Available From | Link                                                                              |\n+========================+================+=================+=============+=======================================================+================+===================================================================================+\n| 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 \u003chttps://github.com/Yelp/swagger_spec_validator\u003e`__     |\n+------------------------+----------------+-----------------+-------------+-------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+\n| flex                   | 2 and 3        | 2.0 only        | n/a         | Fastest; unfortunately deprecated.                    | prance 0.8     | `flex \u003chttps://github.com/pipermerriam/flex\u003e`__                                   |\n+------------------------+----------------+-----------------+-------------+-------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+\n| 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 \u003chttps://github.com/p1c2u/openapi-spec-validator\u003e`__    |\n+------------------------+----------------+-----------------+-------------+-------------------------------------------------------+----------------+-----------------------------------------------------------------------------------+\n\nYou can select the backend in the constructor of the parser(s):\n\n.. code:: python\n\n    parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json', backend = 'openapi-spec-validator')\n\n\nNo backend is included in the dependencies; they are detected at run-time. If you install them,\nthey can be used:\n\n.. code:: bash\n\n    $ pip install openapi-spec-validator\n    $ pip install prance\n    $ prance validate --backend=openapi-spec-validator path/to/spec.yml\n\n*A note on flex usage:* While flex is the fastest validation backend, unfortunately it is no longer\nmaintained and there are issues with its dependencies. For one thing, it depends on a version of `PyYAML`\nthat contains security flaws. For another, it depends explicitly on older versions of `click`.\n\nIf you use the flex subpackage, therefore, you do so at your own risk.\n\n*Compatibility*\n\nSee `COMPATIBILITY.rst \u003chttps://github.com/jfinkhaeuser/prance/blob/master/COMPATIBILITY.rst\u003e`__\nfor a list of known issues.\n\n\nPartial Reference Resolution\n----------------------------\n\nIt's possible to instruct the parser to only resolve some kinds of references.\nThis allows e.g. resolving references from external URLs, whilst keeping local\nreferences (i.e. to local files, or file internal) intact.\n\n.. code:: python\n\n    from prance import ResolvingParser\n    from prance.util.resolver import RESOLVE_HTTP\n\n    parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP)\n\n\nMultiple types can be specified by OR-ing constants together:\n\n.. code:: python\n\n    from prance import ResolvingParser\n    from prance.util.resolver import RESOLVE_HTTP, RESOLVE_FILES\n\n    parser = ResolvingParser('/path/to/spec', resolve_types = RESOLVE_HTTP | RESOLVE_FILES)\n\n\nExtensions\n----------\n\nPrance includes the ability to reference outside swagger definitions\nin outside Python packages. Such a package must already be importable\n(i.e. installed), and be accessible via the\n`ResourceManager API \u003chttps://setuptools.readthedocs.io/en/latest/pkg_resources.html#resourcemanager-api\u003e`__\n(some more info `here \u003chttps://setuptools.readthedocs.io/en/latest/setuptools.html#including-data-files\u003e`__).\n\nFor example, you might create a package ``common_swag`` with the file\n``base.yaml`` containing the definition\n\n.. code:: yaml\n\n    definitions:\n      Severity:\n        type: string\n        enum:\n        - INFO\n        - WARN\n        - ERROR\n        - FATAL\n\nIn the ``setup.py`` for ``common_swag`` you would add lines such as\n\n.. code:: python\n\n    packages=find_packages('src'),\n    package_dir={'': 'src'},\n    package_data={\n        '': '*.yaml'\n    }\n\nThen, having installed ``common_swag`` into some application, you could\nnow write\n\n.. code:: yaml\n\n    definitions:\n      Message:\n        type: object\n        properties:\n          severity:\n            $ref: 'python://common_swag/base.yaml#/definitions/Severity'\n          code:\n            type: string\n          summary:\n            type: string\n          description:\n            type: string\n        required:\n        - severity\n        - summary\n\nContributing\n============\n\nSee `CONTRIBUTING.md \u003chttps://github.com/jfinkhaeuser/prance/blob/master/CONTRIBUTING.md\u003e`__ for details.\n\nProfessional support is available through `finkhaeuser consulting \u003chttps://finkhaeuser.de\u003e`__.\n\nLicense\n=======\n\nLicensed under MIT. See the `LICENSE.txt \u003chttps://github.com/RonnyPfannschmidt/prance/blob/master/LICENSE.txt\u003e`__ file for details.\n\n\"Prancing unicorn\" logo image Copyright (c) Jens Finkhaeuser.\nMade by `Moreven B \u003chttp://morevenb.com/\u003e`__. Use of the logo is permitted under\nthe `Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International license \u003chttps://creativecommons.org/licenses/by-nc-sa/4.0/\u003e`__.\n\n\n.. |License| image:: https://img.shields.io/pypi/l/prance.svg\n   :target: https://pypi.python.org/pypi/prance/\n.. |PyPI| image:: https://img.shields.io/pypi/v/prance.svg\n   :target: https://pypi.python.org/pypi/prance/\n.. |Package Format| image:: https://img.shields.io/pypi/format/prance.svg\n   :target: https://pypi.python.org/pypi/prance/\n.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/prance.svg\n   :target: https://pypi.python.org/pypi/prance/\n.. |Package Status| image:: https://img.shields.io/pypi/status/prance.svg\n   :target: https://pypi.python.org/pypi/prance/\n.. |Logo| image:: https://raw.githubusercontent.com/RonnyPfannschmidt/prance/master/docs/images/prance_logo_256.png\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronnypfannschmidt%2Fprance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronnypfannschmidt%2Fprance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronnypfannschmidt%2Fprance/lists"}