py2axum 0.1.0__tar.gz

py2axum-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+target/
+__pycache__/
+.pytest_cache/
+*.tar.gz
+*.bundle
+.venv/
+.cargo/
+.cache/
+logs/
+reports/
+# generated crates, except the typed backend's committed reference output
+generated/*
+!generated/app_axum/
+storage-test/
+dist/
+*.egg-info/

py2axum-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+- aio-pika 10: connect, channels, durable queues, publishing with confirms, `queue.get()`.
+- `json.loads` accepts bytes (UTF-8/16/32 detection, like CPython).
+- `importlib.import_module` of a literal project module (module objects), `callable()`.
+- `collections.defaultdict` (builtin type factories), `string.Formatter().vformat/format`; `str.format`
+  gains `!r`/`!s` and CPython's error messages.
+- tenacity 9 (`@retry` and its strategies). `g`/`e`/`G`/`E`/`X`/`o`/`b` presentations and `#` in `format()`
+  and `%`; `ConnectionError` and its subclasses; `logging` level constants and `Logger.log`.
+
+## [0.1.0] — first public release
+
+- Ahead-of-time compilation of FastAPI + SQLAlchemy 2.0 (async, PostgreSQL) + Pydantic v2 applications to
+  Rust (axum, tokio, sqlx): the **dyn** backend (general) and the **typed** backend (simple CRUD).
+- Runtime reproducing CPython, Pydantic v2, SQLAlchemy and Starlette semantics, plus a closed list of
+  standard and third-party libraries ([docs/supported.md](docs/supported.md)).
+- `--report`: per-route coverage report with the first blocking construct (`file:line`).
+- `--python-side`: paths and `lifespan` left to the Python application, relayed by the binary when
+  `PY2AXUM_PYTHON_URL` is set.
+- Differential conformance harness (`tests/conformance.py`) and reference applications.
+- `pip install`-able package with a `py2axum` command; example application with a multi-stage Dockerfile.

py2axum-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to py2axum
+
+Thanks for helping! The most useful contributions are **real constructs that do not translate yet** and
+**behaviours that differ from Python**.
+
+## Reporting a construct or a difference
+
+Open an issue with:
+
+1. the smallest Python snippet that shows it (a route is ideal);
+2. what FastAPI answers (status, headers, body) and what the binary answers, or py2axum's error message;
+3. the versions involved (Python, FastAPI, Pydantic, SQLAlchemy — or your `uv.lock`).
+
+`py2axum <package> --root <root> --report coverage.md` lists, per route, the first blocking construct with
+`file:line`: attach the relevant lines.
+
+## Development setup
+
+```bash
+uv venv && uv pip install -e ".[dev,conformance]"
+python -m pytest                     # transpiler tests (rejections, report)
+```
+
+Conformance suites need PostgreSQL (and Redis and RabbitMQ for `dynapp`):
+
+```bash
+createdb py2axum_dyn
+export DATABASE_URL=postgresql://postgres@127.0.0.1/py2axum_dyn
+python -m py2axum fixtures/dynapp --root . --backend dyn --python-side '/dunders/proxied/{name}' \
+    -o generated/dynapp_axum --name dynapp_axum
+(cd generated/dynapp_axum && RUSTFLAGS="-D warnings" cargo build --release)
+python -c "from tests.scenarios import dynapp; dynapp.reset('$DATABASE_URL')"
+./scripts_start_dyn.sh
+python tests/conformance.py http://127.0.0.1:8200 http://127.0.0.1:8280 --scenario dynapp
+```
+
+## The rules of the project
+
+1. **Observable equivalence.** A translated construct behaves like Python: status, headers, content type and
+   body bytes (JSON key order, Pydantic error details). Every new behaviour comes with a conformance case in
+   a fixture app (`fixtures/`) compared against FastAPI.
+2. **Refuse rather than guess.** What the runtime cannot reproduce is refused at compile time with a
+   `TranspileError` pointing at `file:line`, and a test in `tests/test_rejects_dyn.py`. Never translate a
+   construct approximately and silently.
+3. **Document every difference** in [docs/supported.md](docs/supported.md).
+4. **Library behaviour follows the project's locked version** (`uv.lock`) when it changed across versions.
+5. The generated crate must build with `RUSTFLAGS="-D warnings"`; never edit generated code by hand — fix the
+   transpiler or the runtime.
+
+## Where things are
+
+- `py2axum/dyn.py` — the compiler of project code (dyn backend); `libmap.py` — the library map.
+- `py2axum/runtime/dynrt/*.rs` — the runtime (one module per area or library).
+- `fixtures/dynapp/` — the reference app; add your case to the module that fits (or a new router) and a
+  request to `tests/scenarios/dynapp.py`.
+
+## Pull requests
+
+Keep them focused, describe the Python behaviour you reproduce (with the library version), and include the
+conformance result. By contributing you agree that your contribution is licensed under the Apache License 2.0.
+
+## Releasing
+
+1. Update `version` in `pyproject.toml` and `CHANGELOG.md`; tag `vX.Y.Z` and create the GitHub release.
+2. Run the **Publish to PyPI** workflow on that tag (Trusted Publishing: the PyPI project's trusted
+   publisher names this repository, `release.yml` and the `pypi` environment).

py2axum-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

py2axum-0.1.0/NOTICE

@@ -0,0 +1,5 @@
+py2axum
+Copyright 2026 Larry Motalavigne
+
+This product includes software developed as part of the py2axum project
+(https://github.com/larrymotalavigne/py2axum), licensed under the Apache License, Version 2.0.

py2axum-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: py2axum
+Version: 0.1.0
+Summary: Ahead-of-time compiler from FastAPI + SQLAlchemy + Pydantic applications to Rust (axum), with response-level conformance testing
+Project-URL: Homepage, https://github.com/larrymotalavigne/py2axum
+Project-URL: Issues, https://github.com/larrymotalavigne/py2axum/issues
+Author: Larry Motalavigne
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: axum,compiler,fastapi,performance,pydantic,rust,sqlalchemy,transpiler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.12
+Provides-Extra: conformance
+Requires-Dist: fastapi>=0.115; extra == 'conformance'
+Requires-Dist: httpx>=0.27; extra == 'conformance'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'conformance'
+Requires-Dist: pydantic[email]>=2.9; extra == 'conformance'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'conformance'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'conformance'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# py2axum
+
+**Compile a FastAPI + SQLAlchemy + Pydantic application ahead of time into a Rust ([axum](https://github.com/tokio-rs/axum)) binary — and prove, response by response, that it behaves like the Python app.**
+
+You keep writing, testing and debugging your API in idiomatic Python. `py2axum` reads the source (it never imports or runs it), compiles every route and the project code it reaches into Rust over a small runtime that reproduces CPython, Pydantic v2, SQLAlchemy 2.0 (async) and Starlette semantics, and produces a self-contained binary for production.
+
+```
+app/ (FastAPI)  ──py2axum──▶  Rust crate (axum + tokio + sqlx)  ──cargo──▶  one static-ish binary
+```
+
+On the bundled example ([`examples/notes`](examples/notes)), same machine (Apple M1 Pro), same PostgreSQL, 4 uvicorn workers vs 4 tokio threads, 64 connections:
+
+| Endpoint | FastAPI + uvicorn | py2axum binary | |
+|---|---:|---:|---:|
+| `GET /notes/1` (1 SELECT + relationship) | 4 276 req/s, p99 40 ms | **17 674 req/s, p99 4.1 ms** | ×4.1 |
+| `GET /notes?limit=20` | 3 149 req/s, p99 47 ms | **11 822 req/s, p99 6.9 ms** | ×3.8 |
+| `GET /health` | 76 712 req/s | **130 105 req/s** | ×1.7 |
+
+The binary used 19 MB of RSS under load. Gains depend on how much of your request time is Python (validation, serialization, ORM) versus the database: measure your own app with `bench/`.
+
+> **Status: alpha.** py2axum translates a *closed, growing subset* of Python and of a list of libraries. Anything outside it is **refused at compile time with `file:line`** — never approximated silently. A per-route coverage report tells you what blocks and what each fix would unlock.
+
+## Why
+
+- **Equivalence you can check.** Every supported behaviour is verified by differential testing: the same requests are sent to FastAPI and to the binary, and status, headers, content type and bodies must match **byte for byte** (JSON key order, Pydantic 422 error details and messages included). The project's own suites run 350+ such requests.
+- **No rewrite, no fork.** The Python app stays the source of truth: unit tests, debugging, local development and the OpenAPI docs keep working as before.
+- **Incremental.** Routes or ASGI apps that cannot be translated can stay in Python (`--python-side`): the binary relays them to a Python process, so one deployment serves both.
+
+## Quick start
+
+```bash
+pip install git+https://github.com/larrymotalavigne/py2axum     # Python ≥ 3.12, no dependencies (PyPI soon)
+
+# what would translate, route by route (nothing is generated)
+py2axum examples/notes/app --root examples/notes --report coverage.md
+
+# generate the Rust crate, build it, run it
+py2axum examples/notes/app --root examples/notes --backend dyn -o build/notes --name notes
+cargo build --release --manifest-path build/notes/Cargo.toml
+DATABASE_URL=postgresql://postgres@localhost/notes PORT=8080 ./build/notes/target/release/notes
+```
+
+The binary reads `DATABASE_URL`, `HOST` (`0.0.0.0`), `PORT` (`8080`), plus whatever your code reads from the environment (`os.environ`, pydantic-settings). It does not create tables: run your migrations as usual.
+
+Run the transpiler on a Python **at least as recent** as the one your app targets (the parser only knows its own syntax). Library behaviours that changed between versions (Starlette's CORS, Pydantic error URLs, CPython messages) follow the versions pinned in your project's `uv.lock`.
+
+## In a Dockerfile
+
+```dockerfile
+FROM python:3.13-slim AS transpile
+RUN pip install --no-cache-dir git+https://github.com/larrymotalavigne/py2axum
+WORKDIR /src
+COPY . .
+RUN py2axum app --root . --backend dyn -o /crate --name api
+
+FROM rust:1-bookworm AS build
+WORKDIR /crate
+COPY --from=transpile /crate .
+RUN cargo build --release
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=build /crate/target/release/api /usr/local/bin/api
+EXPOSE 8080
+CMD ["api"]
+```
+
+See [docs/docker.md](docs/docker.md) for caching the cargo build, the hybrid setup (binary + Python sidecar for `--python-side` routes) and a docker-compose file.
+
+## Verify your own app
+
+```bash
+# reference and candidate on the same database, reset between runs
+python tests/conformance.py http://127.0.0.1:8000 http://127.0.0.1:8080 --scenario myapp
+```
+
+A scenario is a list of requests plus a `reset()` function ([docs/conformance.md](docs/conformance.md), [`tests/scenarios/notes.py`](tests/scenarios/notes.py)). The harness prints every difference with both responses.
+
+## What is supported
+
+A summary — the full list, with every documented difference from CPython, is in [docs/supported.md](docs/supported.md).
+
+- **FastAPI / Starlette**: routes and routers (prefixes, factories, conditional registration), path/query/header/body/form/file parameters with FastAPI's exact 422 errors, dependencies (`Depends`, `yield`, per-request cache, `Annotated` aliases, OAuth2/HTTPBearer), `response_model` filtering, returned `Response` objects, `StreamingResponse`/SSE, `BackgroundTasks`, exception handlers, the middleware stack (`CORSMiddleware`, `GZipMiddleware`, `BaseHTTPMiddleware`, `@app.middleware("http")`), Starlette routing (405, trailing-slash redirects).
+- **Pydantic v2**: lax-mode validation with pydantic-core's error types and messages, unions, enums, `Field` constraints and aliases, validators (`field_validator`/`model_validator`, before/after), computed defaults, `model_dump`/`model_validate`/`model_copy`, `TypeAdapter`, frozen models, URL and email types, `BaseSettings`.
+- **SQLAlchemy 2.0 async**: declarative models (composite keys, `Identity`, JSON/JSONB, enums, `Numeric`, `TypeDecorator`), sessions (identity map, autoflush, `expire_on_commit`, savepoints, refresh, rollback), relationships and loader strategies, `select`/`update`/`delete`/`insert ... on conflict`, joins, aliases, subqueries, aggregates, `case`, `text()`.
+- **Python**: functions, closures, decorators, classes (with `__eq__`/`__str__`/`__aenter__`...), dataclasses, exceptions, comprehensions, generators, `match`, coroutines and `asyncio` (`gather`, tasks, locks), `threading`, `pickle` (CPython-compatible bytes), `datetime`/`decimal`/`uuid`/`re`/`json`/`csv`/`base64`/`hashlib`/`hmac`/`math`/`urllib.parse`...
+- **Libraries**: httpx and aiohttp clients, redis.asyncio, python-jose (HMAC), bcrypt, pyotp, itsdangerous, cryptography's Fernet, jinja2 + `email` + aiosmtplib, pywebpush, google-auth id tokens, alembic config, psutil.
+
+Not translated (stay in Python with `--python-side`, or refused): WebSockets, `lifespan`, other libraries, arbitrary `eval`/reflection, C extensions.
+
+## How it works
+
+1. **Frontend** — indexes the package's modules and imports statically (`ast`), finds the FastAPI app(s), routers, routes, models and schemas.
+2. **Backends** — a *typed* backend emits idiomatic statically-typed Rust for simple CRUD handlers; the *dyn* backend (the general one) compiles every reachable project function to Rust over a dynamic value type with CPython semantics. Library calls go through a closed map (`py2axum/libmap.py`): anything unlisted is refused.
+3. **Runtime** — `py2axum/runtime/dynrt/` (Rust, copied into each generated crate): values and operators, Pydantic validation and serialization, the SQLAlchemy session and SQL compiler (on sqlx/PostgreSQL), Starlette's middleware and routing, and the supported libraries.
+
+Details: [docs/how-it-works.md](docs/how-it-works.md).
+
+## Project layout
+
+```
+py2axum/            the transpiler (Python, stdlib only) and the Rust runtime it embeds
+examples/notes/     a small API + Dockerfile, translated in full
+fixtures/           reference apps exercising the supported subset (used by the test suites)
+tests/              conformance harness and scenarios, rejection tests
+bench/              throughput / latency / memory benchmarks
+docs/               documentation
+```
+
+## Contributing
+
+Contributions are welcome — especially failing constructs from real applications. See [CONTRIBUTING.md](CONTRIBUTING.md). The rule that keeps the project honest: every new behaviour comes with a conformance case comparing it to the Python reference, and every unsupported case is refused with a test.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

py2axum-0.1.0/README.md

@@ -0,0 +1,116 @@
+# py2axum
+
+**Compile a FastAPI + SQLAlchemy + Pydantic application ahead of time into a Rust ([axum](https://github.com/tokio-rs/axum)) binary — and prove, response by response, that it behaves like the Python app.**
+
+You keep writing, testing and debugging your API in idiomatic Python. `py2axum` reads the source (it never imports or runs it), compiles every route and the project code it reaches into Rust over a small runtime that reproduces CPython, Pydantic v2, SQLAlchemy 2.0 (async) and Starlette semantics, and produces a self-contained binary for production.
+
+```
+app/ (FastAPI)  ──py2axum──▶  Rust crate (axum + tokio + sqlx)  ──cargo──▶  one static-ish binary
+```
+
+On the bundled example ([`examples/notes`](examples/notes)), same machine (Apple M1 Pro), same PostgreSQL, 4 uvicorn workers vs 4 tokio threads, 64 connections:
+
+| Endpoint | FastAPI + uvicorn | py2axum binary | |
+|---|---:|---:|---:|
+| `GET /notes/1` (1 SELECT + relationship) | 4 276 req/s, p99 40 ms | **17 674 req/s, p99 4.1 ms** | ×4.1 |
+| `GET /notes?limit=20` | 3 149 req/s, p99 47 ms | **11 822 req/s, p99 6.9 ms** | ×3.8 |
+| `GET /health` | 76 712 req/s | **130 105 req/s** | ×1.7 |
+
+The binary used 19 MB of RSS under load. Gains depend on how much of your request time is Python (validation, serialization, ORM) versus the database: measure your own app with `bench/`.
+
+> **Status: alpha.** py2axum translates a *closed, growing subset* of Python and of a list of libraries. Anything outside it is **refused at compile time with `file:line`** — never approximated silently. A per-route coverage report tells you what blocks and what each fix would unlock.
+
+## Why
+
+- **Equivalence you can check.** Every supported behaviour is verified by differential testing: the same requests are sent to FastAPI and to the binary, and status, headers, content type and bodies must match **byte for byte** (JSON key order, Pydantic 422 error details and messages included). The project's own suites run 350+ such requests.
+- **No rewrite, no fork.** The Python app stays the source of truth: unit tests, debugging, local development and the OpenAPI docs keep working as before.
+- **Incremental.** Routes or ASGI apps that cannot be translated can stay in Python (`--python-side`): the binary relays them to a Python process, so one deployment serves both.
+
+## Quick start
+
+```bash
+pip install git+https://github.com/larrymotalavigne/py2axum     # Python ≥ 3.12, no dependencies (PyPI soon)
+
+# what would translate, route by route (nothing is generated)
+py2axum examples/notes/app --root examples/notes --report coverage.md
+
+# generate the Rust crate, build it, run it
+py2axum examples/notes/app --root examples/notes --backend dyn -o build/notes --name notes
+cargo build --release --manifest-path build/notes/Cargo.toml
+DATABASE_URL=postgresql://postgres@localhost/notes PORT=8080 ./build/notes/target/release/notes
+```
+
+The binary reads `DATABASE_URL`, `HOST` (`0.0.0.0`), `PORT` (`8080`), plus whatever your code reads from the environment (`os.environ`, pydantic-settings). It does not create tables: run your migrations as usual.
+
+Run the transpiler on a Python **at least as recent** as the one your app targets (the parser only knows its own syntax). Library behaviours that changed between versions (Starlette's CORS, Pydantic error URLs, CPython messages) follow the versions pinned in your project's `uv.lock`.
+
+## In a Dockerfile
+
+```dockerfile
+FROM python:3.13-slim AS transpile
+RUN pip install --no-cache-dir git+https://github.com/larrymotalavigne/py2axum
+WORKDIR /src
+COPY . .
+RUN py2axum app --root . --backend dyn -o /crate --name api
+
+FROM rust:1-bookworm AS build
+WORKDIR /crate
+COPY --from=transpile /crate .
+RUN cargo build --release
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/*
+COPY --from=build /crate/target/release/api /usr/local/bin/api
+EXPOSE 8080
+CMD ["api"]
+```
+
+See [docs/docker.md](docs/docker.md) for caching the cargo build, the hybrid setup (binary + Python sidecar for `--python-side` routes) and a docker-compose file.
+
+## Verify your own app
+
+```bash
+# reference and candidate on the same database, reset between runs
+python tests/conformance.py http://127.0.0.1:8000 http://127.0.0.1:8080 --scenario myapp
+```
+
+A scenario is a list of requests plus a `reset()` function ([docs/conformance.md](docs/conformance.md), [`tests/scenarios/notes.py`](tests/scenarios/notes.py)). The harness prints every difference with both responses.
+
+## What is supported
+
+A summary — the full list, with every documented difference from CPython, is in [docs/supported.md](docs/supported.md).
+
+- **FastAPI / Starlette**: routes and routers (prefixes, factories, conditional registration), path/query/header/body/form/file parameters with FastAPI's exact 422 errors, dependencies (`Depends`, `yield`, per-request cache, `Annotated` aliases, OAuth2/HTTPBearer), `response_model` filtering, returned `Response` objects, `StreamingResponse`/SSE, `BackgroundTasks`, exception handlers, the middleware stack (`CORSMiddleware`, `GZipMiddleware`, `BaseHTTPMiddleware`, `@app.middleware("http")`), Starlette routing (405, trailing-slash redirects).
+- **Pydantic v2**: lax-mode validation with pydantic-core's error types and messages, unions, enums, `Field` constraints and aliases, validators (`field_validator`/`model_validator`, before/after), computed defaults, `model_dump`/`model_validate`/`model_copy`, `TypeAdapter`, frozen models, URL and email types, `BaseSettings`.
+- **SQLAlchemy 2.0 async**: declarative models (composite keys, `Identity`, JSON/JSONB, enums, `Numeric`, `TypeDecorator`), sessions (identity map, autoflush, `expire_on_commit`, savepoints, refresh, rollback), relationships and loader strategies, `select`/`update`/`delete`/`insert ... on conflict`, joins, aliases, subqueries, aggregates, `case`, `text()`.
+- **Python**: functions, closures, decorators, classes (with `__eq__`/`__str__`/`__aenter__`...), dataclasses, exceptions, comprehensions, generators, `match`, coroutines and `asyncio` (`gather`, tasks, locks), `threading`, `pickle` (CPython-compatible bytes), `datetime`/`decimal`/`uuid`/`re`/`json`/`csv`/`base64`/`hashlib`/`hmac`/`math`/`urllib.parse`...
+- **Libraries**: httpx and aiohttp clients, redis.asyncio, python-jose (HMAC), bcrypt, pyotp, itsdangerous, cryptography's Fernet, jinja2 + `email` + aiosmtplib, pywebpush, google-auth id tokens, alembic config, psutil.
+
+Not translated (stay in Python with `--python-side`, or refused): WebSockets, `lifespan`, other libraries, arbitrary `eval`/reflection, C extensions.
+
+## How it works
+
+1. **Frontend** — indexes the package's modules and imports statically (`ast`), finds the FastAPI app(s), routers, routes, models and schemas.
+2. **Backends** — a *typed* backend emits idiomatic statically-typed Rust for simple CRUD handlers; the *dyn* backend (the general one) compiles every reachable project function to Rust over a dynamic value type with CPython semantics. Library calls go through a closed map (`py2axum/libmap.py`): anything unlisted is refused.
+3. **Runtime** — `py2axum/runtime/dynrt/` (Rust, copied into each generated crate): values and operators, Pydantic validation and serialization, the SQLAlchemy session and SQL compiler (on sqlx/PostgreSQL), Starlette's middleware and routing, and the supported libraries.
+
+Details: [docs/how-it-works.md](docs/how-it-works.md).
+
+## Project layout
+
+```
+py2axum/            the transpiler (Python, stdlib only) and the Rust runtime it embeds
+examples/notes/     a small API + Dockerfile, translated in full
+fixtures/           reference apps exercising the supported subset (used by the test suites)
+tests/              conformance harness and scenarios, rejection tests
+bench/              throughput / latency / memory benchmarks
+docs/               documentation
+```
+
+## Contributing
+
+Contributions are welcome — especially failing constructs from real applications. See [CONTRIBUTING.md](CONTRIBUTING.md). The rule that keeps the project honest: every new behaviour comes with a conformance case comparing it to the Python reference, and every unsupported case is refused with a test.
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).

py2axum-0.1.0/docs/conformance.md

@@ -0,0 +1,56 @@
+# Checking that the binary behaves like your application
+
+`tests/conformance.py` sends the same requests to two servers — the FastAPI application (reference) and the
+binary (candidate) — on a database reset before each run, and compares, for every request: status, content
+type, encoding, `Allow`/`Location`/`WWW-Authenticate`, cookies, middleware headers (CORS, `Vary`...) and the
+body (JSON compared after parsing with key order kept, other bodies byte for byte).
+
+## Write a scenario
+
+A scenario is a module in `tests/scenarios/`:
+
+```python
+# tests/scenarios/myapp.py
+SETTLE = 0.2          # optional: pause after writes (FastAPI commits after the response)
+
+STEPS = [
+    ("GET", "/health", None),
+    ("POST", "/items", {"name": "a"}),                       # JSON body
+    ("POST", "/upload", b"raw", {"content-type": "text/plain"}),   # bytes body + headers
+    ("GET", "/items?limit=0", None),                         # a 422
+]
+
+def reset(db: str) -> None:
+    """Bring the database (DATABASE_URL) back to the initial state, e.g. TRUNCATE ... RESTART IDENTITY."""
+
+def normalize(body):  # optional: mask values that legitimately differ (random tokens, timestamps)
+    return body
+```
+
+`HEADER_MASKS` and `COOKIE_MASKS` mask header or cookie values that are random on both sides.
+
+## Run it
+
+```bash
+export DATABASE_URL=postgresql://postgres@127.0.0.1/myapp_conformance   # a dedicated database
+uvicorn app.main:app --port 8000 &                                      # reference
+PORT=8080 ./target/release/api &                                        # candidate
+python tests/conformance.py http://127.0.0.1:8000 http://127.0.0.1:8080 --scenario myapp
+```
+
+The output lists every step (`ok` / `DIFF` with both responses) and ends with `N/N identical responses`.
+Options: `--ignore-encoding` (compare bodies regardless of gzip). Datetimes generated at request time are
+masked automatically.
+
+## The repository's own suites
+
+| Scenario | Application | Requests |
+|---|---|---:|
+| `dynapp` | `fixtures/dynapp`: the dyn backend's reference app (every supported construct) | 418 |
+| `factoryapp` | `fixtures/factoryapp`: app factory, middleware stack, exception handlers | 25 |
+| `notes` | `examples/notes` | 24 |
+| `app` | `app/`: the typed backend's reference app | 40 |
+
+`dynapp` needs PostgreSQL, Redis (database 13 is flushed), RabbitMQ (`BROKER_DSN`, default
+`amqp://guest:guest@localhost:5672/`; its `py2axum_test_*` queues are deleted) and the web-push sink (`tests/push_sink.py`,
+started by `scripts_start_dyn.sh`).