aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/sender.py
diff options
context:
space:
mode:
authorDennis Fink2026-11-14 18:44:23 +0100
committerDennis Fink2026-11-14 18:44:23 +0100
commit968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 (patch)
tree0096a0125c4d94a047e5bd24288e1f3f4a58ada5 /webmentions_ssg/tasks/sender.py
parent2366d455c7d1ae16c84e0bcbffb94ed762c16832 (diff)
downloadwebmentions-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/tasks/sender.py41
1 files changed, 35 insertions, 6 deletions
diff --git a/webmentions_ssg/tasks/sender.py b/webmentions_ssg/tasks/sender.py
index 339dfe6..cf8ab9d 100644
--- a/webmentions_ssg/tasks/sender.py
+++ b/webmentions_ssg/tasks/sender.py
@@ -40,7 +40,7 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool:
:param webmention: Sent Webmention being processed.
:param revision: Source revision represented by the current attempt.
- :return: Whether the attempt is still current and requires processing.
+ :returns: Whether the attempt is still current and requires processing.
"""
db.session.refresh(webmention)
@@ -48,7 +48,11 @@ def attempt_is_current(webmention: SentWebmention, revision: int) -> bool:
def retry_delay(attempt: int) -> timedelta:
- """Calculate the capped exponential delay after a numbered send attempt."""
+ """Calculate the capped exponential delay after a numbered send attempt.
+
+ :param attempt: One-based send attempt number.
+ :returns: Delay until the next attempt, capped by the configured maximum.
+ """
base = max(1, int(current_app.config["SEND_RETRY_BASE_SECONDS"]))
maximum = max(base, int(current_app.config["SEND_RETRY_MAX_SECONDS"]))
return timedelta(seconds=min(base * 2 ** (attempt - 1), maximum))
@@ -63,6 +67,8 @@ def send_webmention(webmention_uuid: uuid.UUID) -> None:
scanner requeues them when due; Huey does not retry them independently.
The retry budget is per desired source revision.
+ Run the delivery workflow under a lock associated with the outgoing Webmention.
+
:param webmention_uuid: Identifier of the sent Webmention to process.
"""
# Huey locks have static names when used as decorators. Acquire one keyed by
@@ -107,7 +113,12 @@ class DeliveryResult:
def is_due(webmention: SentWebmention, now: datetime) -> bool:
- """Return whether an unprocessed Webmention has reached its retry deadline."""
+ """Return whether an unprocessed Webmention has reached its retry deadline.
+
+ :param webmention: Outgoing Webmention whose retry eligibility is checked.
+ :param now: Current timestamp against which the retry deadline is compared.
+ :returns: ``True`` if the Webmention is pending and its retry deadline has elapsed.
+ """
if not webmention.pending:
return False
@@ -124,6 +135,10 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
An attempt's next retry deadline is persisted *before* the HTTP request so
a lost worker cannot cause an immediate duplicate send.
+
+ :param webmention: Outgoing Webmention to reserve for sending.
+ :param now: Timestamp at which the attempt is claimed.
+ :returns: Reserved attempt details, or ``None`` if no attempt can be started.
"""
revision = webmention.desired_revision
max_attempts = max(1, int(current_app.config["SEND_MAX_ATTEMPTS"]))
@@ -199,7 +214,13 @@ def claim_attempt(webmention: SentWebmention, now: datetime) -> SendAttempt | No
def deliver_webmention(
source: str, target: str, *, webmention_uuid: uuid.UUID
) -> DeliveryResult:
- """Discover and POST a Webmention, returning an outcome without DB writes."""
+ """Discover and POST a Webmention, returning an outcome without DB writes.
+
+ :param source: Public source URL advertising the target link.
+ :param target: Target URL to notify.
+ :param webmention_uuid: Identifier used for delivery logging.
+ :returns: Delivery status, endpoint, response details, and any failure reason.
+ """
endpoint: str | None = None
response_status: int | None = None
status_url: str | None = None
@@ -275,7 +296,14 @@ def record_outcome(
*,
terminal: bool,
) -> bool:
- """Record an outcome only while the claimed source revision is current."""
+ """Record an outcome only while the claimed source revision is current.
+
+ :param webmention: Outgoing Webmention being updated.
+ :param attempt: Claimed revision and attempt details.
+ :param result: Result of the delivery attempt.
+ :param terminal: Whether this outcome ends attempts for the current revision.
+ :returns: ``True`` if the outcome was recorded for the current revision.
+ """
# A scanner may have reopened or superseded the revision during I/O.
if not attempt_is_current(webmention, attempt.revision):
return False
@@ -305,7 +333,8 @@ def record_outcome(
def _send_locked(webmention_uuid: uuid.UUID) -> bool:
"""Process a due Webmention while holding its per-UUID task lock.
- :return: Whether this worker recorded a delivery outcome.
+ :param webmention_uuid: Identifier of the outgoing Webmention being processed.
+ :returns: Whether this worker recorded a delivery outcome.
"""
webmention = db.session.get(SentWebmention, webmention_uuid)
if webmention is None: