pyiv_common

Ubiquitous-library integrations for pyiv.

pyiv-common is the #include <stdlib.h> extra for pyiv: PyYAML and requests only. Core pyiv stays stdlib-only.

What Problem Does This Solve?

Libraries such as PyYAML and requests are everywhere in Python, but they are not the standard library. Putting them in core would break pyiv’s zero-runtime-dependency guarantee. A dedicated package per library would proliferate wheels. pyiv-common is that middle tier.

Real-World Use Cases: - YAML config files via YAMLSerDe - HTTP with the requests stack via RequestsClient - Injecting those types through a pyiv Config

Usage:

>>> from pyiv_common.serde import YAMLSerDe
>>> YAMLSerDe().handler_type
'yaml'
>>> from pyiv_common.network import RequestsClient
>>> RequestsClient().handler_type
'http'

class pyiv_common.RequestsClient

Bases: NetworkClient

HTTP(S) client using the requests library.

handler_type is "http" so it can replace urllib HTTPClient on the NETWORK_CLIENT chain. Both http:// and https:// URLs are accepted.

Example

>>> from pyiv import ChainType, Config, get_injector
>>> from pyiv_common.network import RequestsClient
>>> class MyConfig(Config):
...     def configure(self):
...         self.register_chain_handler(
...             ChainType.NETWORK_CLIENT, "http", RequestsClient
...         )
>>> injector = get_injector(MyConfig)
>>> client = injector.inject_chain_handler(ChainType.NETWORK_CLIENT, "http")
>>> isinstance(client, RequestsClient)
True

property handler_type: str

Return 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]

Make an HTTP request with requests.

Parameters:

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

• url – The URL to request (must be http:// or 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:

• ValueError – If URL is not http:// or https://

• requests.RequestException – If the request fails

class pyiv_common.YAMLSerDe

Bases: SerDe

YAML encoding SerDe using PyYAML.

Install with pip install pyiv-common. Register on the ENCODING chain like any other SerDe.

Example

>>> from pyiv import ChainType, Config, get_injector
>>> from pyiv_common.serde import YAMLSerDe
>>> class MyConfig(Config):
...     def configure(self):
...         self.register_chain_handler(ChainType.ENCODING, "yaml", YAMLSerDe)
>>> injector = get_injector(MyConfig)
>>> serde = injector.inject_chain_handler(ChainType.ENCODING, "yaml")
>>> serde.deserialize(serde.serialize({"a": 1}))
{'a': 1}

deserialize(data: str | bytes, target_type: Type[T] | None = None) → T

Deserialize YAML string/bytes back to a Python object.

Parameters:

• data – The YAML string or bytes

• target_type – Optional type hint for the expected result type

Returns:

Deserialized Python object

property handler_type: str

Return the handler type identifier (“yaml”).

serialize(obj: Any) → str

Serialize using YAML encoding.

Parameters:

obj – The Python object to serialize

Returns:

YAML string representation

Modules

serde	YAML SerDe for pyiv, backed by PyYAML.
network	requests-backed NetworkClient for pyiv.