diff options
| author | Dennis Fink | 2026-11-14 18:44:23 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-14 18:44:23 +0100 |
| commit | 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 (patch) | |
| tree | 0096a0125c4d94a047e5bd24288e1f3f4a58ada5 /webmentions_ssg/config.py | |
| parent | 2366d455c7d1ae16c84e0bcbffb94ed762c16832 (diff) | |
| download | webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.tar.gz webmentions-ssg-968e1b4e4a6fbd5a15037cdb11a3f9dee5108570.zip | |
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.
Diffstat (limited to '')
| -rw-r--r-- | webmentions_ssg/config.py | 24 |
1 files changed, 22 insertions, 2 deletions
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"): |
