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
Metadata
1 maintainer
Release files for valentina-python-client 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| valentina_python_client-3.3.0.tar.gz | 127.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| valentina_python_client-3.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 311.0 kB
Release files / valentina_python_client-3.3.0.tar.gz
| Download URL | valentina_python_client-3.3.0.tar.gz |
|---|---|
| Size | 127.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7ebb83d4d4408b7f51536b7b857c3a4d6b0505a796f16eae0b356fffcd31abcb
|
|
BLAKE2b-256 checksum How to use checksums |
4c03c07229ff218ea84e582485aad269086463173700a433d99c5ca045552478
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / valentina_python_client-3.3.0-py3-none-any.whl
| Download URL | valentina_python_client-3.3.0-py3-none-any.whl |
|---|---|
| Size | 183.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
228b1080f05dd92e9cba28ab088140074ff9339927b7f82b65c2b1398d36e91f
|
|
BLAKE2b-256 checksum How to use checksums |
eacb9d7c01ad1d13e753ee5356063672537f606cb423e3f8099d8237dbe7b780
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
