valentina-python-client 1.1.1__tar.gz → 1.2.0__tar.gz

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: valentina-python-client
-Version: 1.1.1
+Version: 1.2.0
 Summary: Async Python client library for the Valentina Noir API
 Author: Nate Landau
 Author-email: Nate Landau <github@natenate.org>
@@ -43,6 +43,28 @@ This client is a supported and up-to-date reference implementation for the Valen
 
 For complete documentation including configuration options, all available services, response models, and error handling, see the **[Full Documentation](https://docs.valentina-noir.com/python-api-client/)**.
 
+## Development Tools
+
+### Validate Constants
+
+Verify that the `Literal` type constants in this package are in sync with the live API's `/options` endpoint. This catches drift between client and server before a release.
+
+```bash
+# Via duty task
+uv run duty validate_constants
+
+# Via script directly
+uv run python scripts/validate_constants.py --api-key <key> --company-id <id>
+```
+
+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
+
+Exit codes: `0` = all constants match, `1` = mismatches found, `2` = missing configuration.
+
 ## Resources
 
 -   [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/README.md

@@ -18,6 +18,28 @@ This client is a supported and up-to-date reference implementation for the Valen
 
 For complete documentation including configuration options, all available services, response models, and error handling, see the **[Full Documentation](https://docs.valentina-noir.com/python-api-client/)**.
 
+## Development Tools
+
+### Validate Constants
+
+Verify that the `Literal` type constants in this package are in sync with the live API's `/options` endpoint. This catches drift between client and server before a release.
+
+```bash
+# Via duty task
+uv run duty validate_constants
+
+# Via script directly
+uv run python scripts/validate_constants.py --api-key <key> --company-id <id>
+```
+
+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
+
+Exit codes: `0` = all constants match, `1` = mismatches found, `2` = missing configuration.
+
 ## Resources
 
 -   [Full Client Documentation](https://docs.valentina-noir.com/python-api-client/)

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/pyproject.toml

@@ -10,7 +10,7 @@
     name = "valentina-python-client"
     readme = "README.md"
     requires-python = ">=3.13"
-    version = "1.1.1"
+    version = "1.2.0"
 
     [project.urls]
         Homepage   = "https://docs.valentina-noir.com/python-api-client/"
@@ -140,8 +140,13 @@
             "TD002",  # Missing author in TODO
             "TD003",  # Missing issue link on the line following this TODO
         ]
-        per-file-ignores = { "src/vclient/services/*.py" = [
+        per-file-ignores = { "scripts/*.py" = [
+            "INP001", # Implicit namespace package (no __init__.py needed)
+            "T201",   # print() is intentional for CLI output
+        ], "src/vclient/services/*.py" = [
             "PLR0913", # Too many arguments
+        ], "src/vclient/validate_constants.py" = [
+            "T201", # print() is intentional for report output
         ], "tests/**/*.py" = [
             "A002",
             "A003",

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/client.py

@@ -1,5 +1,6 @@
 """Main API client for Valentina."""
 
+import os
 from types import TracebackType
 from typing import TYPE_CHECKING, Self
 
@@ -11,6 +12,9 @@ from vclient.constants import (
     DEFAULT_MAX_RETRIES,
     DEFAULT_RETRY_DELAY,
     DEFAULT_TIMEOUT,
+    ENV_API_KEY,
+    ENV_BASE_URL,
+    ENV_DEFAULT_COMPANY_ID,
 )
 
 if TYPE_CHECKING:
@@ -64,8 +68,8 @@ class VClient:
 
     def __init__(  # noqa: PLR0913
         self,
-        base_url: str,
-        api_key: str,
+        base_url: str | None = None,
+        api_key: str | None = None,
         *,
         timeout: float = DEFAULT_TIMEOUT,
         max_retries: int = DEFAULT_MAX_RETRIES,
@@ -78,9 +82,18 @@ class VClient:
     ) -> None:
         """Initialize the API client.
 
+        Values for ``base_url``, ``api_key``, and ``default_company_id`` can be
+        provided as constructor arguments or via environment variables. Explicit
+        arguments always take precedence over environment variables.
+
+        Environment variables:
+            VALENTINA_CLIENT_BASE_URL: Base URL for the API.
+            VALENTINA_CLIENT_API_KEY: API key for authentication.
+            VALENTINA_CLIENT_DEFAULT_COMPANY_ID: Default company ID.
+
         Args:
-            base_url: Base URL for the API.
-            api_key: API key for authentication.
+            base_url: Base URL for the API. Falls back to VALENTINA_CLIENT_BASE_URL.
+            api_key: API key for authentication. Falls back to VALENTINA_CLIENT_API_KEY.
             timeout: Request timeout in seconds.
             max_retries: Maximum number of retry attempts for failed requests.
             retry_delay: Base delay between retries in seconds.
@@ -88,21 +101,38 @@ class VClient:
             auto_idempotency_keys: Automatically generate idempotency keys for
                 POST/PUT/PATCH requests.
             default_company_id: Default company ID to use when not explicitly provided
-                to service factory methods.
+                to service factory methods. Falls back to
+                VALENTINA_CLIENT_DEFAULT_COMPANY_ID.
             headers: Additional headers to include with all requests.
             set_as_default: If True, register this client as the default for factory
                 functions. Set to False when creating multiple clients or when using
                 the context manager pattern exclusively.
+
+        Raises:
+            ValueError: If base_url or api_key is not provided and the corresponding
+                environment variable is not set.
         """
+        resolved_base_url = base_url or os.environ.get(ENV_BASE_URL)
+        if resolved_base_url is None:
+            msg = "base_url is required (set it directly or via the VALENTINA_CLIENT_BASE_URL environment variable)"
+            raise ValueError(msg)
+
+        resolved_api_key = api_key or os.environ.get(ENV_API_KEY)
+        if resolved_api_key is None:
+            msg = "api_key is required (set it directly or via the VALENTINA_CLIENT_API_KEY environment variable)"
+            raise ValueError(msg)
+
+        resolved_company_id = default_company_id or os.environ.get(ENV_DEFAULT_COMPANY_ID)
+
         self._config = _APIConfig(
-            base_url=base_url,
-            api_key=api_key,
+            base_url=resolved_base_url,
+            api_key=resolved_api_key,
             timeout=timeout,
             max_retries=max_retries,
             retry_delay=retry_delay,
             auto_retry_rate_limit=auto_retry_rate_limit,
             auto_idempotency_keys=auto_idempotency_keys,
-            default_company_id=default_company_id,
+            default_company_id=resolved_company_id,
             headers=headers or {},
         )
 

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/constants.py

@@ -5,6 +5,10 @@ from typing import Literal
 # Authentication
 API_KEY_HEADER = "X-API-KEY"
 
+# Environment variable names
+ENV_BASE_URL = "VALENTINA_CLIENT_BASE_URL"
+ENV_API_KEY = "VALENTINA_CLIENT_API_KEY"
+ENV_DEFAULT_COMPANY_ID = "VALENTINA_CLIENT_DEFAULT_COMPANY_ID"
 
 # Request defaults
 DEFAULT_TIMEOUT = 30.0

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/endpoints.py

@@ -124,12 +124,12 @@ class Endpoints:
     BLUEPRINT_TRAIT_DETAIL = f"{BLUEPRINT_TRAITS}/{{trait_id}}"
     CONCEPTS = f"{BLUEPRINT_BASE}/concepts"
     CONCEPT_DETAIL = f"{CONCEPTS}/{{concept_id}}"
-    VAMPIRE_CLANS = f"{BLUEPRINT_BASE}/vampireclans"
+    VAMPIRE_CLANS = f"{BLUEPRINT_BASE}/vampire-clans"
     VAMPIRE_CLAN_DETAIL = f"{VAMPIRE_CLANS}/{{vampire_clan_id}}"
     WEREWOLF_TRIBES = f"{BLUEPRINT_BASE}/werewolf-tribes"
     WEREWOLF_TRIBE_DETAIL = f"{WEREWOLF_TRIBES}/{{werewolf_tribe_id}}"
     WEREWOLF_AUSPICES = f"{BLUEPRINT_BASE}/werewolf-auspices"
-    WEREWOLF_AUSPIE_DETAIL = f"{WEREWOLF_AUSPICES}/{{werewolf_auspice_id}}"
+    WEREWOLF_AUSPICE_DETAIL = f"{WEREWOLF_AUSPICES}/{{werewolf_auspice_id}}"
     WEREWOLF_GIFTS = f"{BLUEPRINT_BASE}/werewolf-gifts"
     WEREWOLF_GIFT_DETAIL = f"{WEREWOLF_GIFTS}/{{werewolf_gift_id}}"
     WEREWOLF_RITES = f"{BLUEPRINT_BASE}/werewolf-rites"
@@ -140,7 +140,7 @@ class Endpoints:
     HUNTER_EDGE_PERK_DETAIL = f"{HUNTER_EDGE_PERKS}/{{hunter_edge_perk_id}}"
 
     # Dictionary endpoints
-    DICTIONARY_TERMS = f"{COMPANY}/dictionary"
+    DICTIONARY_TERMS = f"{COMPANY}/dictionaries"
     DICTIONARY_TERM = f"{DICTIONARY_TERMS}/{{term_id}}"
 
     # Dice Rolls

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/models/users.py

@@ -151,8 +151,8 @@ class _ExperienceAddRemove(BaseModel):
     """
 
     amount: int
-    user_id: str
     campaign_id: str
+    requesting_user_id: str
 
 
 __all__ = [

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/services/character_blueprint.py

@@ -436,7 +436,7 @@ class CharacterBlueprintService(BaseService):
         """Get a werewolf auspice by ID."""
         response = await self._get(
             self._format_endpoint(
-                Endpoints.WEREWOLF_AUSPIE_DETAIL, werewolf_auspice_id=werewolf_auspice_id
+                Endpoints.WEREWOLF_AUSPICE_DETAIL, werewolf_auspice_id=werewolf_auspice_id
             ),
         )
         return WerewolfAuspice.model_validate(response.json())

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/services/character_traits.py

@@ -251,7 +251,7 @@ class CharacterTraitsService(BaseService):
             target_value=new_value,
             currency=currency,
         )
-        response = await self._post(
+        response = await self._put(
             self._format_endpoint(
                 Endpoints.CHARACTER_TRAIT_VALUE, character_trait_id=character_trait_id
             ),

{valentina_python_client-1.1.1 → valentina_python_client-1.2.0}/src/vclient/services/users.py

@@ -413,6 +413,7 @@ class UsersService(BaseService):
         user_id: str,
         campaign_id: str,
         amount: int,
+        requesting_user_id: str,
     ) -> CampaignExperience:
         """Award experience points to a user for a specific campaign.
 
@@ -423,6 +424,7 @@ class UsersService(BaseService):
             user_id: The ID of the user to award XP to.
             campaign_id: The ID of the campaign to add XP for.
             amount: The amount of XP to add.
+            requesting_user_id: ID of the user making the request (for permissions).
 
         Returns:
             Updated CampaignExperience object.
@@ -435,8 +437,8 @@ class UsersService(BaseService):
         body = self._validate_request(
             _ExperienceAddRemove,
             amount=amount,
-            user_id=user_id,
             campaign_id=campaign_id,
+            requesting_user_id=requesting_user_id,
         )
         response = await self._post(
             self._format_endpoint(Endpoints.USER_EXPERIENCE_XP_ADD, user_id=user_id),
@@ -449,6 +451,7 @@ class UsersService(BaseService):
         user_id: str,
         campaign_id: str,
         amount: int,
+        requesting_user_id: str,
     ) -> CampaignExperience:
         """Deduct experience points from a user's current XP pool.
 
@@ -458,6 +461,7 @@ class UsersService(BaseService):
             user_id: The ID of the user to remove XP from.
             campaign_id: The ID of the campaign to remove XP for.
             amount: The amount of XP to remove.
+            requesting_user_id: ID of the user making the request (for permissions).
 
         Returns:
             Updated CampaignExperience object.
@@ -471,8 +475,8 @@ class UsersService(BaseService):
         body = self._validate_request(
             _ExperienceAddRemove,
             amount=amount,
-            user_id=user_id,
             campaign_id=campaign_id,
+            requesting_user_id=requesting_user_id,
         )
         response = await self._post(
             self._format_endpoint(Endpoints.USER_EXPERIENCE_XP_REMOVE, user_id=user_id),
@@ -485,6 +489,7 @@ class UsersService(BaseService):
         user_id: str,
         campaign_id: str,
         amount: int,
+        requesting_user_id: str,
     ) -> CampaignExperience:
         """Award cool points to a user for a specific campaign.
 
@@ -495,6 +500,7 @@ class UsersService(BaseService):
             user_id: The ID of the user to award cool points to.
             campaign_id: The ID of the campaign to add cool points for.
             amount: The amount of cool points to add.
+            requesting_user_id: ID of the user making the request (for permissions).
 
         Returns:
             Updated CampaignExperience object.
@@ -507,8 +513,8 @@ class UsersService(BaseService):
         body = self._validate_request(
             _ExperienceAddRemove,
             amount=amount,
-            user_id=user_id,
             campaign_id=campaign_id,
+            requesting_user_id=requesting_user_id,
         )
         response = await self._post(
             self._format_endpoint(Endpoints.USER_EXPERIENCE_CP_ADD, user_id=user_id),

valentina_python_client-1.2.0/src/vclient/validate_constants.py

@@ -0,0 +1,237 @@
+"""Validate client constants against the API options endpoint.
+
+Compare the Literal type constants defined in constants.py against the
+values returned by the API's /options endpoint to detect drift between
+client and server.
+"""
+
+from __future__ import annotations
+
+import typing
+from dataclasses import dataclass, field
+
+from vclient import constants
+
+
+@dataclass(frozen=True)
+class ConstantMapping:
+    """Map a local constant name to its location in the API options response.
+
+    Args:
+        api_category: Top-level key in the options response (e.g., "characters").
+        api_option: Option name within that category (e.g., "CharacterClass").
+    """
+
+    api_category: str
+    api_option: str
+
+
+@dataclass
+class ConstantMismatch:
+    """Record of a single constant that differs between client and API.
+
+    Args:
+        constant_name: The local constant name in constants.py.
+        api_category: The API category this constant maps to.
+        api_option: The API option name this constant maps to.
+        missing_from_client: Values present in the API but not in the local Literal.
+        extra_in_client: Values present in the local Literal but not in the API.
+    """
+
+    constant_name: str
+    api_category: str
+    api_option: str
+    missing_from_client: set[str | int] = field(default_factory=set)
+    extra_in_client: set[str | int] = field(default_factory=set)
+
+
+@dataclass
+class ValidationResult:
+    """Result of validating client constants against the API.
+
+    Args:
+        is_valid: True if all mapped constants match and no unmapped API options exist.
+        mismatches: Constants with value differences between client and API.
+        unmapped_api_options: API option keys that have no corresponding local constant.
+    """
+
+    is_valid: bool
+    mismatches: list[ConstantMismatch] = field(default_factory=list)
+    unmapped_api_options: dict[str, list[str]] = field(default_factory=dict)
+
+
+CONSTANT_MAP: dict[str, ConstantMapping] = {
+    "AbilityFocus": ConstantMapping("characters", "AbilityFocus"),
+    "AutoGenExperienceLevel": ConstantMapping("characters", "AutoGenExperienceLevel"),
+    "BlueprintTraitOrderBy": ConstantMapping("characters", "BlueprintTraitOrderBy"),
+    "CharacterClass": ConstantMapping("characters", "CharacterClass"),
+    "CharacterInventoryType": ConstantMapping("characters", "InventoryItemType"),
+    "CharacterStatus": ConstantMapping("characters", "CharacterStatus"),
+    "CharacterType": ConstantMapping("characters", "CharacterType"),
+    "DiceSize": ConstantMapping("gameplay", "DiceSize"),
+    "FreeTraitChangesPermission": ConstantMapping("companies", "PermissionsFreeTraitChanges"),
+    "GameVersion": ConstantMapping("characters", "GameVersion"),
+    "GrantXPPermission": ConstantMapping("companies", "PermissionsGrantXP"),
+    "HunterCreed": ConstantMapping("characters", "HunterCreed"),
+    "HunterEdgeType": ConstantMapping("characters", "HunterEdgeType"),
+    "ManageCampaignPermission": ConstantMapping("companies", "PermissionManageCampaign"),
+    "PermissionLevel": ConstantMapping("companies", "CompanyPermission"),
+    "RollResultType": ConstantMapping("gameplay", "RollResultType"),
+    "S3AssetParentType": ConstantMapping("assets", "AssetParentType"),
+    "S3AssetType": ConstantMapping("assets", "AssetType"),
+    "SpecialtyType": ConstantMapping("characters", "SpecialtyType"),
+    "TraitModifyCurrency": ConstantMapping("characters", "TraitModifyCurrency"),
+    "UserRole": ConstantMapping("users", "UserRole"),
+    "WerewolfRenown": ConstantMapping("characters", "WerewolfRenown"),
+}
+
+
+def validate(api_options: dict[str, dict[str, list | dict]]) -> ValidationResult:
+    """Compare local Literal constants against values from the API options endpoint.
+
+    Args:
+        api_options: The raw dictionary returned by OptionsService.get_options().
+
+    Returns:
+        ValidationResult with is_valid=True if all constants match, otherwise
+        populated with mismatches and unmapped API options.
+    """
+    mismatches: list[ConstantMismatch] = []
+    mapped_api_options: set[tuple[str, str]] = set()
+
+    for constant_name, mapping in CONSTANT_MAP.items():
+        mapped_api_options.add((mapping.api_category, mapping.api_option))
+
+        local_values = set(typing.get_args(getattr(constants, constant_name)))
+
+        category_data = api_options.get(mapping.api_category, {})
+        api_values_raw = category_data.get(mapping.api_option)
+        if api_values_raw is None:
+            mismatches.append(
+                ConstantMismatch(
+                    constant_name=constant_name,
+                    api_category=mapping.api_category,
+                    api_option=mapping.api_option,
+                    missing_from_client=set(),
+                    extra_in_client=local_values,
+                )
+            )
+            continue
+
+        api_values = set(api_values_raw)
+        missing_from_client = api_values - local_values
+        extra_in_client = local_values - api_values
+
+        if missing_from_client or extra_in_client:
+            mismatches.append(
+                ConstantMismatch(
+                    constant_name=constant_name,
+                    api_category=mapping.api_category,
+                    api_option=mapping.api_option,
+                    missing_from_client=missing_from_client,
+                    extra_in_client=extra_in_client,
+                )
+            )
+
+    unmapped_api_options: dict[str, list[str]] = {}
+    for category, options in api_options.items():
+        if not isinstance(options, dict):
+            continue
+        for option_name, option_values in options.items():
+            if option_name.startswith("_"):
+                continue
+            if not isinstance(option_values, list):
+                continue
+            if (category, option_name) not in mapped_api_options:
+                unmapped_api_options.setdefault(category, []).append(option_name)
+
+    is_valid = len(mismatches) == 0 and len(unmapped_api_options) == 0
+
+    return ValidationResult(
+        is_valid=is_valid,
+        mismatches=mismatches,
+        unmapped_api_options=unmapped_api_options,
+    )
+
+
+def _print_status_lines(mismatched_names: set[str]) -> None:
+    """Print OK/FAIL status line for each constant in the mapping table."""
+    for constant_name in sorted(CONSTANT_MAP):
+        status = "FAIL" if constant_name in mismatched_names else "OK  "
+        print(f"  {status}  {constant_name}")
+
+
+def _print_mismatches(mismatches: list[ConstantMismatch]) -> None:
+    """Print detailed mismatch information for each failing constant."""
+    print()
+    print("-" * 60)
+    print("Mismatches:")
+    print("-" * 60)
+    for mismatch in mismatches:
+        print(f"\n  {mismatch.constant_name}")
+        print(f"    API: {mismatch.api_category}.{mismatch.api_option}")
+        if mismatch.missing_from_client:
+            print(f"    Missing from client: {sorted(mismatch.missing_from_client)}")
+        if mismatch.extra_in_client:
+            print(f"    Extra in client:     {sorted(mismatch.extra_in_client)}")
+
+
+def _print_unmapped(unmapped_api_options: dict[str, list[str]]) -> None:
+    """Print API options that have no corresponding local constant."""
+    print()
+    print("-" * 60)
+    print("Unmapped API options (no local constant):")
+    print("-" * 60)
+    for category, options in sorted(unmapped_api_options.items()):
+        for option in sorted(options):
+            print(f"  {category}.{option}")
+
+
+def _build_summary(
+    matched_count: int,
+    total: int,
+    mismatch_count: int,
+    unmapped_api_options: dict[str, list[str]],
+) -> str:
+    """Build the final summary line for the report."""
+    if mismatch_count == 0 and not unmapped_api_options:
+        return f"  {matched_count}/{total} constants in sync"
+
+    summary_parts: list[str] = []
+    if mismatch_count:
+        summary_parts.append(f"{mismatch_count} mismatch(es)")
+    if unmapped_api_options:
+        unmapped_count = sum(len(v) for v in unmapped_api_options.values())
+        summary_parts.append(f"{unmapped_count} unmapped API option(s)")
+    return f"  {matched_count}/{total} constants in sync, {', '.join(summary_parts)}"
+
+
+def print_report(result: ValidationResult) -> None:
+    """Print a human-readable validation report to stdout.
+
+    Args:
+        result: The ValidationResult from validate().
+    """
+    total = len(CONSTANT_MAP)
+    mismatch_count = len(result.mismatches)
+    matched_count = total - mismatch_count
+    mismatched_names = {m.constant_name for m in result.mismatches}
+
+    print()
+    print("=" * 60)
+    print("Constants Validation Report")
+    print("=" * 60)
+
+    _print_status_lines(mismatched_names)
+
+    if result.mismatches:
+        _print_mismatches(result.mismatches)
+
+    if result.unmapped_api_options:
+        _print_unmapped(result.unmapped_api_options)
+
+    print()
+    print("=" * 60)
+    print(_build_summary(matched_count, total, mismatch_count, result.unmapped_api_options))
+    print("=" * 60)
+    print()