docs: complete Google-style docstring coverage (99.2% → 100%)#37
Conversation
…coverage Adds the three docstrings flagged by interrogate as missing: - src/python_libs/middleware/__init__.py: module docstring for the middleware namespace package (file was previously empty). - cloudflare_auth.utils.mask_sensitive_data.mask_match: docstring and type annotations (re.Match[str] -> str) for the inner replacement callback used with re.sub. - cloudflare_auth.middleware_enhanced.require_tier.dependency: docstring for the closure returned as a FastAPI dependency, describing tier ordering and the HTTPException raised when a user's tier is below the required minimum. No behavior changes. Interrogate coverage: 99.2% -> 100.0%.
|
Warning Review limit reached
More reviews will be available in 23 minutes and 1 second. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (4)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR completes docstring coverage across the repo by adding the remaining missing docstrings (and one inner-function type annotation) to reach 100% interrogate coverage, without changing runtime behavior.
Changes:
- Added a module docstring for
python_libs.middleware. - Added a docstring +
re.Match[str] -> strtype hints for themask_sensitive_dataregex callback. - Added a docstring for the
require_tier()FastAPI dependency closure documenting tier ordering and raised errors.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/python_libs/middleware/__init__.py |
Adds a new module docstring for the middleware package. |
packages/cloudflare-auth/src/cloudflare_auth/utils.py |
Documents and types the mask_match callback used by mask_sensitive_data. |
packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py |
Documents the require_tier() dependency closure behavior and errors. |
| @@ -0,0 +1,6 @@ | |||
| """Middleware components for Python Libs. | |||
|
|
|||
| This namespace package is reserved for middleware modules (request/response | |||
| For email-like matches (containing ``@``), masks the local and domain | ||
| parts separately. For all other matches, replaces every character | ||
| with ``*``. | ||
|
|
||
| Args: | ||
| match: Regex match object produced by :func:`re.sub`. |
| """Validate that the current user meets ``minimum_tier``. | ||
|
|
||
| Resolved as a FastAPI dependency by :func:`require_tier`. The user is | ||
| loaded from request state via :func:`get_current_user`; tiers are | ||
| ordered ``LIMITED < FULL < ADMIN``. | ||
|
|
||
| Args: | ||
| request: Incoming FastAPI/Starlette request. | ||
|
|
||
| Returns: | ||
| The authenticated :class:`CloudflareUser`. | ||
|
|
||
| Raises: | ||
| HTTPException: ``403`` if the user's tier is below | ||
| ``minimum_tier``; ``401`` (via :func:`get_current_user`) if |
- Rephrase middleware/__init__.py docstring: drop the inaccurate "namespace package" wording (a directory with __init__.py is a regular package per PEP 420 terminology). - Convert the new docstrings in cloudflare_auth/utils.py and cloudflare_auth/middleware_enhanced.py from Sphinx/reST markup (:func:, :class:, ``double-backticks``) to plain Google-style prose so they match the surrounding docstrings in those files and render cleanly in non-Sphinx tooling. - Add Documentation entry to [Unreleased] in CHANGELOG.md to satisfy the Changelog Check.
|
Re-resolve against current main (#36/#41/#37 landed after the first sync): - mutation-testing.yml, scorecard.yml: take main's versions (preserve the already-merged #41/#36 changes; #40's per-job permission tightening on those two files is dropped to avoid reverting merged work). - CHANGELOG.md: keep both the Security (this PR) and Documentation (main) sections. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Combine #40's security-hardening docstring content with #45's pydoclint style (arg-type-hints-in-docstring=true), and bring the docstrings #40/#37 added into pydoclint compliance: - validators.py: drop the __init__ docstring (DOC301; moved Raises into the class docstring), keep typed arg style, drop the removed verify_exp param. - client.py: typed Returns/args, keep the empty-prefix Raises; remove the non-raised Exception entry from _get_or_create_bucket. - middleware_enhanced.py / utils.py: add type hints to the dependency and mask_match closures' docstrings. pydoclint: 0 violations. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Summary
Audited the library against the four-step docstring brief (module / class / function & method / type hints) and filled in the only three items still missing a docstring. Every other public module, class, and function already has a Google-style docstring (
Args:/Returns:/Raises:), so the diff is small and surgical — no business logic changes.Interrogate coverage (before / after)
Measured with
uvx interrogate -v src/ packages/*/src/(interrogate 1.7.0).Items that were missing
The three nodes interrogate flagged as
MISSED, all of which are now documented:src/python_libs/middleware/__init__.py— empty file, no module docstring. Added a module docstring describing the namespace package.cloudflare_auth.utils.mask_sensitive_data.mask_match(utils.py:224) — inner regex-substitution callback. Added a Google-style docstring and parameter / return type annotations (re.Match[str] -> str, using only the already-imported stdlibremodule — no new dependencies).cloudflare_auth.middleware_enhanced.require_tier.dependency(middleware_enhanced.py:723) — closure returned as a FastAPI dependency. Added a docstring describing theLIMITED < FULL < ADMINtier ordering and theHTTPException403 raised when the user's tier is below the required minimum.Why so few changes?
The library was already heavily documented prior to this PR:
cloudflare_auth.validators,models,middleware,middleware_enhanced) already document expected token format, validated claims, exceptions raised, and security assumptions (e.g. RS256 + Cloudflare-issued JWKS, audience/issuer validation, expiration checking).gcs_utilities.client,exceptions) already document the bucket / key contract, the env-var configuration (GCP_SA_KEY,GCS_BUCKET,GCP_PROJECT), and theNotFound→GCSNotFoundErrormapping.Requestparameters incsrf.validate_requestandutils.get_client_ipare intentionally left un-annotated with# noqa: ANN001becausefastapi/starletteare optional extras ([project.optional-dependencies].fastapi) — adding a hard import would violate the brief's "Do not introduce new dependencies" rule. These were left as-is.Verification
uvx interrogate src/ packages/*/src/→PASSED (minimum: 80.0%, actual: 100.0%)uv run ruff checkon the changed files →All checks passed!pytest tests/inpackages/cloudflare-auth→ 111 passedmask_sensitive_data,sanitize_email,sanitize_for_loggingend-to-end — output identical to pre-change behavior.Test plan
Generated by Claude Code