Loaders

Configuration Loaders

Configuration loaders for Confii.

This module provides loader classes for loading configuration from various sources including files (YAML, JSON, TOML, INI), environment variables, and remote sources (HTTP, cloud storage, Git).

Available Loaders

File Loaders:

YamlLoader: Load from YAML files (.yaml, .yml)
JsonLoader: Load from JSON files (.json)
TomlLoader: Load from TOML files (.toml)
IniLoader: Load from INI files (.ini, .cfg)

Environment Loaders:

EnvironmentLoader: Load from system environment variables

Remote Loaders:

HTTPLoader: Load from HTTP/HTTPS URLs
S3Loader: Load from AWS S3
SSMLoader: Load from AWS SSM Parameter Store
AzureBlobLoader: Load from Azure Blob Storage
GCPStorageLoader: Load from Google Cloud Storage
IBMCloudObjectStorageLoader: Load from IBM Cloud Object Storage
GitLoader: Load from Git repositories

Example

>>> from confii.loaders import YamlLoader, EnvironmentLoader
>>> from confii import Config
>>>
>>> config = Config(loaders=[YamlLoader("config.yaml"), EnvironmentLoader("APP")])

class confii.loaders.AzureBlobLoader(container_url: str, blob_name: str, account_name: str | None = None, account_key: str | None = None, sas_token: str | None = None, connection_string: str | None = None)[source]

Bases: RemoteLoader

Load configuration from Azure Blob Storage.

AzureBlobLoader downloads configuration files from Azure Blob Storage containers. It supports multiple authentication methods: connection strings, account key, SAS tokens, and Azure Managed Identity via DefaultAzureCredential.

url: Synthetic URI in the form azure://<container>/<blob>.

container_url: The Azure container URL or container name.

blob_name: The blob (file) name within the container.

account_name: Azure Storage account name.

account_key: Azure Storage account key (may be None).

sas_token: Shared Access Signature token (may be None).

connection_string: Full Azure Storage connection string (may be None).

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import AzureBlobLoader
>>> loader = AzureBlobLoader(
...     container_url="my-container",
...     blob_name="config/app.yaml",
...     account_name="mystorageaccount",
...     account_key="base64key==",
... )
>>> config_dict = loader.load()

Note

Requires the azure-storage-blob package. Install it with:

pip install azure-storage-blob

Environment variable fallbacks: AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY, AZURE_SAS_TOKEN, AZURE_STORAGE_CONNECTION_STRING.

__init__(container_url: str, blob_name: str, account_name: str | None = None, account_key: str | None = None, sas_token: str | None = None, connection_string: str | None = None)[source]

Initialize Azure Blob loader.

Parameters:

container_url – Azure container URL or plain container name.
blob_name – Name of the blob (file) to load.
account_name – Azure storage account name. Falls back to AZURE_STORAGE_ACCOUNT environment variable.
account_key – Azure storage account key. Falls back to AZURE_STORAGE_KEY environment variable.
sas_token – Shared Access Signature token. Falls back to AZURE_SAS_TOKEN environment variable.
connection_string – Full connection string (alternative to individual credentials). Falls back to AZURE_STORAGE_CONNECTION_STRING environment variable.

load() → Dict[str, Any][source]

Load configuration from Azure Blob Storage.

Downloads the blob content and parses it based on the blob name’s file extension (e.g., .yaml, .json, .toml).

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If azure-storage-blob is not installed.
ValueError – If account_name is required but not provided.
ConfigLoadError – If the Azure request fails or the content cannot be parsed.

Example

>>> loader = AzureBlobLoader(
...     "my-container", "config.yaml", account_name="myaccount"
... )
>>> config = loader.load()

class confii.loaders.EnvFileLoader(source: str = '.env')[source]

Bases: Loader

Loader for .env files with support for nested configurations.

EnvFileLoader parses .env files in the standard KEY=VALUE format used by tools such as Docker Compose, Heroku, and direnv. It supports quoted values, inline comments, escape sequences in double-quoted strings, and nested key structures via dot notation.

source: Path to the .env configuration file.

config: Loaded configuration dictionary.

Example

>>> from confii.loaders import EnvFileLoader
>>> from confii import Config
>>>
>>> loader = EnvFileLoader(".env")
>>> config = Config(loaders=[loader])
>>> print(config.DATABASE_URL)

Note

The .env format supports the following features:

Comments: lines starting with # are ignored.
Quoting: values wrapped in single or double quotes have the quotes stripped. Single-quoted values are treated literally; double-quoted values process \n and \t escapes.
Inline comments: VALUE # comment is supported for unquoted values (the # comment part is stripped).
Nested keys: dot-separated keys like database.host=localhost are expanded into nested dictionaries.
Type coercion: values are automatically converted to int, float, bool, or None where appropriate.
Missing files return None instead of raising an exception.

__init__(source: str = '.env')[source]

Initialize the .env file loader.

Parameters:: source – Path to the .env file. Defaults to ".env" in the current working directory.

load() → Dict[str, Any] | None[source]

Load configuration from a .env file.

Parses each KEY=VALUE line, strips quotes, handles escape sequences, expands dot-notation keys into nested dictionaries, and coerces scalar values to appropriate Python types.

Returns:

Dictionary containing the loaded configuration, or None if the file does not exist.

Raises:

PermissionError – If the file exists but is not readable.
UnicodeDecodeError – If the file contains non-UTF-8 content.

Example

>>> loader = EnvFileLoader(".env.production")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(config_dict["database"]["host"])

class confii.loaders.EnvironmentLoader(prefix: str, separator: str = '__')[source]

Bases: Loader

Loader for environment variables with prefix support.

This loader reads environment variables with a specific prefix and converts them into a nested configuration structure.

__init__(prefix: str, separator: str = '__') → None[source]

Initialize the environment loader.

Parameters:

prefix – Prefix for environment variables to load (e.g., “APP”)
separator – Separator for nested keys (default: “__”) Example: APP_DATABASE__HOST -> database.host

load() → Dict[str, Any] | None[source]

Load configuration from environment variables.

Returns:: Dictionary containing loaded environment variables, or None if no matching environment variables found.
Raises:: ConfigLoadError – If loading fails due to an error

class confii.loaders.GCPStorageLoader(bucket_name: str, blob_name: str, project_id: str | None = None, credentials_path: str | None = None)[source]

Bases: RemoteLoader

Load configuration from Google Cloud Storage.

GCPStorageLoader downloads configuration files from GCS buckets. Authentication is handled via explicit service account credentials or Application Default Credentials (ADC).

url: Synthetic URI in the form gs://<bucket>/<blob>.

bucket_name: The GCS bucket name.

blob_name: The blob (file) name within the bucket.

project_id: GCP project ID.

credentials_path: Path to a service account JSON key file.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import GCPStorageLoader
>>> loader = GCPStorageLoader(
...     bucket_name="my-config-bucket",
...     blob_name="services/app.yaml",
...     project_id="my-gcp-project",
... )
>>> config_dict = loader.load()

Note

Requires the google-cloud-storage package. Install it with:

pip install google-cloud-storage

Environment variable fallbacks: GCP_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS.

__init__(bucket_name: str, blob_name: str, project_id: str | None = None, credentials_path: str | None = None)[source]

Initialize GCP Storage loader.

Parameters:

bucket_name – GCS bucket name.
blob_name – Name of the blob (file) to load.
project_id – GCP project ID. Falls back to the GCP_PROJECT_ID environment variable.
credentials_path – Path to a service account JSON key file. Falls back to the GOOGLE_APPLICATION_CREDENTIALS environment variable.

load() → Dict[str, Any][source]

Load configuration from Google Cloud Storage.

Downloads the blob content as text and parses it based on the blob name’s file extension.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If google-cloud-storage is not installed.
ConfigLoadError – If the GCS request fails or the content cannot be parsed.

Example

>>> loader = GCPStorageLoader("my-bucket", "config.yaml")
>>> config = loader.load()

class confii.loaders.GitLoader(repo_url: str, file_path: str, branch: str = 'main', token: str | None = None)[source]

Bases: RemoteLoader

Load configuration from a Git repository hosted on GitHub or GitLab.

GitLoader constructs a raw-content URL for the specified file and branch, then delegates to HTTPLoader to fetch and parse it. Private repositories are supported via personal access tokens.

url: The Git repository URL (e.g., https://github.com/org/repo).

file_path: Path to the configuration file within the repository.

branch: The Git branch to read from.

token: Access token for private repositories (may be None).

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import GitLoader
>>> loader = GitLoader(
...     repo_url="https://github.com/myorg/myrepo",
...     file_path="config/production.yaml",
...     branch="main",
...     token="ghp_xxxxxxxxxxxx",
... )
>>> config_dict = loader.load()

Note

Currently supports GitHub and GitLab. The GIT_TOKEN environment variable is used as a fallback when token is not provided.

__init__(repo_url: str, file_path: str, branch: str = 'main', token: str | None = None)[source]

Initialize Git loader.

Parameters:

repo_url – Git repository URL (GitHub or GitLab).
file_path – Path to the configuration file within the repository.
branch – Git branch to read from. Defaults to "main".
token – Access token for private repositories. Falls back to the GIT_TOKEN environment variable.

load() → Dict[str, Any][source]

Load configuration from a Git repository.

Converts the repository URL to a raw-content URL based on the hosting provider (GitHub or GitLab), then fetches the file via HTTPLoader.

Returns:

Dictionary containing the loaded configuration.

Raises:

ValueError – If the Git provider is not supported (neither GitHub nor GitLab).
ConfigLoadError – If the HTTP request or parsing fails.

Example

>>> loader = GitLoader("https://github.com/org/repo", "config.yaml")
>>> config = loader.load()

class confii.loaders.HTTPLoader(url: str, timeout: int = 30, headers: Dict[str, str] | None = None, auth: Tuple[str, str] | None = None)[source]

Bases: RemoteLoader

Load configuration from HTTP/HTTPS endpoints.

HTTPLoader fetches configuration files from any HTTP or HTTPS URL. The response content-type header is used to determine the configuration format; if the content-type is ambiguous, the URL’s file extension is used as a fallback. Supports JSON, YAML, and TOML formats.

url: The HTTP/HTTPS URL of the configuration resource.

timeout: Request timeout in seconds.

headers: HTTP headers sent with the request.

auth: Optional basic-auth credentials as a (username, password) tuple.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import HTTPLoader
>>> loader = HTTPLoader(
...     "https://config-server.example.com/app/config.yaml",
...     headers={"X-API-Key": "secret"},
...     timeout=10,
... )
>>> config_dict = loader.load()
>>> print(config_dict["database"]["host"])

Note

Requires the requests package. Install it with:

pip install requests

__init__(url: str, timeout: int = 30, headers: Dict[str, str] | None = None, auth: Tuple[str, str] | None = None)[source]

Initialize HTTP loader.

Parameters:

url – HTTP/HTTPS URL to fetch configuration from.
timeout – Request timeout in seconds. Defaults to 30.
headers – Optional HTTP headers (e.g., API keys).
auth – Optional (username, password) tuple for HTTP Basic Auth.

Raises:

ImportError – If the requests package is not installed.

load() → Dict[str, Any][source]

Load configuration from an HTTP/HTTPS endpoint.

Sends a GET request to the configured URL, detects the response format from the content-type header or URL extension, and parses the content into a dictionary.

Returns:: Dictionary containing the loaded configuration.
Raises:: ConfigLoadError – If the HTTP request fails or the response content cannot be parsed.

Example

>>> loader = HTTPLoader("https://example.com/config.json")
>>> config = loader.load()

class confii.loaders.IBMCloudObjectStorageLoader(bucket_name: str, object_key: str, api_key: str | None = None, service_instance_id: str | None = None, endpoint_url: str | None = None, region: str = 'us-south')[source]

Bases: RemoteLoader

Load configuration from IBM Cloud Object Storage.

IBMCloudObjectStorageLoader fetches configuration files stored in IBM Cloud Object Storage (COS) buckets using the S3-compatible API provided by the ibm-cos-sdk package. Authentication uses IBM IAM OAuth via an API key and service instance ID.

url: Synthetic URI in the form ibmcos://<bucket>/<key>.

bucket_name: The IBM COS bucket name.

object_key: The object key (path) within the bucket.

api_key: IBM Cloud API key.

service_instance_id: IBM COS service instance ID.

region: IBM Cloud region (e.g., "us-south").

endpoint_url: The S3-compatible endpoint URL.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import IBMCloudObjectStorageLoader
>>> loader = IBMCloudObjectStorageLoader(
...     bucket_name="my-config-bucket",
...     object_key="app/config.yaml",
...     api_key="ibm-api-key",
...     service_instance_id="crn:v1:...",
... )
>>> config_dict = loader.load()

Note

Requires the ibm-cos-sdk package. Install it with:

pip install ibm-cos-sdk

Environment variable fallbacks: IBM_API_KEY, IBM_SERVICE_INSTANCE_ID.

__init__(bucket_name: str, object_key: str, api_key: str | None = None, service_instance_id: str | None = None, endpoint_url: str | None = None, region: str = 'us-south')[source]

Initialize IBM Cloud Object Storage loader.

Parameters:

bucket_name – IBM COS bucket name.
object_key – Key (path) of the object to load.
api_key – IBM Cloud API key. Falls back to the IBM_API_KEY environment variable.
service_instance_id – IBM COS service instance ID. Falls back to the IBM_SERVICE_INSTANCE_ID environment variable.
endpoint_url – Custom S3-compatible endpoint URL. Defaults to the public endpoint for the given region.
region – IBM Cloud region. Defaults to "us-south".

load() → Dict[str, Any][source]

Load configuration from IBM Cloud Object Storage.

Downloads the object content and parses it based on the object key’s file extension.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If ibm-cos-sdk is not installed.
ConfigLoadError – If the IBM COS request fails or the content cannot be parsed.

Example

>>> loader = IBMCloudObjectStorageLoader("my-bucket", "config.yaml")
>>> config = loader.load()

class confii.loaders.IniLoader(source: str)[source]

Bases: Loader

Loader for INI configuration files.

IniLoader loads configuration data from INI (.ini or .cfg) files using Python’s configparser.RawConfigParser. The raw parser is used to avoid interpolation of % characters that may appear in configuration values such as connection strings or format patterns.

Each INI section becomes a top-level key in the resulting dictionary, with the section’s key-value pairs nested underneath. Scalar values are automatically coerced to appropriate Python types (int, float, bool, None) via parse_scalar_value.

source: Path to the INI configuration file.

config: Loaded configuration dictionary.

Example

>>> from confii.loaders import IniLoader
>>> from confii import Config
>>>
>>> loader = IniLoader("database.ini")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files are handled gracefully and return None instead of raising an exception. This allows for optional configuration files. The DEFAULT section in INI files is not included as a separate key; its values are inherited by other sections per standard configparser behavior.

__init__(source: str)[source]

Initialize the INI loader.

Parameters:: source – Path to the INI file.

load() → Dict[str, Any] | None[source]

Load configuration from an INI file.

Reads the INI file, parses each section into a nested dictionary, and coerces scalar values to their appropriate Python types.

Returns:: Dictionary containing the loaded configuration keyed by section name, or None if the file does not exist or is unreadable.
Raises:: configparser.MissingSectionHeaderError – If the file is not valid INI format (missing section headers).

Example

>>> loader = IniLoader("app.ini")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(config_dict["database"]["host"])

class confii.loaders.JsonLoader(source: str)[source]

Bases: Loader

Loader for JSON configuration files.

JsonLoader loads configuration data from JSON (.json) files. It uses Python’s built-in json module to parse the configuration.

source: Path to the JSON configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import JsonLoader
>>> from confii import Config
>>>
>>> loader = JsonLoader("config.json")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files are handled gracefully and return None instead of raising an exception. This allows for optional configuration files.

load() → Dict[str, Any] | None[source]

Load configuration from JSON file.

This method reads the JSON file specified in the source attribute, parses it using Python’s json.loads, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the JSON file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = JsonLoader("config.json")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

class confii.loaders.Loader(source: str)[source]

Bases: ABC

Abstract base class for configuration loaders.

All configuration loaders must inherit from this class and implement the load() method. This provides a consistent interface for loading configuration from various sources (files, remote URLs, environment, etc.).

source: The source identifier (file path, URL, prefix, etc.)

config: The loaded configuration dictionary (may be empty if not loaded yet)

__init__(source: str) → None[source]

Initialize the loader with a source.

Parameters:: source – The source identifier (file path, URL, prefix, etc.)

abstractmethod load() → Dict[str, Any] | None[source]

Load configuration from the source.

This method must be implemented by subclasses to load configuration from their specific source type.

Returns:

Dictionary containing the loaded configuration, or None if the source doesn’t exist or couldn’t be loaded (depending on loader behavior).

Raises:

ConfigLoadError – If loading fails due to an error (not just missing source)
ConfigFormatError – If the configuration format is invalid

class confii.loaders.RemoteLoader(url: str, timeout: int = 30, headers: Dict[str, str] | None = None)[source]

Bases: object

Base class for remote configuration loading.

RemoteLoader provides the shared interface and common attributes for all remote configuration loaders. Subclasses implement the load() method to fetch configuration from specific remote backends (HTTP, S3, Azure Blob Storage, GCP Storage, Git repositories, IBM COS).

The loaded content is automatically parsed into a Python dictionary based on the file extension or content-type header using the format_parser utility.

url: The remote URL or URI identifying the configuration source.

timeout: Request timeout in seconds.

headers: HTTP headers sent with the request (where applicable).

source: Alias for url, used for source tracking.

config: The loaded configuration dictionary (populated after load()).

Example

>>> # RemoteLoader is abstract; use a concrete subclass:
>>> loader = HTTPLoader("https://example.com/config.json")
>>> config_dict = loader.load()

__init__(url: str, timeout: int = 30, headers: Dict[str, str] | None = None)[source]

Initialize remote loader.

Parameters:

url – URL or URI to load configuration from.
timeout – Request timeout in seconds. Defaults to 30.
headers – Optional HTTP headers to include in requests.

load() → Dict[str, Any][source]

Load configuration from remote source.

Returns:: Dictionary containing the loaded configuration.
Raises:: NotImplementedError – Always; subclasses must override this method.

class confii.loaders.S3Loader(s3_url: str, aws_access_key: str | None = None, aws_secret_key: str | None = None, region: str = 'us-east-1')[source]

Bases: RemoteLoader

Load configuration from AWS S3.

S3Loader fetches configuration files stored in Amazon S3 buckets. Authentication can be provided explicitly via access keys, or implicitly through IAM roles, environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), or the default boto3 credential chain.

url: The original s3:// URL.

bucket: The S3 bucket name (parsed from the URL).

key: The object key / path within the bucket.

aws_access_key: AWS access key ID (may be None for IAM).

aws_secret_key: AWS secret access key (may be None for IAM).

region: AWS region name.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import S3Loader
>>> loader = S3Loader("s3://my-bucket/configs/app.yaml", region="eu-west-1")
>>> config_dict = loader.load()

Note

Requires the boto3 package. Install it with:

pip install boto3

__init__(s3_url: str, aws_access_key: str | None = None, aws_secret_key: str | None = None, region: str = 'us-east-1')[source]

Initialize S3 loader.

Parameters:

s3_url – S3 URL in the form s3://bucket/path/to/config.json.
aws_access_key – AWS access key ID. Falls back to the AWS_ACCESS_KEY_ID environment variable or IAM role.
aws_secret_key – AWS secret access key. Falls back to the AWS_SECRET_ACCESS_KEY environment variable or IAM role.
region – AWS region name. Defaults to "us-east-1".

Raises:

ValueError – If the URL scheme is not s3.

load() → Dict[str, Any][source]

Load configuration from an AWS S3 bucket.

Downloads the object specified by bucket and key, then parses the content based on the file extension of the key.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If boto3 is not installed.
ConfigLoadError – If the S3 request fails or the content cannot be parsed.

Example

>>> loader = S3Loader("s3://my-bucket/config.yaml")
>>> config = loader.load()

class confii.loaders.SSMLoader(path_prefix: str, decrypt: bool = True, aws_region: str | None = None, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None)[source]

Bases: Loader

Load configuration from AWS Systems Manager Parameter Store.

SSMLoader fetches parameters stored under a given path prefix in AWS SSM Parameter Store and converts them into a nested Python dictionary. For example, parameters stored at /myapp/production/database/host and /myapp/production/database/port with a path_prefix of /myapp/production/ produce:

{"database": {"host": "db.example.com", "port": 5432}}

Authentication can be provided explicitly via constructor arguments, or implicitly through IAM roles, environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION), or the default boto3 credential chain.

String values are automatically coerced to appropriate Python types (int, float, bool) via parse_scalar_value.

source: The SSM path prefix used as the configuration source.

path_prefix: The SSM path prefix to fetch parameters from.

decrypt: Whether to decrypt SecureString parameters.

aws_region: AWS region name.

aws_access_key_id: AWS access key ID (may be None for IAM).

aws_secret_access_key: AWS secret access key (may be None for IAM).

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.ssm_loader import SSMLoader
>>> loader = SSMLoader(
...     path_prefix="/myapp/production/",
...     decrypt=True,
...     aws_region="us-west-2",
... )
>>> config_dict = loader.load()
>>> print(config_dict["database"]["host"])

Note

Requires the boto3 package. Install it with:

pip install boto3

__init__(path_prefix: str, decrypt: bool = True, aws_region: str | None = None, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None) → None[source]

Initialize SSM Parameter Store loader.

Parameters:

path_prefix – SSM path prefix to fetch parameters from (e.g., /myapp/production/). A trailing slash is added automatically if not present.
decrypt – Whether to decrypt SecureString parameters. Defaults to True.
aws_region – AWS region name. Falls back to the AWS_DEFAULT_REGION environment variable, then "us-east-1".
aws_access_key_id – AWS access key ID. Falls back to the AWS_ACCESS_KEY_ID environment variable or IAM role.
aws_secret_access_key – AWS secret access key. Falls back to the AWS_SECRET_ACCESS_KEY environment variable or IAM role.

load() → Dict[str, Any] | None[source]

Load configuration from AWS SSM Parameter Store.

Fetches all parameters under path_prefix using the SSM get_parameters_by_path API with automatic pagination. Each parameter’s path (relative to the prefix) is split into nested dictionary keys, and string values are coerced to native Python types where possible.

Returns:

Dictionary containing the loaded configuration, or None if no parameters were found under the prefix.

Raises:

ImportError – If boto3 is not installed.
ConfigLoadError – If the SSM API call fails.

Example

>>> loader = SSMLoader("/myapp/production/")
>>> config = loader.load()

class confii.loaders.TomlLoader(source: str)[source]

Bases: Loader

Loader for TOML configuration files.

TomlLoader loads configuration data from TOML (.toml) files. It uses the toml library to parse the configuration.

source: Path to the TOML configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import TomlLoader
>>> from confii import Config
>>>
>>> loader = TomlLoader("config.toml")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files raise ConfigLoadError. Ensure the file exists or handle the exception appropriately.

load() → Dict[str, Any] | None[source]

Load configuration from TOML file.

This method reads the TOML file specified in the source attribute, parses it using the toml library, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the TOML file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = TomlLoader("config.toml")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

class confii.loaders.YamlLoader(source: str)[source]

Bases: Loader

Loader for YAML configuration files.

YamlLoader loads configuration data from YAML (.yaml or .yml) files. It uses PyYAML’s safe_load to parse the configuration, which prevents arbitrary code execution.

source: Path to the YAML configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import YamlLoader
>>> from confii import Config
>>>
>>> loader = YamlLoader("config.yaml")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files are handled gracefully and return None instead of raising an exception. This allows for optional configuration files.

load() → Dict[str, Any] | None[source]

Load configuration from YAML file.

This method reads the YAML file specified in the source attribute, parses it using PyYAML’s safe_load, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the YAML file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = YamlLoader("config.yaml")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

Base Loader

class confii.loaders.loader.Loader(source: str)[source]

Bases: ABC

Abstract base class for configuration loaders.

All configuration loaders must inherit from this class and implement the load() method. This provides a consistent interface for loading configuration from various sources (files, remote URLs, environment, etc.).

source: The source identifier (file path, URL, prefix, etc.)

config: The loaded configuration dictionary (may be empty if not loaded yet)

__init__(source: str) → None[source]

Initialize the loader with a source.

Parameters:: source – The source identifier (file path, URL, prefix, etc.)

abstractmethod load() → Dict[str, Any] | None[source]

Load configuration from the source.

This method must be implemented by subclasses to load configuration from their specific source type.

Returns:

Dictionary containing the loaded configuration, or None if the source doesn’t exist or couldn’t be loaded (depending on loader behavior).

Raises:

ConfigLoadError – If loading fails due to an error (not just missing source)
ConfigFormatError – If the configuration format is invalid

YAML Loader

YAML configuration loader for Confii.

This module provides the YamlLoader class for loading configuration from YAML files.

class confii.loaders.yaml_loader.YamlLoader(source: str)[source]

Bases: Loader

Loader for YAML configuration files.

YamlLoader loads configuration data from YAML (.yaml or .yml) files. It uses PyYAML’s safe_load to parse the configuration, which prevents arbitrary code execution.

source: Path to the YAML configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import YamlLoader
>>> from confii import Config
>>>
>>> loader = YamlLoader("config.yaml")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files are handled gracefully and return None instead of raising an exception. This allows for optional configuration files.

load() → Dict[str, Any] | None[source]

Load configuration from YAML file.

This method reads the YAML file specified in the source attribute, parses it using PyYAML’s safe_load, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the YAML file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = YamlLoader("config.yaml")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

JSON Loader

JSON configuration loader for Confii.

This module provides the JsonLoader class for loading configuration from JSON files.

class confii.loaders.json_loader.JsonLoader(source: str)[source]

Bases: Loader

Loader for JSON configuration files.

JsonLoader loads configuration data from JSON (.json) files. It uses Python’s built-in json module to parse the configuration.

source: Path to the JSON configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import JsonLoader
>>> from confii import Config
>>>
>>> loader = JsonLoader("config.json")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files are handled gracefully and return None instead of raising an exception. This allows for optional configuration files.

load() → Dict[str, Any] | None[source]

Load configuration from JSON file.

This method reads the JSON file specified in the source attribute, parses it using Python’s json.loads, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the JSON file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = JsonLoader("config.json")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

TOML Loader

TOML configuration loader for Confii.

This module provides the TomlLoader class for loading configuration from TOML files.

class confii.loaders.toml_loader.TomlLoader(source: str)[source]

Bases: Loader

Loader for TOML configuration files.

TomlLoader loads configuration data from TOML (.toml) files. It uses the toml library to parse the configuration.

source: Path to the TOML configuration file

config: Loaded configuration dictionary

Example

>>> from confii.loaders import TomlLoader
>>> from confii import Config
>>>
>>> loader = TomlLoader("config.toml")
>>> config = Config(loaders=[loader])
>>> print(config.database.host)

Note

Missing files raise ConfigLoadError. Ensure the file exists or handle the exception appropriately.

load() → Dict[str, Any] | None[source]

Load configuration from TOML file.

This method reads the TOML file specified in the source attribute, parses it using the toml library, and returns the configuration as a dictionary.

Returns:

Dictionary containing the loaded configuration, or None if the file doesn’t exist (allows for optional configuration files).

Raises:

ConfigFormatError – If the TOML file contains invalid syntax or cannot be parsed.
ConfigLoadError – If there’s an error reading the file (other than file not found).

Example

>>> loader = TomlLoader("config.toml")
>>> config_dict = loader.load()
>>> if config_dict:
...     print(f"Loaded {len(config_dict)} keys")

Environment Loader

class confii.loaders.environment_loader.EnvironmentLoader(prefix: str, separator: str = '__')[source]

Bases: Loader

Loader for environment variables with prefix support.

This loader reads environment variables with a specific prefix and converts them into a nested configuration structure.

__init__(prefix: str, separator: str = '__') → None[source]

Initialize the environment loader.

Parameters:

prefix – Prefix for environment variables to load (e.g., “APP”)
separator – Separator for nested keys (default: “__”) Example: APP_DATABASE__HOST -> database.host

load() → Dict[str, Any] | None[source]

Load configuration from environment variables.

Returns:: Dictionary containing loaded environment variables, or None if no matching environment variables found.
Raises:: ConfigLoadError – If loading fails due to an error

Remote Loaders

Remote configuration loaders for Confii.

class confii.loaders.remote_loader.AzureBlobLoader(container_url: str, blob_name: str, account_name: str | None = None, account_key: str | None = None, sas_token: str | None = None, connection_string: str | None = None)[source]

Bases: RemoteLoader

Load configuration from Azure Blob Storage.

AzureBlobLoader downloads configuration files from Azure Blob Storage containers. It supports multiple authentication methods: connection strings, account key, SAS tokens, and Azure Managed Identity via DefaultAzureCredential.

url: Synthetic URI in the form azure://<container>/<blob>.

container_url: The Azure container URL or container name.

blob_name: The blob (file) name within the container.

account_name: Azure Storage account name.

account_key: Azure Storage account key (may be None).

sas_token: Shared Access Signature token (may be None).

connection_string: Full Azure Storage connection string (may be None).

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import AzureBlobLoader
>>> loader = AzureBlobLoader(
...     container_url="my-container",
...     blob_name="config/app.yaml",
...     account_name="mystorageaccount",
...     account_key="base64key==",
... )
>>> config_dict = loader.load()

Note

Requires the azure-storage-blob package. Install it with:

pip install azure-storage-blob

Environment variable fallbacks: AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY, AZURE_SAS_TOKEN, AZURE_STORAGE_CONNECTION_STRING.

__init__(container_url: str, blob_name: str, account_name: str | None = None, account_key: str | None = None, sas_token: str | None = None, connection_string: str | None = None)[source]

Initialize Azure Blob loader.

Parameters:

container_url – Azure container URL or plain container name.
blob_name – Name of the blob (file) to load.
account_name – Azure storage account name. Falls back to AZURE_STORAGE_ACCOUNT environment variable.
account_key – Azure storage account key. Falls back to AZURE_STORAGE_KEY environment variable.
sas_token – Shared Access Signature token. Falls back to AZURE_SAS_TOKEN environment variable.
connection_string – Full connection string (alternative to individual credentials). Falls back to AZURE_STORAGE_CONNECTION_STRING environment variable.

load() → Dict[str, Any][source]

Load configuration from Azure Blob Storage.

Downloads the blob content and parses it based on the blob name’s file extension (e.g., .yaml, .json, .toml).

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If azure-storage-blob is not installed.
ValueError – If account_name is required but not provided.
ConfigLoadError – If the Azure request fails or the content cannot be parsed.

Example

>>> loader = AzureBlobLoader(
...     "my-container", "config.yaml", account_name="myaccount"
... )
>>> config = loader.load()

class confii.loaders.remote_loader.GCPStorageLoader(bucket_name: str, blob_name: str, project_id: str | None = None, credentials_path: str | None = None)[source]

Bases: RemoteLoader

Load configuration from Google Cloud Storage.

GCPStorageLoader downloads configuration files from GCS buckets. Authentication is handled via explicit service account credentials or Application Default Credentials (ADC).

url: Synthetic URI in the form gs://<bucket>/<blob>.

bucket_name: The GCS bucket name.

blob_name: The blob (file) name within the bucket.

project_id: GCP project ID.

credentials_path: Path to a service account JSON key file.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import GCPStorageLoader
>>> loader = GCPStorageLoader(
...     bucket_name="my-config-bucket",
...     blob_name="services/app.yaml",
...     project_id="my-gcp-project",
... )
>>> config_dict = loader.load()

Note

Requires the google-cloud-storage package. Install it with:

pip install google-cloud-storage

Environment variable fallbacks: GCP_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS.

__init__(bucket_name: str, blob_name: str, project_id: str | None = None, credentials_path: str | None = None)[source]

Initialize GCP Storage loader.

Parameters:

bucket_name – GCS bucket name.
blob_name – Name of the blob (file) to load.
project_id – GCP project ID. Falls back to the GCP_PROJECT_ID environment variable.
credentials_path – Path to a service account JSON key file. Falls back to the GOOGLE_APPLICATION_CREDENTIALS environment variable.

load() → Dict[str, Any][source]

Load configuration from Google Cloud Storage.

Downloads the blob content as text and parses it based on the blob name’s file extension.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If google-cloud-storage is not installed.
ConfigLoadError – If the GCS request fails or the content cannot be parsed.

Example

>>> loader = GCPStorageLoader("my-bucket", "config.yaml")
>>> config = loader.load()

class confii.loaders.remote_loader.GitLoader(repo_url: str, file_path: str, branch: str = 'main', token: str | None = None)[source]

Bases: RemoteLoader

Load configuration from a Git repository hosted on GitHub or GitLab.

GitLoader constructs a raw-content URL for the specified file and branch, then delegates to HTTPLoader to fetch and parse it. Private repositories are supported via personal access tokens.

url: The Git repository URL (e.g., https://github.com/org/repo).

file_path: Path to the configuration file within the repository.

branch: The Git branch to read from.

token: Access token for private repositories (may be None).

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import GitLoader
>>> loader = GitLoader(
...     repo_url="https://github.com/myorg/myrepo",
...     file_path="config/production.yaml",
...     branch="main",
...     token="ghp_xxxxxxxxxxxx",
... )
>>> config_dict = loader.load()

Note

Currently supports GitHub and GitLab. The GIT_TOKEN environment variable is used as a fallback when token is not provided.

__init__(repo_url: str, file_path: str, branch: str = 'main', token: str | None = None)[source]

Initialize Git loader.

Parameters:

repo_url – Git repository URL (GitHub or GitLab).
file_path – Path to the configuration file within the repository.
branch – Git branch to read from. Defaults to "main".
token – Access token for private repositories. Falls back to the GIT_TOKEN environment variable.

load() → Dict[str, Any][source]

Load configuration from a Git repository.

Converts the repository URL to a raw-content URL based on the hosting provider (GitHub or GitLab), then fetches the file via HTTPLoader.

Returns:

Dictionary containing the loaded configuration.

Raises:

ValueError – If the Git provider is not supported (neither GitHub nor GitLab).
ConfigLoadError – If the HTTP request or parsing fails.

Example

>>> loader = GitLoader("https://github.com/org/repo", "config.yaml")
>>> config = loader.load()

class confii.loaders.remote_loader.HTTPLoader(url: str, timeout: int = 30, headers: Dict[str, str] | None = None, auth: Tuple[str, str] | None = None)[source]

Bases: RemoteLoader

Load configuration from HTTP/HTTPS endpoints.

HTTPLoader fetches configuration files from any HTTP or HTTPS URL. The response content-type header is used to determine the configuration format; if the content-type is ambiguous, the URL’s file extension is used as a fallback. Supports JSON, YAML, and TOML formats.

url: The HTTP/HTTPS URL of the configuration resource.

timeout: Request timeout in seconds.

headers: HTTP headers sent with the request.

auth: Optional basic-auth credentials as a (username, password) tuple.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import HTTPLoader
>>> loader = HTTPLoader(
...     "https://config-server.example.com/app/config.yaml",
...     headers={"X-API-Key": "secret"},
...     timeout=10,
... )
>>> config_dict = loader.load()
>>> print(config_dict["database"]["host"])

Note

Requires the requests package. Install it with:

pip install requests

__init__(url: str, timeout: int = 30, headers: Dict[str, str] | None = None, auth: Tuple[str, str] | None = None)[source]

Initialize HTTP loader.

Parameters:

url – HTTP/HTTPS URL to fetch configuration from.
timeout – Request timeout in seconds. Defaults to 30.
headers – Optional HTTP headers (e.g., API keys).
auth – Optional (username, password) tuple for HTTP Basic Auth.

Raises:

ImportError – If the requests package is not installed.

load() → Dict[str, Any][source]

Load configuration from an HTTP/HTTPS endpoint.

Sends a GET request to the configured URL, detects the response format from the content-type header or URL extension, and parses the content into a dictionary.

Returns:: Dictionary containing the loaded configuration.
Raises:: ConfigLoadError – If the HTTP request fails or the response content cannot be parsed.

Example

>>> loader = HTTPLoader("https://example.com/config.json")
>>> config = loader.load()

class confii.loaders.remote_loader.IBMCloudObjectStorageLoader(bucket_name: str, object_key: str, api_key: str | None = None, service_instance_id: str | None = None, endpoint_url: str | None = None, region: str = 'us-south')[source]

Bases: RemoteLoader

Load configuration from IBM Cloud Object Storage.

IBMCloudObjectStorageLoader fetches configuration files stored in IBM Cloud Object Storage (COS) buckets using the S3-compatible API provided by the ibm-cos-sdk package. Authentication uses IBM IAM OAuth via an API key and service instance ID.

url: Synthetic URI in the form ibmcos://<bucket>/<key>.

bucket_name: The IBM COS bucket name.

object_key: The object key (path) within the bucket.

api_key: IBM Cloud API key.

service_instance_id: IBM COS service instance ID.

region: IBM Cloud region (e.g., "us-south").

endpoint_url: The S3-compatible endpoint URL.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import IBMCloudObjectStorageLoader
>>> loader = IBMCloudObjectStorageLoader(
...     bucket_name="my-config-bucket",
...     object_key="app/config.yaml",
...     api_key="ibm-api-key",
...     service_instance_id="crn:v1:...",
... )
>>> config_dict = loader.load()

Note

Requires the ibm-cos-sdk package. Install it with:

pip install ibm-cos-sdk

Environment variable fallbacks: IBM_API_KEY, IBM_SERVICE_INSTANCE_ID.

__init__(bucket_name: str, object_key: str, api_key: str | None = None, service_instance_id: str | None = None, endpoint_url: str | None = None, region: str = 'us-south')[source]

Initialize IBM Cloud Object Storage loader.

Parameters:

bucket_name – IBM COS bucket name.
object_key – Key (path) of the object to load.
api_key – IBM Cloud API key. Falls back to the IBM_API_KEY environment variable.
service_instance_id – IBM COS service instance ID. Falls back to the IBM_SERVICE_INSTANCE_ID environment variable.
endpoint_url – Custom S3-compatible endpoint URL. Defaults to the public endpoint for the given region.
region – IBM Cloud region. Defaults to "us-south".

load() → Dict[str, Any][source]

Load configuration from IBM Cloud Object Storage.

Downloads the object content and parses it based on the object key’s file extension.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If ibm-cos-sdk is not installed.
ConfigLoadError – If the IBM COS request fails or the content cannot be parsed.

Example

>>> loader = IBMCloudObjectStorageLoader("my-bucket", "config.yaml")
>>> config = loader.load()

class confii.loaders.remote_loader.RemoteLoader(url: str, timeout: int = 30, headers: Dict[str, str] | None = None)[source]

Bases: object

Base class for remote configuration loading.

RemoteLoader provides the shared interface and common attributes for all remote configuration loaders. Subclasses implement the load() method to fetch configuration from specific remote backends (HTTP, S3, Azure Blob Storage, GCP Storage, Git repositories, IBM COS).

The loaded content is automatically parsed into a Python dictionary based on the file extension or content-type header using the format_parser utility.

url: The remote URL or URI identifying the configuration source.

timeout: Request timeout in seconds.

headers: HTTP headers sent with the request (where applicable).

source: Alias for url, used for source tracking.

config: The loaded configuration dictionary (populated after load()).

Example

>>> # RemoteLoader is abstract; use a concrete subclass:
>>> loader = HTTPLoader("https://example.com/config.json")
>>> config_dict = loader.load()

__init__(url: str, timeout: int = 30, headers: Dict[str, str] | None = None)[source]

Initialize remote loader.

Parameters:

url – URL or URI to load configuration from.
timeout – Request timeout in seconds. Defaults to 30.
headers – Optional HTTP headers to include in requests.

load() → Dict[str, Any][source]

Load configuration from remote source.

Returns:: Dictionary containing the loaded configuration.
Raises:: NotImplementedError – Always; subclasses must override this method.

class confii.loaders.remote_loader.S3Loader(s3_url: str, aws_access_key: str | None = None, aws_secret_key: str | None = None, region: str = 'us-east-1')[source]

Bases: RemoteLoader

Load configuration from AWS S3.

S3Loader fetches configuration files stored in Amazon S3 buckets. Authentication can be provided explicitly via access keys, or implicitly through IAM roles, environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), or the default boto3 credential chain.

url: The original s3:// URL.

bucket: The S3 bucket name (parsed from the URL).

key: The object key / path within the bucket.

aws_access_key: AWS access key ID (may be None for IAM).

aws_secret_key: AWS secret access key (may be None for IAM).

region: AWS region name.

config: The loaded configuration dictionary.

Example

>>> from confii.loaders.remote_loader import S3Loader
>>> loader = S3Loader("s3://my-bucket/configs/app.yaml", region="eu-west-1")
>>> config_dict = loader.load()

Note

Requires the boto3 package. Install it with:

pip install boto3

__init__(s3_url: str, aws_access_key: str | None = None, aws_secret_key: str | None = None, region: str = 'us-east-1')[source]

Initialize S3 loader.

Parameters:

s3_url – S3 URL in the form s3://bucket/path/to/config.json.
aws_access_key – AWS access key ID. Falls back to the AWS_ACCESS_KEY_ID environment variable or IAM role.
aws_secret_key – AWS secret access key. Falls back to the AWS_SECRET_ACCESS_KEY environment variable or IAM role.
region – AWS region name. Defaults to "us-east-1".

Raises:

ValueError – If the URL scheme is not s3.

load() → Dict[str, Any][source]

Load configuration from an AWS S3 bucket.

Downloads the object specified by bucket and key, then parses the content based on the file extension of the key.

Returns:

Dictionary containing the loaded configuration.

Raises:

ImportError – If boto3 is not installed.
ConfigLoadError – If the S3 request fails or the content cannot be parsed.

Example

>>> loader = S3Loader("s3://my-bucket/config.yaml")
>>> config = loader.load()