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/auth.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/auth.py | 26 |
1 files changed, 22 insertions, 4 deletions
diff --git a/webmentions_ssg/auth.py b/webmentions_ssg/auth.py index a5f3089..08abaa1 100644 --- a/webmentions_ssg/auth.py +++ b/webmentions_ssg/auth.py @@ -28,7 +28,13 @@ MIN_PASSWORD_LENGTH = 8 @cache def dummy_password_hash() -> str: - """Lazily generate a reusable hash for unknown login usernames.""" + """Lazily generate a reusable hash for unknown login usernames. + + The hash is calculated once and reused so missing accounts follow a comparable + password-check path. + + :returns: Reusable password hash for timing-safe unknown-user authentication. + """ return generate_password_hash(secrets.token_urlsafe()) @@ -37,6 +43,10 @@ def validate_password(password: str) -> None: Allow Unicode, whitespace-only passwords, and arbitrarily long passphrases, but reject empty passwords and control characters. + + :param password: Proposed new password to validate. + :raises ValueError: If the password is empty, too short, or contains control + characters. """ if not password: raise ValueError("Password must not be empty.") @@ -53,7 +63,7 @@ def load_user(session_id: object) -> User | None: """Load a user from the database by identifier. :param session_id: Database ID and password-hash fingerprint stored in the session. - :return: Matching user, or ``None`` if no user exists with the identifier. + :returns: Matching user, or ``None`` if no user exists with the identifier. """ if not isinstance(session_id, str): return None @@ -69,7 +79,11 @@ def load_user(session_id: object) -> User | None: def login_username_limit_key() -> str: - """Group usernames across IPs without exposing plaintext to rate-limit storage.""" + """Group usernames across IPs without exposing plaintext to rate-limit storage. + + :returns: Hashed username rate-limit key, or an IP-specific key if no username was + submitted. + """ username = request.form.get("username", "").strip().casefold() if not username: return f"missing-username:{get_remote_address()}" @@ -78,7 +92,11 @@ def login_username_limit_key() -> str: def is_safe_next_url(next_url: str) -> bool: - """Allow redirects only to paths on this site.""" + """Allow redirects only to paths on this site. + + :param next_url: Requested post-login redirect path. + :returns: ``True`` if the redirect is a safe site-local path. + """ if "\\" in next_url or not next_url.startswith("/") or next_url.startswith("//"): return False try: |
