clientele 2.0.0__tar.gz → 2.2.0__tar.gz

{clientele-2.0.0 → clientele-2.2.0}/.claude/settings.local.json

@@ -20,7 +20,12 @@
       "Bash(gh api *)",
       "Bash(python3 *)",
       "Bash(gh issue *)",
-      "WebSearch"
+      "WebSearch",
+      "Bash(uv pip *)",
+      "Bash(.venv/bin/pytest *)",
+      "Bash(.venv/bin/python *)",
+      "Bash(pip list *)",
+      "Bash(git *)"
     ]
   }
 }

{clientele-2.0.0 → clientele-2.2.0}/.github/workflows/ci.yml

@@ -1,13 +1,17 @@
 name: CI - Lint and Test
 
-on: [push]
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15-dev"]
     steps:
       #----------------------------------------------
       #       check-out repo and set-up python

{clientele-2.0.0 → clientele-2.2.0}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Change log
 
+## 2.2.0
+
+- Support OpenAPI `default` and `const` in schema generation ([#247](https://github.com/phalt/clientele/pull/247)).
+- Fix `$ref` parameter types and double-nullable handling in client generation ([#247](https://github.com/phalt/clientele/pull/247)).
+- Fix array response schemas being emitted as plain type aliases (`list[...]`) which pydantic rejects in `response_map` — they are now emitted as `clientele.schemas.ListResponse` subclasses, which support `len()`, indexing, and iteration directly ([#248](https://github.com/phalt/clientele/issues/248)).
+- Fix generated `config.py` documenting `API_BASE_URL` as the environment variable name when pydantic-settings reads `BASE_URL` — the example now uses the correct name ([#248](https://github.com/phalt/clientele/issues/248)).
+- Initial CI support for Python 3.15
+
+## 2.1.0
+
+- Introduce `RequestsHTTPBackend` for making HTTP requests using the `requests` library.
+  - This backend implements synchronous HTTP requests only.
+  - The library `requests` is not installed by default. See the documentation for installation instructions.
+- Introduce `AIOHTTPBackend` for making HTTP requests using the `aiohttp` library.
+  - This backend implements asynchronous HTTP requests only.
+  - The library `aiohttp` is not installed by default. See the documentation for installation instructions.
+- Introduce `NiquestsHTTPBackend` for making HTTP requests using the `niquests` library.
+  - This backend implements both synchronous and asynchronous HTTP requests.
+  - The library `niquests` is not installed by default. See the documentation for installation instructions.
+
 ## 2.0.0
 
 This release includes many breaking changes, improved type support, and dependency changes.

{clientele-2.0.0 → clientele-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clientele
-Version: 2.0.0
+Version: 2.2.0
 Summary: Clientele is a different way to build Python API Clients
 Project-URL: Homepage, https://clientele.dev
 Project-URL: Changelog, https://docs.clientele.dev/CHANGELOG/

{clientele-2.0.0 → clientele-2.2.0}/SECURITY.md

@@ -4,8 +4,8 @@
 
 | Version       | Supported          |
 | --------------| ------------------ |
-| 2.0.0         | :white_check_mark: |
-| 1.11.1 or less | :x:                |
+| 2.2.0         | :white_check_mark: |
+| 2.1.0 or less | :x:                |
 
 ## Reporting a Vulnerability
 

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/api/templates/config_py.jinja2

@@ -19,14 +19,12 @@ class Config(clientele_api.BaseConfig):
 
     Example:
         # From environment variables
-        export API_BASE_URL="https://api.example.com"
-        export BEARER_TOKEN="my-secret-token"
+        export BASE_URL="https://api.example.com"
         config = Config()
 
         # Direct instantiation
         config = Config(
-            api_base_url="https://api.example.com",
-            bearer_token="my-token",
+            base_url="https://api.example.com",
             timeout=10.0
         )
     """

clientele-2.2.0/clientele/generators/api/templates/schema_root_model.jinja2

@@ -0,0 +1,4 @@
+
+
+class {{class_name}}(ListResponse[{{inner_type}}]):
+    pass

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/api/templates/schemas_py.jinja2

@@ -6,3 +6,5 @@ import decimal
 import enum
 
 import pydantic
+
+from clientele.schemas import ListResponse  # noqa

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/base_clients.py

@@ -143,16 +143,20 @@ class BaseClientsGenerator:
             required = param.get("required", False) or in_ != "query"
             if in_ == "query":
                 # URL query string values
+                param_type = utils.resolve_forward_refs_for_client(utils.get_type(param["schema"]))
                 if required:
-                    query_args[clean_key] = utils.get_type(param["schema"])
+                    query_args[clean_key] = param_type
                 else:
-                    query_args[clean_key] = f"typing.Optional[{utils.get_type(param['schema'])}]"
+                    param_type = utils.strip_none_from_type(param_type)
+                    query_args[clean_key] = f"typing.Optional[{param_type}]"
             elif in_ == "path":
                 # Function arguments
+                param_type = utils.resolve_forward_refs_for_client(utils.get_type(param["schema"]))
                 if required:
-                    path_args[clean_key] = utils.get_type(param["schema"])
+                    path_args[clean_key] = param_type
                 else:
-                    path_args[clean_key] = f"typing.Optional[{utils.get_type(param['schema'])}]"
+                    param_type = utils.strip_none_from_type(param_type)
+                    path_args[clean_key] = f"typing.Optional[{param_type}]"
             elif in_ == "header":
                 # Header object arguments
                 headers_args[param["name"]] = utils.get_type(param["schema"])

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/cicerone_compat.py

@@ -191,6 +191,14 @@ def schema_to_dict(schema) -> dict:
     if hasattr(schema, "__pydantic_extra__") and schema.__pydantic_extra__ and "enum" in schema.__pydantic_extra__:
         result["enum"] = schema.__pydantic_extra__["enum"]
 
+    # Handle default - it's in the extra fields; use "in" check since defaults can be falsy
+    if hasattr(schema, "__pydantic_extra__") and schema.__pydantic_extra__ and "default" in schema.__pydantic_extra__:
+        result["default"] = schema.__pydantic_extra__["default"]
+
+    # Handle const - it's in the extra fields
+    if hasattr(schema, "__pydantic_extra__") and schema.__pydantic_extra__ and "const" in schema.__pydantic_extra__:
+        result["const"] = schema.__pydantic_extra__["const"]
+
     # Handle properties
     if hasattr(schema, "properties") and schema.properties:
         result["properties"] = {k: schema_to_dict(v) for k, v in schema.properties.items()}

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/shared/generators/schemas.py

@@ -54,12 +54,19 @@ class SchemasGenerator:
             sanitized_arg = utils.snake_case_prop(arg)
             arg_type = utils.get_type(arg_details)
             is_optional = required and arg not in required
+            has_default = "default" in arg_details
 
             needs_alias = sanitized_arg != arg
             if needs_alias:
                 has_aliases = True
 
-            if is_optional and not arg_type.startswith("typing.Optional["):
+            if has_default:
+                py_default = repr(arg_details["default"])
+                if needs_alias:
+                    type_string = f'{arg_type} = pydantic.Field(default={py_default}, alias="{arg}")'
+                else:
+                    type_string = f"{arg_type} = {py_default}"
+            elif is_optional and not arg_type.startswith("typing.Optional["):
                 if needs_alias:
                     type_string = f'typing.Optional[{arg_type}] = pydantic.Field(default=None, alias="{arg}")'
                 else:
@@ -128,10 +135,15 @@ class SchemasGenerator:
             return
 
         if schema.get("type") == "array":
-            array_type = utils.get_type(schema)
-            array_type = utils.remove_forward_ref_quotes(array_type)
-            template = self.writer.templates.get_template("schema_type_alias.jinja2")
-            content = template.render(class_name=schema_key, union_type=array_type)
+            # Emit a pydantic.RootModel subclass rather than a plain type alias.
+            # list[...] is a GenericAlias, not a type, so pydantic rejects it
+            # when it appears in response_map: dict[int, type[Any]].  A RootModel
+            # subclass is a proper class and satisfies that constraint.
+            items_schema = schema.get("items") or {}
+            item_type = utils.get_type(items_schema) if items_schema else "typing.Any"
+            item_type = utils.remove_forward_ref_quotes(item_type)
+            template = self.writer.templates.get_template("schema_root_model.jinja2")
+            content = template.render(class_name=schema_key, inner_type=item_type)
             self.writer.write_to_schemas(content, output_dir=self.output_dir)
             self.schemas[schema_key] = ""
             return

{clientele-2.0.0 → clientele-2.2.0}/clientele/generators/shared/utils.py

@@ -97,6 +97,9 @@ def get_func_name(operation: dict, path: str) -> str:
 
 
 def get_type(t):
+    if "const" in t:
+        return f"typing.Literal[{repr(t['const'])}]"
+
     t_type = t.get("type")
     t_format = t.get("format")
     t_nullable = t.get("nullable", False)
@@ -277,8 +280,21 @@ def remove_forward_ref_quotes(type_string: str) -> str:
     This is used for type aliases where forward references are not needed
     because all types are defined in the same module and model_rebuild() is called.
     """
-    import re
-
-    # Replace quoted strings within type annotations
-    # Pattern: matches quoted strings that are type names (alphanumeric + underscore)
     return re.sub(r'"([A-Za-z_][A-Za-z0-9_]*)"', r"\1", type_string)
+
+
+def resolve_forward_refs_for_client(type_string: str) -> str:
+    """Replace forward references with schemas module references for client.py context."""
+    return re.sub(r'"([A-Za-z_][A-Za-z0-9_]*)"', r"schemas.\1", type_string)
+
+
+def strip_none_from_type(type_string: str) -> str:
+    """Strip None/Optional wrapping so the caller can re-wrap without duplication."""
+    if type_string.startswith("typing.Optional[") and type_string.endswith("]"):
+        return type_string[len("typing.Optional[") : -1]
+    m = re.match(r"^typing\.Union\[(.+),\s*None\]$", type_string)
+    if m:
+        return m.group(1)
+    if type_string.endswith(" | None"):
+        return type_string[: -len(" | None")]
+    return type_string

clientele-2.2.0/clientele/http/aiohttp_backend.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import typing
+
+try:
+    import aiohttp as aiohttp_lib
+except ImportError as exc:
+    raise ImportError(
+        "The AiohttpHTTPBackend requires the 'aiohttp' library. Install it with: pip install aiohttp"
+    ) from exc
+
+from clientele.api import exceptions as api_exceptions
+from clientele.api.stream import hydrate_content
+from clientele.http import backends, response
+
+
+class AiohttpHTTPBackend(backends.HTTPBackend):
+    """Asynchronous-only HTTP backend using the aiohttp library.
+
+    Sync methods (build_client, send_sync_request, handle_sync_stream) raise
+    NotImplementedError. Use HttpxHTTPBackend for sync support.
+
+    Args:
+        base_url: Base URL prepended to all relative request paths.
+        headers: Default headers applied to every request.
+        timeout: Request timeout in seconds. None means no timeout.
+        follow_redirects: Whether to follow HTTP redirects.
+        verify: SSL certificate verification. False to disable; str CA bundle paths
+            are not supported (use an ssl.SSLContext via a custom connector instead).
+    """
+
+    _async_client: aiohttp_lib.ClientSession | None = None
+
+    def __init__(
+        self,
+        base_url: str = "",
+        headers: dict[str, str] | None = None,
+        timeout: float | None = 5.0,
+        follow_redirects: bool = False,
+        verify: bool | str = True,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.headers = headers or {}
+        self.aiohttp_timeout = (
+            aiohttp_lib.ClientTimeout(total=timeout) if timeout is not None else aiohttp_lib.ClientTimeout(total=None)
+        )
+        self.follow_redirects = follow_redirects
+        # aiohttp uses ssl=False to disable; str CA paths are not supported here
+        self._ssl: bool | None = None if verify else False
+
+    @classmethod
+    def from_config(cls, config: typing.Any) -> "AiohttpHTTPBackend":
+        return cls(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=config.timeout,
+            follow_redirects=config.follow_redirects,
+            verify=config.verify,
+        )
+
+    def _full_url(self, url: str) -> str:
+        if url.startswith("http://") or url.startswith("https://"):
+            return url
+        return self.base_url + url
+
+    def build_client(self) -> typing.Any:
+        raise NotImplementedError("AiohttpHTTPBackend does not support sync requests. Use HttpxHTTPBackend instead.")
+
+    def build_async_client(self) -> aiohttp_lib.ClientSession:
+        if not self._async_client or self._async_client.closed:
+            self._async_client = aiohttp_lib.ClientSession(headers=self.headers)
+        return self._async_client
+
+    @staticmethod
+    def convert_to_response(native_response: typing.Any) -> response.Response:
+        # Body must be pre-read via await resp.read() before calling this
+        content: bytes = native_response._body or b""
+        return response.Response(
+            status_code=native_response.status,
+            headers=dict(native_response.headers),
+            content=content,
+            request_method=native_response.method.upper(),
+            request_url=str(native_response.url),
+        )
+
+    def send_sync_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: typing.Any,
+    ) -> response.Response:
+        raise NotImplementedError("AiohttpHTTPBackend does not support sync requests. Use HttpxHTTPBackend instead.")
+
+    async def send_async_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: typing.Any,
+    ) -> response.Response:
+        session = self.build_async_client()
+        async with session.request(
+            method,
+            self._full_url(url),
+            timeout=self.aiohttp_timeout,
+            allow_redirects=self.follow_redirects,
+            ssl=self._ssl,
+            **kwargs,
+        ) as resp:
+            await resp.read()
+            return self.convert_to_response(resp)
+
+    def handle_sync_stream(
+        self,
+        method: str,
+        url: str,
+        inner_type: typing.Any,
+        response_parser: typing.Callable[[str], typing.Any] | None = None,
+        **kwargs: typing.Any,
+    ) -> typing.Generator[typing.Any, None, None]:
+        raise NotImplementedError("AiohttpHTTPBackend does not support sync requests. Use HttpxHTTPBackend instead.")
+        yield  # type: ignore[misc]
+
+    async def handle_async_stream(
+        self,
+        method: str,
+        url: str,
+        inner_type: typing.Any,
+        response_parser: typing.Callable[[str], typing.Any] | None = None,
+        **kwargs: typing.Any,
+    ) -> typing.AsyncGenerator[typing.Any, None]:
+        session = self.build_async_client()
+        async with session.request(
+            method,
+            self._full_url(url),
+            timeout=self.aiohttp_timeout,
+            allow_redirects=self.follow_redirects,
+            ssl=self._ssl,
+            **kwargs,
+        ) as resp:
+            if 400 <= resp.status < 600:
+                await resp.read()
+                generic_response = self.convert_to_response(resp)
+                raise api_exceptions.HTTPStatusError(
+                    response=generic_response,
+                    reason=f"HTTP {resp.status}",
+                )
+            while True:
+                line = await resp.content.readline()
+                if not line:
+                    break
+                decoded = line.decode("utf-8").rstrip("\r\n")
+                if not decoded:
+                    continue
+                if response_parser is not None:
+                    yield response_parser(decoded)
+                else:
+                    yield hydrate_content(decoded, inner_type)
+
+    def close(self) -> None:
+        pass
+
+    async def aclose(self) -> None:
+        if self._async_client and not self._async_client.closed:
+            await self._async_client.close()
+            self._async_client = None

clientele-2.2.0/clientele/http/niquests_backend.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import typing
+
+try:
+    import niquests as niquests_lib
+except ImportError as exc:
+    raise ImportError(
+        "The NiquestsHTTPBackend requires the 'niquests' library. Install it with: pip install niquests"
+    ) from exc
+
+from clientele.api import exceptions as api_exceptions
+from clientele.api.stream import hydrate_content
+from clientele.http import backends, response
+
+
+class NiquestsHTTPBackend(backends.HTTPBackend):
+    """HTTP backend using the niquests library, supporting both sync and async.
+
+    This backend supports both synchronous and asynchronous requests in a single instance.
+
+    Args:
+        base_url: Base URL prepended to all relative request paths.
+        headers: Default headers applied to every request.
+        timeout: Request timeout in seconds. None means no timeout.
+        follow_redirects: Whether to follow HTTP redirects.
+        verify: SSL certificate verification. True to enable, False to disable.
+    """
+
+    _sync_client: niquests_lib.Session | None = None
+    _async_client: niquests_lib.AsyncSession | None = None
+
+    def __init__(
+        self,
+        base_url: str = "",
+        headers: dict[str, str] | None = None,
+        timeout: float | None = 5.0,
+        follow_redirects: bool = False,
+        verify: bool = True,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.headers = headers or {}
+        self.timeout = timeout
+        self.follow_redirects = follow_redirects
+        self.verify = verify
+
+    @classmethod
+    def from_config(cls, config: typing.Any) -> NiquestsHTTPBackend:
+        return cls(
+            base_url=config.base_url,
+            headers=config.headers,
+            timeout=config.timeout,
+            follow_redirects=config.follow_redirects,
+            verify=bool(config.verify),
+        )
+
+    def _full_url(self, url: str) -> str:
+        if url.startswith("http://") or url.startswith("https://"):
+            return url
+        return self.base_url + url
+
+    def build_client(self) -> niquests_lib.Session:
+        if not self._sync_client:
+            session = niquests_lib.Session(headers=self.headers, timeout=self.timeout)
+            session.verify = self.verify
+            self._sync_client = session
+        return self._sync_client
+
+    def build_async_client(self) -> niquests_lib.AsyncSession:
+        if not self._async_client:
+            session = niquests_lib.AsyncSession(headers=self.headers, timeout=self.timeout)
+            session.verify = self.verify
+            self._async_client = session
+        return self._async_client
+
+    @staticmethod
+    def convert_to_response(native_response: typing.Any) -> response.Response:
+        # Accepts both sync Response and non-streaming async Response (same type)
+        return response.Response(
+            status_code=native_response.status_code,
+            headers=dict(native_response.headers),
+            content=native_response.content or b"",
+            text=native_response.text or "",
+            request_method=native_response.request.method,
+            request_url=native_response.request.url or "",
+        )
+
+    def send_sync_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: typing.Any,
+    ) -> response.Response:
+        session = self.build_client()
+        resp = session.request(
+            method,
+            self._full_url(url),
+            timeout=self.timeout,
+            allow_redirects=self.follow_redirects,
+            **kwargs,
+        )
+        return self.convert_to_response(resp)
+
+    async def send_async_request(
+        self,
+        method: str,
+        url: str,
+        **kwargs: typing.Any,
+    ) -> response.Response:
+        session = self.build_async_client()
+        # Non-streaming async returns a regular Response (sync content/text)
+        resp = await session.request(
+            method,
+            self._full_url(url),
+            timeout=self.timeout,
+            allow_redirects=self.follow_redirects,
+            **kwargs,
+        )
+        return self.convert_to_response(resp)
+
+    def handle_sync_stream(
+        self,
+        method: str,
+        url: str,
+        inner_type: typing.Any,
+        response_parser: typing.Callable[[str], typing.Any] | None = None,
+        **kwargs: typing.Any,
+    ) -> typing.Generator[typing.Any, None, None]:
+        session = self.build_client()
+        resp = session.request(
+            method,
+            self._full_url(url),
+            stream=True,
+            timeout=self.timeout,
+            allow_redirects=self.follow_redirects,
+            **kwargs,
+        )
+        try:
+            if resp.status_code is not None and 400 <= resp.status_code < 600:
+                generic_response = self.convert_to_response(resp)
+                raise api_exceptions.HTTPStatusError(
+                    response=generic_response,
+                    reason=f"HTTP {resp.status_code}",
+                )
+            for line in resp.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                if response_parser is not None:
+                    yield response_parser(line)
+                else:
+                    yield hydrate_content(line, inner_type)
+        finally:
+            resp.close()
+
+    async def handle_async_stream(
+        self,
+        method: str,
+        url: str,
+        inner_type: typing.Any,
+        response_parser: typing.Callable[[str], typing.Any] | None = None,
+        **kwargs: typing.Any,
+    ) -> typing.AsyncGenerator[typing.Any, None]:
+        session = self.build_async_client()
+        # stream=True returns AsyncResponse with async content/text/close
+        resp = await session.request(
+            method,
+            self._full_url(url),
+            stream=True,
+            timeout=self.timeout,
+            allow_redirects=self.follow_redirects,
+            **kwargs,
+        )
+        try:
+            if resp.status_code is not None and 400 <= resp.status_code < 600:
+                content = await resp.content or b""
+                text = await resp.text or ""
+                headers: dict[str, str] = {
+                    k: v if isinstance(v, str) else v.decode("latin-1") for k, v in resp.headers.items()
+                }
+                request_method = (resp.request.method or "GET") if resp.request is not None else "GET"
+                request_url = (resp.request.url or "") if resp.request is not None else ""
+                generic_response = response.Response(
+                    status_code=resp.status_code,
+                    headers=headers,
+                    content=content,
+                    text=text,
+                    request_method=request_method,
+                    request_url=request_url,
+                )
+                raise api_exceptions.HTTPStatusError(
+                    response=generic_response,
+                    reason=f"HTTP {resp.status_code}",
+                )
+            # AsyncResponse.iter_lines is annotated as a coroutine returning AsyncGenerator,
+            # but niquests implements it as an async generator function (runtime discrepancy).
+            # Assigning to Any lets us iterate correctly at runtime without misrepresenting types.
+            resp_any: typing.Any = resp
+            async for line in resp_any.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                if response_parser is not None:
+                    yield response_parser(line)
+                else:
+                    yield hydrate_content(line, inner_type)
+        finally:
+            await resp.close()
+
+    def close(self) -> None:
+        if self._sync_client is not None:
+            self._sync_client.close()
+            self._sync_client = None
+
+    async def aclose(self) -> None:
+        if self._async_client is not None:
+            await self._async_client.close()
+            self._async_client = None