From 5bfcc3c06ebe6d6694221c25f07a4901572f97f5 Mon Sep 17 00:00:00 2001
From: Dennis Fink
Date: Thu, 20 Aug 2026 23:01:59 +0200
Subject: docs(core): add docstrings and type annotations

Document forms, validators, models, and views with PEP 287-style
docstrings and complete missing type annotations.

Add developer-readable representations for Webmention models and mark
the user password property as write-only in its return type.
---
 webmentions_ssg/views.py | 72 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

(limited to 'webmentions_ssg/views.py')

diff --git a/webmentions_ssg/views.py b/webmentions_ssg/views.py
index eb2b372..3430cea 100644
--- a/webmentions_ssg/views.py
+++ b/webmentions_ssg/views.py
@@ -33,11 +33,25 @@ root_page = Blueprint("root", __name__)
 
 @root_page.route("/")
 def index() -> ResponseReturnValue:
+    """
+    Redirect to the received Webmentions view.
+
+    :return: Redirect response to the received Webmentions view.
+    """
     return redirect(url_for("root.received"))
 
 
 @root_page.route("/login", methods=["GET", "POST"])
 def login() -> ResponseReturnValue:
+    """
+    Authenticate a user and start a login session.
+
+    Authenticated users are redirected to the application index. After a
+    successful login, the user is redirected to the requested local URL when
+    provided.
+
+    :return: Rendered login page or redirect response.
+    """
     if current_user.is_authenticated:
         return redirect(url_for("root.index"))
 
@@ -64,6 +78,11 @@ def login() -> ResponseReturnValue:
 
 @root_page.route("/logout")
 def logout() -> ResponseReturnValue:
+    """
+    End the current user's login session.
+
+    :return: Redirect response to the application index.
+    """
     logout_user()
     return redirect(url_for("root.index"))
 
@@ -71,6 +90,11 @@ def logout() -> ResponseReturnValue:
 @root_page.route("/received")
 @login_required
 def received() -> ResponseReturnValue:
+    """
+    Display received Webmentions.
+
+    :return: Rendered page containing the paginated received Webmentions.
+    """
     webmentions = db.paginate(
         sa.select(ReceivedWebmention).order_by(ReceivedWebmention.uuid.desc()),
         per_page=25,
@@ -87,6 +111,12 @@ def received() -> ResponseReturnValue:
 @root_page.post("/received/<uuid:identifier>/delete")
 @login_required
 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.
+    """
     form = forms.AdminActionForm()
 
     if not form.validate_on_submit():
@@ -110,6 +140,14 @@ def delete_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
 @root_page.post("/received/<uuid:identifier>/reverify")
 @login_required
 def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
+    """
+    Queue a received Webmention for reverification.
+
+    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.
+    """
     form = forms.AdminActionForm()
 
     if not form.validate_on_submit():
@@ -137,6 +175,11 @@ def reverify_received_webmention(identifier: uuid.UUID) -> ResponseReturnValue:
 @root_page.route("/sent")
 @login_required
 def sent() -> ResponseReturnValue:
+    """
+    Display sources with sent Webmentions.
+
+    :return: Rendered page containing the paginated source list.
+    """
     sources = db.paginate(
         sa.select(Source)
         .options(selectinload(Source.sent_webmentions))
@@ -153,7 +196,12 @@ def sent() -> ResponseReturnValue:
 
 @root_page.post("/sent/rescan")
 @login_required
-def rescan_sent_sources():
+def rescan_sent_sources() -> ResponseReturnValue:
+    """
+    Queue a manual scan of sent Webmention sources.
+
+    :return: Redirect response to the sent Webmentions view.
+    """
     form = forms.AdminActionForm()
     if form.validate_on_submit():
         manual_scan_sources()
@@ -164,6 +212,12 @@ def rescan_sent_sources():
 @root_page.route("/sent/<uuid:identifier>")
 @login_required
 def sent_source(identifier: uuid.UUID) -> ResponseReturnValue:
+    """
+    Display the sent Webmentions associated with a source.
+
+    :param identifier: Identifier of the source to display.
+    :return: Rendered source details page.
+    """
     source = db.session.scalar(
         sa.select(Source)
         .options(selectinload(Source.sent_webmentions))
@@ -186,6 +240,16 @@ def sent_source(identifier: uuid.UUID) -> ResponseReturnValue:
 @root_page.post("/endpoint")
 @CSRF.exempt
 def endpoint() -> ResponseReturnValue:
+    """
+    Receive and queue a Webmention for verification.
+
+    Existing Webmentions with the same source and target are reset for
+    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.
+    """
     form = forms.EndpointForm(meta={"csrf": False})
 
     if not form.validate_on_submit():
@@ -245,6 +309,12 @@ def endpoint() -> ResponseReturnValue:
 
 @root_page.route("/status/<uuid:identifier>")
 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.
+    """
     webmention = db.session.get(ReceivedWebmention, identifier)
 
     if webmention is None:
-- 
cgit v1.3.1