Getting started¶

Installation¶

You can install EYConf from PyPI using pip.

pip install eyconf

Basic Usage¶

from dataclasses import dataclass
from eyconf import EYConf

@dataclass
class AppConfig:
    """Application configuration"""
    database_url: str = "sqlite:///app.db"
    debug: bool = False

# Creates/loads config.yaml automatically
config = EYConf(AppConfig)

# Use your config
print(config.data.debug)  # False

This will create a config.yaml file in your current working directory with the following content:

# Application configuration

database_url: sqlite:///app.db
debug: false

Core concepts¶

The main idea of EYConf is to define your configuration schema using one or multiple strongly typed dataclasses. This is similar to how Pydantic works, but way less heavy weight. EYConf uses Python’s built-in dataclasses and the jsonschema library to perform validation.

1. Define Your Schema¶

Start by defining your configuration structure using dataclasses:

from dataclasses import dataclass

@dataclass
class Transport:
    """Email transport configuration"""
    host: str = 'imap.example.com'
    port: int = 993
    username: str = 'user'
    password: str = 'password'
    use_ssl: bool = False

@dataclass
class Other:
    """Other configuration options"""
    bar: int | None = None

@dataclass
class ConfigSchema:
    """My configuration schema

    Docstrings are used as comments in the generated yaml file!
    """
    transport: Transport
    other: Other

2. Create and Use Configuration¶

We can now create a configuration using the EYConf class directly, if you need more control it is also possible to extend the class or use the Config base class.

from eyconf import EYConf

config = EYConf(ConfigSchema)

This created the config.yaml file in your current working directory with the following content. Notice that the docstrings are used as comments in the generated yaml file.

# My configuration schema
# Docstrings are used as comments in the generated yaml file!

transport:
  # Email transport configuration

  host: imap.example.com
  port: 993
  username: user
  password: password
  use_ssl: false

other:
  # Other configuration options

  bar: null

3. Modify and Reload¶

Edit config.yaml and reload changes:

transport:
  host: production-db.example.com
  username: prod_user

config.reload()
print(config.data.transport.host)  # "production-db.example.com"

Configuration errors will be caught during loading with detailed error messages:

transport:
  host: imap.example.com
  port: not_a_number  # Invalid type

config.reload()
# Raises
# ConfigurationError:
# 'not_a_number' is not of type 'integer' in section 'transport.port'