diff options
| author | Dennis Fink | 2026-11-14 18:44:23 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-14 18:44:23 +0100 |
| commit | 968e1b4e4a6fbd5a15037cdb11a3f9dee5108570 (patch) | |
| tree | 0096a0125c4d94a047e5bd24288e1f3f4a58ada5 /webmentions_ssg/views/endpoint.py | |
| parent | 2366d455c7d1ae16c84e0bcbffb94ed762c16832 (diff) | |
| download | webmentions-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/endpoint.py')
| -rw-r--r-- | webmentions_ssg/views/endpoint.py | 39 |
1 files changed, 33 insertions, 6 deletions
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) |
