kiarina-lib-cloudflare 2.3.0

Cloudflare client library for kiarina namespace

kiarina-lib-cloudflare

English | 日本語

A Python library for Cloudflare authentication with configuration management using pydantic-settings-manager.

Features

• Configuration Management: Use pydantic-settings-manager for flexible configuration
• Type Safety: Full type hints and Pydantic validation
• Secure Credential Handling: API tokens are protected using SecretStr
• Multiple Configurations: Support for multiple named configurations (e.g., different accounts)
• Environment Variable Support: Configure via environment variables with KIARINA_LIB_CLOUDFLARE_ prefix

Installation

pip install kiarina-lib-cloudflare

Quick Start

Basic Usage

from kiarina.lib.cloudflare import CloudflareSettings, settings_manager

# Configure Cloudflare authentication
settings_manager.user_config = {
    "default": {
        "account_id": "your-account-id",
        "api_token": "your-api-token"
    }
}

# Get settings
settings = settings_manager.settings
print(f"Account ID: {settings.account_id}")
print(f"API Token: {settings.api_token.get_secret_value()}")  # Access secret value

Environment Variable Configuration

Configure authentication using environment variables:

export KIARINA_LIB_CLOUDFLARE_ACCOUNT_ID="your-account-id"
export KIARINA_LIB_CLOUDFLARE_API_TOKEN="your-api-token"

from kiarina.lib.cloudflare import settings_manager

# Settings are automatically loaded from environment variables
settings = settings_manager.settings
print(f"Account ID: {settings.account_id}")

Multiple Configurations

Manage multiple Cloudflare accounts:

from kiarina.lib.cloudflare import settings_manager

# Configure multiple accounts
settings_manager.user_config = {
    "production": {
        "account_id": "prod-account-id",
        "api_token": "prod-api-token"
    },
    "staging": {
        "account_id": "staging-account-id",
        "api_token": "staging-api-token"
    }
}

# Switch between configurations
settings_manager.active_key = "production"
prod_settings = settings_manager.settings
print(f"Production Account: {prod_settings.account_id}")

settings_manager.active_key = "staging"
staging_settings = settings_manager.settings
print(f"Staging Account: {staging_settings.account_id}")

Configuration

This library uses pydantic-settings-manager for flexible configuration management.

CloudflareSettings

The CloudflareSettings class provides the following configuration fields:

Field	Type	Required	Description
account_id	str	Yes	Cloudflare account ID
api_token	SecretStr	Yes	Cloudflare API token (masked in logs)

Environment Variables

All settings can be configured via environment variables with the KIARINA_LIB_CLOUDFLARE_ prefix:

# Account ID
export KIARINA_LIB_CLOUDFLARE_ACCOUNT_ID="your-account-id"

# API Token (will be automatically wrapped in SecretStr)
export KIARINA_LIB_CLOUDFLARE_API_TOKEN="your-api-token"

Programmatic Configuration

from pydantic import SecretStr
from kiarina.lib.cloudflare import CloudflareSettings, settings_manager

# Direct settings object
settings = CloudflareSettings(
    account_id="your-account-id",
    api_token=SecretStr("your-api-token")
)

# Via settings manager
settings_manager.user_config = {
    "default": {
        "account_id": "your-account-id",
        "api_token": "your-api-token"  # Automatically converted to SecretStr
    }
}

Runtime Overrides

from kiarina.lib.cloudflare import settings_manager

# Override specific settings at runtime
settings_manager.cli_args = {
    "account_id": "override-account-id"
}

settings = settings_manager.settings
print(f"Account ID: {settings.account_id}")  # Uses overridden value

Security

API Token Protection

API tokens are stored using Pydantic's SecretStr type, which provides the following security benefits:

• Masked in logs: Tokens are displayed as ********** in string representations
• Prevents accidental exposure: Tokens won't appear in debug output or error messages
• Explicit access required: Must use .get_secret_value() to access the actual token

from kiarina.lib.cloudflare import settings_manager

settings = settings_manager.settings

# Token is masked in string representation
print(settings)  # api_token=SecretStr('**********')

# Explicit access to get the actual token
token = settings.api_token.get_secret_value()

API Reference

CloudflareSettings

class CloudflareSettings(BaseSettings):
    account_id: str
    api_token: SecretStr

Pydantic settings model for Cloudflare authentication.

Fields:

• account_id (str): Cloudflare account ID
• api_token (SecretStr): Cloudflare API token (protected)

settings_manager

settings_manager: SettingsManager[CloudflareSettings]

Global settings manager instance for Cloudflare authentication. See: pydantic-settings-manager

Development

Prerequisites

• Python 3.12+

Setup

# Clone the repository
git clone https://github.com/kiarina/kiarina-python.git
cd kiarina-python

# Setup development environment
mise run setup

Running Tests

# Run format, lint, type checks and tests
cd packages/kiarina-lib-cloudflare && make check

# Coverage report
mise run test kiarina-lib-cloudflare --coverage

Dependencies

• pydantic-settings - Settings management
• pydantic-settings-manager - Advanced settings management

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

This is a personal project, but contributions are welcome! Please feel free to submit issues or pull requests.

Related Projects

• kiarina-python - The main monorepo containing this package
• pydantic-settings-manager - Configuration management library used by this package