Skip to main content

rn-forge-web

Documentation · Changelog · Source · All pykit packages

Framework-agnostic HTTP/API primitives, built on rn-forge-commons.

These are the wire semantics an application promises its callers — W3C Trace Context propagation, the error body, the precondition contract, the pagination envelope, the idempotency contract, the readiness aggregate, the authentication contract, the OpenAPI naming rules, and the conformance table the framework packages are tested against.

Flat modules, all one kind of mechanism: inbound HTTP wire semantics.

Where it sits

rn-forge-web depends on rn-forge-commons and nothing else in the workspace. It never imports rn_forge.cli or rn_forge.tooling — those are the command-line and file-owning layers, and a package that ships into an ASGI server has no business reaching either. It never imports a web framework: not django, not fastapi, not starlette, not rest_framework. task lint proves them.

Inbound, not outbound

The tempting rule is "everything HTTP lives in rn-forge-web", and it is wrong. A circuit breaker, a retry policy and a token bucket are transport-agnostic: a worker retrying a database call, a CLI retrying a blob upload and an LLM adapter backing off all need them, and none of them speaks server-side HTTP. Those live in rn_forge.commons.integration.resilience, so that an Azure Blob or Key Vault adapter package can depend on commons alone rather than dragging ASGI middleware and cursor codecs into a process that serves no requests.

The one concern that runs the other way is problem_from_body, which parses an upstream's application/problem+json back into a ProblemDetail. It takes a parsed mapping and a status — not a response object — precisely so no HTTP client library is pulled in either direction.

What stays in a framework package

Logic that both framework packages need lives here, as framework-free functions: rendering a problem response (render_problem), the field-error entry (field_error), reading the current trace id, parsing an Authorization header, requiring an idempotency key, the liveness body and the OpenAPI problem-response declarations. rn-forge-django and rn-forge-fastapi keep only the code that reads their framework's native shapes (a DRF error tree, a pydantic error list, a Starlette exception) and writes their framework's native response.

Installation

Require the package by version range:

dependencies = ["rn-forge-web>=0.3,<0.4"]

Its dependencies are rn-forge-commons[pydantic] and opentelemetry-api. The security extra adds secure, for rn_forge.web.security; the testing extra adds assertpy and pytest.

Minimum example

from rn_forge.web import default_registry, render_problem

registry = default_registry()
rendered = render_problem(registry, exc, instance="/orders/1")
# rendered.status, rendered.body, rendered.headers: application/problem+json

Errors

Every exception here is an AppException and renders as an RFC 9457 application/problem+json body: AuthenticationFailed 401, PermissionDenied 403, VersionConflict 412, PreconditionRequired 428. A 5xx carries a fixed generic detail, never str(exc).

Dependencies and why

rn-forge-commons — AppException (every exception here subclasses it, so a consumer already catching that catches these), through its pydantic extra.

pydantic, through that extra — models.py holds WireModel, the camelCase base, and ProblemDetail, Page[T], CheckResult and HealthReport are WireModel subclasses. Both framework packages use them directly: FastAPI as request and response models, Django for its OpenAPI components and health bodies. rn-forge-django therefore installs pydantic transitively.

secure (2.0.1), behind this package's own security extra — and only for rn_forge.web.security. It is framework-agnostic (no dependencies of its own) and emits the OWASP REST Security Cheat Sheet header preset exactly, so it is wrapped rather than hand-rolled. Behind an extra and excluded from the curated __init__.py so the rest of the package stays dependency-free; import rn_forge.web.security directly.

opentelemetry-api, a base dependency — and only for rn_forge.web.tracing. W3C Trace Context is read through OpenTelemetry's active-span API, following OpenTelemetry's own library guidance: a library depends on the API only, which is a no-op until the application configures the SDK. This package never configures a TracerProvider or an exporter.

Nothing else beyond those. The problem shape, ETag preconditions, cursor pagination, idempotency and health aggregation are implemented here: the maintained libraries for each either depend on a web framework or fix a different wire shape.

Documentation

task docs:build builds every site. docs/guides/api-conventions.md is the normative wire contract for an application's specification. docs/guides/model-conventions.md compares implemented ORM building blocks and optional application design advice.

Metadata

Release files for rn-forge-web 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rn-forge-web 0.3.3
File Size Uploaded Provenance Actions
rn_forge_web-0.3.3.tar.gz 58.5 kB With provenance Details for rn_forge_web-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rn-forge-web 0.3.3
File Interpreter ABI Platform Actions
rn_forge_web-0.3.3-py3-none-any.whl Python 3 none any Details for rn_forge_web-0.3.3-py3-none-any.whl

Total release size: 129.4 kB

Release files / rn_forge_web-0.3.3.tar.gz

Download URL rn_forge_web-0.3.3.tar.gz
Size 58.5 kB
Tags Source
SHA-256 checksum
How to use checksums
53d93e3a602658d11f31fe8bb16a6255065ba74265c5922cdcc4f1574581d858
BLAKE2b-256 checksum
How to use checksums
81f9475fbaa061e44f1376e57db4939f8db61c5526718dbaa51915844d08b661
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / rn_forge_web-0.3.3-py3-none-any.whl

Download URL rn_forge_web-0.3.3-py3-none-any.whl
Size 70.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bc7ee0936f703119b8e0200d990867637898c0aad41ecb1a7f26377ff05248f9
BLAKE2b-256 checksum
How to use checksums
30d7fc81a00900d7dccde46a7b5d6c1d28536189ab63eb78f57786555af6c453
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for rn-forge-web 0.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rn_forge_web-0.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page