Skip to content

Settings and Configuration

Sayer provides a built-in way to configure your CLI application using centralized settings, powered by the SAYER_SETTINGS_MODULE environment variable.

This mechanism lets you:

  • Keep config logic out of command code
  • Load settings dynamically
  • Easily override settings in dev, test, and prod environments

βš™οΈ Default Settings Class

Sayer includes a built-in Settings dataclass that defines the default configuration used when no SAYER_SETTINGS_MODULE is set, or when internal tools need immediate settings access.

This class covers:

  • Debug mode and logging
  • Output color systems
  • Version tagging
  • Serialization utilities

πŸ“¦ Location

from sayer.conf.settings import Settings

This is not to be confused with your application-level settings β€” it is used internally and as a base for custom configurations.


🧾 Default Fields

Field Type Description
debug bool Enables debug mode (more logging, errors)
logging_level str Logging threshold (DEBUG, INFO, etc.)
version str Version of the Sayer library (auto-filled)
is_logging_setup bool Tracks if logging has already been configured
force_terminal bool | None Force terminal output regardless of environment
color_system "auto" | "standard" | "256" | ... Controls terminal color profile
display_full_help bool Flag indicating the the display of each command must be diplayed in full
display_help_length int The length of the help if display_full_help is set to False. Defaults to 99

πŸŽ›οΈ Field Examples

settings.debug = True
settings.logging_level = "DEBUG"
settings.force_terminal = True
settings.color_system = "256"

🧠 logging_config Property

This is a dynamic property that returns a LoggingConfig object based on the current logging level.

config = settings.logging_config

Sayer uses this internally to configure rich/standard logging output. You can override it:

from sayer.logging import CustomLoggingConfig

settings.logging_config = CustomLoggingConfig(level="DEBUG")

πŸ”„ Converting to Dict or Tuples

The Settings class provides two helpers to introspect or export the config:

dict(...)

settings.dict(exclude_none=True, upper=True)

Args:

  • exclude_none: Omit fields with None values
  • upper: Transform keys to uppercase (useful for env-like exports)

Returns:

{
  "DEBUG": True,
  "LOGGING_LEVEL": "INFO",
  ...
}

tuple(...)

settings.tuple(exclude_none=True, upper=False)

Returns:

[("debug", True), ("logging_level", "INFO"), ...]

Useful for exporting to .env files or logging config introspection.


🧰 Internal Use

The Settings class is primarily used:

  • As the fallback configuration if SAYER_SETTINGS_MODULE is not defined
  • By components like sayer.logging and rich terminal integration
  • To bootstrap internal state when settings aren’t user-defined

πŸ§ͺ Customizing in Tests

You can use it in test environments or override fields dynamically:

from sayer.conf.global_settings import Settings

s = Settings(debug=True, logging_level="DEBUG")
print(s.dict())

🧬 Summary

Feature Supported
Built-in debug mode βœ…
Color and terminal control βœ…
Logging abstraction βœ…
Dict export βœ…
Tuple export βœ…
Used in fallback mode βœ…

This class is the core config contract Sayer uses internally β€” you can use it as a reference to build more advanced or environment-specific config systems.


πŸ“¦ How It Works

At runtime, Sayer looks for the environment variable:

SAYER_SETTINGS_MODULE=your_project.settings.Dev

It will:

  1. Import the specified module
  2. Access the specified class (e.g., Dev)
  3. Instantiate and expose it as settings anywhere you need

🧠 Anatomy of a Settings Module

# your_project/settings.py
from dataclasses import dataclass

@dataclass
class Base:
    debug = False
    retries = 3

@dataclass
class Dev(Base):
    debug = True
    retries = 10

πŸš€ Setting the Module

You must set the environment variable before launching the CLI:

export SAYER_SETTINGS_MODULE=your_project.settings.Dev
python app.py my-command

You can also set it inline:

SAYER_SETTINGS_MODULE=your_project.settings.Dev python app.py my-command

πŸ§ͺ Accessing Settings in Commands

from sayer.conf import settings

@command()
def show():
    print("Debug mode:", settings.debug)

No need to pass it explicitly β€” it’s global, and lazily loaded on first access.


🧰 Settings Best Practices

1. Split environments:

# settings.py
from dataclasses import dataclass

@dataclass
class Base:
    retries = 3

@dataclass
class Dev(Base):
    debug = True

@dataclass
class Prod(Base):
    debug = False
    retries = 1

Use different envs like:

SAYER_SETTINGS_MODULE=myapp.settings.Dev

2. Type Your Settings

Sayer doesn’t enforce typing but it’s recommended:

class Dev:
    debug: bool = True
    retries: int = 3

You can combine this with Pydantic, attrs, or msgspec for stricter validation if desired.


πŸ§ͺ Overriding Settings in Tests

Tests that rely on settings should override the environment variable or monkey-patch sayer.conf.settings.

Example:

import os
from sayer.conf import settings

def test_behavior(monkeypatch):
    monkeypatch.setenv("SAYER_SETTINGS_MODULE", "tests.fake_settings.Mocked")
    assert settings.debug is True

Or if settings is already imported:

settings.debug = True  # override directly for testing

🧠 Under the Hood

If SAYER_SETTINGS_MODULE is unset, it will use the internal by default or if invalid, Sayer will raise a helpful exception.


🧰 Recap

Feature Description
SAYER_SETTINGS_MODULE Points to your settings class
settings Auto-loaded global settings object
Lazy loading Only instantiated when accessed
Nested inheritance Use Base, Dev, Prod hierarchies
Test override Patch env var or mutate settings in test

βœ… Example Project Structure

myapp/
β”œβ”€β”€ settings.py
β”‚   β”œβ”€β”€ class Base
β”‚   β”œβ”€β”€ class Dev(Base)
β”‚   └── class Prod(Base)
β”œβ”€β”€ commands.py
└── main.py

Set it:

export SAYER_SETTINGS_MODULE=myapp.settings.Dev

Access it:

from sayer.conf import settings
print(settings.retries)

πŸ‘‰ Next: Commands