🐷 Client

The main entry points for the Oinker library.

AsyncPiglet

The async client for the Porkbun API. Use this for async applications.

oinker.AsyncPiglet

AsyncPiglet(
    api_key: str | None = None,
    secret_key: str | None = None,
    *,
    base_url: str | None = None,
    timeout: float | None = None,
    max_retries: int | None = None,
    _http_client: AsyncClient | None = None,
)

Async client for the Porkbun API.

Use as an async context manager for proper resource cleanup:

async with AsyncPiglet() as piglet:
    pong = await piglet.ping()
    print(f"Your IP: {pong.your_ip}")

Credentials are loaded from environment variables by default

• PORKBUN_API_KEY
• PORKBUN_SECRET_KEY

Or pass them explicitly:

async with AsyncPiglet(api_key="pk1_...", secret_key="sk1_...") as piglet:
    ...

Initialize the async Porkbun client.

Parameters:

Name	Type	Description	Default
api_key	str | None	Porkbun API key. Falls back to PORKBUN_API_KEY env var.	None
secret_key	str | None	Porkbun secret key. Falls back to PORKBUN_SECRET_KEY env var.	None
base_url	str | None	Override the default API base URL.	None
timeout	float | None	Request timeout in seconds.	None
max_retries	int | None	Maximum retry attempts for transient failures.	None
_http_client	AsyncClient | None	Pre-configured httpx client (for testing).	None

Source code in src/oinker/_client.py

def __init__(
    self,
    api_key: str | None = None,
    secret_key: str | None = None,
    *,
    base_url: str | None = None,
    timeout: float | None = None,
    max_retries: int | None = None,
    _http_client: httpx.AsyncClient | None = None,
) -> None:
    """Initialize the async Porkbun client.

    Args:
        api_key: Porkbun API key. Falls back to PORKBUN_API_KEY env var.
        secret_key: Porkbun secret key. Falls back to PORKBUN_SECRET_KEY env var.
        base_url: Override the default API base URL.
        timeout: Request timeout in seconds.
        max_retries: Maximum retry attempts for transient failures.
        _http_client: Pre-configured httpx client (for testing).
    """
    self._config = OinkerConfig(
        api_key=api_key or "",
        secret_key=secret_key or "",
        base_url=base_url or BASE_URL,
        timeout=timeout or DEFAULT_TIMEOUT,
        max_retries=max_retries if max_retries is not None else DEFAULT_MAX_RETRIES,
    )
    self._http = HttpClient(self._config, client=_http_client)
    self._dns = AsyncDNSAPI(self._http)
    self._dnssec = AsyncDNSSECAPI(self._http)
    self._domains = AsyncDomainsAPI(self._http)
    self._ssl = AsyncSSLAPI(self._http)

dns property

dns: AsyncDNSAPI

Access DNS operations.

Returns:

Type	Description
AsyncDNSAPI	AsyncDNSAPI instance for DNS management.

domains property

domains: AsyncDomainsAPI

Access domain operations.

Returns:

Type	Description
AsyncDomainsAPI	AsyncDomainsAPI instance for domain management.

dnssec property

dnssec: AsyncDNSSECAPI

Access DNSSEC operations.

Returns:

Type	Description
AsyncDNSSECAPI	AsyncDNSSECAPI instance for DNSSEC management.

ssl property

ssl: AsyncSSLAPI

Access SSL operations.

Returns:

Type	Description
AsyncSSLAPI	AsyncSSLAPI instance for SSL certificate management.

ping async

ping() -> PingResponse

Test API connectivity and authentication.

Returns:

Type	Description
PingResponse	PingResponse with your public IP address.

Raises:

Type	Description
AuthenticationError	If credentials are invalid.
APIError	If the request fails.

Source code in src/oinker/_client.py

async def ping(self) -> PingResponse:
    """Test API connectivity and authentication.

    Returns:
        PingResponse with your public IP address.

    Raises:
        AuthenticationError: If credentials are invalid.
        APIError: If the request fails.
    """
    data = await self._http.post("/ping")
    return PingResponse(your_ip=data.get("yourIp", ""))

Piglet

The sync client, wrapping AsyncPiglet for synchronous code.

oinker.Piglet

Piglet(
    api_key: str | None = None,
    secret_key: str | None = None,
    *,
    base_url: str | None = None,
    timeout: float | None = None,
    max_retries: int | None = None,
    _http_client: AsyncClient | None = None,
)

Synchronous client for the Porkbun API.

A convenience wrapper around AsyncPiglet for non-async code.

piglet = Piglet()
pong = piglet.ping()
print(f"Your IP: {pong.your_ip}")
piglet.close()

Or use as a context manager:

with Piglet() as piglet:
    pong = piglet.ping()

Credentials are loaded from environment variables by default

• PORKBUN_API_KEY
• PORKBUN_SECRET_KEY

Initialize the sync Porkbun client.

Parameters:

Name	Type	Description	Default
api_key	str | None	Porkbun API key. Falls back to PORKBUN_API_KEY env var.	None
secret_key	str | None	Porkbun secret key. Falls back to PORKBUN_SECRET_KEY env var.	None
base_url	str | None	Override the default API base URL.	None
timeout	float | None	Request timeout in seconds.	None
max_retries	int | None	Maximum retry attempts for transient failures.	None
_http_client	AsyncClient | None	Pre-configured httpx client (for testing).	None

Source code in src/oinker/_sync.py

def __init__(
    self,
    api_key: str | None = None,
    secret_key: str | None = None,
    *,
    base_url: str | None = None,
    timeout: float | None = None,
    max_retries: int | None = None,
    _http_client: httpx.AsyncClient | None = None,
) -> None:
    """Initialize the sync Porkbun client.

    Args:
        api_key: Porkbun API key. Falls back to PORKBUN_API_KEY env var.
        secret_key: Porkbun secret key. Falls back to PORKBUN_SECRET_KEY env var.
        base_url: Override the default API base URL.
        timeout: Request timeout in seconds.
        max_retries: Maximum retry attempts for transient failures.
        _http_client: Pre-configured httpx client (for testing).
    """
    self._async_client = AsyncPiglet(
        api_key=api_key,
        secret_key=secret_key,
        base_url=base_url,
        timeout=timeout,
        max_retries=max_retries,
        _http_client=_http_client,
    )
    self._loop: asyncio.AbstractEventLoop | None = None
    self._dns: SyncDNSAPI | None = None
    self._dnssec: SyncDNSSECAPI | None = None
    self._domains: SyncDomainsAPI | None = None
    self._ssl: SyncSSLAPI | None = None

dns property

dns: SyncDNSAPI

Access DNS operations.

domains property

domains: SyncDomainsAPI

Access domain operations.

dnssec property

dnssec: SyncDNSSECAPI

Access DNSSEC operations.

ssl property

ssl: SyncSSLAPI

Access SSL operations.

ping

ping() -> PingResponse

Test API connectivity and authentication.

Returns:

Type	Description
PingResponse	PingResponse with your public IP address.

Raises:

Type	Description
AuthenticationError	If credentials are invalid.
APIError	If the request fails.

Source code in src/oinker/_sync.py

def ping(self) -> PingResponse:
    """Test API connectivity and authentication.

    Returns:
        PingResponse with your public IP address.

    Raises:
        AuthenticationError: If credentials are invalid.
        APIError: If the request fails.
    """
    return self._run(self._async_client.ping())

close

close() -> None

Close the client and release resources.

Source code in src/oinker/_sync.py

def close(self) -> None:
    """Close the client and release resources."""
    self._run(self._async_client.__aexit__(None, None, None))
    if self._loop is not None and not self._loop.is_running():
        self._loop.close()
        self._loop = None

PingResponse

oinker.PingResponse dataclass

PingResponse(your_ip: str)

Response from the ping endpoint.

Attributes:

Name	Type	Description
your_ip	str	The client's public IP address as seen by Porkbun.