fastapi-perfstats 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. fastapi_perfstats-0.1.0/.githooks/pre-commit +19 -0
  2. fastapi_perfstats-0.1.0/.githooks/pre-push +36 -0
  3. fastapi_perfstats-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +39 -0
  4. fastapi_perfstats-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  5. fastapi_perfstats-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml +21 -0
  6. fastapi_perfstats-0.1.0/.github/dependabot.yml +16 -0
  7. fastapi_perfstats-0.1.0/.github/pull_request_template.md +10 -0
  8. fastapi_perfstats-0.1.0/.github/workflows/benchmark.yml +37 -0
  9. fastapi_perfstats-0.1.0/.github/workflows/ci.yml +41 -0
  10. fastapi_perfstats-0.1.0/.github/workflows/release.yml +66 -0
  11. fastapi_perfstats-0.1.0/.gitignore +10 -0
  12. fastapi_perfstats-0.1.0/.pre-commit-config.yaml +7 -0
  13. fastapi_perfstats-0.1.0/.python-version +1 -0
  14. fastapi_perfstats-0.1.0/CHANGELOG.md +18 -0
  15. fastapi_perfstats-0.1.0/CONTRIBUTING.md +38 -0
  16. fastapi_perfstats-0.1.0/LICENSE +21 -0
  17. fastapi_perfstats-0.1.0/PKG-INFO +478 -0
  18. fastapi_perfstats-0.1.0/README.md +431 -0
  19. fastapi_perfstats-0.1.0/RELEASING.md +18 -0
  20. fastapi_perfstats-0.1.0/SECURITY.md +6 -0
  21. fastapi_perfstats-0.1.0/benchmarks/overhead.py +236 -0
  22. fastapi_perfstats-0.1.0/examples/demo.py +37 -0
  23. fastapi_perfstats-0.1.0/pyproject.toml +87 -0
  24. fastapi_perfstats-0.1.0/src/fastapi_perfstats/__init__.py +73 -0
  25. fastapi_perfstats-0.1.0/src/fastapi_perfstats/auth.py +60 -0
  26. fastapi_perfstats-0.1.0/src/fastapi_perfstats/collector.py +159 -0
  27. fastapi_perfstats-0.1.0/src/fastapi_perfstats/config.py +163 -0
  28. fastapi_perfstats-0.1.0/src/fastapi_perfstats/ext/__init__.py +9 -0
  29. fastapi_perfstats-0.1.0/src/fastapi_perfstats/ext/base.py +102 -0
  30. fastapi_perfstats-0.1.0/src/fastapi_perfstats/ext/recent.py +167 -0
  31. fastapi_perfstats-0.1.0/src/fastapi_perfstats/ext/sizes.py +109 -0
  32. fastapi_perfstats-0.1.0/src/fastapi_perfstats/ext/stddev.py +84 -0
  33. fastapi_perfstats-0.1.0/src/fastapi_perfstats/headers.py +36 -0
  34. fastapi_perfstats-0.1.0/src/fastapi_perfstats/keys.py +34 -0
  35. fastapi_perfstats-0.1.0/src/fastapi_perfstats/lifecycle.py +43 -0
  36. fastapi_perfstats-0.1.0/src/fastapi_perfstats/live.py +133 -0
  37. fastapi_perfstats-0.1.0/src/fastapi_perfstats/middleware.py +81 -0
  38. fastapi_perfstats-0.1.0/src/fastapi_perfstats/models.py +93 -0
  39. fastapi_perfstats-0.1.0/src/fastapi_perfstats/mounts.py +34 -0
  40. fastapi_perfstats-0.1.0/src/fastapi_perfstats/page.py +299 -0
  41. fastapi_perfstats-0.1.0/src/fastapi_perfstats/parts.py +9 -0
  42. fastapi_perfstats-0.1.0/src/fastapi_perfstats/prometheus.py +96 -0
  43. fastapi_perfstats-0.1.0/src/fastapi_perfstats/py.typed +0 -0
  44. fastapi_perfstats-0.1.0/src/fastapi_perfstats/reset.py +60 -0
  45. fastapi_perfstats-0.1.0/src/fastapi_perfstats/route.py +48 -0
  46. fastapi_perfstats-0.1.0/src/fastapi_perfstats/slow_context.py +118 -0
  47. fastapi_perfstats-0.1.0/src/fastapi_perfstats/sqlite_schema.py +53 -0
  48. fastapi_perfstats-0.1.0/src/fastapi_perfstats/stores.py +400 -0
  49. fastapi_perfstats-0.1.0/tests/fakes.py +57 -0
  50. fastapi_perfstats-0.1.0/tests/test_all.py +526 -0
  51. fastapi_perfstats-0.1.0/tests/test_auth.py +119 -0
  52. fastapi_perfstats-0.1.0/tests/test_benchmark_smoke.py +72 -0
  53. fastapi_perfstats-0.1.0/tests/test_contracts.py +362 -0
  54. fastapi_perfstats-0.1.0/tests/test_ext_recent.py +262 -0
  55. fastapi_perfstats-0.1.0/tests/test_ext_sizes.py +249 -0
  56. fastapi_perfstats-0.1.0/tests/test_ext_stddev.py +132 -0
  57. fastapi_perfstats-0.1.0/tests/test_headers.py +81 -0
  58. fastapi_perfstats-0.1.0/tests/test_hooks.py +333 -0
  59. fastapi_perfstats-0.1.0/tests/test_integration.py +350 -0
  60. fastapi_perfstats-0.1.0/tests/test_keys.py +108 -0
  61. fastapi_perfstats-0.1.0/tests/test_lifecycle.py +223 -0
  62. fastapi_perfstats-0.1.0/tests/test_live.py +118 -0
  63. fastapi_perfstats-0.1.0/tests/test_middleware_timing.py +181 -0
  64. fastapi_perfstats-0.1.0/tests/test_mounts.py +143 -0
  65. fastapi_perfstats-0.1.0/tests/test_page_columns.py +60 -0
  66. fastapi_perfstats-0.1.0/tests/test_prometheus.py +179 -0
  67. fastapi_perfstats-0.1.0/tests/test_reset.py +160 -0
  68. fastapi_perfstats-0.1.0/tests/test_slow_context.py +245 -0
  69. fastapi_perfstats-0.1.0/tests/test_slow_thresholds.py +135 -0
  70. fastapi_perfstats-0.1.0/tests/test_sqlite_schema.py +130 -0
  71. fastapi_perfstats-0.1.0/tests/test_stats_route.py +77 -0
  72. fastapi_perfstats-0.1.0/tests/test_store_wiring.py +398 -0
  73. fastapi_perfstats-0.1.0/tests/test_version.py +33 -0
  74. fastapi_perfstats-0.1.0/tests/test_without_fastapi.py +59 -0
  75. fastapi_perfstats-0.1.0/uv.lock +795 -0
@@ -0,0 +1,19 @@
1
+ #!/bin/sh
2
+ # Opt-in maintainer hook: only runs when `git config core.hooksPath .githooks` is set, so contributors are unaffected.
3
+ # Blocks commits whose author or committer e-mail is not a GitHub no-reply address.
4
+ bad=0
5
+ for role in AUTHOR COMMITTER; do
6
+ ident=$(git var "GIT_${role}_IDENT") || exit 1
7
+ email=$(printf '%s' "$ident" | sed 's/^[^<]*<\([^>]*\)>.*$/\1/')
8
+ case "$email" in
9
+ *@users.noreply.github.com) ;;
10
+ *)
11
+ domain=${email##*@}
12
+ echo "Commit blocked: the $role e-mail (domain: $domain) is not a GitHub no-reply address." >&2
13
+ echo "Fix: git config user.email <your-id>@users.noreply.github.com" >&2
14
+ bad=1
15
+ ;;
16
+ esac
17
+ done
18
+ [ "$bad" -eq 0 ] || exit 1
19
+ exit 0
@@ -0,0 +1,36 @@
1
+ #!/bin/sh
2
+ # Opt-in maintainer hook: only runs when `git config core.hooksPath .githooks` is set, so contributors are unaffected.
3
+ # Blocks pushes containing commits whose author or committer e-mail is not a GitHub no-reply address.
4
+ remote_name=$1
5
+ input=$(cat)
6
+ zero=0000000000000000000000000000000000000000
7
+ bad=0
8
+ while read -r local_ref local_sha remote_ref remote_sha; do
9
+ [ -n "$local_sha" ] || continue
10
+ [ "$local_sha" = "$zero" ] && continue
11
+ if [ "$remote_sha" != "$zero" ] && git cat-file -e "$remote_sha^{commit}" 2>/dev/null; then
12
+ commits=$(git rev-list "$remote_sha..$local_sha")
13
+ else
14
+ commits=$(git rev-list "$local_sha" --not --remotes="$remote_name")
15
+ fi
16
+ for c in $commits; do
17
+ for pair in "author $(git log -1 --format=%ae "$c")" "committer $(git log -1 --format=%ce "$c")"; do
18
+ role=${pair%% *}
19
+ email=${pair#* }
20
+ case "$email" in
21
+ *@users.noreply.github.com) ;;
22
+ *)
23
+ echo "Push blocked: commit $(git rev-parse --short "$c") has a $role e-mail (domain: ${email##*@}) that is not a GitHub no-reply address." >&2
24
+ bad=1
25
+ ;;
26
+ esac
27
+ done
28
+ done
29
+ done <<EOT
30
+ $input
31
+ EOT
32
+ if [ "$bad" -ne 0 ]; then
33
+ echo "Fix: git config user.email <your-id>@users.noreply.github.com, then rewrite the offending commits." >&2
34
+ exit 1
35
+ fi
36
+ exit 0
@@ -0,0 +1,39 @@
1
+ name: Bug report
2
+ description: Something does not work as documented
3
+ labels: [bug]
4
+ body:
5
+ - type: input
6
+ id: python
7
+ attributes:
8
+ label: Python version
9
+ validations:
10
+ required: true
11
+ - type: input
12
+ id: starlette
13
+ attributes:
14
+ label: Starlette version
15
+ validations:
16
+ required: true
17
+ - type: input
18
+ id: fastapi
19
+ attributes:
20
+ label: FastAPI version (if used)
21
+ - type: textarea
22
+ id: reproducer
23
+ attributes:
24
+ label: Minimal reproducer
25
+ render: python
26
+ validations:
27
+ required: true
28
+ - type: textarea
29
+ id: expected
30
+ attributes:
31
+ label: Expected behaviour
32
+ validations:
33
+ required: true
34
+ - type: textarea
35
+ id: actual
36
+ attributes:
37
+ label: Actual behaviour
38
+ validations:
39
+ required: true
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: false
2
+ contact_links:
3
+ - name: Report a security vulnerability
4
+ url: https://github.com/rt87/fastapi-perfstats/security/policy
5
+ about: Please do not open a public issue; follow the security policy.
@@ -0,0 +1,21 @@
1
+ name: Feature request
2
+ description: Suggest an improvement
3
+ labels: [enhancement]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: Problem
9
+ description: What do you want to do that is hard or impossible today?
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: Proposed solution
16
+ validations:
17
+ required: true
18
+ - type: textarea
19
+ id: alternatives
20
+ attributes:
21
+ label: Alternatives considered
@@ -0,0 +1,16 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ groups:
8
+ actions:
9
+ update-types: [minor, patch]
10
+ - package-ecosystem: uv
11
+ directory: /
12
+ schedule:
13
+ interval: weekly
14
+ groups:
15
+ python-deps:
16
+ update-types: [minor, patch]
@@ -0,0 +1,10 @@
1
+ ## Summary
2
+
3
+ <!-- What does this change and why? Link the issue. -->
4
+
5
+ ## Checklist
6
+
7
+ - [ ] Tests added or updated (positive and negative, >= 90 % coverage for new code)
8
+ - [ ] `uv run ruff check .`, `uv run ruff format --check .`, `uv run mypy` and `uv run pytest` pass
9
+ - [ ] Docs updated (README / docstrings) where behaviour changed
10
+ - [ ] Changelog entry added if the change is user-visible
@@ -0,0 +1,37 @@
1
+ name: Benchmark
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ inputs:
6
+ n:
7
+ description: Requests per repeat
8
+ default: "20000"
9
+ repeats:
10
+ description: Repeats per scenario (median reported)
11
+ default: "5"
12
+ python:
13
+ description: Python version
14
+ default: "3.14"
15
+
16
+ permissions:
17
+ contents: read
18
+
19
+ jobs:
20
+ overhead:
21
+ runs-on: ubuntu-latest
22
+ timeout-minutes: 45
23
+ env:
24
+ UV_PYTHON: ${{ inputs.python }}
25
+ steps:
26
+ - uses: actions/checkout@v4
27
+ - uses: astral-sh/setup-uv@v5
28
+ - run: uv sync
29
+ - run: uv run python --version
30
+ - run: uv run python benchmarks/overhead.py --n ${{ inputs.n }} --repeats ${{ inputs.repeats }} --json-file overhead.json | tee overhead.md
31
+ - run: cat overhead.md >> "$GITHUB_STEP_SUMMARY"
32
+ - uses: actions/upload-artifact@v4
33
+ with:
34
+ name: overhead
35
+ path: |
36
+ overhead.md
37
+ overhead.json
@@ -0,0 +1,41 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: ci-${{ github.ref }}
13
+ cancel-in-progress: true
14
+
15
+ jobs:
16
+ test:
17
+ runs-on: ubuntu-latest
18
+ timeout-minutes: 15
19
+ strategy:
20
+ fail-fast: false
21
+ matrix:
22
+ python-version: ["3.12", "3.13", "3.14", "3.15"]
23
+ steps:
24
+ - uses: actions/checkout@v4
25
+ - uses: astral-sh/setup-uv@v5
26
+ - run: uv sync --python ${{ matrix.python-version }}
27
+ - run: uv run ruff check .
28
+ - run: uv run ruff format --check .
29
+ - run: uv run mypy
30
+ if: matrix.python-version == '3.12' || matrix.python-version == '3.14'
31
+ - run: uv run pytest
32
+
33
+ lowest:
34
+ # Lowest allowed direct dependency versions (starlette>=0.37): the declared floor must be truthful.
35
+ runs-on: ubuntu-latest
36
+ timeout-minutes: 15
37
+ steps:
38
+ - uses: actions/checkout@v4
39
+ - uses: astral-sh/setup-uv@v5
40
+ - run: uv sync --python 3.12 --resolution lowest-direct
41
+ - run: uv run pytest
@@ -0,0 +1,66 @@
1
+ name: Release
2
+
3
+ # Builds and verifies the package; on a v* tag it publishes to PyPI after the owner approves the `pypi`
4
+ # environment (see RELEASING.md).
5
+
6
+ on:
7
+ push:
8
+ tags: ["v*"]
9
+ workflow_dispatch:
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ jobs:
15
+ build:
16
+ runs-on: ubuntu-latest
17
+ timeout-minutes: 15
18
+ permissions:
19
+ contents: read
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: astral-sh/setup-uv@v5
23
+ - run: uv build
24
+ - run: uvx twine check dist/*
25
+ - name: Check wheel contents and tag
26
+ env:
27
+ REF_TYPE: ${{ github.ref_type }}
28
+ REF_NAME: ${{ github.ref_name }}
29
+ run: |
30
+ python3 - <<'PY'
31
+ import glob
32
+ import os
33
+ import tomllib
34
+ import zipfile
35
+
36
+ (wheel,) = glob.glob("dist/*.whl")
37
+ names = zipfile.ZipFile(wheel).namelist()
38
+ assert "fastapi_perfstats/py.typed" in names, "py.typed missing from the wheel"
39
+ assert not any(n.startswith("tests/") for n in names), "tests/ must not be in the wheel"
40
+
41
+ if os.environ["REF_TYPE"] == "tag":
42
+ with open("pyproject.toml", "rb") as fh:
43
+ version = tomllib.load(fh)["project"]["version"]
44
+ tag = os.environ["REF_NAME"].removeprefix("v")
45
+ assert tag == version, f"tag {tag!r} does not match pyproject version {version!r}"
46
+ print("ok:", wheel)
47
+ PY
48
+ - uses: actions/upload-artifact@v4
49
+ with:
50
+ name: dist
51
+ path: dist/
52
+ if-no-files-found: error
53
+
54
+ publish-pypi:
55
+ needs: build
56
+ if: github.ref_type == 'tag'
57
+ runs-on: ubuntu-latest
58
+ environment: pypi
59
+ permissions:
60
+ id-token: write
61
+ steps:
62
+ - uses: actions/download-artifact@v4
63
+ with:
64
+ name: dist
65
+ path: dist/
66
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ .coverage
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ *.db
8
+ .env
9
+ *.db-*
10
+ .venv-*/
@@ -0,0 +1,7 @@
1
+ repos:
2
+ - repo: https://github.com/astral-sh/ruff-pre-commit
3
+ rev: v0.17.5
4
+ hooks:
5
+ - id: ruff-check
6
+ args: [--fix]
7
+ - id: ruff-format
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,18 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file.
4
+
5
+ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-11-16
10
+
11
+ First alpha release.
12
+
13
+ ### Added
14
+
15
+ - Per-route call statistics for Starlette / FastAPI: call counts, errors and latency quantiles.
16
+ - Bounded slow-call log.
17
+ - Built-in HTML stats page, with all values escaped and no external assets.
18
+ - Runtime dependency on `starlette` only; `fastapi` is not required.
@@ -0,0 +1,38 @@
1
+ # Contributing
2
+
3
+ Thanks for your interest in fastapi-perfstats.
4
+
5
+ ## Setup
6
+
7
+ ```bash
8
+ uv sync --all-groups
9
+ ```
10
+
11
+ ## Checks
12
+
13
+ All of these must pass before a change is merged:
14
+
15
+ ```bash
16
+ uv run ruff check .
17
+ uv run ruff format --check .
18
+ uv run mypy
19
+ uv run pytest
20
+ ```
21
+
22
+ New code needs at least 90 % test coverage, with positive and negative tests.
23
+
24
+ ## Design principles
25
+
26
+ - The only runtime dependency is `starlette`. Never depend on `fastapi`; it is a dev dependency only.
27
+ - Otherwise use the standard library only.
28
+ - Memory use is bounded: every collection that grows with traffic has a cap.
29
+ - Every string rendered on the stats page is escaped.
30
+ - The stats page loads no external assets.
31
+
32
+ ## Releasing
33
+
34
+ See [RELEASING.md](RELEASING.md).
35
+
36
+ ## Conduct
37
+
38
+ Be respectful.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 rt87
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.