aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/views/admin.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/views/admin.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/views/admin.py19
1 files changed, 11 insertions, 8 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()