fastapi-oneshot 0.1.0__py3-none-any.whl

fastapi_oneshot/__init__.py

@@ -0,0 +1,3 @@
+from fastapi_oneshot.runner import get_argv
+
+__all__ = ["get_argv"]

fastapi_oneshot/cli.py

@@ -0,0 +1,50 @@
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from fastapi_oneshot.runner import ScriptExit, ScriptLoadError, load_app, run
+
+
+def split_at_double_dash(args: list[str]) -> tuple[list[str], list[str]]:
+    if "--" not in args:
+        return args, []
+    index = args.index("--")
+    return args[:index], args[index + 1 :]
+
+
+def main() -> None:
+    cli_args, script_argv = split_at_double_dash(sys.argv[1:])
+    parser = argparse.ArgumentParser(
+        prog="fastapi-oneshot",
+        usage="%(prog)s SCRIPT --app MODULE:ATTR [-- SCRIPT_ARG ...]",
+        description="Run a script's main function with a FastAPI app's dependencies.",
+    )
+    parser.add_argument(
+        "script", type=Path, metavar="SCRIPT", help="script file that defines main"
+    )
+    parser.add_argument(
+        "--app",
+        required=True,
+        metavar="MODULE:ATTR",
+        help="import string of the FastAPI instance, e.g. myapp.main:app",
+    )
+    args = parser.parse_args(cli_args)
+
+    sys.path.insert(0, os.getcwd())
+    try:
+        app = load_app(args.app)
+        response = run(app, args.script, script_argv)
+    except ScriptLoadError as error:
+        parser.error(str(error))
+    except ScriptExit as error:
+        sys.exit(error.code)
+
+    if not response.is_success:
+        print(
+            f"fastapi-oneshot: request failed with status {response.status_code}",
+            file=sys.stderr,
+        )
+        if response.text:
+            print(response.text, file=sys.stderr)
+        sys.exit(1)

fastapi_oneshot/runner.py

@@ -0,0 +1,153 @@
+import asyncio
+import importlib
+import importlib.util
+import inspect
+import sys
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Any
+
+import httpx
+from fastapi import FastAPI
+from starlette.types import Receive, Scope, Send
+
+ROUTE_PATH = "/__fastapi_oneshot__"
+SCRIPT_MODULE_NAME = "__oneshot_script__"
+
+
+class ScriptLoadError(Exception):
+    """The --app target or the script cannot be loaded; the CLI maps it to exit 2."""
+
+
+class ScriptExit(Exception):
+    """SystemExit raised by main, carried through the app as an Exception."""
+
+    def __init__(self, code: str | int | None) -> None:
+        super().__init__(code)
+        self.code = code
+
+
+def get_argv() -> list[str]:
+    raise RuntimeError(
+        "get_argv is provided by fastapi-oneshot; it is only available "
+        "inside a script run with the fastapi-oneshot command"
+    )
+
+
+def load_app(app_spec: str) -> FastAPI:
+    module_name, _, attr = app_spec.rpartition(":")
+    if not module_name or not attr:
+        raise ScriptLoadError("--app must be in MODULE:ATTR form")
+
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as error:
+        if error.name is not None and (
+            module_name == error.name or module_name.startswith(error.name + ".")
+        ):
+            raise ScriptLoadError(f"cannot import module {module_name!r}") from error
+        raise
+
+    if not hasattr(module, attr):
+        raise ScriptLoadError(f"module {module_name!r} has no attribute {attr!r}")
+    app = getattr(module, attr)
+    if not isinstance(app, FastAPI):
+        raise ScriptLoadError("--app must point to a FastAPI instance")
+    return app
+
+
+def load_main(script_path: Path) -> Callable[..., Any]:
+    if not script_path.is_file():
+        raise ScriptLoadError(f"script {script_path} is not a file")
+    spec = importlib.util.spec_from_file_location(SCRIPT_MODULE_NAME, script_path)
+    if spec is None or spec.loader is None:
+        raise ScriptLoadError("script must be a .py file")
+
+    sys.path.insert(0, str(script_path.resolve().parent))
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[SCRIPT_MODULE_NAME] = module
+    spec.loader.exec_module(module)
+
+    if not hasattr(module, "main"):
+        raise ScriptLoadError(f"script {script_path} defines no main function")
+    main = module.main
+    if not inspect.isfunction(main):
+        raise ScriptLoadError("main must be a function defined with def or async def")
+    if inspect.isgeneratorfunction(main) or inspect.isasyncgenfunction(main):
+        raise ScriptLoadError("main must not be a generator function")
+    return main
+
+
+def build_endpoint(main: Callable[..., Any]) -> Callable[..., Any]:
+    signature = inspect.signature(main, eval_str=True)
+    endpoint: Callable[..., Any]
+
+    if inspect.iscoroutinefunction(main):
+
+        async def call_async(**values: Any) -> None:
+            try:
+                await main(**values)
+            except SystemExit as error:
+                raise ScriptExit(error.code) from error
+
+        endpoint = call_async
+
+    else:
+
+        def call_sync(**values: Any) -> None:
+            try:
+                result = main(**values)
+            except SystemExit as error:
+                raise ScriptExit(error.code) from error
+            if inspect.isawaitable(result):
+                raise TypeError(
+                    "main returned an awaitable; define main with async def"
+                )
+
+        endpoint = call_sync
+
+    setattr(endpoint, "__signature__", signature.replace(return_annotation=None))  # noqa: B010
+    return endpoint
+
+
+def run(app: FastAPI, script_path: Path, argv: list[str]) -> httpx.Response:
+    main = load_main(script_path)
+
+    def provide_argv() -> list[str]:
+        return argv
+
+    app.dependency_overrides[get_argv] = provide_argv
+    app.add_api_route(
+        ROUTE_PATH,
+        build_endpoint(main),
+        methods=["POST"],
+        include_in_schema=False,
+        response_model=None,
+    )
+    app.router.routes.insert(0, app.router.routes.pop())
+    return asyncio.run(execute(app))
+
+
+async def execute(app: FastAPI) -> httpx.Response:
+    failure: Exception | None = None
+    async with app.router.lifespan_context(app) as lifespan_state:
+        try:
+            return await post_once(app, lifespan_state)
+        except Exception as error:
+            failure = error
+    assert failure is not None
+    raise failure
+
+
+async def post_once(
+    app: FastAPI, lifespan_state: Mapping[str, Any] | None
+) -> httpx.Response:
+    async def app_with_state(scope: Scope, receive: Receive, send: Send) -> None:
+        scope["state"] = dict(lifespan_state or {})
+        await app(scope, receive, send)
+
+    transport = httpx.ASGITransport(app=app_with_state)
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://localhost"
+    ) as client:
+        return await client.post(ROUTE_PATH)

fastapi_oneshot-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: fastapi-oneshot
+Version: 0.1.0
+Summary: Run one-shot scripts with a FastAPI app's dependencies
+Project-URL: Repository, https://github.com/himkt/fastapi-oneshot
+Author: himkt
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastapi<1.0.0,>=0.115.0
+Requires-Dist: httpx<1.0.0,>=0.23.0
+Description-Content-Type: text/markdown
+
+# fastapi-oneshot
+
+Run a one-shot Python script against an existing FastAPI app, so that the script's `main` function receives the app's dependencies — DB sessions, settings, clients — through ordinary `Depends`.
+
+`fastapi-oneshot` registers `main` as a temporary path operation, enters the app's lifespan, and sends a single in-process request to it through `httpx.ASGITransport`. Dependency resolution, `yield` cleanup, `dependency_overrides` and the lifespan all work exactly as they do for a request handler, and everything runs on one event loop in the main thread.
+
+## Installation
+
+Install `fastapi-oneshot` into the same environment as your app, because it imports the app:
+
+```console
+uv add --dev fastapi-oneshot
+```
+
+or
+
+```console
+pip install fastapi-oneshot
+```
+
+Python 3.10 or later and FastAPI 0.115.0 or later (below 1.0) are required.
+
+## Usage
+
+```console
+fastapi-oneshot SCRIPT --app MODULE:ATTR [-- SCRIPT_ARG ...]
+```
+
+| Argument | Meaning |
+|----------|---------|
+| `SCRIPT` | Path to the script file that defines `main`. |
+| `--app MODULE:ATTR` | Import string of the `FastAPI` instance, e.g. `myapp.main:app`. |
+| `--` | Everything after the first `--` is passed to the script verbatim. |
+
+Run the command from your project root: the current working directory is put on `sys.path` before `--app` is imported, as with `uvicorn` and `fastapi run`.
+
+## Writing a script
+
+A script is a Python file that defines a module-level function named `main`, with `def` or `async def`. Every parameter of `main` is a dependency, declared with `Depends(...)` exactly as in a path operation:
+
+```python
+# scripts/backfill.py
+import argparse
+import sqlite3
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi_oneshot import get_argv
+
+from myapp.dependencies import get_db
+
+
+def main(
+    db: Annotated[sqlite3.Connection, Depends(get_db)],
+    argv: Annotated[list[str], Depends(get_argv)],
+) -> None:
+    parser = argparse.ArgumentParser(prog="backfill")
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args(argv)
+    ...
+```
+
+```console
+fastapi-oneshot scripts/backfill.py --app myapp.main:app -- --dry-run
+```
+
+- The app's lifespan runs around `main`, so dependencies can read lifespan-initialized state through `request.app.state` and lifespan-yielded state through `request.state`.
+- A sync `main` runs in FastAPI's threadpool; an async `main` runs on the main-thread event loop shared with the lifespan.
+- The return value of `main` is discarded. Signal failure by raising an exception.
+- The script's directory is put on `sys.path`, so the script can import sibling modules, as with `python script.py`.
+- The script runs as a module named `__oneshot_script__`, so an `if __name__ == "__main__":` block does not run.
+
+### Script arguments: `get_argv`
+
+`fastapi_oneshot.get_argv` is a dependency that returns the arguments after `--` as `list[str]` (`[]` when there is no `--`). Parse them with `argparse` or any other parser, as in the example above.
+
+Script options always come from `get_argv`. A plain parameter of `main` that is not a dependency is not a CLI option: a plain parameter with a default (`verbose: bool = False`) always receives its default, and a required plain parameter fails the run with a 422 validation error.
+
+Calling `get_argv` outside a `fastapi-oneshot` run, e.g. from a normal app route, raises `RuntimeError`.
+
+### Overriding dependencies
+
+The request that runs `main` carries no headers, cookies, query or body. Override every dependency that reads them — such as "current user from a bearer token" — with `app.dependency_overrides` at module level in the script:
+
+```python
+from myapp.auth import get_current_user
+from myapp.main import app
+from myapp.models import User
+
+app.dependency_overrides[get_current_user] = lambda: User(id=0, name="oneshot")
+```
+
+The same applies to app-level dependencies given to `FastAPI(dependencies=[...])`, such as a global authentication check: they run before `main`, so override them in the script.
+
+Import the app through the same module path as `--app` (`from myapp.main import app` for `--app myapp.main:app`). Importing it through another path, such as `src.myapp.main`, creates a second app instance, and the override applies to that instance instead of the one that runs. Set overrides at module level: overrides set inside `main` are too late to affect `main`'s own parameters.
+
+## Exit codes
+
+| Outcome | Exit code |
+|---------|-----------|
+| `main` returns and the response is 2xx | 0 |
+| An exception is raised in `main`, a dependency, the lifespan, the app import or the script import (the traceback is printed) | 1 |
+| The response is not 2xx — e.g. `HTTPException`, a 422 validation error, a rejecting app-level dependency or middleware | 1 |
+| `main` raises `SystemExit` (e.g. `sys.exit(3)`, `argparse` errors) | the requested status |
+| The script or `--app` cannot be loaded, or `main` is missing or not a plain function | 2 |
+| Missing `SCRIPT` or `--app` | 2 |
+
+A non-2xx response is reported on stderr with its status and body:
+
+```text
+fastapi-oneshot: request failed with status 401
+{"detail":"missing Authorization"}
+```
+
+Once the lifespan has started, it is shut down normally before `fastapi-oneshot` exits, whatever the outcome.
+
+## Known limitations
+
+- **Middleware runs.** Every app middleware processes the request, which is sent to `http://localhost/__fastapi_oneshot__`. A middleware that rejects it (e.g. authentication, `TrustedHostMiddleware` without `localhost` in `allowed_hosts`, `HTTPSRedirectMiddleware` answering 307 — redirects are not followed) results in a non-2xx exit.
+- **App-level dependencies run.** Dependencies given to `FastAPI(dependencies=[...])` apply to the oneshot route, so a global authentication or rate-limit dependency runs before `main` and typically rejects the request (401/403 → exit 1). Override such a dependency in the script with `app.dependency_overrides`. Dependencies attached to an `APIRouter` do not apply, because the route is added to the app directly.
+- **Request-derived dependencies.** The request carries no headers, cookies, query or body beyond httpx defaults; dependencies that read them must be overridden in the script.
+- **Lifespan entered directly.** The lifespan runs through `app.router.lifespan_context(app)`, not through an ASGI `lifespan` scope, so ASGI middleware that intercepts the `lifespan` scope does not see startup and shutdown.
+- **Ctrl-C.** `fastapi-oneshot` installs no signal handling of its own. On Python 3.11+, the first Ctrl-C cancels the run: `CancelledError` is raised at the current `await`, propagates through `yield`-dependency cleanup and into the lifespan, and the process ends with `KeyboardInterrupt`; a second Ctrl-C raises `KeyboardInterrupt` immediately. On Python 3.10, `KeyboardInterrupt` is raised wherever the main thread is, and the run is cancelled the same way. Lifespan shutdown code runs on this path only when it is in `try/finally`. A sync `main` running in a worker thread cannot be interrupted, and the process exits only after it returns. The exit status is Python's default for an uncaught `KeyboardInterrupt` (130 in POSIX shells). Make scripts that must stay consistent when interrupted rely on DB transactions.
+- **`sys.exit()` in `main` is a failed request to the app.** `sys.exit(...)` — including `sys.exit(0)` and `argparse`'s `--help` — travels through the app as an exception: it is thrown into `yield` dependencies at their `yield` (post-`yield` success code such as `db.commit()` is skipped and `except Exception` rollback branches run) and reaches the app's `Exception` / 500 handler and error-reporting middleware as a server error. The process still exits with the requested status. End a successful run by returning from `main`; use `sys.exit` only for usage errors and failures. `SystemExit` raised by a dependency rather than by `main` is unsupported: lifespan shutdown is then best-effort, as on Ctrl-C.
+
+## License
+
+MIT

fastapi_oneshot-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fastapi_oneshot/__init__.py,sha256=PRE6spw-uWRO5jSXvqGfdEesNUqmjpeEb0urvS2cpGc,68
+fastapi_oneshot/cli.py,sha256=h3CR5LoyyUwlhHKcC_OLdr0o8qNCVM-fDvj8J44Ds0M,1518
+fastapi_oneshot/runner.py,sha256=F8Xs0YRwo9IQlbI82alIZK7BiReQ-tMusI82NaBf7Y4,4939
+fastapi_oneshot-0.1.0.dist-info/METADATA,sha256=paVozoEPObwjGJY_j8g-qXJP9vWr5CYN3TrYwjuYqQg,8412
+fastapi_oneshot-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastapi_oneshot-0.1.0.dist-info/entry_points.txt,sha256=eTPp_dbWWf4JmdlxMGLVi3JirOPR_srq7tYc0dq5_cg,61
+fastapi_oneshot-0.1.0.dist-info/licenses/LICENSE,sha256=QRCxO0skUXxUfiJVgU81NO667j7pVUnmPI_Q5BDphwI,1062
+fastapi_oneshot-0.1.0.dist-info/RECORD,,

fastapi_oneshot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fastapi_oneshot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastapi-oneshot = fastapi_oneshot.cli:main

fastapi_oneshot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 himkt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.