Skip to content

BaseClient

Base class for all API clients.

Subclass from BaseClient and define appropriate attributes from the list below to create your own API client.

By default, all API client endpoints will share the same auth mechanism and HTTP client. This can be overridden on a per-endpoint basis if needed.

Attributes:

Name Type Description
base_url str | object | None

The base URL that all API endpoints will use.
auth BaseHttpClientAuth

Optional authentication to be used across all API endpoints. Can be any class supported by the HTTP client.
http_client BaseHttpClient | None

Optional HTTP client to be used across all API endpoints if not using the default (HTTPx). Or if wanting to customize the default client.

Raises:

Type Description
ClientSetupError

If the class attributes are not correctly defined.

Examples:

A very basic example of an API client definition:

Python
import quickapi


@dataclass
class ResponseBody:
    current_page: int
    data: list[str]


class GetFactsApi(quickapi.BaseApi[ResponseBody]):
    url = "/facts"
    response_body = ResponseBody


class MyClient(quickapi.BaseClient):
    base_url = "https://example.com"
    get_facts = quickapi.ApiEndpoint(GetFactsApi)

Which can be used like this:

Python
client = MyClient()
response = api.get_facts()
assert isinstance(response.body, ResponseBody)
Source code in quickapi/client.py
Python
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class BaseClient:
    """
    Base class for all API clients.

    Subclass from `BaseClient` and define appropriate attributes from
    the list below to create your own API client.

    By default, all API client endpoints will share the same auth mechanism
    and HTTP client. This can be overridden on a per-endpoint basis if needed.

    Attributes:
        base_url: The base URL that all API endpoints will use.
        auth: Optional authentication to be used across all API endpoints.
            Can be any class supported by the HTTP client.
        http_client: Optional HTTP client to be used across all API endpoints
            if not using the default (HTTPx). Or if wanting to customize the
            default client.

    Raises:
        ClientSetupError: If the class attributes are not correctly defined.

    Examples:
        A very basic example of an API client definition:

        ```python
        import quickapi


        @dataclass
        class ResponseBody:
            current_page: int
            data: list[str]


        class GetFactsApi(quickapi.BaseApi[ResponseBody]):
            url = "/facts"
            response_body = ResponseBody


        class MyClient(quickapi.BaseClient):
            base_url = "https://example.com"
            get_facts = quickapi.ApiEndpoint(GetFactsApi)
        ```

        Which can be used like this:

        ```python
        client = MyClient()
        response = api.get_facts()
        assert isinstance(response.body, ResponseBody)
        ```
    """

    base_url: str | object | None = None
    auth: BaseHttpClientAuth = None
    http_client: BaseHttpClient | None = HTTPxClient()

    def __init__(
        self,
        http_client: BaseHttpClient | None = None,
        auth: BaseHttpClientAuth = USE_DEFAULT,
        base_url: str | object = USE_DEFAULT,
    ):
        self.http_client = http_client or self.http_client
        self.auth = auth if auth != USE_DEFAULT else self.auth
        self.base_url = base_url if base_url != USE_DEFAULT else self.base_url