[suppagoddo]

Final status (head fd1f35f, rebased on master 0cf565b)

Root cause of #106.

• init_fastapi() may run only once per process. That guard is intentional and unchanged.
• The report's app/main.py initialises json-logging and then, under if __name__ == "__main__":, calls uvicorn.run("app.main:app").
• The module body therefore runs twice in one process: first as __main__, then again as app.main when uvicorn imports the string. The second init_fastapi() raises RuntimeError: Can not call init more than once.

Two safe startup patterns (example/fastapi_startup/):

1. Import string (recommended): python -m uvicorn app.main:app. uvicorn imports app.main once. Required for --reload and --workers.
2. App object from a separate launcher (run.py): uvicorn.run(app, ...). Suits a simple single-process start.

This round:

• README verify command fixed. The example README says to run commands from example/fastapi_startup, but gave tests/test_fastapi_startup.py, which finds no tests there. It now gives ../../tests/test_fastapi_startup.py (6 passed when run from that directory) and mentions the root-relative form.

• Real uvicorn config path. The import-string test now runs uvicorn.Config("app.main:app").load(), which is what the CLI does, instead of import_from_string(). It runs in a fresh subprocess with socket.bind made to fail, and checks that:

  • the loaded app (unwrapped from uvicorn's middleware) is app.main.app;
  • init_fastapi() ran once;
  • no socket was bound.

  A mutation where app/main.py calls init_fastapi() twice and suppresses the error fails it with "init_fastapi() ran 2 times". Checked with uvicorn 0.39 (Python 3.9) and 0.54 (Python 3.12/3.13).

• Reload and multiple workers documented.

  • uvicorn exits when given an app object with reload or workers > 1; confirmed in the uvicorn 0.39 and 0.54 source.
  • Each worker process initialises once, which is expected.
  • Only two initialisations in one process are an error.

• Kept unchanged:

  • the run.py launcher test (uvicorn.run recorded; app object, not a string; one init) and its two negative controls;
  • the Initialisation error: "Can not call init more than once" [FastAPI] #106 reproduction (module run as __main__, then imported as app.main, raises RuntimeError);
  • the in-process duplicate-init test.

  With the guard disabled as a mutation, both negative tests fail.

• Manual check, not a committed test: a real python -m uvicorn app.main:app server answered with the supplied X-Correlation-ID after one initialisation. With --workers 2 it initialised once per worker, 2 in total, with no error.

• Rebase: onto master 0cf565b, which includes fix: prevent fabricated correlation IDs outside active requests #127, fix: safely handle correlation ID lookup in non-web mode #128, feat: support configurable exclusion of JSON log fields #129 and ci: add Python 3.14 unit and framework smoke-test coverage #133. Only CHANGELOG.md conflicted; all master entries are kept and the Initialisation error: "Can not call init more than once" [FastAPI] #106 entry is added. The diff against master is docs, example, tests and changelog only. No json_logging/ or tests/test_fastapi.py changes.

Results:

• Locally: 6/6 in tests/test_fastapi_startup.py; 94/94 full suite on Python 3.9–3.13, in forward and reversed order; each startup test passes alone and after the other FastAPI and field-exclusion suites. Blocking flake8 0.
• GitHub Actions on fd1f35f: 15/15 (unit tests on Python 3.9–3.14; Flask/Quart/FastAPI/Sanic smoke tests on 3.9 and 3.14; Flake8). Run: https://github.com/bobbui/json-logging-python/actions/runs/39519610612

Not covered by committed tests: --reload (the file-watcher process) and real port binding. These are covered only by the manual check and the uvicorn source.

---

PR 4 — docs: clarify FastAPI initialisation and Uvicorn startup (Fixes #106)

Branch docs/106-fastapi-init, commit 178a295.

Problem. The reported RuntimeError: Can not call init more than once happens when a module started as a script also
passes an import string to uvicorn, so the module body runs twice.

Reproduced on master by running the reporter's pattern: the error is raised at the second init_fastapi().

Change (docs and example only). example/fastapi_startup/ with app/main.py and a README listing the two working
patterns (python -m uvicorn app.main:app, and passing the app object to uvicorn.run) and the failing pattern. A FAQ
entry points to the example. No library code changes: the protection against double initialisation is kept.

Tests. tests/test_fastapi_startup.py (4 tests): both working patterns import once; the reported pattern still
fails with the same error; a second init in one process still raises. All 4 pass on master, as they are guards.

Local results. Full unit suite on Python 3.9 and 3.13: 39 passed each (35 + 4). Blocking flake8: 0. Not run on
3.10–3.12 in this session.

Not verified. A real uvicorn server was not bound, because the sandbox blocks binding. The working patterns were
checked through uvicorn.importer.import_from_string and by importing the app object.

---

Review update (round 2)

• Head 44a0201: the duplicate-initialisation test now raises an explicit AssertionError if the second
  initialisation succeeds, instead of failing only on a missing marker. Verified: with the guard intact, 4/4 pass; with
  the guard removed in a copy, the test fails with the explicit message.
• Verified: 39/39 on Python 3.9 and 3.13; blocking flake8 clean. The documented startup patterns are unchanged, and the
  core initialisation guard is not modified.

Review update (round 3, head b03cbe8)

The app-object pattern was not actually exercised. Confirmed and fixed.

• test_app_object_pattern_initialises_once_without_serving only imported app.main. It never ran the documented uvicorn.run(app) launcher, so it could not show that this pattern initialises once.
• Added example/fastapi_startup/run.py, the launcher the README already showed, and pointed the README at it.
• New test test_app_object_launcher_passes_the_app_to_uvicorn_and_initialises_once, in a subprocess:
  • wraps json_logging.init_fastapi with a call counter;
  • replaces uvicorn.run with a recorder, so no port is bound and no server starts;
  • runs run.py with runpy.run_path(..., run_name="__main__").
• It asserts that uvicorn.run() is called once with the app object from sys.modules["app.main"], not a string, and that init_fastapi() ran exactly once.
• Negative controls (test_launcher_check_detects_a_launcher_that_reimports_the_app): the same check fails for a launcher that reloads app.main (it raises the double-init RuntimeError) and for one that passes "app.main:app" (it trips the assertion).
• The reported-pattern test and the duplicate-init guard test are unchanged. No library code changed.

Results: 41/41 on Python 3.9–3.13; blocking flake8 0; GitHub Actions 10/10 on b03cbe8.

Not verified: a real uvicorn server binding a port; the sandbox here does not allow it.

Summary by CodeRabbit

• Documentation

  • Added FAQ and changelog guidance for avoiding duplicate FastAPI logging initialization.
  • Documented recommended Uvicorn startup patterns, reload and worker behavior, and common failure scenarios.

• New Examples

  • Added a runnable FastAPI startup example with request correlation IDs and JSON logging.
  • Included a separate launcher demonstrating app-object startup.

• Tests

  • Added coverage for supported startup methods and expected errors from duplicate initialization.

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4aa10a99-547e-4c10-9c02-5941a623247c

📥 Commits

Reviewing files that changed from the base of the PR and between 0cf565b and fd1f35f.

📒 Files selected for processing: 7

• CHANGELOG.md
• README.md
• example/fastapi_startup/README.md
• example/fastapi_startup/app/__init__.py
• example/fastapi_startup/app/main.py
• example/fastapi_startup/run.py
• tests/test_fastapi_startup.py

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The pull request adds a FastAPI startup example, documents Uvicorn launch patterns that avoid duplicate initialization, and tests supported startup flows and the resulting RuntimeError for repeated initialization.

Changes: FastAPI startup

Layer / File(s)	Summary
App initialization and launcher example/fastapi_startup/app/main.py, example/fastapi_startup/run.py	The app initializes JSON request instrumentation, configures an INFO-level logger, and exposes a root endpoint that returns the correlation ID. The launcher passes the imported app object to Uvicorn.
Startup guidance example/fastapi_startup/README.md, README.md, CHANGELOG.md	The documentation describes import-string and app-object startup patterns, reload and worker behavior, and the duplicate-initialization error.
Startup and initialization tests tests/test_fastapi_startup.py	Isolated-process tests check the supported launch patterns, negative controls, and repeated-initialization errors.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Uvicorn
  participant AppMain as app.main
  participant JsonLogging as json_logging
  Uvicorn->>AppMain: Import app.main:app
  AppMain->>JsonLogging: Call init_fastapi once
  AppMain-->>Uvicorn: Provide FastAPI app

Loading

Merge Risk: ⚪ Minimal · up to fd1f3

The documented startup patterns and duplicate-initialization behavior present no identified merge-blocking risk.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (3 skipped: 3…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check		Issue #106 asks for an explanation and advice for the duplicate json_logging.init_fastapi() call. The PR documents that script execution plus the "app.main:app" import string executes the module t…
Out of Scope Changes check		The reported changes stay within issue #106. The FAQ, changelog, example application, launcher, and tests support the documented FastAPI and Uvicorn initialization behavior. The tests avoid socket bin…
Title check		The title clearly identifies the main change: documenting FastAPI double initialization with Uvicorn. The issue reference and documentation scope are relevant, although the parenthetical is redundant.

Full details: Linked Issues check

Explanation

Issue #106 asks for an explanation and advice for the duplicate json_logging.init_fastapi() call. The PR documents that script execution plus the "app.main:app" import string executes the module twice. It documents python -m uvicorn app.main:app and an app-object uvicorn.run launcher. example/fastapi_startup/ demonstrates these patterns. tests/test_fastapi_startup.py covers both working patterns, the reported failing pattern, and repeated initialization. The existing initialization guard remains unchanged.

Full details: Out of Scope Changes check

Explanation

The reported changes stay within issue #106. The FAQ, changelog, example application, launcher, and tests support the documented FastAPI and Uvicorn initialization behavior. The tests avoid socket binding because they verify configuration and launcher behavior. No unrelated library behavior change is reported.

Full details: Docstring Coverage

Explanation

Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 7 functions across 3 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}