Valentina Python Client
Async and sync Python client library for accessing the Valentina Noir API.
Features
- Async and sync clients - Both
VClient(async) andSyncVClient(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 withlist_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.
Documentation
The full documentation is available at https://natelandau.github.io/valentina-python-client/.
Claude Code Skill
This repo includes a Claude Code skill that gives Claude deep knowledge of vclient's services, models, constants, and testing utilities. Install it so Claude can help you build applications against the Valentina API.
Install
claude install-skill /path/to/valentina-python-client/vclient-guide-skill
Once installed, Claude will automatically activate the skill when you're working with vclient imports, Valentina API endpoints, or FakeVClient testing.
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.
# 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):
- CLI arguments (
--api-url,--api-key,--company-id) - System environment variables (
VALENTINA_CLIENT_BASE_URL,VALENTINA_CLIENT_API_KEY,VALENTINA_CLIENT_DEFAULT_COMPANY_ID) - A
.env.secretfile in the project root
Exit codes: 0 = all constants match, 1 = mismatches found, 2 = missing configuration.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file valentina_python_client-3.1.1.tar.gz.
File metadata
- Download URL: valentina_python_client-3.1.1.tar.gz
- Upload date:
- Size: 124.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f1b23f477acb7c1dd6e27be82e216a36ae5b8bb90f892f4004a04c23b24cbb98
|
|
| MD5 |
44dbfe6d93154423af7d4725f07f24ed
|
|
| BLAKE2b-256 |
1c9f02b0a0a75c5e1c6e469b3b766a135cc6f586f2553d12581b398a5c1a03bf
|
File details
Details for the file valentina_python_client-3.1.1-py3-none-any.whl.
File metadata
- Download URL: valentina_python_client-3.1.1-py3-none-any.whl
- Upload date:
- Size: 182.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8902afc8fa48a47b613fe4d035cab06f6580aabc9739277cf2d2e028c4136651
|
|
| MD5 |
f3dae445b643007f5c13fef022ac1462
|
|
| BLAKE2b-256 |
53342df6e9add7e23e931c609a4a84eb4cbce410cf45b1f7062b3f85f9a741dc
|
