Expose client option types

[RobertCraigie]

The type hints for the Client and AsyncClient __init__ methods are not publicly exposed, this means that I cannot type hint the arguments as I want to forward arguments to the Client to allow consumers to modify the internal httpx client that my library uses (see RobertCraigie/prisma-client-py#95).

An alternative solution to forwarding arguments would be for users to directly provide their own client instances, however I'd rather support forwarding arguments as I want to be able to set defaults for certain options and I do not know how well httpx plays with modifying options post __init__.

I already have a PR lined up for this if it is deemed necessary: RobertCraigie@bd21754

[lovelydinosaur]

I'd prefer that we avoid this if possible.

Something feels a bit odd about including types as part of our API, that I don't know how to express. (We include the byte stream cases because it's necessary to subclass them for some kinds of usage.)

[RobertCraigie]

Fair, the use case is very niche anyway.

[rattrayalex]

Heya @tomchristie, I'm running into this as well.

When building a client library for a given API, it's often nice to be able to pass various params through to the underlying httpx instance. In our case, proxies and timeout are some examples.

You can see here where we try to approximate the Proxies type, but it's a bit awkward: https://github.com/lithic-com/lithic-python/blob/main/lithic/_core.py#L18-L19

(The code you see there is outdated and contains type errors; in order to get mypy/pyright happy, we had to add # type: ignore comments where we pass proxies=proxies and transport=transport, which isn't great).

Any chance you'd be willing to reconsider this?

[Midnighter]

Hey there,

I came here with this exact issue.

Something feels a bit odd about including types as part of our API, that I don't know how to express.

@lovelydinosaur I will argue the exact opposite. The arguments to your public classes, in my case AsyncHTTPTransport.__init__, are part of their public interface, that means all types of those arguments are part of your public interface and should be exposed.

Concretely, I have a method where I want to pass through keyword arguments given to the method to the constructor of AsyncHTTPTransport. In order to properly type those keyword arguments, I need to use a TypedDict and unpack it. That then looks as below which is not good as it imports from "private" modules.

import ssl
from typing import Iterable, TypedDict

import httpx


class HTTPXAsyncHTTPTransportKeywordArguments(TypedDict, total=False):
    """Keyword arguments for the httpx.AsyncHTTPTransport constructor."""

    verify: ssl.SSLContext | str | bool
    cert: httpx._types.CertTypes | None
    trust_env: bool
    http1: bool
    http2: bool
    limits: httpx._config.Limits
    proxy: httpx._types.ProxyTypes | None
    uds: str | None
    local_address: str | None
    retries: int
    socket_options: Iterable[httpx._transports.default.SOCKET_OPTION] | None

and elsewhere I can then use that TypedDict

    @classmethod
    def create(
        cls,
        limiter: AbstractAsyncLimiter,
        **kwargs: Unpack[HTTPXAsyncHTTPTransportKeywordArguments],
    ) -> AsyncRateLimitedTransport:
        return cls(
            limiter=limiter,
            transport=httpx.AsyncHTTPTransport(**kwargs),
        )

[Midnighter]

See also the special issue with that in pyodide Midnighter/httpx-limiter#11