gc_batch.settings

Configuration settings for gc-batch.

This module centralizes every value that differs between deployments (project ids, VPC network settings, etc.) into a single :class:GCBatchSettings object with neutral defaults. A deployment adapts gc-batch entirely through configuration -- environment variables or a TOML file -- with no code changes.

Resolution precedence (highest priority first):

1. Explicit constructor arguments, e.g. GCBatchSettings(job_name_prefix="foo-").
2. GC_BATCH_* environment variables (nested fields use __ as a delimiter, e.g. GC_BATCH_JOB_PROFILES__MY_VPC__NETWORK).
3. A TOML configuration file, only consulted via :meth:GCBatchSettings.load.
4. The neutral defaults defined in this module.

Classes:

Name	Description
JobProfile	A named bundle of networking/VM settings for --job-profile.
GCBatchSettings	The top-level settings object.

GCBatchSettings

Bases: BaseSettings

Top-level configuration for gc-batch.

All fields have neutral defaults. Deployment-specific behavior is supplied through GC_BATCH_* environment variables or a TOML config file loaded via :meth:load.

Attributes:

Name	Type	Description
job_name_prefix	str	Prefix prepended to every created job's name.
created_using_label	str	Value of the "created-using" label set on every job.
owner_email_env_vars	list[str]	Environment variables checked, in order, to determine the "created-by" label value. The default list covers the All of Us Researcher Workbench, which does not set $USER but does set $OWNER_EMAIL (and the equivalent $WORKBENCH_USER_EMAIL / $TERRA_USER_EMAIL); without them every job there is labelled created-by=unknown, which makes list-my-jobs useless.
default_project_id	str | None	Fallback GCP project id when none is given on the command line or via $GOOGLE_PROJECT.
job_profiles	dict[str, JobProfile]	Named bundles of networking/VM settings selectable via --job-profile. Always includes the built-in all-of-us profile; user-supplied profiles are merged with (and may override) it.

Source code in src/gc_batch/settings.py

class GCBatchSettings(BaseSettings):
    """Top-level configuration for gc-batch.

    All fields have neutral defaults. Deployment-specific behavior is supplied
    through ``GC_BATCH_*`` environment variables or a TOML config file loaded via
    :meth:`load`.

    Attributes:
        job_name_prefix: Prefix prepended to every created job's name.
        created_using_label: Value of the "created-using" label set on every job.
        owner_email_env_vars: Environment variables checked, in order, to
            determine the "created-by" label value. The default list covers the
            All of Us Researcher Workbench, which does not set ``$USER`` but does
            set ``$OWNER_EMAIL`` (and the equivalent ``$WORKBENCH_USER_EMAIL`` /
            ``$TERRA_USER_EMAIL``); without them every job there is labelled
            ``created-by=unknown``, which makes ``list-my-jobs`` useless.
        default_project_id: Fallback GCP project id when none is given on the
            command line or via ``$GOOGLE_PROJECT``.
        job_profiles: Named bundles of networking/VM settings selectable via
            ``--job-profile``. Always includes the built-in ``all-of-us`` profile;
            user-supplied profiles are merged with (and may override) it.
    """

    model_config = SettingsConfigDict(
        env_prefix="GC_BATCH_",
        env_nested_delimiter="__",
        extra="ignore",
    )

    # Set by `load()` immediately before construction so `settings_customise_sources`
    # knows which config file (if any) to read. Not thread-safe: concurrent calls to
    # `load()` from different threads could race. This is acceptable for gc-batch's
    # CLI/script usage patterns; callers needing concurrency should pass `config_file`
    # explicitly and avoid overlapping `load()` calls.
    _config_file_override: ClassVar[Any] = _TOML_DISABLED

    job_name_prefix: str = ""
    created_using_label: str = "gc-batch"
    owner_email_env_vars: list[str] = Field(
        default_factory=lambda: [
            "OWNER_EMAIL",
            "WORKBENCH_USER_EMAIL",
            "TERRA_USER_EMAIL",
            "USER",
        ]
    )
    default_project_id: str | None = None
    job_profiles: dict[str, JobProfile] = Field(default_factory=dict)

    def __init__(self, **data: Any) -> None:
        """Initialize settings and merge in the built-in job profiles.

        Args:
            **data: Field overrides, following the standard pydantic-settings
                precedence (constructor arguments > environment variables >
                configured TOML source > defaults).
        """
        super().__init__(**data)
        self.job_profiles = {**_built_in_job_profiles(), **self.job_profiles}

    @classmethod
    def settings_customise_sources(
        cls,
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        """Insert a TOML file source between env vars and the default sources.

        Returns:
            The settings sources in priority order (highest first): constructor
            arguments, environment variables, the TOML file (if one was
            requested via :meth:`load`), then the standard dotenv/secrets
            sources that fall through to field defaults.
        """
        sources: tuple[PydanticBaseSettingsSource, ...] = (
            init_settings,
            env_settings,
        )
        if cls._config_file_override is not _TOML_DISABLED:
            config_file = _resolve_config_file(cls._config_file_override)
            sources += (TomlConfigSettingsSource(settings_cls, toml_file=config_file),)
        return sources + (dotenv_settings, file_secret_settings)

    @classmethod
    def load(cls, config_file: str | Path | None = None, **overrides: Any) -> "GCBatchSettings":
        """Load settings, including values from a TOML configuration file.

        Args:
            config_file: An explicit path to a TOML config file. When omitted,
                the standard discovery order is used: ``$GC_BATCH_CONFIG_FILE``,
                then ``./gc-batch.toml``, then ``$XDG_CONFIG_HOME/gc-batch/config.toml``
                (or ``~/.config/gc-batch/config.toml`` when ``$XDG_CONFIG_HOME`` is unset).
            **overrides: Explicit field overrides, which take precedence over
                everything else (environment variables, the TOML file, and defaults).

        Returns:
            A fully resolved ``GCBatchSettings`` instance.
        """
        cls._config_file_override = config_file
        try:
            return cls(**overrides)
        finally:
            cls._config_file_override = _TOML_DISABLED

created_using_label = 'gc-batch' class-attribute instance-attribute

default_project_id = None class-attribute instance-attribute

job_name_prefix = '' class-attribute instance-attribute

job_profiles = {None: _built_in_job_profiles(), None: self.job_profiles} class-attribute instance-attribute

model_config = SettingsConfigDict(env_prefix='GC_BATCH_', env_nested_delimiter='__', extra='ignore') class-attribute instance-attribute

owner_email_env_vars = Field(default_factory=(lambda: ['OWNER_EMAIL', 'WORKBENCH_USER_EMAIL', 'TERRA_USER_EMAIL', 'USER'])) class-attribute instance-attribute

__init__(**data)

Initialize settings and merge in the built-in job profiles.

Parameters:

Name	Type	Description	Default
**data	Any	Field overrides, following the standard pydantic-settings precedence (constructor arguments > environment variables > configured TOML source > defaults).	{}

Source code in src/gc_batch/settings.py

def __init__(self, **data: Any) -> None:
    """Initialize settings and merge in the built-in job profiles.

    Args:
        **data: Field overrides, following the standard pydantic-settings
            precedence (constructor arguments > environment variables >
            configured TOML source > defaults).
    """
    super().__init__(**data)
    self.job_profiles = {**_built_in_job_profiles(), **self.job_profiles}

load(config_file=None, **overrides) classmethod

Load settings, including values from a TOML configuration file.

Parameters:

Name	Type	Description	Default
config_file	str | Path | None	An explicit path to a TOML config file. When omitted, the standard discovery order is used: $GC_BATCH_CONFIG_FILE, then ./gc-batch.toml, then $XDG_CONFIG_HOME/gc-batch/config.toml (or ~/.config/gc-batch/config.toml when $XDG_CONFIG_HOME is unset).	None
**overrides	Any	Explicit field overrides, which take precedence over everything else (environment variables, the TOML file, and defaults).	{}

Returns:

Type	Description
GCBatchSettings	A fully resolved GCBatchSettings instance.

Source code in src/gc_batch/settings.py

@classmethod
def load(cls, config_file: str | Path | None = None, **overrides: Any) -> "GCBatchSettings":
    """Load settings, including values from a TOML configuration file.

    Args:
        config_file: An explicit path to a TOML config file. When omitted,
            the standard discovery order is used: ``$GC_BATCH_CONFIG_FILE``,
            then ``./gc-batch.toml``, then ``$XDG_CONFIG_HOME/gc-batch/config.toml``
            (or ``~/.config/gc-batch/config.toml`` when ``$XDG_CONFIG_HOME`` is unset).
        **overrides: Explicit field overrides, which take precedence over
            everything else (environment variables, the TOML file, and defaults).

    Returns:
        A fully resolved ``GCBatchSettings`` instance.
    """
    cls._config_file_override = config_file
    try:
        return cls(**overrides)
    finally:
        cls._config_file_override = _TOML_DISABLED

settings_customise_sources(settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings) classmethod

Insert a TOML file source between env vars and the default sources.

Returns:

Type	Description
PydanticBaseSettingsSource	The settings sources in priority order (highest first): constructor
...	arguments, environment variables, the TOML file (if one was
tuple[PydanticBaseSettingsSource, ...]	requested via :meth:load), then the standard dotenv/secrets
tuple[PydanticBaseSettingsSource, ...]	sources that fall through to field defaults.

Source code in src/gc_batch/settings.py

@classmethod
def settings_customise_sources(
    cls,
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    env_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
) -> tuple[PydanticBaseSettingsSource, ...]:
    """Insert a TOML file source between env vars and the default sources.

    Returns:
        The settings sources in priority order (highest first): constructor
        arguments, environment variables, the TOML file (if one was
        requested via :meth:`load`), then the standard dotenv/secrets
        sources that fall through to field defaults.
    """
    sources: tuple[PydanticBaseSettingsSource, ...] = (
        init_settings,
        env_settings,
    )
    if cls._config_file_override is not _TOML_DISABLED:
        config_file = _resolve_config_file(cls._config_file_override)
        sources += (TomlConfigSettingsSource(settings_cls, toml_file=config_file),)
    return sources + (dotenv_settings, file_secret_settings)

JobProfile

Bases: BaseModel

A named bundle of networking/VM settings applied via --job-profile.

Attributes:

Name	Type	Description
network	str | None	VPC network path for the VM (e.g. "global/networks/network").
subnetwork	str | None	Subnetwork path for the VM.
use_private_address	bool	Whether to use a private IP (no external IP).
regions	list[str] | None	List of allowed regions for job placement.
service_account_from_gcloud	bool	Whether to resolve the job's service account from the current gcloud authenticated account.
cloud_logging_unreadable	bool	Whether callers in this environment are expected to be unable to read Cloud Logging. When True, create warns if no --logs-bucket is given, because the job's logs would be written somewhere the user cannot read and the choice cannot be changed after the job is created.

Source code in src/gc_batch/settings.py

class JobProfile(BaseModel):
    """A named bundle of networking/VM settings applied via ``--job-profile``.

    Attributes:
        network: VPC network path for the VM (e.g. "global/networks/network").
        subnetwork: Subnetwork path for the VM.
        use_private_address: Whether to use a private IP (no external IP).
        regions: List of allowed regions for job placement.
        service_account_from_gcloud: Whether to resolve the job's service account
            from the current ``gcloud`` authenticated account.
        cloud_logging_unreadable: Whether callers in this environment are expected
            to be unable to read Cloud Logging. When ``True``, ``create`` warns if
            no ``--logs-bucket`` is given, because the job's logs would be written
            somewhere the user cannot read and the choice cannot be changed after
            the job is created.
    """

    network: str | None = None
    subnetwork: str | None = None
    use_private_address: bool = False
    regions: list[str] | None = None
    service_account_from_gcloud: bool = False
    cloud_logging_unreadable: bool = False

cloud_logging_unreadable = False class-attribute instance-attribute

network = None class-attribute instance-attribute

regions = None class-attribute instance-attribute

service_account_from_gcloud = False class-attribute instance-attribute

subnetwork = None class-attribute instance-attribute

use_private_address = False class-attribute instance-attribute