This release is a pre-release and may not be stable for production use.
apiconfig
Flexible, extensible configuration and authentication for Python API clients.
Table of Contents
- Project Overview
- Quickstart
- Installation
- Key Features
- Usage
- Practical Example: Real API Client Setup
- Logging
- Error Handling
- Testing and Coverage
- CI/CD
- Further Documentation
- Navigation
- License
Navigation
Project Overview
apiconfig is a standalone Python library for managing API client configuration and authentication. It provides a robust, extensible foundation for building API clients, handling configuration (base URLs, timeouts, retries, headers) and supporting multiple authentication strategies (API key, Basic, Bearer, custom).
apiconfig is designed for:
- Developers building reusable, testable API clients.
- Projects needing flexible configuration sources (env, file, memory).
- Secure, pluggable authentication for HTTP APIs.
Quickstart
pip install apiconfig
from apiconfig import ClientConfig, ApiKeyAuth
auth = ApiKeyAuth(api_key="my-secret-key", header_name="X-API-Key")
config = ClientConfig(
hostname="api.example.com",
version="v1",
auth_strategy=auth,
timeout=10.0,
retries=3,
)
print(config.base_url) # https://api.example.com/v1
Installation
Install from PyPI:
pip install apiconfig
Or with Poetry:
poetry add apiconfig
Key Features
- Unified API Client Configuration: Manage base URLs, versions, headers, timeouts, retries, and more with a single, validated config object.
- Authentication Strategies: Built-in support for API Key, Basic, Bearer, and custom authentication via the Strategy Pattern.
- Config Providers: Load configuration from environment variables, files, or in-memory sources.
- Extensible: Easily add new authentication methods or config providers.
- Robust Error Handling: Clear, structured exception hierarchy for all config and auth errors.
- Type Safety: Strong type hints and type-checked public API.
- Logging Integration: Standard logging hooks for debugging and auditability.
- High Test Coverage: Around 94% coverage with unit and integration tests.
Usage
Basic Configuration
from apiconfig import ClientConfig
config = ClientConfig(
hostname="api.example.com",
version="v1",
headers={"X-My-Header": "value"},
timeout=10.0,
retries=3,
)
print(config.base_url) # https://api.example.com/v1
Authentication Strategies
API Key in Header
from apiconfig import ClientConfig, ApiKeyAuth
auth = ApiKeyAuth(api_key="my-secret-key", header_name="X-API-Key")
config = ClientConfig(
hostname="api.example.com",
version="v1",
auth_strategy=auth,
)
API Key in Query Parameter
from apiconfig import ApiKeyAuth
auth = ApiKeyAuth(api_key="my-secret-key", param_name="api_key")
Basic and Bearer Auth
from apiconfig import BasicAuth, BearerAuth
basic = BasicAuth(username="user", password="pass")
bearer = BearerAuth(access_token="my-jwt-token")
Custom Authentication
from apiconfig import CustomAuth
custom = CustomAuth(auth_callable=lambda: {"Authorization": "Custom xyz"})
Using Configuration Providers
Environment Variables
from apiconfig import EnvProvider
env = EnvProvider(prefix="MYAPI_")
config_dict = env.load()
# Example: MYAPI_HOSTNAME=api.example.com, MYAPI_TIMEOUT=5
File and Memory Providers
from apiconfig import FileProvider, MemoryProvider
file_provider = FileProvider(file_path="config.json")
file_config = file_provider.load()
# MemoryProvider accepts configuration via the ``config_data`` parameter and
# exposes ``get_config`` instead of ``load``
memory_provider = MemoryProvider(config_data={"hostname": "api.example.com"})
memory_config = memory_provider.get_config()
Merging Configurations
from apiconfig import ClientConfig
base = ClientConfig(hostname="api.example.com", timeout=10)
override = ClientConfig(timeout=5, retries=2)
merged = base.merge(override)
Practical Example: Real API Client Setup
Below is a real-world example based on the integration tests. This pattern demonstrates how to use apiconfig to load configuration and secrets from environment variables, set up authentication, and make a request with an HTTP client (e.g., httpx):
import os
import httpx
from apiconfig import EnvProvider, ClientConfig, BearerAuth
# Load config and secrets from environment variables
env = EnvProvider()
config_dict = env.load()
# Get token and base URL from environment or use defaults
access_token = config_dict.get("FIKEN_ACCESS_TOKEN") or os.environ.get("FIKEN_ACCESS_TOKEN")
base_url = config_dict.get("FIKEN_BASE_URL") or os.environ.get("FIKEN_BASE_URL") or "https://api.fiken.no/api/v2"
# Set up authentication strategy if token is available
auth_strategy = BearerAuth(access_token) if access_token else None
# Create the API client configuration
client_config = ClientConfig(
hostname=base_url,
auth_strategy=auth_strategy,
)
# Prepare request headers using the auth strategy
headers = {}
if client_config.auth_strategy is not None:
headers.update(client_config.auth_strategy.prepare_request_headers())
# Make a real HTTP request using httpx
with httpx.Client(timeout=10.0) as client:
response = client.get(f"{client_config.base_url}/companies", headers=headers)
print(response.status_code, response.json())
This approach can be adapted for any API and authentication method supported by apiconfig. See the integration tests for more real-world examples.
Logging
apiconfig uses standard Python logging. To enable debug output:
import logging
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("apiconfig").setLevel(logging.INFO)
Error Handling
All errors are structured and documented. Common exceptions include:
APIConfigErrorConfigurationErrorAuthenticationErrorInvalidConfigErrorMissingConfigErrorAuthStrategyError
Testing and Coverage
apiconfig is fully tested with pytest and coverage.py. To run tests and check coverage:
pytest --cov=apiconfig --cov-report=html
Static Type Checking
apiconfig uses Pyright for optional static type checking. Before running Pyright, ensure development dependencies are installed and the virtual environment is active:
poetry install --with dev
poetry shell
pyright
This guarantees libraries like httpx, pytest, and their stubs are available.
CI/CD
Continuous integration and deployment are managed with GitHub Actions. All pushes and pull requests are tested, and releases are published to PyPI after passing tests.
Further Documentation
- Documentation (latest)
- CONTRIBUTING.md — Contribution guidelines
- Bug Tracker
- PyPI Project Page
See Also
License
LGPL-3.0-or-later. See LICENSE for details.
Status
Stability: Stable - the project is actively used in production environments. API Version: Follows Semantic Versioning starting at version 0.x. Deprecations: None
Maintenance Notes
The library is currently stable and actively maintained. Issues and pull requests are triaged on a best-effort basis. Minor feature requests and fixes are welcome.
Changelog
See CHANGELOG.md for a complete history of changes.
Future Considerations
Planned improvements include enhanced documentation, additional auth strategies, expanded test coverage, and formatter enhancements for more consistent styling.
1 maintainer
Metadata
1 maintainer
Release files for apiconfig 0.3.2.dev529
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| apiconfig-0.3.2.dev529.tar.gz | 93.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| apiconfig-0.3.2.dev529-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 219.9 kB
Release files / apiconfig-0.3.2.dev529.tar.gz
| Download URL | apiconfig-0.3.2.dev529.tar.gz |
|---|---|
| Size | 93.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3019a0f6b0964c1a9825c1f107d8e861f75cc7842386b960c92aefa0a2857ea8
|
|
BLAKE2b-256 checksum How to use checksums |
39f4b7e10d72d14ff621e3f0cd3360e9cb33785c283ad008bcb7734792128911
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2025.
Transparency logRelease files / apiconfig-0.3.2.dev529-py3-none-any.whl
| Download URL | apiconfig-0.3.2.dev529-py3-none-any.whl |
|---|---|
| Size | 126.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
421dc562fd16627d7f3f940104085d8449e010de33f1fd5e495254fa594784e1
|
|
BLAKE2b-256 checksum How to use checksums |
ba5eb88c0f146e90e73246c566c59880c2e5c56b228df0059e322e1751339093
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2025.
Transparency logSecurity for apiconfig 0.3.2.dev529
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for apiconfig-0.3.2.dev529.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 13, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
