APICORE_Python

APICORE access framework for Python

Main Repo

APICORE

High-performance APICORE parser and validator for APICORE v1 and v2.

A collaboration by Little Tree Studio and SRInternet Studio.

Features

• Import name is apicore, while the published package name is APICORE_Python.
• Uses orjson for fast JSON decoding.
• Uses ruamel.yaml with ruamel.yaml.clib for YAML decoding.
• Keeps msgspec for fast TOML decoding.
• Supports APICORE v1 and v2 with a single API.
• Defaults to v2 when APICORE_version is omitted, unless you manually force version="v1".
• Preserves custom v2 parameter fields in Parameter.extra.
• Includes a CLI validator for release pipelines and local checks.
• Includes a desktop GUI validator for interactive file and folder inspection.
• Exposes typed document models plus APICoreError, ParseError, and ValidationError for precise error handling.

Install

uv add APICORE_Python

or

pip install APICORE_Python

Quick Start

from apicore import __version__, load, loads

print(__version__)

document = load("example.api.yaml")
print(document.apicore_version)

inline = loads("""
friendly_name: Demo
link: https://api.example.com/v2/generate
func: POST
parameters:
	- name: api_key
		type: string
		friendly_name: API Key
		value: ''
response:
	image:
		content_type: URL
		path: data.output.url
""", format="yaml")

forced_v1 = loads("""
{
	"friendly_name": "Legacy",
	"link": "https://api.example.com/legacy",
	"func": "POST",
	"APICORE_version": "1.0",
	"parameters": [],
	"response": {
		"image": {
			"content_type": "URL",
			"path": "data.image.url"
		}
	}
}
""", version="v1")

CLI

apicore-validate path/to/config.api.yaml
apicore-validate path/to/config.api.json --version v1

Desktop GUI

apicore-gui

The GUI lets you open files or folders, validate multiple APICORE documents, and inspect parsed metadata, parameters, response mappings, configs, and handlers.

Error Handling

from apicore import load
from apicore.errors import APICoreError, ParseError, ValidationError

try:
	doc = load("example.api.yaml")
except ParseError as exc:
	print(f"Syntax error: {exc}")
except ValidationError as exc:
	print(f"Schema error: {exc}")
except APICoreError as exc:
	print(f"APICORE error: {exc}")

Benchmark

uv run python benchmarks/parse_benchmark.py

Release Workflow

uv sync --all-groups
uv run pytest -q
uv build
uv run --with twine twine check dist/*

Detailed release steps are in RELEASING.md.

Documentation

Full documentation is available on the GitHub Wiki.

• Wiki home: docs/Home.md
• API reference: docs/API-Reference.md
• CLI and GUI: docs/CLI.md
• Data models: docs/Models.md
• Errors: docs/Errors.md
• Changelog summary: docs/Changelog.md