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/tasks/discovery.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 '')
| -rw-r--r-- | webmentions_ssg/tasks/discovery.py | 26 |
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} |
