aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/views
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/views
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 'webmentions_ssg/views')
-rw-r--r--webmentions_ssg/views/admin.py19
-rw-r--r--webmentions_ssg/views/endpoint.py39
-rw-r--r--webmentions_ssg/views/session.py6
3 files changed, 47 insertions, 17 deletions
diff --git a/webmentions_ssg/views/admin.py b/webmentions_ssg/views/admin.py
index f095de8..b9ab53e 100644
--- a/webmentions_ssg/views/admin.py
+++ b/webmentions_ssg/views/admin.py
@@ -22,7 +22,10 @@ from .blueprint import root_page
def validate_admin_action() -> None:
- """Reject invalid administrative action forms with HTTP 400."""
+ """Reject invalid administrative action forms with HTTP 400.
+
+ Abort the request when the posted form does not pass CSRF or other validation.
+ """
if not forms.AdminActionForm().validate_on_submit():
abort(400)
@@ -32,7 +35,7 @@ def validate_admin_action() -> None:
def received() -> ResponseReturnValue:
"""Display received Webmentions.
- :return: Rendered page containing the paginated received Webmentions.
+ :returns: Rendered page containing the paginated received Webmentions.
"""
webmentions = db.paginate(
sa.select(ReceivedWebmention).order_by(ReceivedWebmention.uuid.desc()),
@@ -53,7 +56,7 @@ def delete_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
"""Delete a received Webmention.
:param identifier: Identifier of the Webmention to delete.
- :return: Redirect response to the received Webmentions view.
+ :returns: Redirect response to the received Webmentions view.
"""
validate_admin_action()
@@ -77,7 +80,7 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
The Webmention status is reset before a new verification task is queued.
:param identifier: Identifier of the Webmention to reverify.
- :return: Redirect response to the received Webmentions view.
+ :returns: Redirect response to the received Webmentions view.
"""
validate_admin_action()
@@ -101,7 +104,7 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
def sent() -> ResponseReturnValue:
"""Display sources with sent Webmentions.
- :return: Rendered page containing the paginated source list.
+ :returns: Rendered page containing the paginated source list.
"""
sources = db.paginate(
sa.select(Source)
@@ -122,7 +125,7 @@ def sent() -> ResponseReturnValue:
def rescan_sent_sources() -> ResponseReturnValue:
"""Queue a manual scan of sent Webmention sources.
- :return: Redirect response to the sent Webmentions view.
+ :returns: Redirect response to the sent Webmentions view.
"""
validate_admin_action()
@@ -138,7 +141,7 @@ def sent_source(source_identifier: uuid.UUID) -> ResponseReturnValue:
"""Display the sent Webmentions associated with a source.
:param source_identifier: Identifier of the source to display.
- :return: Rendered source details page.
+ :returns: Rendered source details page.
"""
source = db.get_or_404(Source, source_identifier)
@@ -172,7 +175,7 @@ def resend_sent_webmention(
:param source_identifier: Identifier of the source owning the Webmention.
:param webmention_identifier: Identifier of the sent Webmention to resend.
- :return: Redirect response to the source details view.
+ :returns: Redirect response to the source details view.
"""
validate_admin_action()
diff --git a/webmentions_ssg/views/endpoint.py b/webmentions_ssg/views/endpoint.py
index a7badfd..85ec398 100644
--- a/webmentions_ssg/views/endpoint.py
+++ b/webmentions_ssg/views/endpoint.py
@@ -26,7 +26,14 @@ class UrlDigestCollisionError(Exception):
def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention | None:
- """Return the matching Webmention, or raise on a SHA-256 collision."""
+ """Return the matching Webmention, or raise on a SHA-256 collision.
+
+ :param source: Exact source URL to look up.
+ :param target: Exact target URL to look up.
+ :returns: Matching Webmention, or ``None`` if none is stored.
+ :raises UrlDigestCollisionError: If the digest matches a different source/target
+ pair.
+ """
webmention = db.session.execute(
sa.select(ReceivedWebmention).where(
ReceivedWebmention.url_digest == received_url_digest(source, target)
@@ -43,7 +50,14 @@ def find_webmention_by_digest(source: str, target: str) -> ReceivedWebmention |
def insert_webmention(source: str, target: str) -> ReceivedWebmention | None:
- """Insert and return a Webmention, or None if another request won the race."""
+ """Insert and return a Webmention, or None if another request won the race.
+
+ Use an atomic insert and treat uniqueness conflicts as concurrent submissions.
+
+ :param source: Source URL of the new Webmention.
+ :param target: Target URL of the new Webmention.
+ :returns: New Webmention, or ``None`` if a concurrent insert won.
+ """
webmention = ReceivedWebmention(uuid=uuid.uuid7(), source=source, target=target)
db.session.add(webmention)
@@ -57,7 +71,13 @@ def insert_webmention(source: str, target: str) -> ReceivedWebmention | None:
def reopen_if_cooled_down(webmention: ReceivedWebmention) -> bool:
- """Atomically reopen an old Webmention and return whether it was reopened."""
+ """Atomically reopen an old Webmention and return whether it was reopened.
+
+ Only a terminal Webmention beyond the cooldown interval can be reset.
+
+ :param webmention: Existing Webmention to conditionally reopen.
+ :returns: ``True`` when the Webmention was reopened for verification.
+ """
now = datetime.now(UTC)
cutoff = now - timedelta(
seconds=current_app.config["ENDPOINT_REVERIFY_COOLDOWN_SECONDS"]
@@ -80,6 +100,13 @@ def submit_received(source: str, target: str) -> tuple[uuid.UUID, bool] | None:
"""Return (identifier, enqueue flag), or None on a digest conflict.
A new submission is committed before it can be queued for verification.
+
+ Commit new submissions before returning whether a verification task should be
+ queued.
+
+ :param source: Submitted Webmention source URL.
+ :param target: Submitted Webmention target URL.
+ :returns: Webmention identifier and enqueue flag, or ``None`` on a digest collision.
"""
try:
if (webmention := find_webmention_by_digest(source, target)) is None:
@@ -108,8 +135,8 @@ def endpoint() -> ResponseReturnValue:
reverification. Concurrent insertion of the same Webmention is handled by
retrieving and updating the row created by the competing request.
- :return: HTTP 201 response with the Webmention status URL in the
- ``Location`` header, or validation errors with HTTP 400.
+ :returns: HTTP 201 response with the Webmention status URL in the ``Location``
+ header, or validation errors with HTTP 400.
"""
form = forms.EndpointForm(meta={"csrf": False})
@@ -139,7 +166,7 @@ def status(identifier: uuid.UUID) -> ResponseReturnValue:
"""Display the verification status of a received Webmention.
:param identifier: Identifier of the Webmention to display.
- :return: Rendered Webmention status page.
+ :returns: Rendered Webmention status page.
"""
webmention = db.get_or_404(ReceivedWebmention, identifier)
diff --git a/webmentions_ssg/views/session.py b/webmentions_ssg/views/session.py
index 870c967..371997d 100644
--- a/webmentions_ssg/views/session.py
+++ b/webmentions_ssg/views/session.py
@@ -21,7 +21,7 @@ from .blueprint import root_page
def index() -> ResponseReturnValue:
"""Redirect to the received Webmentions view.
- :return: Redirect response to the received Webmentions view.
+ :returns: Redirect response to the received Webmentions view.
"""
return redirect(url_for("root.received"))
@@ -45,7 +45,7 @@ def login() -> ResponseReturnValue:
successful login, the user is redirected to the requested local URL when
provided.
- :return: Rendered login page or redirect response.
+ :returns: Rendered login page or redirect response.
"""
if current_user.is_authenticated:
return redirect(url_for("root.index"))
@@ -77,7 +77,7 @@ def login() -> ResponseReturnValue:
def logout() -> ResponseReturnValue:
"""End the current user's login session.
- :return: Redirect response to the application index.
+ :returns: Redirect response to the application index.
"""
logout_user()
return redirect(url_for("root.index"))