valentina-python-client 1.2.1__tar.gz → 1.3.1__tar.gz

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 1.2.1
+Version: 1.3.1
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: anyio>=4.12.1
 Requires-Dist: httpx>=0.28.1
+Requires-Dist: loguru>=0.7.3
 Requires-Dist: pydantic[email]>=2.12.5
 Requires-Python: >=3.13
 Project-URL: Homepage, https://docs.valentina-noir.com/python-api-client/
@@ -29,13 +30,13 @@ Async Python client library for accessing the Valentina Noir API.
 
 ## Features
 
--   **Async-first design** - Built on httpx for efficient async HTTP operations
--   **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()`
--   **Robust error handling** - Specific exception types for different error conditions
--   **Idempotency support** - Optional automatic idempotency keys for safe retries
--   **Rate limit handling** - Built-in support for automatic rate limit retries
+- **Async-first design** - Built on httpx for efficient async HTTP operations
+- **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()`
+- **Robust error handling** - Specific exception types for different error conditions
+- **Idempotency support** - Optional automatic idempotency keys for safe retries
+- **Rate limit handling** - Built-in support for automatic rate limit retries
 
 This client is a supported and up-to-date reference implementation for the Valentina Noir API. The full documentation for is available at https://docs.valentina-noir.com/python-api-client/.
 
@@ -61,12 +62,12 @@ The script reads configuration from (highest precedence first):
 
 1. CLI arguments (`--api-url`, `--api-key`, `--company-id`)
 2. System environment variables (`VALENTINA_CLIENT_BASE_URL`, `VALENTINA_CLIENT_API_KEY`, `VALENTINA_CLIENT_DEFAULT_COMPANY_ID`)
-3. A `.env.secrets` file in the project root
+3. A `.env.secret` file in the project root
 
 Exit codes: `0` = all constants match, `1` = mismatches found, `2` = missing configuration.
 
 ## Resources
 
--   [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)
--   [API Concepts](https://docs.valentina-noir.com/concepts/)
--   [API Reference](https://api.valentina-noir.com/docs)
+- [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)
+- [API Concepts](https://docs.valentina-noir.com/concepts/)
+- [API Reference](https://api.valentina-noir.com/docs)

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/README.md

@@ -4,13 +4,13 @@ Async Python client library for accessing the Valentina Noir API.
 
 ## Features
 
--   **Async-first design** - Built on httpx for efficient async HTTP operations
--   **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()`
--   **Robust error handling** - Specific exception types for different error conditions
--   **Idempotency support** - Optional automatic idempotency keys for safe retries
--   **Rate limit handling** - Built-in support for automatic rate limit retries
+- **Async-first design** - Built on httpx for efficient async HTTP operations
+- **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()`
+- **Robust error handling** - Specific exception types for different error conditions
+- **Idempotency support** - Optional automatic idempotency keys for safe retries
+- **Rate limit handling** - Built-in support for automatic rate limit retries
 
 This client is a supported and up-to-date reference implementation for the Valentina Noir API. The full documentation for is available at https://docs.valentina-noir.com/python-api-client/.
 
@@ -36,12 +36,12 @@ The script reads configuration from (highest precedence first):
 
 1. CLI arguments (`--api-url`, `--api-key`, `--company-id`)
 2. System environment variables (`VALENTINA_CLIENT_BASE_URL`, `VALENTINA_CLIENT_API_KEY`, `VALENTINA_CLIENT_DEFAULT_COMPANY_ID`)
-3. A `.env.secrets` file in the project root
+3. A `.env.secret` file in the project root
 
 Exit codes: `0` = all constants match, `1` = mismatches found, `2` = missing configuration.
 
 ## Resources
 
--   [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)
--   [API Concepts](https://docs.valentina-noir.com/concepts/)
--   [API Reference](https://api.valentina-noir.com/docs)
+- [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)
+- [API Concepts](https://docs.valentina-noir.com/concepts/)
+- [API Reference](https://api.valentina-noir.com/docs)

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/pyproject.toml

@@ -4,13 +4,13 @@
         "Programming Language :: Python :: 3.13",
         "Programming Language :: Python :: 3.14",
     ]
-    dependencies = ["anyio>=4.12.1", "httpx>=0.28.1", "pydantic[email]>=2.12.5"]
+    dependencies = ["anyio>=4.12.1", "httpx>=0.28.1", "loguru>=0.7.3", "pydantic[email]>=2.12.5"]
     description = "Async Python client library for the Valentina Noir API"
     license = { file = "LICENSE" }
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "1.2.1"
+    version = "1.3.1"
 
     [project.urls]
         Homepage   = "https://docs.valentina-noir.com/python-api-client/"
@@ -25,10 +25,10 @@
 
 [dependency-groups]
     dev = [
-        "commitizen>=4.13.7",
+        "commitizen>=4.13.8",
         "coverage>=7.13.4",
         "duty>=1.9.0",
-        "prek>=0.3.2",
+        "prek>=0.3.3",
         "pytest-anyio>=0.0.0",
         "pytest-clarity>=1.0.1",
         "pytest-cov>=7.0.0",
@@ -39,10 +39,10 @@
         "pytest-xdist>=3.8.0",
         "pytest>=9.0.2",
         "respx>=0.22.0",
-        "ruff>=0.15.1",
+        "ruff>=0.15.2",
         "shellcheck-py>=0.11.0.1",
         "ty>=0.0.17",
-        "typos>=1.43.4",
+        "typos>=1.43.5",
         "vulture>=2.14",
         "yamllint>=1.38.0",
     ]
@@ -52,7 +52,7 @@
     changelog_merge_prerelease = true
     tag_format                 = "v$version"
     update_changelog_on_bump   = true
-    version                    = "1.0.1"
+    version_files              = ["src/vclient/__init__.py:__version__"]
     version_provider           = "uv"
 
 [tool.coverage.report] # https://coverage.readthedocs.io/en/latest/config.html#report
@@ -80,26 +80,6 @@
 [tool.coverage.xml]
     output = ".cache/coverage.xml"
 
-[tool.mypy] # https://mypy.readthedocs.io/en/latest/config_file.html
-    cache_dir                   = ".cache/mypy"
-    disallow_any_unimported     = false
-    disallow_subclassing_any    = false
-    disallow_untyped_decorators = false
-    disallow_untyped_defs       = true
-    exclude                     = ['duties.py', 'tests/']
-    follow_imports              = "normal"
-    ignore_missing_imports      = true
-    junit_xml                   = ".cache/mypy.xml"
-    no_implicit_optional        = true
-    pretty                      = false
-    show_column_numbers         = true
-    show_error_codes            = true
-    show_error_context          = true
-    strict_optional             = false
-    warn_redundant_casts        = true
-    warn_unreachable            = true
-    warn_unused_ignores         = true
-
 [tool.pytest.ini_options]
 
     addopts        = "--color=yes --doctest-modules --strict-config --strict-markers -n auto --dist loadfile"

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/__init__.py

@@ -11,8 +11,28 @@ For models, use: from vclient.models import Character, Campaign, ...
 For service classes, use: from vclient.services import CharactersService, ...
 """
 
-from vclient.client import VClient
-from vclient.registry import (
+import logging as _logging
+
+from loguru import logger as _logger
+
+
+class _PropagateHandler(_logging.Handler):
+    """Forward loguru messages to stdlib logging for caplog/handler compatibility."""
+
+    def emit(self, record: _logging.LogRecord) -> None:
+        _logging.getLogger(record.name).handle(record)
+
+
+_logger.add(
+    _PropagateHandler(),
+    format="{message}",
+    filter=lambda record: record["name"].startswith("vclient"),
+)
+
+_logger.disable("vclient")
+
+from vclient.client import VClient  # noqa: E402
+from vclient.registry import (  # noqa: E402
     books_service,
     campaigns_service,
     chapters_service,
@@ -50,3 +70,5 @@ __all__ = (
     "system_service",
     "users_service",
 )
+
+__version__ = "1.3.1"

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/client.py

@@ -1,16 +1,19 @@
 """Main API client for Valentina."""
 
 import os
+import platform
 from types import TracebackType
 from typing import TYPE_CHECKING, Self
 
 import httpx
+from loguru import logger
 
 from vclient.config import _APIConfig
 from vclient.constants import (
     API_KEY_HEADER,
     DEFAULT_MAX_RETRIES,
     DEFAULT_RETRY_DELAY,
+    DEFAULT_RETRY_STATUSES,
     DEFAULT_TIMEOUT,
     ENV_API_KEY,
     ENV_BASE_URL,
@@ -76,6 +79,7 @@ class VClient:
         retry_delay: float = DEFAULT_RETRY_DELAY,
         auto_retry_rate_limit: bool = True,
         auto_idempotency_keys: bool = False,
+        retry_statuses: set[int] | frozenset[int] | None = None,
         default_company_id: str | None = None,
         headers: dict[str, str] | None = None,
         set_as_default: bool = True,
@@ -100,6 +104,8 @@ class VClient:
             auto_retry_rate_limit: Automatically retry requests that hit rate limits.
             auto_idempotency_keys: Automatically generate idempotency keys for
                 POST/PUT/PATCH requests.
+            retry_statuses: HTTP status codes that trigger automatic retries.
+                Defaults to {429, 500, 502, 503, 504}.
             default_company_id: Default company ID to use when not explicitly provided
                 to service factory methods. Falls back to
                 VALENTINA_CLIENT_DEFAULT_COMPANY_ID.
@@ -132,6 +138,9 @@ class VClient:
             retry_delay=retry_delay,
             auto_retry_rate_limit=auto_retry_rate_limit,
             auto_idempotency_keys=auto_idempotency_keys,
+            retry_statuses=frozenset(retry_statuses)
+            if retry_statuses is not None
+            else DEFAULT_RETRY_STATUSES,
             default_company_id=resolved_company_id,
             headers=headers or {},
         )
@@ -147,11 +156,22 @@ class VClient:
 
             configure_default_client(self)
 
+        logger.bind(
+            base_url=self._config.base_url,
+            timeout=self._config.timeout,
+            max_retries=self._config.max_retries,
+        ).info("Initialize VClient")
+
     def _create_http_client(self) -> httpx.AsyncClient:
         """Create and configure the HTTP client."""
+        from vclient import __version__
+
+        user_agent = f"vclient/{__version__} Python/{platform.python_version()}"
+
         headers = {
             "Accept": "application/json",
             "Content-Type": "application/json",
+            "User-Agent": user_agent,
             **self._config.headers,
         }
 
@@ -179,7 +199,11 @@ class VClient:
 
     async def close(self) -> None:
         """Close the HTTP client and release resources."""
+        from vclient.registry import clear_default_client
+
+        logger.bind(base_url=self._config.base_url).info("Close VClient")
         await self._http.aclose()
+        clear_default_client(self)
 
     @property
     def is_closed(self) -> bool:

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/config.py

@@ -5,6 +5,7 @@ from dataclasses import dataclass, field
 from vclient.constants import (
     DEFAULT_MAX_RETRIES,
     DEFAULT_RETRY_DELAY,
+    DEFAULT_RETRY_STATUSES,
     DEFAULT_TIMEOUT,
 )
 
@@ -23,6 +24,7 @@ class _APIConfig:
         retry_delay: Base delay between retries in seconds.
         auto_retry_rate_limit: Automatically retry requests that hit rate limits (429).
         auto_idempotency_keys: Automatically generate idempotency keys for POST/PUT/PATCH.
+        retry_statuses: HTTP status codes that trigger automatic retries.
         default_company_id: Default company ID to use when not explicitly provided.
     """
 
@@ -33,6 +35,7 @@ class _APIConfig:
     retry_delay: float = DEFAULT_RETRY_DELAY
     auto_retry_rate_limit: bool = True
     auto_idempotency_keys: bool = False
+    retry_statuses: frozenset[int] = DEFAULT_RETRY_STATUSES
     default_company_id: str | None = None
     headers: dict[str, str] = field(default_factory=dict)
 

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/constants.py

@@ -14,6 +14,8 @@ ENV_DEFAULT_COMPANY_ID = "VALENTINA_CLIENT_DEFAULT_COMPANY_ID"
 DEFAULT_TIMEOUT = 30.0
 DEFAULT_MAX_RETRIES = 3
 DEFAULT_RETRY_DELAY = 1.0
+DEFAULT_RETRY_STATUSES: frozenset[int] = frozenset({429, 500, 502, 503, 504})
+IDEMPOTENT_HTTP_METHODS: frozenset[str] = frozenset({"GET", "PUT", "DELETE"})
 
 # Pagination defaults
 DEFAULT_PAGE_LIMIT = 10

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/campaigns.py

@@ -1,6 +1,7 @@
 """Pydantic models for Campaign API responses and requests."""
 
 from datetime import datetime
+from typing import Annotated
 
 from pydantic import BaseModel, Field
 
@@ -39,7 +40,7 @@ class CampaignCreate(BaseModel):
     """
 
     name: str = Field(min_length=3, max_length=50)
-    description: str | None = Field(default=None, min_length=3)
+    description: Annotated[str, Field(min_length=3)] | None = None
     desperation: int = Field(default=0, ge=0, le=5)
     danger: int = Field(default=0, ge=0, le=5)
 
@@ -50,10 +51,10 @@ class CampaignUpdate(BaseModel):
     Only include fields that need to be changed; omitted fields remain unchanged.
     """
 
-    name: str | None = Field(default=None, min_length=3, max_length=50)
-    description: str | None = Field(default=None, min_length=3)
-    desperation: int | None = Field(default=None, ge=0, le=5)
-    danger: int | None = Field(default=None, ge=0, le=5)
+    name: Annotated[str, Field(min_length=3, max_length=50)] | None = None
+    description: Annotated[str, Field(min_length=3)] | None = None
+    desperation: Annotated[int, Field(ge=0, le=5)] | None = None
+    danger: Annotated[int, Field(ge=0, le=5)] | None = None
 
 
 __all__ = [

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/character_blueprint.py

@@ -123,7 +123,7 @@ class CharacterConcept(BaseModel):
 
     id: str
     name: str
-    description: str | None = None
+    description: str
     date_created: datetime
     date_modified: datetime
     examples: list[str]

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/characters.py

@@ -1,7 +1,7 @@
 """Pydantic models for Character API responses and requests."""
 
 from datetime import datetime
-from typing import Any
+from typing import Annotated
 
 from pydantic import BaseModel, Field
 
@@ -29,8 +29,10 @@ class VampireAttributes(BaseModel):
     clan_name: str | None = Field(default=None, description="Name of the vampire clan.")
     generation: int | None = Field(default=None, description="Vampire generation.")
     sire: str | None = Field(default=None, description="Name of the vampire's sire.")
-    bane: dict[str, Any] | None = Field(default=None, description="Clan bane details.")
-    compulsion: dict[str, Any] | None = Field(default=None, description="Clan compulsion details.")
+    bane: NameDescriptionSubDocument | None = Field(default=None, description="Clan bane details.")
+    compulsion: NameDescriptionSubDocument | None = Field(
+        default=None, description="Clan compulsion details."
+    )
 
 
 class VampireAttributesCreate(BaseModel):
@@ -63,6 +65,7 @@ class WerewolfAttributes(BaseModel):
     pack_name: str | None = Field(default=None, description="Name of the werewolf's pack.")
     rite_ids: list[str] = Field(default_factory=list, description="List of werewolf rite IDs.")
     gift_ids: list[str] = Field(default_factory=list, description="List of werewolf gift IDs.")
+    total_renown: int = Field(default=0, description="Total renown.")
 
 
 class WerewolfAttributesCreate(BaseModel):
@@ -153,20 +156,22 @@ class Character(BaseModel):
     # Identity
     name_first: str = Field(..., min_length=3, description="Character's first name.")
     name_last: str = Field(..., min_length=3, description="Character's last name.")
-    name_nick: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nickname."
+    name_nick: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nickname."
     )
     name: str = Field(..., description="Character's display name.")
     name_full: str = Field(..., description="Character's full name.")
 
     # Biography
     age: int | None = Field(default=None, description="Character's age.")
-    biography: str | None = Field(default=None, min_length=3, description="Character biography.")
-    demeanor: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's demeanor."
+    biography: Annotated[str, Field(min_length=3)] | None = Field(
+        default=None, description="Character biography."
+    )
+    demeanor: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's demeanor."
     )
-    nature: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nature."
+    nature: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nature."
     )
     concept_id: str | None = Field(default=None, description="ID of the character concept.")
 
@@ -218,16 +223,18 @@ class CharacterCreate(BaseModel):
 
     # Optional fields
     type: CharacterType | None = Field(default=None, description="Character type.")
-    name_nick: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nickname."
+    name_nick: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nickname."
     )
     age: int | None = Field(default=None, description="Character's age.")
-    biography: str | None = Field(default=None, min_length=3, description="Character biography.")
-    demeanor: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's demeanor."
+    biography: Annotated[str, Field(min_length=3)] | None = Field(
+        default=None, description="Character biography."
+    )
+    demeanor: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's demeanor."
     )
-    nature: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nature."
+    nature: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nature."
     )
     concept_id: str | None = Field(default=None, description="ID of the character concept.")
     user_player_id: str | None = Field(
@@ -261,21 +268,25 @@ class CharacterUpdate(BaseModel):
     game_version: GameVersion | None = None
     status: CharacterStatus | None = None
 
-    name_first: str | None = Field(
-        default=None, min_length=3, description="Character's first name."
+    name_first: Annotated[str, Field(min_length=3)] | None = Field(
+        default=None, description="Character's first name."
     )
-    name_last: str | None = Field(default=None, min_length=3, description="Character's last name.")
-    name_nick: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nickname."
+    name_last: Annotated[str, Field(min_length=3)] | None = Field(
+        default=None, description="Character's last name."
+    )
+    name_nick: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nickname."
     )
 
     age: int | None = None
-    biography: str | None = Field(default=None, min_length=3, description="Character biography.")
-    demeanor: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's demeanor."
+    biography: Annotated[str, Field(min_length=3)] | None = Field(
+        default=None, description="Character biography."
+    )
+    demeanor: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's demeanor."
     )
-    nature: str | None = Field(
-        default=None, min_length=3, max_length=50, description="Character's nature."
+    nature: Annotated[str, Field(min_length=3, max_length=50)] | None = Field(
+        default=None, description="Character's nature."
     )
     concept_id: str | None = Field(default=None, description="ID of the character concept.")
 

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/companies.py

@@ -1,6 +1,7 @@
 """Pydantic models for Company API responses."""
 
 from datetime import datetime
+from typing import Annotated
 
 from pydantic import BaseModel, Field
 
@@ -77,7 +78,7 @@ class CompanyCreate(BaseModel):
 
     name: str = Field(min_length=3, max_length=50)
     email: str
-    description: str | None = Field(default=None, min_length=3)
+    description: Annotated[str, Field(min_length=3)] | None = None
     settings: CompanySettings | None = None
 
 
@@ -87,9 +88,9 @@ class CompanyUpdate(BaseModel):
     Only include fields that need to be changed; omitted fields remain unchanged.
     """
 
-    name: str | None = Field(default=None, min_length=3, max_length=50)
+    name: Annotated[str, Field(min_length=3, max_length=50)] | None = None
     email: str | None = None
-    description: str | None = Field(default=None, min_length=3)
+    description: Annotated[str, Field(min_length=3)] | None = None
     settings: CompanySettings | None = None
 
 

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/diceroll.py

@@ -12,16 +12,16 @@ class DiceRollResultSchema(BaseModel):
 
     total_result: int | None = None
     total_result_type: RollResultType
-    total_result_humanized: str | None = None
+    total_result_humanized: str
     total_dice_roll: list[int] = Field(default_factory=list)
     player_roll: list[int] = Field(default_factory=list)
     desperation_roll: list[int] = Field(default_factory=list)
-    total_dice_roll_emoji: str | None = None
-    total_dice_roll_shortcode: str | None = None
-    player_roll_emoji: str | None = None
-    player_roll_shortcode: str | None = None
-    desperation_roll_emoji: str | None = None
-    desperation_roll_shortcode: str | None = None
+    total_dice_roll_emoji: str
+    total_dice_roll_shortcode: str
+    player_roll_emoji: str
+    player_roll_shortcode: str
+    desperation_roll_emoji: str
+    desperation_roll_shortcode: str
 
 
 class Diceroll(BaseModel):

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/dictionary.py

@@ -15,6 +15,8 @@ class DictionaryTerm(BaseModel):
     synonyms: list[str] = Field(default_factory=list)
     date_created: datetime
     date_modified: datetime
+    is_global: bool = False
+    company_id: str | None = None
 
 
 class DictionaryTermCreate(BaseModel):

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/shared.py

@@ -1,7 +1,7 @@
 """Shared Pydantic models used across multiple services."""
 
 from datetime import datetime
-from typing import Any
+from typing import Annotated, Any
 
 from pydantic import BaseModel, Field
 
@@ -40,11 +40,14 @@ class S3Asset(BaseModel):
     id: str
     date_created: datetime
     date_modified: datetime
-    file_type: S3AssetType
+    asset_type: S3AssetType
+    mime_type: str
     original_filename: str
     public_url: str
     uploaded_by: str
+    company_id: str
     parent_type: S3AssetParentType | None = None
+    parent_id: str | None = None
 
 
 # -----------------------------------------------------------------------------
@@ -81,8 +84,8 @@ class NoteUpdate(BaseModel):
     Only include fields that need to be changed; omitted fields remain unchanged.
     """
 
-    title: str | None = Field(default=None, min_length=3, max_length=50)
-    content: str | None = Field(default=None, min_length=3)
+    title: Annotated[str, Field(min_length=3, max_length=50)] | None = None
+    content: Annotated[str, Field(min_length=3)] | None = None
 
 
 # -----------------------------------------------------------------------------
@@ -190,7 +193,7 @@ class CharacterSpecialty(BaseModel):
 
     name: str
     type: SpecialtyType
-    description: str | None = None
+    description: str
 
 
 __all__ = [

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/models/users.py

@@ -1,6 +1,7 @@
 """Pydantic models for User API responses and requests."""
 
 from datetime import datetime
+from typing import Annotated
 
 from pydantic import BaseModel, Field
 
@@ -89,7 +90,7 @@ class UserUpdate(BaseModel):
     Only include fields that need to be changed; omitted fields remain unchanged.
     """
 
-    name: str | None = Field(default=None, min_length=3, max_length=50)
+    name: Annotated[str, Field(min_length=3, max_length=50)] | None = None
     email: str | None = None
     role: UserRole | None = None
     discord_profile: DiscordProfile | None = None
@@ -124,7 +125,7 @@ class QuickrollCreate(BaseModel):
     """
 
     name: str = Field(min_length=3, max_length=50)
-    description: str | None = Field(default=None, min_length=3)
+    description: Annotated[str, Field(min_length=3)] | None = None
     trait_ids: list[str] = Field(default_factory=list)
 
 
@@ -134,8 +135,8 @@ class QuickrollUpdate(BaseModel):
     Only include fields that need to be changed; omitted fields remain unchanged.
     """
 
-    name: str | None = Field(default=None, min_length=3, max_length=50)
-    description: str | None = Field(default=None, min_length=3)
+    name: Annotated[str, Field(min_length=3, max_length=50)] | None = None
+    description: Annotated[str, Field(min_length=3)] | None = None
     trait_ids: list[str] | None = None
 
 

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/registry.py

@@ -64,6 +64,21 @@ def configure_default_client(client: "VClient") -> None:
     _default_client = client
 
 
+def clear_default_client(client: "VClient") -> None:
+    """Clear the default client if it matches the given instance.
+
+    Called automatically by ``VClient.close()`` so that subsequent calls to
+    ``default_client()`` raise a clear ``RuntimeError`` instead of returning a
+    closed HTTP session.
+
+    Args:
+        client: The client instance to compare against the current default.
+    """
+    global _default_client  # noqa: PLW0603
+    if _default_client is client:
+        _default_client = None
+
+
 def default_client() -> "VClient":
     """Retrieve the configured default client.
 

{valentina_python_client-1.2.1 → valentina_python_client-1.3.1}/src/vclient/services/base.py

@@ -7,6 +7,7 @@ from collections.abc import AsyncIterator
 from typing import TYPE_CHECKING, Any, TypeVar
 
 import httpx
+from loguru import logger
 from pydantic import BaseModel, ValidationError as PydanticValidationError
 
 from vclient.constants import (
@@ -14,6 +15,7 @@ from vclient.constants import (
     HTTP_500_INTERNAL_SERVER_ERROR,
     HTTP_600_UPPER_BOUND,
     IDEMPOTENCY_KEY_HEADER,
+    IDEMPOTENT_HTTP_METHODS,
     MAX_PAGE_LIMIT,
     RATE_LIMIT_HEADER,
 )
@@ -109,6 +111,25 @@ class BaseService:
         jitter = random.uniform(0, delay * 0.25)
         return delay + jitter
 
+    @staticmethod
+    def _is_retryable_method(method: str, headers: dict[str, str] | None) -> bool:
+        """Check if a request method is safe to retry.
+
+        Idempotent methods (GET, PUT, DELETE) are always safe. Non-idempotent
+        methods (POST, PATCH) are only safe if an idempotency key is present.
+
+        Args:
+            method: The HTTP method (uppercase).
+            headers: The request headers, or None.
+
+        Returns:
+            True if the request is safe to retry.
+        """
+        if method in IDEMPOTENT_HTTP_METHODS:
+            return True
+
+        return IDEMPOTENCY_KEY_HEADER in (headers or {})
+
     async def _request(
         self,
         method: str,
@@ -118,11 +139,15 @@ class BaseService:
         json: dict[str, Any] | None = None,
         data: dict[str, Any] | None = None,
         headers: dict[str, str] | None = None,
+        files: Any | None = None,
     ) -> httpx.Response:
-        """Make an HTTP request with automatic retry on rate limits.
+        """Make an HTTP request with automatic retry on transient errors.
 
-        When rate limited (429), automatically retries with exponential backoff
-        if auto_retry_rate_limit is enabled in the config.
+        Retries on rate limits (429), server errors (5xx in retry_statuses),
+        and network errors (ConnectError, TimeoutException). Non-idempotent
+        methods (POST, PATCH) only retry on 5xx/network errors when an
+        idempotency key header is present. Rate limit retries (429) always
+        apply regardless of method.
 
         Args:
             method: HTTP method (GET, POST, PUT, DELETE, etc.).
@@ -131,56 +156,109 @@ class BaseService:
             json: JSON body data.
             data: Form data.
             headers: Additional headers to include in the request.
+            files: Files to upload (passed through to httpx).
 
         Returns:
             The HTTP response.
 
         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.
             APIError: For other API error responses.
         """
         config = self._client._config  # noqa: SLF001
         max_attempts = config.max_retries + 1 if config.auto_retry_rate_limit else 1
+        retry_statuses = config.retry_statuses
+        request_logger = logger.bind(method=method, url=path)
 
-        last_error: RateLimitError | None = None
+        request_logger.debug("Send request")
+
+        last_error: RateLimitError | ServerError | None = None
 
         for attempt in range(max_attempts):
-            response = await self._http.request(
-                method=method,
-                url=path,
-                params=params,
-                json=json,
-                data=data,
-                headers=headers,
-            )
+            try:
+                response = await self._http.request(
+                    method=method,
+                    url=path,
+                    params=params,
+                    json=json,
+                    data=data,
+                    headers=headers,
+                    files=files,
+                )
+            except (httpx.ConnectError, httpx.TimeoutException) as exc:
+                if not self._is_retryable_method(method, headers) or attempt >= max_attempts - 1:
+                    raise
+
+                error_type = type(exc).__name__
+                delay = self._calculate_backoff_delay(attempt, retry_after=None)
+                request_logger.bind(
+                    error_type=error_type,
+                    attempt=attempt + 1,
+                    max_attempts=max_attempts,
+                    delay=delay,
+                ).warning("Retry after network error")
+                await asyncio.sleep(delay)
+                continue
 
             try:
-                self._raise_for_status(response)
+                self._raise_for_status(response, method, path)
+
+                elapsed_ms = response.elapsed.total_seconds() * 1000
+                request_logger.bind(
+                    status=response.status_code,
+                    elapsed_ms=elapsed_ms,
+                ).debug("Receive response")
                 return response  # noqa: TRY300
             except RateLimitError as e:
                 last_error = e
 
-                # If this was the last attempt, don't wait
                 if attempt >= max_attempts - 1:
                     break
 
-                # Calculate backoff and wait
                 delay = self._calculate_backoff_delay(attempt, e.retry_after)
+                request_logger.bind(
+                    attempt=attempt + 1,
+                    max_attempts=max_attempts,
+                    delay=delay,
+                ).warning("Retry after rate limit")
+                await asyncio.sleep(delay)
+            except ServerError as e:
+                if e.status_code not in retry_statuses or not self._is_retryable_method(
+                    method, headers
+                ):
+                    raise
+
+                last_error = e
+
+                if attempt >= max_attempts - 1:
+                    break
+
+                delay = self._calculate_backoff_delay(attempt, retry_after=None)
+                request_logger.bind(
+                    status=e.status_code,
+                    attempt=attempt + 1,
+                    max_attempts=max_attempts,
+                    delay=delay,
+                ).warning("Retry after server error")
                 await asyncio.sleep(delay)
 
-        # Re-raise the last rate limit error
         if last_error is not None:
+            request_logger.bind(attempts=max_attempts).error("Exhaust retries")
             raise last_error
 
-        # This should never happen, but satisfies type checker
         msg = "Unexpected state: no response or error"
         raise RuntimeError(msg)
 
-    def _raise_for_status(self, response: httpx.Response) -> None:
+    def _raise_for_status(self, response: httpx.Response, method: str, url: str) -> None:
         """Raise appropriate exception for error responses.
 
         Args:
             response: The HTTP response to check.
+            method: The HTTP method of the request.
+            url: The URL path of the request.
 
         Raises:
             AuthenticationError: For 401 responses.
@@ -203,14 +281,7 @@ class BaseService:
             response_data = {}
             message = response.text or f"HTTP {status_code}"
 
-        error_map: dict[int, type[APIError]] = {
-            400: ValidationError,
-            401: AuthenticationError,
-            403: AuthorizationError,
-            404: NotFoundError,
-            409: ConflictError,
-            429: RateLimitError,
-        }
+        error_logger = logger.bind(method=method, url=url, status=status_code)
 
         if status_code == 429:  # noqa: PLR2004
             retry_after = self._parse_retry_after(response)
@@ -219,8 +290,25 @@ class BaseService:
                 message, status_code, response_data, retry_after=retry_after, remaining=remaining
             )
 
-        if status_code in error_map:
-            raise error_map[status_code](message, status_code, response_data)
+        if status_code == 401:  # noqa: PLR2004
+            error_logger.error("Fail authentication")
+            raise AuthenticationError(message, status_code, response_data)
+
+        if status_code == 403:  # noqa: PLR2004
+            error_logger.error("Deny authorization")
+            raise AuthorizationError(message, status_code, response_data)
+
+        if status_code == 404:  # noqa: PLR2004
+            error_logger.debug("Return 404")
+            raise NotFoundError(message, status_code, response_data)
+
+        if status_code == 400:  # noqa: PLR2004
+            error_logger.warning("Reject with validation error")
+            raise ValidationError(message, status_code, response_data)
+
+        if status_code == 409:  # noqa: PLR2004
+            error_logger.warning("Return 409 conflict")
+            raise ConflictError(message, status_code, response_data)
 
         if HTTP_500_INTERNAL_SERVER_ERROR <= status_code < HTTP_600_UPPER_BOUND:
             raise ServerError(message, status_code, response_data)
@@ -480,40 +568,18 @@ class BaseService:
             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.
         """
-        config = self._client._config  # noqa: SLF001
-        max_attempts = config.max_retries + 1 if config.auto_retry_rate_limit else 1
-
-        last_error: RateLimitError | None = None
-        headers = self._build_idempotency_headers(idempotency_key)
         filename, content, content_type = file
 
-        for attempt in range(max_attempts):
-            response = await self._http.post(
-                url=path,
-                files={"file": (filename, content, content_type)},
-                headers=headers,
-            )
-
-            try:
-                self._raise_for_status(response)
-                return response  # noqa: TRY300
-            except RateLimitError as e:
-                last_error = e
-
-                if attempt >= max_attempts - 1:
-                    break
-
-                delay = self._calculate_backoff_delay(attempt, e.retry_after)
-                await asyncio.sleep(delay)
-
-        if last_error is not None:
-            raise last_error
-
-        msg = "Unexpected state: no response or error"
-        raise RuntimeError(msg)
+        return await self._request(
+            "POST",
+            path,
+            files={"file": (filename, content, content_type)},
+            headers=self._build_idempotency_headers(idempotency_key),
+        )
 
     # -------------------------------------------------------------------------
     # Pagination Methods