From 83fe61a5857c49299e79c0d87d7b125af11688a1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 15 May 2026 22:42:58 +0000 Subject: [PATCH 1/2] docs: fill in remaining missing docstrings to reach 100% interrogate 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%. --- .../src/cloudflare_auth/middleware_enhanced.py | 17 +++++++++++++++++ .../src/cloudflare_auth/utils.py | 14 +++++++++++++- src/python_libs/middleware/__init__.py | 6 ++++++ 3 files changed, 36 insertions(+), 1 deletion(-) diff --git a/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py b/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py index 6fc8b67..224ab6a 100644 --- a/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py +++ b/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py @@ -721,6 +721,23 @@ async def premium(user: CloudflareUser = Depends(require_full)): """ def dependency(request: Request) -> CloudflareUser: + """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 + the request is unauthenticated. + """ user = get_current_user(request) tier_order = { diff --git a/packages/cloudflare-auth/src/cloudflare_auth/utils.py b/packages/cloudflare-auth/src/cloudflare_auth/utils.py index bd83c53..af30a82 100644 --- a/packages/cloudflare-auth/src/cloudflare_auth/utils.py +++ b/packages/cloudflare-auth/src/cloudflare_auth/utils.py @@ -221,7 +221,19 @@ def mask_sensitive_data( 'Contact ***@***.*** for help' """ - def mask_match(match): + def mask_match(match: re.Match[str]) -> str: + """Replace a regex match with a masked representation. + + 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`. + + Returns: + Masked replacement string for the matched text. + """ matched = match.group(0) if "@" in matched: # Email-like pattern diff --git a/src/python_libs/middleware/__init__.py b/src/python_libs/middleware/__init__.py index e69de29..8fadc48 100644 --- a/src/python_libs/middleware/__init__.py +++ b/src/python_libs/middleware/__init__.py @@ -0,0 +1,6 @@ +"""Middleware components for Python Libs. + +This namespace package is reserved for middleware modules (request/response +hooks, ASGI/WSGI middleware, instrumentation). It is currently empty; submodules +will be added here as middleware features are introduced. +""" From 062e9fb241cbbd1f7b982e659b71c250f8f919a4 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 15 May 2026 22:47:06 +0000 Subject: [PATCH 2/2] docs: address Copilot review + add CHANGELOG entry - 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. --- CHANGELOG.md | 8 ++++++++ .../src/cloudflare_auth/middleware_enhanced.py | 15 +++++++-------- .../cloudflare-auth/src/cloudflare_auth/utils.py | 6 +++--- src/python_libs/middleware/__init__.py | 6 +++--- 4 files changed, 21 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ee78fc..b482ca2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Documentation + +- Filled in remaining missing docstrings to reach 100% interrogate coverage + (up from 99.2%): module docstring for `python_libs.middleware`, docstring + + type annotations for the `mask_match` inner callback in + `cloudflare_auth.utils.mask_sensitive_data`, and docstring for the + `dependency` closure returned by `cloudflare_auth.middleware_enhanced.require_tier`. + ### Changed - Migrated `sonarcloud.yml` to use `python-sonarcloud.yml` reusable workflow diff --git a/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py b/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py index 224ab6a..dfc8bd8 100644 --- a/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py +++ b/packages/cloudflare-auth/src/cloudflare_auth/middleware_enhanced.py @@ -721,22 +721,21 @@ async def premium(user: CloudflareUser = Depends(require_full)): """ def dependency(request: Request) -> CloudflareUser: - """Validate that the current user meets ``minimum_tier``. + """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``. + Resolved as a FastAPI dependency by require_tier. The user is loaded + from request state via get_current_user; tiers are ordered + LIMITED < FULL < ADMIN. Args: request: Incoming FastAPI/Starlette request. Returns: - The authenticated :class:`CloudflareUser`. + The authenticated CloudflareUser object. Raises: - HTTPException: ``403`` if the user's tier is below - ``minimum_tier``; ``401`` (via :func:`get_current_user`) if - the request is unauthenticated. + HTTPException: 403 if the user's tier is below minimum_tier; 401 + (via get_current_user) if the request is unauthenticated. """ user = get_current_user(request) diff --git a/packages/cloudflare-auth/src/cloudflare_auth/utils.py b/packages/cloudflare-auth/src/cloudflare_auth/utils.py index af30a82..54d6b88 100644 --- a/packages/cloudflare-auth/src/cloudflare_auth/utils.py +++ b/packages/cloudflare-auth/src/cloudflare_auth/utils.py @@ -224,12 +224,12 @@ def mask_sensitive_data( def mask_match(match: re.Match[str]) -> str: """Replace a regex match with a masked representation. - For email-like matches (containing ``@``), masks the local and domain + For email-like matches (containing '@'), masks the local and domain parts separately. For all other matches, replaces every character - with ``*``. + with '*'. Args: - match: Regex match object produced by :func:`re.sub`. + match: Regex match object produced by re.sub. Returns: Masked replacement string for the matched text. diff --git a/src/python_libs/middleware/__init__.py b/src/python_libs/middleware/__init__.py index 8fadc48..ac221c3 100644 --- a/src/python_libs/middleware/__init__.py +++ b/src/python_libs/middleware/__init__.py @@ -1,6 +1,6 @@ """Middleware components for Python Libs. -This namespace package is reserved for middleware modules (request/response -hooks, ASGI/WSGI middleware, instrumentation). It is currently empty; submodules -will be added here as middleware features are introduced. +This package is reserved for middleware modules (request/response hooks, +ASGI/WSGI middleware, instrumentation). It is currently empty; submodules will +be added here as middleware features are introduced. """