From 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Sat, 14 Nov 2026 18:44:23 +0100 Subject: docs(core): standardize reST docstrings Expand function and method documentation with consistent reST parameter, return, and exception fields while clarifying behavior where additional context is useful. Normalize test and migration docstrings to the same documentation conventions. --- webmentions_ssg/config.py | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) (limited to 'webmentions_ssg/config.py') diff --git a/webmentions_ssg/config.py b/webmentions_ssg/config.py index 33647a1..6e6b4bf 100644 --- a/webmentions_ssg/config.py +++ b/webmentions_ssg/config.py @@ -120,7 +120,13 @@ class TestingConfig(DefaultConfig): def normalize_hostnames(value: object) -> set[str]: - """Validate and normalize a collection of hostnames.""" + """Validate and normalize a collection of hostnames. + + :param value: List, tuple, set, or frozenset of hostnames to normalize. + :returns: Normalized, lowercase hostnames without trailing dots. + :raises TypeError: If the input is not a supported collection type. + :raises ValueError: If a collection item is not a nonempty hostname string. + """ if not isinstance(value, (list, tuple, set, frozenset)): raise TypeError("Expected a list, tuple, or set of hostnames.") @@ -137,7 +143,13 @@ def normalize_hostnames(value: object) -> set[str]: def validate_secret_key(value: object) -> str | bytes: - """Require a non-placeholder, sufficiently long deployment signing key.""" + """Require a non-placeholder, sufficiently long deployment signing key. + + :param value: Configured Flask signing key to validate. + :returns: The original validated signing key. + :raises TypeError: If the configured key is neither text nor bytes. + :raises RuntimeError: If the key is too short, blank, or a known placeholder. + """ if not isinstance(value, (str, bytes)): raise TypeError( "Configure a persistent SECRET_KEY of at least 32 random bytes " @@ -172,6 +184,14 @@ def validate_config( The caller applies the returned values once; validation does not mutate the Flask application or install extensions. + + :param config: Current Flask configuration to check. + :param config_class: Configuration class selected for the application. + :returns: Normalized settings for the caller to apply. + :raises TypeError: If a hostname setting has an invalid collection type. + :raises ValueError: If a hostname or a numeric setting is invalid. + :raises RuntimeError: If production security or shared-storage configuration is + unsafe. """ normalized: dict[str, object] = {} for key in ("ALLOWED_HOSTNAMES", "IGNORED_HOSTNAMES"): -- cgit v1.3.1