aboutsummaryrefslogtreecommitdiff
path: root/webmentions_ssg/tasks/discovery.py
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--webmentions_ssg/tasks/discovery.py26
1 files changed, 15 insertions, 11 deletions
diff --git a/webmentions_ssg/tasks/discovery.py b/webmentions_ssg/tasks/discovery.py
index becac58..6d01e53 100644
--- a/webmentions_ssg/tasks/discovery.py
+++ b/webmentions_ssg/tasks/discovery.py
@@ -41,9 +41,8 @@ def resolve_endpoint(response: httpx.Response, href: str) -> str:
:param response: Response from which the endpoint was discovered.
:param href: Endpoint reference to resolve.
- :return: Absolute Webmention endpoint URL.
- :raises PermanentSenderError: If the resolved endpoint is not an HTTP or
- HTTPS URL.
+ :returns: Absolute Webmention endpoint URL.
+ :raises PermanentSenderError: If the resolved endpoint is not an HTTP or HTTPS URL.
"""
try:
endpoint = urljoin(str(response.url), href.strip())
@@ -60,7 +59,7 @@ def parse_link_value(value: str) -> tuple[str, set[str]] | None:
"""Parse a Link header value into its target and relations.
:param value: Link header value to parse.
- :return: Link target and relation names, or ``None`` if the value is invalid.
+ :returns: Link target and relation names, or ``None`` if the value is invalid.
"""
value = value.strip()
@@ -89,8 +88,8 @@ def endpoint_from_headers(response: httpx.Response) -> str | None:
"""Find a Webmention endpoint in the response Link headers.
:param response: HTTP response whose headers should be inspected.
- :return: First valid advertised Webmention endpoint, or ``None`` if none
- is found. Invalid candidates are ignored.
+ :returns: First valid advertised Webmention endpoint, or ``None`` if none is found.
+ Invalid candidates are ignored.
"""
for header in response.headers.get_list("Link"):
for value in LINK_SPLIT.split(header):
@@ -115,8 +114,8 @@ def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
:param response: HTTP response from which the document was retrieved.
:param body: HTML document body.
- :return: First valid advertised Webmention endpoint, or ``None`` if none
- is found. Invalid candidates are ignored.
+ :returns: First valid advertised Webmention endpoint, or ``None`` if none is found.
+ Invalid candidates are ignored.
"""
document = BeautifulSoup(body, "html5lib")
@@ -132,7 +131,12 @@ def endpoint_from_html(response: httpx.Response, body: bytes) -> str | None:
def read_target_body(response: httpx.Response) -> bytes:
- """Return a bounded target body, using the shared HTTP size guard."""
+ """Return a bounded target body, using the shared HTTP size guard.
+
+ :param response: HTTP response to read with the configured target-size limit.
+ :returns: Response body, provided it is within the target-size limit.
+ :raises PermanentSenderError: If the target document is too large.
+ """
try:
return read_limited_body(
response, current_app.config["MAX_TARGET_BYTES"], label="Target"
@@ -150,7 +154,7 @@ def discover_webmention_endpoint(client: httpx.Client, target: str) -> str | Non
:param client: HTTP client to use for discovery requests.
:param target: Target URL whose Webmention endpoint should be discovered.
- :return: Discovered Webmention endpoint, or ``None`` if none is advertised.
+ :returns: Discovered Webmention endpoint, or ``None`` if none is advertised.
:raises TemporarySenderError: If the target returns a temporary HTTP failure.
:raises PermanentSenderError: If GET returns a permanent HTTP failure.
"""
@@ -191,7 +195,7 @@ def post_webmention(
:param endpoint: Webmention endpoint URL.
:param source: Source URL of the Webmention.
:param target: Target URL of the Webmention.
- :return: HTTP response status code and optional status URL.
+ :returns: HTTP response status code and optional status URL.
"""
with client.stream(
"POST", endpoint, data={"source": source, "target": target}