Question about maintenance of the Async and Sync client function signatures

[Benoss]

I am working on a library that has support for sync and async and I quite like the way HTTPX does it.
Can you tell me if I get the high level design correct:

A BaseClient class with no IO that regroups everything that can be shared between sync and async

Client(BaseClient) the "sync" version of the client
AsyncClient(BaseClient) the async version of the client

The method signature between the sync and async clients are then identical with the exception of they keyword async in front of the AsyncClient version of it. Those functions are not implemented at all in the BaseClient.

My main question is, how do you maintain those 2 signatures? Is it just manual or is there a way to test for the difference during CI/CD to make sure that both public methods with the same name have the same parameters/response types

    def options(
        self,
        url: URLTypes,
        *,
        params: typing.Optional[QueryParamTypes] = None,
        headers: typing.Optional[HeaderTypes] = None,
        cookies: typing.Optional[CookieTypes] = None,
        auth: typing.Union[AuthTypes, UseClientDefault] = USE_CLIENT_DEFAULT,
        follow_redirects: typing.Union[bool, UseClientDefault] = USE_CLIENT_DEFAULT,
        timeout: typing.Union[TimeoutTypes, UseClientDefault] = USE_CLIENT_DEFAULT,
        extensions: typing.Optional[RequestExtensions] = None,
    ) -> Response:
        """
        Send an `OPTIONS` request.
        **Parameters**: See `httpx.request`.
        """
        return self.request(
            "OPTIONS",
            url,
            params=params,
            headers=headers,
            cookies=cookies,
            auth=auth,
            follow_redirects=follow_redirects,
            timeout=timeout,
            extensions=extensions,
        )

and async

    async def options(
        self,
        url: URLTypes,
        *,
        params: typing.Optional[QueryParamTypes] = None,
        headers: typing.Optional[HeaderTypes] = None,
        cookies: typing.Optional[CookieTypes] = None,
        auth: typing.Union[AuthTypes, UseClientDefault] = USE_CLIENT_DEFAULT,
        follow_redirects: typing.Union[bool, UseClientDefault] = USE_CLIENT_DEFAULT,
        timeout: typing.Union[TimeoutTypes, UseClientDefault] = USE_CLIENT_DEFAULT,
        extensions: typing.Optional[RequestExtensions] = None,
    ) -> Response:
        """
        Send an `OPTIONS` request.
        **Parameters**: See `httpx.request`.
        """
        return await self.request(
            "OPTIONS",
            url,
            params=params,
            headers=headers,
            cookies=cookies,
            auth=auth,
            follow_redirects=follow_redirects,
            timeout=timeout,
            extensions=extensions,
        )

[lovelydinosaur]

My main question is, how do you maintain those 2 signatures? Is it just manual or is there a way to test for the difference during CI/CD to make sure that both public methods with the same name have the same parameters/response types

Good question. So... There's not actually too much duplicated async/sync code in httpx. In this case we just manage that maintainance via code review. As you say, "manually".

That applies to the Client and AsyncClient cases, and also to a few methods on the Response model, such as read() vs. aread().

This is different to the approach that we take in the httpcore package, which is the networking layer we use in httpx. In that case we have a script that generates the sync version based on the async version. Our CI hooks into this and ensures that the two versions are in sync

The auto-generation approach is based on ideas from the trio team, who maintain an unasync tool. You might find that tool helpful for your own project.

[Benoss]

Thanks for the detailed answer, this helps a lot for my design
To help me maintain the signature I just wrote a small function that can compare 2 classes (sync and async)
I am planning to add this as part of the test suite so that CI/CD fails if it is not matching (I will probably have to add something to ignore some exceptions)

def compare_2_classes(sync_klass: type, async_klass: type) -> dict:
    """
    compare the signature of 2 class definition ignoring private methods
    check that async_klass has a method with the same name of sync_klass but returning a coroutine
    returns the difference between the 2 classes as a dict
    """
    import inspect

    sync_methods = {m for m in dir(sync_klass) if not m.startswith("_") and inspect.isfunction(getattr(sync_klass, m))}
    async_methods = {
        m for m in dir(async_klass) if not m.startswith("_") and inspect.iscoroutinefunction(getattr(async_klass, m))
    }
    common = sync_methods.intersection(async_methods)
    missing_from_sync = async_methods - sync_methods
    missing_from_async = sync_methods - async_methods
    issues = {}
    if len(missing_from_sync):
        issues["missing_from_sync"] = missing_from_sync
    if len(missing_from_async):
        issues["missing_from_async"] = missing_from_async

    # Compare each function signature types
    for method in common:
        sync_sig = inspect.signature(getattr(sync_klass, method))
        async_sig = inspect.signature(getattr(async_klass, method))
        if sync_sig != async_sig:
            issues[method] = {}
            issues[method]["issues"] = []
            for param_sync, param_async in zip(sync_sig.parameters.items(), async_sig.parameters.items(), strict=True):
                if param_sync != param_async:
                    key_sync, params_sync = param_sync
                    key_async, params_async = param_async

                    issues[method]["issues"].append(f"param {key_sync} | {key_async} {params_sync} != {params_async}")

            issues[method]["sync_sig"] = str(sync_sig)
            issues[method]["async_sig"] = str(async_sig)

    return issues

Out of curiosity I tested it on httpx Client vs AsyncClient and found one issue, the auth param in the get method has a slight difference in typing.