lang_tools.params.sample_params

Sample params - canonical reference implementation of the Params pattern.

This module is the authoritative example of how to write a Params class in this project. It pairs with SampleConfig in src/lang_tools/config/sample_config.py.

Config / Params split:

• Config (src/lang_tools/config/) defines only the shape of settings using Pydantic models. It never reads environment variables.
• Params (this file) loads actual values and constructs the config model via to_config().

Pattern rules:

1. __init__ accepts env_type: EnvType | None = None as its only argument beyond self. Pass it explicitly when you have it; it will be inferred from environment variables when None. Keeping the argument present - even when not yet needed - makes the API consistent and future-proof across all Params classes.

2. __init__ does nothing except store env_type and call _load_params(). Keep it as a one-liner delegation so the loading logic is easy to test in isolation.

3. _load_params() orchestrates loading in a fixed order:

a. _load_common_params() - attributes shared across all envs. b. Dispatch on env_type.stage (DEV / PROD) via match; each branch sets or overrides stage-specific attributes and then dispatches further on env_type.location (LOCAL / RENDER).

1. _load_common_params() writes values as Python literals, not os.getenv() calls. If a value is the same in every environment, write it once here. If it changes between environments, set it only in the relevant stage or location method - never duplicate it.

2. Secrets are the exception to the no-env-var rule: load them from environment variables using the module-level _load_secret() helper. It uses os.environ[VAR], which raises KeyError naturally when the variable is missing - no custom exception is needed. This surfaces broken configurations at startup rather than at the point of use.

3. to_config() constructs and returns the Pydantic config model.

4. __str__ produces a human-readable summary. Every secret field must be rendered as [REDACTED] - never call .get_secret_value() inside __str__.

See Also

SampleConfig - the paired config model in src/lang_tools/config/. docs/guides/params_config.md - full guide with rationale.

Classes:

• SampleParams –

  Sample params - reference implementation of the Params pattern.

SampleParams

SampleParams(env_type: EnvType | None = None)

Sample params - reference implementation of the Params pattern.

Loads actual runtime values for the given deployment environment and exposes a typed SampleConfig via to_config().

Non-secret values are written as Python literals inside the appropriate loading method - not read from environment variables. If a value differs between environments, write it only in the relevant stage or location method; do not repeat it across branches.

Secrets are the exception: they are loaded via _load_secret() in _load_common_params(), which means a missing secret is caught at startup.

Parameters:

• env_type (EnvType | None, default: None ) –

  Deployment environment (stage + location). If None, inferred from ENV_STAGE_TYPE and ENV_LOCATION_TYPE environment variables (defaults: dev / local).

Load sample params for the given environment.

Parameters:

• env_type (EnvType | None, default: None ) –

  Deployment environment (stage + location). If None, inferred from ENV_STAGE_TYPE and ENV_LOCATION_TYPE environment variables.

Methods:

• __repr__ –

  Return the string representation of the object.

• __str__ –

  Return a human-readable summary with secrets masked.

• to_config –

  Assemble and return the typed config model.

Source code in src/lang_tools/params/sample_params.py

def __init__(self, env_type: EnvType | None = None) -> None:
    """Load sample params for the given environment.

    Args:
        env_type: Deployment environment (stage + location).
            If ``None``, inferred from ``ENV_STAGE_TYPE`` and
            ``ENV_LOCATION_TYPE`` environment variables.
    """
    self.env_type: EnvType = env_type or EnvType.from_env_var()
    self._load_params()

__repr__

__repr__() -> str

Return the string representation of the object.

Source code in src/lang_tools/params/sample_params.py

def __repr__(self) -> str:
    """Return the string representation of the object."""
    return str(self)

__str__

__str__() -> str

Return a human-readable summary with secrets masked.

Source code in src/lang_tools/params/sample_params.py

def __str__(self) -> str:
    """Return a human-readable summary with secrets masked."""
    s = "SampleParams:"
    s += f"\n  env_type: {self.env_type}"
    s += f"\n  some_int: {self.some_int}"
    s += f"\n  nested_model_some_str: {self.nested_model_some_str}"
    s += "\n  secret_api_key: [REDACTED]"
    s += f"\n  custom_kwargs: {self.custom_kwargs}"
    return s

to_config

to_config() -> SampleConfig

Assemble and return the typed config model.

Returns:

• SampleConfig ( SampleConfig ) –

  A Pydantic model carrying all settings. The secret is preserved as SecretStr.

Source code in src/lang_tools/params/sample_params.py

def to_config(self) -> SampleConfig:
    """Assemble and return the typed config model.

    Returns:
        SampleConfig: A Pydantic model carrying all settings.
            The secret is preserved as ``SecretStr``.
    """
    return SampleConfig(
        some_int=self.some_int,
        nested_model=NestedModel(some_str=self.nested_model_some_str),
        secret_api_key=self.secret_api_key,
        kwargs=self.custom_kwargs,
    )