Add base API clients, serde utilities, and auth improvements by MichelEdkrantz · Pull Request #48 · annotell/kognic-auth-python

Michel Edkrantz (MichelEdkrantz) · 2026-02-10T10:57:18Z

Summary

Add BaseApiClient (sync, requests-based) and BaseAsyncApiClient (async, httpx-based) for building authenticated HTTP clients
Add serialization/deserialization utilities (serialize_body, deserialize) with Pydantic v2 support
Add sunset header handling for deprecated API endpoints
Add json_serializer parameter to base clients for overriding request body serialization
Add path validation (reject leading /) to both sync and async base clients
Add async context manager support (async with) to BaseAsyncApiClient
Forward **kwargs to underlying httpx client in BaseAsyncApiClient
Rename config file keys from contexts/default_context to environments/default_environment
Rename CLI --config flag to --env-config-file-path
Rename DEFAULT_CONFIG_PATH to DEFAULT_ENV_CONFIG_FILE_PATH
Rename config.py to env_config.py
Fix sync/async asymmetries: consistent _update_token parameter order, docstring style (Args:), path validation
Fix sunset date parsing to use UTC-aware datetimes and support dates without microseconds
Remove unused PathLike import, redundant Accept-Encoding: gzip header, duplicate imports
Remove legacy ANNOTELL_* env var fallbacks from credentials parser
Use uv for CI instead of pip

Test plan

All 165 unit tests pass
Serialization tests (serialize_body, Pydantic v2, nested objects)
Deserialization tests (envelope handling, type coercion, Pydantic v2)
Sunset header tests (requests + httpx, UTC, with/without microseconds)
Credentials parser tests (parse, resolve, env var fallback)
Base client tests (lazy init, client name auto-detection, from_env)
CLI tests (get-access-token, call, output formats, env resolution)
Config tests (load, resolve environment, domain matching)
Pre-commit hooks pass (ruff, ruff-format)

🤖 Generated with Claude Code

Move Base API Clients from kognic-base-api-client-python into kognic-auth-python: - BaseApiClient (sync, requests-based) with lazy session initialization - BaseAsyncApiClient (async, httpx-based) extending HttpxAuthAsyncClient Features: - OAuth2 authentication with automatic token refresh - Automatic JSON serialization for jsonable objects - Retry logic for transient errors (502, 503, 504) - Sunset header handling (logs warnings for deprecated endpoints) - Enhanced error messages with response body details Also adds: - _protocols.py: Protocol definitions for duck typing - _serde.py: Serialization/deserialization utilities - _sunset.py: Sunset header handling - _user_agent.py: User-Agent string construction Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add recursive serialization for nested objects in containers - Rename serialize_to_json to to_json for consistency - to_json takes precedence over to_dict - Split test_serde.py into test_serialization.py and test_deserialization.py - Rename _serde.py to serde.py (public module) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add model_dump/model_validate support for Pydantic v2 models - Add robust type checking using MutableSequence/MutableMapping - Add pydantic>=2 to dev dependencies - Fix Python 3.9 compatibility (use Optional[str] instead of str | None) - Add test_serde_pydantic.py with 11 Pydantic tests - Add test_type_helpers.py with 12 type helper tests Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Document serialize_body() and deserialize() with examples for: - Pydantic models - Custom classes with to_dict()/from_dict() - Nested objects in containers - Envelope extraction Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Use astral-sh/setup-uv@v5 action with caching - Use uv python install for Python version - Use uv sync --all-extras for dependencies - Use uv run pytest for testing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Fix sunset date parsing to use UTC-aware datetimes - Support sunset dates without microseconds - Add comprehensive credentials_parser tests - Forward **kwargs to httpx client in BaseAsyncApiClient - Document json_serializer in create_session docstring - Fix ruff target-version to match requires-python (py39) - Remove legacy ANNOTELL env var fallbacks Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ts, param order - Remove unused `PathLike` import from httpx/base_client.py - Align `_update_token` parameter order (access_token, refresh_token) in async client - Add path validation (reject leading `/`) to async base client matching sync - Normalize docstrings from `:param` to `Args:` style across auth sessions - Remove redundant explicit `Accept-Encoding: gzip` header from sync client - Run ruff fix + format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ntext) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…/default_environment Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds os.PathLike to type hints for auth, env_config_path, and path parameters across credentials_parser, env_config, and both base clients. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds a WARNING-level handler on kognic.auth logger so sunset deprecation warnings and rate limit errors are visible in CLI output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Michel Edkrantz (MichelEdkrantz) changed the title ~~Add Base API Clients for building authenticated HTTP clients~~ Add base API clients, serde utilities, and auth improvements Feb 11, 2026

Michel Edkrantz (MichelEdkrantz) and others added 9 commits February 12, 2026 13:09

Add serialization examples to README

35021e3

Document serialize_body() and deserialize() with examples for: - Pydantic models - Custom classes with to_dict()/from_dict() - Nested objects in containers - Envelope extraction Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Use uv for CI instead of pip

2094bb1

- Use astral-sh/setup-uv@v5 action with caching - Use uv python install for Python version - Use uv sync --all-extras for dependencies - Use uv run pytest for testing Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix publish flow to publish release candidate

e9686e5

Add overridable json_serializer parameter to base clients

97c12d5

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

interface polishing

6df5be7

Michel Edkrantz (MichelEdkrantz) force-pushed the add-base-api-clients branch from 2a088da to 0fb659a Compare February 12, 2026 13:04

Michel Edkrantz (MichelEdkrantz) and others added 12 commits February 12, 2026 16:32

Replace os.unlink with Path.unlink in credential parser tests

78c6521

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename CLI --config to --env-config-file-path

e28bde6

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename DEFAULT_CONFIG_PATH to DEFAULT_ENV_CONFIG_FILE_PATH

eea9fa2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix test_valid_config to use correct config keys (contexts/default_co…

4716fbd

…ntext) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename config file keys from contexts/default_context to environments…

99a53cf

…/default_environment Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Accept PathLike in all path-accepting interfaces

9b36b63

Adds os.PathLike to type hints for auth, env_config_path, and path parameters across credentials_parser, env_config, and both base clients. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add .json suffix check for PathLike auth credentials

a37c170

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Include path in credentials file validation error message

779e791

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Configure CLI logging to write warnings to stderr

da8fd6b

Adds a WARNING-level handler on kognic.auth logger so sunset deprecation warnings and rate limit errors are visible in CLI output. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Rename default config file from config.json to environments.json

6978ba2

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Use Self return type on base clients and validate CLI input before auth

4320f18

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Michel Edkrantz (MichelEdkrantz) merged commit 83851dc into master Feb 13, 2026
10 checks passed

Michel Edkrantz (MichelEdkrantz) deleted the add-base-api-clients branch February 13, 2026 09:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add base API clients, serde utilities, and auth improvements#48

Add base API clients, serde utilities, and auth improvements#48
Michel Edkrantz (MichelEdkrantz) merged 21 commits intomasterfrom
add-base-api-clients

Michel Edkrantz (MichelEdkrantz) commented Feb 10, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Michel Edkrantz (MichelEdkrantz) commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Michel Edkrantz (MichelEdkrantz) commented Feb 10, 2026 •

edited

Loading