Prance

Warnings

• breaking Prance version 25.04.08.0 dropped support for Python 3.8 and 3.9. It now supports Python 3.11, 3.12, and 3.14. Earlier, Python 2.7 and 3.4 support was removed in versions prior to 0.17.0.
  Fix: Upgrade Python environment to a supported version (e.g., 3.10 or newer, preferably 3.11+ for latest Prance).
• breaking Version 25.04.08.0 migrated its underlying JSON reference resolution engine from `jsonschema` to `referencing`. While the public API is generally stable, advanced users directly interacting with resolver internals might experience breaking changes.
  Fix: Review code that directly manipulates internal resolver components. Test thoroughly after upgrading.
• gotcha Prance's validation backends (`openapi-spec-validator`, `swagger-spec-validator`, `flex`) are optional dependencies. For full functionality and recommended usage, install with extras like `pip install prance[osv,icu,cli]`. If no backend is installed, validation might be limited or fail.
  Fix: Install Prance with the appropriate extra dependencies for your desired validation backend (e.g., `prance[osv]` for OpenAPI 3.0+ validation) and other features (e.g. `[icu]` for better Unicode handling, `[cli]` for command line tools).
• deprecated Version 25.04.08.0 switched the preferred YAML mimetype from `x-yaml` to the official `yaml` form. While older forms might still be handled, it's best to use the official mimetype.
  Fix: Ensure any custom handling or generation of OpenAPI/Swagger specs uses the official `yaml` mimetype.
• gotcha As of version 0.8, Prance defaults to `flex` as the validation backend if available. Note that `flex` accepts integer status codes despite them not being valid JSON, which might lead to less strict validation than other backends. You can explicitly specify a backend in the parser constructor (e.g., `ResolvingParser(..., backend='openapi-spec-validator')`).
  Fix: If strict JSON validation for HTTP status codes is required, explicitly set `backend='openapi-spec-validator'` or `backend='swagger-spec-validator'` during parser initialization, and ensure that backend is installed.

Install

• pip install prance Basic Installation
• pip install prance[osv,icu,cli] Recommended (with OpenAPI validator, ICU, and CLI)

Imports

• ResolvingParser

  from prance import ResolvingParser

  The primary parser for specs with resolved references.
• BaseParser

  from prance import BaseParser

  For parsing specs without resolving references.

Quickstart

This quickstart demonstrates how to use `ResolvingParser` to load an OpenAPI/Swagger specification from a file (or URL) and access its fully resolved dictionary representation.

from prance import ResolvingParser
import os

# Example OpenAPI/Swagger spec content (YAML format for demonstration)
# In a real scenario, this would be loaded from a file or URL
spec_content = """
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /items:
    get:
      summary: Get all items
      responses:
        '200':
          description: A list of items
"""

# Create a dummy spec file for the example
with open('sample_spec.yaml', 'w') as f:
    f.write(spec_content)

try:
    # Initialize the parser with the path to your spec file
    parser = ResolvingParser('sample_spec.yaml')

    # The fully resolved specification is available as a dictionary
    resolved_spec = parser.specification
    print(f"API Title: {resolved_spec['info']['title']}")
    print(f"API Version: {resolved_spec['info']['version']}")
    print("Specification parsed successfully.")

    # Example with a URL (requires internet access)
    # parser = ResolvingParser('http://petstore.swagger.io/v2/swagger.json')
    # resolved_spec = parser.specification
    # print(f"Petstore API Title: {resolved_spec['info']['title']}")

finally:
    # Clean up the dummy spec file
    if os.path.exists('sample_spec.yaml'):
        os.remove('sample_spec.yaml')