Metadata-Version: 2.4
Name: apizit-linking
Version: 1.0.1
Summary: Declarative Python-to-HTTP binding for unchanged functions without framework decorators
Author: APIZIT
License-Expression: Apache-2.0
Project-URL: Homepage, https://chipsi44.github.io/apizit-linking-examples/
Project-URL: Documentation, https://chipsi44.github.io/apizit-linking-examples/quickstart/
Project-URL: Fit and limits, https://chipsi44.github.io/apizit-linking-examples/limits/#choose
Project-URL: Examples, https://github.com/chipsi44/apizit-linking-examples
Project-URL: Issues, https://github.com/chipsi44/apizit-linking-examples/issues
Project-URL: Changelog, https://github.com/chipsi44/apizit-linking-examples/blob/main/CHANGELOG.md
Project-URL: Release notes, https://chipsi44.github.io/apizit-linking-examples/releases/
Project-URL: Migration guide, https://chipsi44.github.io/apizit-linking-examples/migrations/
Project-URL: Security, https://chipsi44.github.io/apizit-linking-examples/security/
Keywords: api,api-framework,apizit,apizit-linking,declarative,fastapi,framework-independent,http,no-decorators,openapi,plain-python,python,python-api,routing,static-analysis,yaml
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0.3
Provides-Extra: models
Requires-Dist: pydantic<3,>=2.10.0; extra == "models"
Provides-Extra: fastapi
Requires-Dist: fastapi<1,>=0.115.0; extra == "fastapi"
Requires-Dist: python-multipart<1,>=0.0.18; extra == "fastapi"
Provides-Extra: preview
Requires-Dist: fastapi<1,>=0.115.0; extra == "preview"
Requires-Dist: python-multipart<1,>=0.0.18; extra == "preview"
Requires-Dist: uvicorn<1,>=0.30.0; extra == "preview"
Dynamic: license-file

# APIZIT Linking

**Python APIs with clear context for AI.** Keep the code. Add the API.
Write and test ordinary Python functions, define the HTTP contract separately,
and follow a route straight back to its source.

Linking is a standalone declarative JSON API framework. Its core requires PyYAML;
FastAPI serving and Pydantic models are optional extras. It needs no APIZIT account.

[Documentation](https://chipsi44.github.io/apizit-linking-examples/) ·
[Quickstart](https://chipsi44.github.io/apizit-linking-examples/quickstart/) ·
[Fork the examples](https://github.com/chipsi44/apizit-linking-examples) ·
[Issues](https://github.com/chipsi44/apizit-linking-examples/issues)

```python
# customer_service.py — existing business code stays unchanged
def create_customer(customer_name: str, age: int):
    return {"name": customer_name, "age": age}
```

```yaml
version: 1
routes:
  - path: /customers
    method: POST
    function: customer_service:create_customer
    parameters:
      customer_name:
        source: {location: body, name: name}
      age:
        source: {location: body, name: age}
    response: {status: 201}
```

## Install Linking 1.0

The **1.0.1** source finalizes registry-verified **1.0.1rc1**, including corrected
inline Annotated input/output signatures. Publication is confirmed by PyPI files
and the public release record; a merge or allocated tag alone is not proof.
The reserved v1.0.0 tag published no files and remains immutable.

Python 3.10–3.14, Apache-2.0. Pin the exact package for a reproducible deployment.
PyPI is the authority for published versions. The 1.0 contract follows Semantic
Versioning; production readiness of an application also depends on its hosting,
identity, storage and operational controls.

```text
python -m pip install "apizit-linking[preview,models]==1.0.1"
apizit-linking validate . --json
apizit-linking preview . --port 8080
```

For static tooling alone, install `apizit-linking==1.0.1`. Validation parses the
manifest and Python AST without importing customer code. Preview imports trusted
code, binds to loopback by default and requires `--allow-network` for other hosts.
It is a development server; [serve with ASGI](https://chipsi44.github.io/apizit-linking-examples/guides/standalone-serving/)
for an application-owned deployment.

## Three reasons to choose Linking

- **Two clear tasks.** Review Python behavior and its direct tests first, then
  review HTTP wiring. Existing libraries stay usable from scripts and jobs.
- **One route map.** Method and pattern lead to `module:function`, source file and
  line. JSON request events carry route IDs and a source fingerprint for diagnosis.
- **A checkable contract.** Static diagnostics, editor schema, typed OpenAPI and
  conservative contract comparison provide gates for proposed changes.

These properties help people and coding assistants find and review the relevant
context. They establish no universal improvement in token use, speed or reliability.
Flask blueprints and FastAPI routers/service layers can also separate business code.
Choose Linking for its external manifest and inspection workflow; choose a native
framework when its Python HTTP interface or broader ecosystem fits better.

## Build a persistent, protected API

Opt into `validation: typed` to prepare Pydantic input and output adapters, nested
models and their schemas. Body bindings accept RFC 6901 pointers. Omitted typed
mode retains legacy conversion; legacy return schemas remain documentary.

A separate `runtime.factory` registers named resource providers and guards.
Providers inject database connections and principals into ordinary functions;
request/application contexts manage acquisition and cleanup. Guards run in order,
fail closed and leave identity and owner policy to the application. Declarative
`response` and `errors` supply success status/headers and safe domain-error mappings.
204/205/HEAD omit bodies; unmapped errors return a generic JSON 500.

The [standalone SQLite example](https://chipsi44.github.io/apizit-linking-examples/guides/persistent-api/)
demonstrates nested models, transactions, owner permissions, process-restart
persistence and 201/204/400/401/403/404/409 without APIZIT. Applications own their
database, identity service, secrets, migrations and backups.

## Locate and control a change

```text
apizit-linking routes . --json
apizit-linking explain . --method GET --path /tasks/12 --json
apizit-linking export . --resolve-models --output before.json
# Edit the business code, then run its direct and HTTP tests.
apizit-linking validate . --json
apizit-linking export . --resolve-models --output after.json
apizit-linking diff before.json after.json --json
```

`--resolve-models` explicitly imports project code and prepares its runtime factory.
Static exports do not. Diff exits 0 for compatibility, 1 for changed/removed
contracts and 2 for invalid exports or unresolved typed changes. Compatible HTTP
does not prove business correctness. See [the diagnostic workflow](https://chipsi44.github.io/apizit-linking-examples/guides/trace-route-to-python/).

## Integration and limits

```python
from apizit_linking.fastapi import create_app
app = create_app(".")
```

The ASGI factories keep documentation disabled unless `docs=True`. Platforms can
compile with `compile_linking_file`, serialize `CompilationResult.to_runtime_dict()`
and load via `create_app_from_runtime_artifact`. Manifest schema v1 remains stable;
1.0 artifacts use format v2 and require the exact compiling engine version.
Recompile after every engine change; never vendor the engine into an adapter.

Opt-in `RequestLimits` bounds received body, query pairs, JSON structure and active
requests. Optional asynchronous business deadlines return 504 after cleanup.
Synchronous work cannot be forcibly stopped; external servers own connection,
header and process limits. Typed routes require HTTP-parameter and return annotations;
explicit Any supplies no filtering. Models and mutable instances follow Pydantic's
configuration and instance-revalidation policy. Legacy return schemas remain documentary.

There is no portable streaming/WebSocket contract, built-in ORM, identity provider,
deployment service or execution sandbox. Private import namespaces prevent module
collisions. Read [current limits](https://chipsi44.github.io/apizit-linking-examples/limits/#choose)
and [migration](https://chipsi44.github.io/apizit-linking-examples/migrations/).
APIZIT is a separate optional hosting platform.

## Development and documentation

```text
uv sync --locked --all-extras --all-groups
uv run python -m unittest discover -s tests -p "test_*.py"
uv run ruff check src tests
uv run black --check src tests
uv build --clear --build-constraints build-constraints.txt --require-hashes
```

CI checks source, real HTTP/restart/reload, minimum dependencies, core-only
installation, wheel installation on Linux/Windows/macOS and identical double
builds. Maintainer contracts and qualification evidence are in `docs/`.
English public documentation is edited once in the examples repository and
exported with source commit and hashes to APIZIT `/linking/`. GitHub Pages stays
public during the protected-site transition; `/docs/linking/` remains the SaaS guide.
