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/net.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/net.py')
| -rw-r--r-- | webmentions_ssg/net.py | 47 |
1 files changed, 41 insertions, 6 deletions
diff --git a/webmentions_ssg/net.py b/webmentions_ssg/net.py index c9c2bec..262434a 100644 --- a/webmentions_ssg/net.py +++ b/webmentions_ssg/net.py @@ -179,7 +179,13 @@ class PublicHTTPTransport(httpx.HTTPTransport): def build_client(user_agent: str, *, accept: str | None = None) -> httpx.Client: - """Return the hardened HTTP client shared by receiver and sender.""" + """Return the hardened HTTP client shared by receiver and sender. + + :param user_agent: User-Agent header sent with each request. + :param accept: Optional Accept header for the client. + :returns: HTTP client configured with public-only transport, deadlines, and bounded + redirects. + """ headers = {"User-Agent": user_agent} if accept is not None: headers["Accept"] = accept @@ -199,6 +205,9 @@ def is_public_address(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> ``is_global`` alone does not reliably exclude IPv6 transition addresses across Python versions or networks with NAT64/6to4 routing. + + :param address: IPv4 or IPv6 address to classify. + :returns: ``True`` if the address is globally routable and safe to connect to. """ if isinstance(address, ipaddress.IPv6Address): # The well-known NAT64 prefix can translate an otherwise global IPv6 @@ -237,6 +246,12 @@ def public_addresses( entirety. IP literals are handled without DNS, including IPv6 literals. The returned strings must be used for the actual TCP connection; checking them and then connecting to ``hostname`` reintroduces DNS rebinding. + + :param hostname: Hostname or IP literal to validate. + :param lifetime: Optional maximum time allotted for DNS resolution, in seconds. + :returns: Checked numeric IP addresses to use for the TCP connection. + :raises AddressResolutionError: If DNS resolution fails or returns no addresses. + :raises UnsafeAddressError: If any resolved address is not publicly routable. """ try: addresses = (ipaddress.ip_address(hostname),) @@ -253,7 +268,11 @@ def public_addresses( def hostname_of(url: str) -> str | None: - """Return a normalized URL hostname, or None for malformed URLs.""" + """Return a normalized URL hostname, or None for malformed URLs. + + :param url: URL from which to extract a hostname. + :returns: Normalized hostname, or ``None`` when the URL is invalid or has no host. + """ try: hostname = urlsplit(url).hostname except TypeError, ValueError: @@ -262,7 +281,11 @@ def hostname_of(url: str) -> str | None: def content_type_of(headers: Mapping[str, str]) -> str: - """Return a normalized media type without Content-Type parameters.""" + """Return a normalized media type without Content-Type parameters. + + :param headers: HTTP response headers to inspect. + :returns: Lowercase media type without parameters, or an empty string if absent. + """ return headers.get("Content-Type", "").partition(";")[0].strip().lower() @@ -270,7 +293,7 @@ def is_http_url(url: str) -> bool: """Check whether a URL is an absolute HTTP or HTTPS URL. :param url: URL to validate. - :return: Whether the URL uses HTTP or HTTPS and contains a hostname. + :returns: Whether the URL uses HTTP or HTTPS and contains a hostname. """ try: parsed = urlsplit(url) @@ -281,7 +304,15 @@ def is_http_url(url: str) -> bool: def read_limited_body(response: httpx.Response, max_bytes: int, *, label: str) -> bytes: - """Read a streaming response, rejecting oversized declared or actual bodies.""" + """Read a streaming response, rejecting oversized declared or actual bodies. + + :param response: Streaming HTTP response to consume. + :param max_bytes: Maximum permitted response body size in bytes. + :param label: Description of the response for size-limit errors. + :returns: Response body if it fits within the configured byte limit. + :raises ResponseTooLargeError: If declared or streamed content exceeds the byte + limit. + """ if (content_length := response.headers.get("Content-Length")) is not None: try: declared_length = int(content_length) @@ -300,7 +331,11 @@ def read_limited_body(response: httpx.Response, max_bytes: int, *, label: str) - def is_temporary_status(status: int) -> bool: - """Return whether an HTTP status is normally retryable.""" + """Return whether an HTTP status is normally retryable. + + :param status: HTTP response status code to classify. + :returns: ``True`` if the HTTP status indicates a retryable failure. + """ return ( status in { |
