pyiv.network

Network client abstractions for pyiv.

This module provides network client abstractions following the chain of responsibility pattern. It supports various network protocols built into Python’s standard library, such as HTTP, HTTPS, and others.

Example

>>> from pyiv.network import HTTPClient
>>> HTTPClient().handler_type
'http'
class pyiv.network.HTTPClient[source]

Bases: NetworkClient

HTTP(S) client using stdlib urllib.

Use this for plain HTTP or HTTPS URLs when you want a zero-dependency client bound into the NETWORK_CLIENT chain. Prefer invalid-URL Traceback examples in docs/tests — do not hit the network from doctests.

Example

>>> client = HTTPClient()
>>> client.handler_type
'http'
>>> client.request("GET", "ftp://example.com")
Traceback (most recent call last):
    ...
ValueError: HTTPClient only supports http:// and https:// URLs, got: ftp://example.com
property handler_type: str

Return the handler type identifier.

Returns:

The handler type identifier (“http”)

request(method: str, url: str, headers: Dict[str, str] | None = None, data: str | bytes | None = None, timeout: float | None = None) → Dict[str, Any][source]

Make an HTTP request.

Parameters:

  • method – HTTP method (GET, POST, PUT, DELETE, etc.)

  • url – The URL to request (must start with http://)

  • headers – Optional dictionary of HTTP headers

  • data – Optional request body (string or bytes)

  • timeout – Optional timeout in seconds

Returns:

  • status: HTTP status code

  • headers: Response headers dictionary

  • body: Response body (bytes)

  • url: Final URL after redirects

Return type:

Dictionary containing

Raises:

  • ValueError – If URL does not start with http://

  • URLError – If the request fails

class pyiv.network.HTTPSClient[source]

Bases: NetworkClient

HTTPS-only client using stdlib urllib.

Use this when you want to reject non-HTTPS URLs at the client boundary (scheme must be https://). Like HTTPClient, doctests should use Traceback examples for invalid schemes rather than live network calls.

Example

>>> client = HTTPSClient()
>>> client.handler_type
'https'
>>> client.request("GET", "http://example.com")
Traceback (most recent call last):
    ...
ValueError: HTTPSClient only supports https:// URLs, got: http://example.com
property handler_type: str

Return the handler type identifier.

Returns:

The handler type identifier (“https”)

request(method: str, url: str, headers: Dict[str, str] | None = None, data: str | bytes | None = None, timeout: float | None = None) → Dict[str, Any][source]

Make an HTTPS request.

Parameters:

  • method – HTTP method (GET, POST, PUT, DELETE, etc.)

  • url – The URL to request (must start with https://)

  • headers – Optional dictionary of HTTP headers

  • data – Optional request body (string or bytes)

  • timeout – Optional timeout in seconds

Returns:

  • status: HTTP status code

  • headers: Response headers dictionary

  • body: Response body (bytes)

  • url: Final URL after redirects

Return type:

Dictionary containing

Raises:
class pyiv.network.NetworkClient[source]

Bases: ChainHandler

Abstract network client in the NETWORK_CLIENT chain.

Use this as the injectable type for protocol-specific clients (HTTP, HTTPS, etc.). Register concrete clients in a chain so callers dispatch by URL scheme without hard-coding urllib. Subclasses must implement handler_type and request().

Why this exists: Injectable HTTP-ish client so call sites do not hard-code urllib.

Example

>>> from typing import Any, Dict, Optional, Union
>>> from pyiv.network.base import NetworkClient
>>> class StubHTTP(NetworkClient):
...     @property
...     def handler_type(self) -> str:
...         return "http"
...     def request(
...         self,
...         method: str,
...         url: str,
...         headers: Optional[Dict[str, str]] = None,
...         data: Optional[Union[str, bytes]] = None,
...         timeout: Optional[float] = None,
...     ) -> Dict[str, Any]:
...         return {"status": 200, "headers": {}, "body": b"ok", "url": url}
>>> StubHTTP().request("GET", "http://example.test")["body"]
b'ok'
property chain_type: ChainType

Return the chain type (always NETWORK_CLIENT for NetworkClient).

Returns:

ChainType.NETWORK_CLIENT

handle(request: Any, **kwargs) → Any[source]

Handle a network request.

This is the chain handler interface. For NetworkClient, requests can be: - A tuple of (method, url, headers, data, timeout) -> returns response - A dict with “method”, “url”, etc. keys -> processes accordingly - A direct URL string -> performs GET request

Parameters:

  • request – The request (can be tuple, dict, or URL string)

  • **kwargs – Additional keyword arguments (method, url, headers, data, timeout)

Returns:

Response dictionary with status, headers, and body

abstract property handler_type: str

Return the protocol identifier (e.g., “http”, “https”).

Returns:

A string identifying the network protocol

abstract request(method: str, url: str, headers: Dict[str, str] | None = None, data: str | bytes | None = None, timeout: float | None = None) → Dict[str, Any][source]

Make a network request.

Parameters:

  • method – HTTP method (GET, POST, PUT, DELETE, etc.)

  • url – The URL to request

  • headers – Optional dictionary of HTTP headers

  • data – Optional request body (string or bytes)

  • timeout – Optional timeout in seconds

Returns:

  • status: HTTP status code

  • headers: Response headers dictionary

  • body: Response body (bytes)

  • url: Final URL after redirects

Return type:

Dictionary containing

Modules

base

Base NetworkClient interface for network operations.

clients

Standard library network client implementations.