valentina-python-client 2.8.0__tar.gz → 3.0.0__tar.gz

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 2.8.0
+Version: 3.0.0
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -16,7 +16,7 @@ License: MIT License
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: anyio>=4.13.0,<5.0.0
-Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx2>=2.4.0
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: polyfactory>=3.3.0,<4.0.0
 Requires-Dist: pydantic[email]>=2.13.4,<3.0.0
@@ -33,7 +33,7 @@ Async and sync Python client library for accessing the Valentina Noir API.
 
 ## Features
 
-- **Async and sync clients** - Both `VClient` (async) and `SyncVClient` (sync) built on httpx
+- **Async and sync clients** - Both `VClient` (async) and `SyncVClient` (sync) built on httpx2
 - **Type-safe** - Full type hints with Pydantic models for request/response validation
 - **Convenient factory pattern** - Create a client once, access services from anywhere
 - **Automatic pagination** - Stream through large datasets with `iter_all()` or fetch everything with `list_all()`

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/README.md

@@ -4,7 +4,7 @@ Async and sync Python client library for accessing the Valentina Noir API.
 
 ## Features
 
-- **Async and sync clients** - Both `VClient` (async) and `SyncVClient` (sync) built on httpx
+- **Async and sync clients** - Both `VClient` (async) and `SyncVClient` (sync) built on httpx2
 - **Type-safe** - Full type hints with Pydantic models for request/response validation
 - **Convenient factory pattern** - Create a client once, access services from anywhere
 - **Automatic pagination** - Stream through large datasets with `iter_all()` or fetch everything with `list_all()`

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/pyproject.toml

@@ -6,7 +6,7 @@
     ]
     dependencies = [
         "anyio>=4.13.0, <5.0.0",
-        "httpx>=0.28.1",
+        "httpx2>=2.4.0",
         "loguru>=0.7.3",
         "polyfactory>=3.3.0, <4.0.0",
         "pydantic[email]>=2.13.4, <3.0.0",
@@ -16,7 +16,7 @@
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "2.8.0"
+    version = "3.0.0"
 
     [project.optional-dependencies]
         testing = ["polyfactory>=3.3.0"]
@@ -37,25 +37,27 @@
         "commitizen>=4.16.3",
         "coverage>=7.14.1",
         "duty>=1.9.0",
+        "httpx>=0.28.1",
         "prek>=0.4.4",
         "pytest-anyio>=0.0.0",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.1.0",
         "pytest-devtools>=1.2.0",
+        "pytest-httpx2>=1.0.0",
         "pytest-mock>=3.15.1",
         "pytest-repeat>=0.9.4",
         "pytest-sugar>=1.1.1",
         "pytest-xdist>=3.8.0",
-        "pytest>=9.0.3",
+        "pytest>=9.1.0",
         "respx>=0.23.1",
-        "ruff>=0.15.16",
+        "ruff>=0.15.17",
         "shellcheck-py>=0.11.0.1",
-        "ty>=0.0.44",
+        "ty>=0.0.49",
         "typos>=1.47.2",
         "vulture>=2.16",
         "yamllint>=1.38.0",
     ]
-    docs = ["zensical>=0.0.44"]
+    docs = ["zensical>=0.0.45"]
 
 [tool.commitizen]
     bump_message               = "bump(release): v$current_version → v$new_version"

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/__init__.py

@@ -116,4 +116,4 @@ __all__ = (
     "users_service",
 )
 
-__version__ = "2.8.0"
+__version__ = "3.0.0"

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/client.py

@@ -6,7 +6,7 @@ import platform
 from types import TracebackType
 from typing import TYPE_CHECKING, Self
 
-import httpx
+import httpx2
 from loguru import logger
 
 from vclient.config import _APIConfig
@@ -144,7 +144,7 @@ class SyncVClient:
             default_company_id=resolved_company_id,
             headers=headers or {},
         )
-        self._http: httpx.Client = self._create_http_client()
+        self._http: httpx2.Client = self._create_http_client()
         self._companies: SyncCompaniesService | None = None
         self._developer: SyncDeveloperService | None = None
         self._global_admin: SyncGlobalAdminService | None = None
@@ -160,7 +160,7 @@ class SyncVClient:
             max_retries=self._config.max_retries,
         ).info("Initialize SyncVClient")
 
-    def _create_http_client(self) -> httpx.Client:
+    def _create_http_client(self) -> httpx2.Client:
         """Create and configure the HTTP client."""
         from vclient import __version__
 
@@ -168,10 +168,10 @@ class SyncVClient:
         headers = {"Accept": "application/json", "User-Agent": user_agent, **self._config.headers}
         if self._config.api_key:
             headers[API_KEY_HEADER] = self._config.api_key
-        return httpx.Client(
+        return httpx2.Client(
             base_url=self._config.base_url,
             headers=headers,
-            timeout=httpx.Timeout(self._config.timeout),
+            timeout=httpx2.Timeout(self._config.timeout),
         )
 
     def __enter__(self) -> Self:

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/base.py

@@ -7,7 +7,7 @@ import uuid
 from collections.abc import Iterator
 from typing import TYPE_CHECKING, Any, TypeVar
 
-import httpx
+import httpx2
 from loguru import logger
 from pydantic import BaseModel, ValidationError as PydanticValidationError
 
@@ -57,7 +57,7 @@ class SyncBaseService:
         self._on_behalf_of: str | None = None
 
     @property
-    def _http(self) -> httpx.Client:
+    def _http(self) -> httpx2.Client:
         """Get the HTTP client from the parent SyncVClient."""
         return self._client._http
 
@@ -137,7 +137,7 @@ class SyncBaseService:
         data: dict[str, Any] | None = None,
         headers: dict[str, str] | None = None,
         files: Any | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make an HTTP request with automatic retry on transient errors.
 
         Retries on rate limits (429), server errors (5xx in retry_statuses),
@@ -153,7 +153,7 @@ class SyncBaseService:
             json: JSON body data.
             data: Form data.
             headers: Additional headers to include in the request.
-            files: Files to upload (passed through to httpx).
+            files: Files to upload (passed through to httpx2).
 
         Returns:
             The HTTP response.
@@ -161,8 +161,8 @@ class SyncBaseService:
         Raises:
             RateLimitError: When rate limit is exceeded and max retries are exhausted.
             ServerError: When server error occurs and max retries are exhausted.
-            httpx.ConnectError: When connection fails and max retries are exhausted.
-            httpx.TimeoutException: When request times out and max retries are exhausted.
+            httpx2.ConnectError: When connection fails and max retries are exhausted.
+            httpx2.TimeoutException: When request times out and max retries are exhausted.
             APIError: For other API error responses.
         """
         headers = self._merge_on_behalf_of_header(headers)
@@ -183,7 +183,7 @@ class SyncBaseService:
                     headers=headers,
                     files=files,
                 )
-            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+            except (httpx2.ConnectError, httpx2.TimeoutException) as exc:
                 if not self._is_retryable_method(method, headers) or attempt >= max_attempts - 1:
                     raise
                 error_type = type(exc).__name__
@@ -232,7 +232,7 @@ class SyncBaseService:
         raise RuntimeError(msg)
 
     @staticmethod
-    def _log_success_response(response: httpx.Response, request_logger: Any) -> None:
+    def _log_success_response(response: httpx2.Response, request_logger: Any) -> None:
         """Log a successful HTTP response with elapsed time and optional request_id.
 
         Args:
@@ -248,7 +248,7 @@ class SyncBaseService:
 
     @staticmethod
     def _inject_request_id_fallback(
-        response_data: dict[str, Any], response: httpx.Response
+        response_data: dict[str, Any], response: httpx2.Response
     ) -> None:
         """Inject request_id from X-Request-Id header when the response body omits it.
 
@@ -262,7 +262,7 @@ class SyncBaseService:
                 response_data["request_id"] = header_id
 
     def _raise_for_status(
-        self, response: httpx.Response, method: str, url: str, params: dict[str, Any] | None = None
+        self, response: httpx2.Response, method: str, url: str, params: dict[str, Any] | None = None
     ) -> None:
         """Raise appropriate exception for error responses.
 
@@ -356,7 +356,7 @@ class SyncBaseService:
             return None
 
     @staticmethod
-    def _parse_retry_after(response: httpx.Response) -> int | None:
+    def _parse_retry_after(response: httpx2.Response) -> int | None:
         """Parse the retry time from response headers.
 
         First checks the RateLimit header for the "t" parameter (seconds until next token),
@@ -382,7 +382,7 @@ class SyncBaseService:
             return None
 
     @staticmethod
-    def _parse_remaining_tokens(response: httpx.Response) -> int | None:
+    def _parse_remaining_tokens(response: httpx2.Response) -> int | None:
         """Parse the remaining tokens from the RateLimit header.
 
         Args:
@@ -402,7 +402,7 @@ class SyncBaseService:
         *,
         params: dict[str, Any] | None = None,
         headers: dict[str, str] | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make a GET request.
 
         Args:
@@ -466,7 +466,7 @@ class SyncBaseService:
         data: dict[str, Any] | None = None,
         params: dict[str, Any] | None = None,
         idempotency_key: str | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make a POST request.
 
         Args:
@@ -498,7 +498,7 @@ class SyncBaseService:
         data: dict[str, Any] | None = None,
         params: dict[str, Any] | None = None,
         idempotency_key: str | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make a PUT request.
 
         Args:
@@ -530,7 +530,7 @@ class SyncBaseService:
         data: dict[str, Any] | None = None,
         params: dict[str, Any] | None = None,
         idempotency_key: str | None = None,
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make a PATCH request.
 
         Args:
@@ -554,7 +554,7 @@ class SyncBaseService:
             headers=self._build_idempotency_headers(idempotency_key),
         )
 
-    def _delete(self, path: str, *, params: dict[str, Any] | None = None) -> httpx.Response:
+    def _delete(self, path: str, *, params: dict[str, Any] | None = None) -> httpx2.Response:
         """Make a DELETE request.
 
         Args:
@@ -568,7 +568,7 @@ class SyncBaseService:
 
     def _post_file(
         self, path: str, *, file: tuple[str, bytes, str], idempotency_key: str | None = None
-    ) -> httpx.Response:
+    ) -> httpx2.Response:
         """Make a POST request with a file upload (multipart/form-data).
 
         Args:
@@ -592,6 +592,34 @@ class SyncBaseService:
             headers=self._build_idempotency_headers(idempotency_key),
         )
 
+    def _put_file(
+        self, path: str, *, file: tuple[str, bytes, str], idempotency_key: str | None = None
+    ) -> httpx2.Response:
+        """Make a PUT request with a file upload (multipart/form-data).
+
+        Mirrors ``_post_file``: an idempotency key is sent only when supplied.
+
+        Args:
+            path: API endpoint path.
+            file: Tuple of (filename, content, content_type) for the file to upload.
+            idempotency_key: Optional idempotency key for safe retries.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            ServerError: When server error occurs and max retries are exhausted.
+            RateLimitError: When rate limit is exceeded and max retries are exhausted.
+            APIError: For other API error responses.
+        """
+        filename, content, content_type = file
+        return self._request(
+            "PUT",
+            path,
+            files={"data": (filename, content, content_type)},
+            headers=self._build_idempotency_headers(idempotency_key),
+        )
+
     def _get_paginated(
         self,
         path: str,

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/campaign_book_chapters.py

@@ -406,9 +406,17 @@ class SyncChaptersService(SyncBaseService):
     def upload_asset(
         self, chapter_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a chapter.
+        """Upload a new image asset for a chapter.
 
-        Uploads a file to S3 storage and associates it with the chapter.
+        Uploads an image to S3 storage and associates it with the chapter.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             chapter_id: The ID of the chapter to upload the asset for.

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/campaign_books.py

@@ -470,9 +470,17 @@ class SyncBooksService(SyncBaseService):
     def upload_asset(
         self, book_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a book.
+        """Upload a new image asset for a book.
 
-        Uploads a file to S3 storage and associates it with the book.
+        Uploads an image to S3 storage and associates it with the book.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             book_id: The ID of the book to upload the asset for.

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/campaigns.py

@@ -316,9 +316,17 @@ class SyncCampaignsService(SyncBaseService):
     def upload_asset(
         self, campaign_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a campaign.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the campaign.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             campaign_id: The ID of the campaign to upload the asset for.

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/characters.py

@@ -499,9 +499,17 @@ class SyncCharactersService(SyncBaseService):
     def upload_asset(
         self, character_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a campaign.
+        """Upload a new image asset for a character.
 
-        Uploads a file to S3 storage and associates it with the campaign.
+        Uploads an image to S3 storage and associates it with the character.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             character_id: The ID of the character to upload the asset for.

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/services/users.py

@@ -557,9 +557,17 @@ class SyncUsersService(SyncBaseService):
     def upload_asset(
         self, user_id: str, filename: str, content: bytes, content_type: str | None = None
     ) -> Asset:
-        """Upload a new asset for a user.
+        """Upload a new image asset for a user.
 
-        Uploads a file to S3 storage and associates it with the user.
+        Uploads an image to S3 storage and associates it with the user.
+
+        Only image files are accepted: PNG, JPEG, GIF, and WEBP. Any other
+        upload (documents, audio, video, archives, SVG, or a non-image payload
+        mislabeled as an image) is rejected with 400 Bad Request, as are
+        oversized images that trip the decompression-bomb guard. The stored
+        ``mime_type`` is detected from the file's bytes; the ``content_type``
+        argument is ignored server-side and cannot change or bypass the stored
+        type. Uploaded assets therefore always have ``asset_type == "image"``.
 
         Args:
             user_id: The ID of the user to upload the asset for.
@@ -583,6 +591,50 @@ class SyncUsersService(SyncBaseService):
         )
         return Asset.model_validate(response.json())
 
+    def upload_avatar(
+        self, user_id: str, filename: str, content: bytes, content_type: str | None = None
+    ) -> User:
+        """Upload a custom avatar for a user, replacing any existing one.
+
+        Accepts PNG, JPEG, WEBP, or GIF (first frame) up to 5 MB. The server
+        normalizes the image to a 512x512 WebP and it overrides any
+        identity-provider-derived avatar. Requires the ``On-Behalf-Of`` header
+        (permitted for the user themselves or an admin).
+
+        Args:
+            user_id: The ID of the user to set the avatar for.
+            filename: The original filename of the image.
+            content: The raw bytes of the image to upload.
+            content_type: The MIME type. If not provided, inferred from filename.
+
+        Returns:
+            The updated User object with the new ``avatar_url``.
+        """
+        if content_type is None:
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+        response = self._put_file(
+            self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id),
+            file=(filename, content, content_type),
+        )
+        return User.model_validate(response.json())
+
+    def delete_avatar(self, user_id: str) -> User:
+        """Remove a user's custom avatar.
+
+        The avatar falls back to the identity-provider avatar, or ``None`` if
+        none exists. Requires the ``On-Behalf-Of`` header (permitted for the
+        user themselves or an admin). Responds 200 OK with the updated user
+        body (not 204).
+
+        Args:
+            user_id: The ID of the user whose custom avatar to remove.
+
+        Returns:
+            The updated User object with the resolved ``avatar_url``.
+        """
+        response = self._delete(self._format_endpoint(Endpoints.USER_AVATAR, user_id=user_id))
+        return User.model_validate(response.json())
+
     def get_experience(self, user_id: str, campaign_id: str) -> CampaignExperience:
         """Retrieve a user's experience points and cool points for a specific campaign.
 

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/_sync/testing/_client.py

@@ -1,7 +1,7 @@
 # AUTO-GENERATED — do not edit. Run 'uv run duty generate_sync' to regenerate.
 """Fake async API client for testing downstream applications.
 
-FakeSyncVClient is a drop-in replacement for SyncVClient that uses httpx.MockTransport
+FakeSyncVClient is a drop-in replacement for SyncVClient that uses httpx2.MockTransport
 instead of real HTTP. All real service classes work unmodified.
 """
 
@@ -10,7 +10,7 @@ from __future__ import annotations
 import secrets
 from typing import TYPE_CHECKING, Any
 
-import httpx
+import httpx2
 from pydantic import BaseModel
 
 from vclient._sync.client import SyncVClient
@@ -65,10 +65,10 @@ class SyncFakeVClient(SyncVClient):
             **kwargs,
         )
 
-    def _create_http_client(self) -> httpx.Client:
+    def _create_http_client(self) -> httpx2.Client:
         """Create an HTTP client backed by the fake router."""
-        return httpx.Client(
-            transport=httpx.MockTransport(self._router.handle),
+        return httpx2.Client(
+            transport=httpx2.MockTransport(self._router.handle),
             base_url="https://fake.valentina-api.test",
         )
 

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/client.py

@@ -5,7 +5,7 @@ import platform
 from types import TracebackType
 from typing import TYPE_CHECKING, Self
 
-import httpx
+import httpx2
 from loguru import logger
 
 from vclient.config import _APIConfig
@@ -147,7 +147,7 @@ class VClient:
             headers=headers or {},
         )
 
-        self._http: httpx.AsyncClient = self._create_http_client()
+        self._http: httpx2.AsyncClient = self._create_http_client()
         self._companies: CompaniesService | None = None
         self._developer: DeveloperService | None = None
         self._global_admin: GlobalAdminService | None = None
@@ -165,7 +165,7 @@ class VClient:
             max_retries=self._config.max_retries,
         ).info("Initialize VClient")
 
-    def _create_http_client(self) -> httpx.AsyncClient:
+    def _create_http_client(self) -> httpx2.AsyncClient:
         """Create and configure the HTTP client."""
         from vclient import __version__
 
@@ -180,10 +180,10 @@ class VClient:
         if self._config.api_key:
             headers[API_KEY_HEADER] = self._config.api_key
 
-        return httpx.AsyncClient(
+        return httpx2.AsyncClient(
             base_url=self._config.base_url,
             headers=headers,
-            timeout=httpx.Timeout(self._config.timeout),
+            timeout=httpx2.Timeout(self._config.timeout),
         )
 
     async def __aenter__(self) -> Self:

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/endpoints.py

@@ -56,6 +56,7 @@ class Endpoints:
     USER_ASSETS = f"{USER}/assets"
     USER_ASSET = f"{USER_ASSETS}/{{asset_id}}"
     USER_ASSET_UPLOAD = f"{USER_ASSETS}/upload"
+    USER_AVATAR = f"{USER}/avatar"
     USER_EXPERIENCE_CAMPAIGN = f"{USER}/experience/{{campaign_id}}"
     USER_EXPERIENCE_XP_ADD = f"{USER}/experience/xp/add"
     USER_EXPERIENCE_XP_REMOVE = f"{USER}/experience/xp/remove"

{valentina_python_client-2.8.0 → valentina_python_client-3.0.0}/src/vclient/models/users.py

@@ -101,6 +101,10 @@ class User(BaseModel):
     google_profile: GoogleProfile | None = None
     github_profile: GitHubProfile | None = None
     apple_profile: AppleProfile | None = None
+    avatar_url: str | None = None
+    """Resolved avatar URL. Precedence: custom uploaded avatar (CloudFront URL),
+    then the identity-provider-derived avatar (currently Discord), else ``None``.
+    Prefer this over ``discord_profile.avatar_url`` for display."""
     campaign_experience: list[CampaignExperience] = Field(default_factory=list)
     asset_ids: list[str] = Field(default_factory=list)
     lifetime_xp: int = 0