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/models.py | 49 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 9 deletions(-) (limited to 'webmentions_ssg/models.py') diff --git a/webmentions_ssg/models.py b/webmentions_ssg/models.py index 622e3b8..33f27d1 100644 --- a/webmentions_ssg/models.py +++ b/webmentions_ssg/models.py @@ -85,6 +85,9 @@ class User(UserMixin, Base): Only a one-way fingerprint is placed in Flask's signed cookie, never the password hash itself. Rehashing the password invalidates all previously issued session identifiers without a schema change. + + :returns: Session identifier combining the user ID and password-hash + fingerprint. """ fingerprint = sha256(self.password_hash.encode("utf-8")).hexdigest() return f"{self.id}:{fingerprint}" @@ -93,7 +96,7 @@ class User(UserMixin, Base): """Check a plain-text password against the stored password hash. :param password: Plain-text password to check. - :return: Whether the password matches the stored hash. + :returns: Whether the password matches the stored hash. """ return check_password_hash(self.password_hash, password) @@ -160,7 +163,12 @@ class ReceivedWebmention(Base): def verification_reset_values( *, at: datetime, recoveries: int = 0 ) -> dict[str, object]: - """Return the columns to reset when verification is explicitly reopened.""" + """Return the columns to reset when verification is explicitly reopened. + + :param at: Timestamp to record for the newly opened verification. + :param recoveries: Number of stale-lease recovery attempts to retain. + :returns: Column values for resetting the verification state. + """ return { "status": ReceivedStatus.RECEIVED, "failure_reason": None, @@ -169,7 +177,11 @@ class ReceivedWebmention(Base): } def reset_for_verification(self) -> None: - """Reopen an existing row for manual verification.""" + """Reopen an existing row for manual verification. + + Clear the previous outcome and restore the received state with a fresh + timestamp. + """ for key, value in self.verification_reset_values(at=datetime.now(UTC)).items(): setattr(self, key, value) @@ -304,14 +316,21 @@ class SentWebmention(Base): return f"" def reopen(self, revision: int, active: bool) -> None: - """Reopen delivery for a revision while preserving send history.""" + """Reopen delivery for a revision while preserving send history. + + :param revision: Source revision to make the desired delivery revision. + :param active: Whether the target still appears in the current source. + """ self.desired_revision = revision self.active = active self.attempt_count = 0 self.next_retry_at = None def resend(self) -> None: - """Retry the current revision, clearing its previous delivery result.""" + """Retry the current revision, clearing its previous delivery result. + + Reset attempt and response state without changing the desired source revision. + """ self.reopen(self.desired_revision, self.active) self.processed_revision = None self.status = None @@ -331,7 +350,10 @@ class SentWebmention(Base): @pending.inplace.expression @classmethod def _pending_expression(cls) -> sa.ColumnElement[bool]: - """Express pending-revision status in database queries.""" + """Express pending-revision status in database queries. + + :returns: SQLAlchemy expression selecting unprocessed source revisions. + """ return sa.or_( cls.processed_revision.is_(None), cls.processed_revision < cls.desired_revision, @@ -347,13 +369,18 @@ def uuid7_to_datetime(identifier: UUID) -> datetime: """Convert a UUID version 7 timestamp to a datetime. :param identifier: UUID whose embedded timestamp should be converted. - :return: Timestamp as a timezone-aware UTC datetime. + :returns: Timestamp as a timezone-aware UTC datetime. """ return datetime.fromtimestamp(identifier.time / 1000, tz=UTC) def received_url_digest(source: str, target: str) -> str: - """Fingerprint an unambiguous, ordered source/target pair.""" + """Fingerprint an unambiguous, ordered source/target pair. + + :param source: Webmention source URL. + :param target: Webmention target URL. + :returns: SHA-256 hexadecimal digest of the ordered URL pair. + """ encoded = json.dumps( [source, target], ensure_ascii=False, separators=(",", ":") ).encode("utf-8") @@ -361,5 +388,9 @@ def received_url_digest(source: str, target: str) -> str: def sent_target_digest(target: str) -> str: - """Fingerprint an outgoing target (unique within each source ID).""" + """Fingerprint an outgoing target (unique within each source ID). + + :param target: Outgoing Webmention target URL. + :returns: SHA-256 hexadecimal digest of the target URL. + """ return sha256(target.encode("utf-8")).hexdigest() -- cgit v1.3.1