import "../autodoc.css" # Environment & fields Read typed environment values and define computed fields. `EnvVar` is a public callable singleton, not a class you need to import from an implementation module. ```python from params_proto import proto, EnvVar, Field @proto class Config: port: int = EnvVar @ "PORT" | 8080 ``` Environment values resolve lazily when accessed. See the [environment guide](/key_concepts/environment_variables) for template expansion and defaults. `parse_env_template` and `all_available` are lower-level template helpers. ## API index | Name | Kind | Defined in | | --- | --- | --- | | [`get_var`](/reference/environment#params_proto.envvar--get_var) | function | `params_proto.envvar` | | [`Field`](/reference/environment#params_proto.envvar--field) | function | `params_proto.envvar` | | [`EnvVar`](/reference/environment#params_proto.envvar--envvar) | singleton | `params_proto.envvar` | | [`parse_env_template`](/reference/environment#params_proto.parse_env_template--parse_env_template) | function | `params_proto.parse_env_template` | | [`all_available`](/reference/environment#params_proto.parse_env_template--all_available) | function | `params_proto.parse_env_template` | ## params_proto.envvar Environment variable support for params-proto. Provides EnvVar class for reading configuration from environment variables with automatic type conversion and template expansion. ### `get_var`

function params_proto.envvar.get_var Source ↗

get_var(default: Any = None, *, env: str = None)

Mark a field as an environment variable.

Parameters

Parameter	Type / default	Description
`default`	`Any` = None	Default value if env var not set
`env`	`str` = None	Environment variable name (defaults to field name)

### `Field`

function params_proto.envvar.Field Source ↗

Field(fn: Callable)

Decorator to mark a method as a computed field.

Parameters

Parameter	Type / default	Description
`fn`	`Callable` required	The method to decorate

Returns

The decorated method

### `EnvVar`

callable singleton params_proto.envvar.EnvVar Source ↗

EnvVar = _EnvVar()

Environment variable reader that supports three syntaxes: 1. Matmul operator with env var name: ```python batch_size: int = EnvVar @ "BATCH_SIZE" ``` 2. Matmul operator with pipe for default: ```python learning_rate: float = EnvVar @ "LR" | 0.001 ``` 3. Function call syntax: ```python db_url: str = EnvVar("DATABASE_URL", default="localhost") data_dir: str = EnvVar("$DATA_DIR/models", default="/tmp/models") ``` 4. OR operation with multiple env var names (tries each in order): ```python api_key: str = EnvVar @ "API_KEY" @ "SECRET_KEY" | "default" # Or function syntax: api_key: str = EnvVar("API_KEY", "SECRET_KEY", default="default") ``` The pipe operator (|) allows clean chaining of env var name with fallback value. Values are loaded lazily - environment variables are read at access time, not definition time.

Parameters

Parameter	Type / default	Description
`*templates`	`str` variadic	One or more environment variable names or template strings. When multiple are provided, they are checked in order (OR operation).
`default`	`Any` = None	Default value if no environment variable is set
`dtype`	`type` = None	Optional type to convert the value to (overrides annotation inference)

#### `EnvVar.__init__`

method params_proto.envvar.EnvVar.__init__ Source ↗

EnvVar.__init__(*templates: str, default: Any = None, dtype: type = None)

Create an environment variable reader.

Parameters

Parameter	Type / default	Description
`*templates`	`str` variadic	One or more environment variable names or template strings. When multiple are provided, they are checked in order (OR operation).
`default`	`Any` = None	Default value if no environment variable is set
`dtype`	`type` = None	Optional type to convert the value to (overrides annotation inference)

#### `EnvVar.template`

property params_proto.envvar.EnvVar.template Source ↗

EnvVar.template

Backward compatibility: return first template or None.

#### `EnvVar.__matmul__`

method params_proto.envvar.EnvVar.__matmul__ Source ↗

EnvVar.__matmul__(other: Any)

Support EnvVar @ "VAR_NAME" syntax, chainable for OR operation. **Examples** ```python EnvVar @ "VAR_NAME" # Single env var EnvVar @ "VAR1" @ "VAR2" # OR: try VAR1, then VAR2 EnvVar @ "VAR1" @ "VAR2" | default # With fallback ``` Note: The | operator has lower precedence than @, so `EnvVar @ "A" @ "B" | default` is parsed as `(EnvVar @ "A" @ "B") | default`.

Parameters

Parameter	Type / default	Description
`other`	`Any` required	Either an environment variable name (str) or a default value

Returns

New _EnvVar instance configured with the given parameter

#### `EnvVar.__or__`

method params_proto.envvar.EnvVar.__or__ Source ↗

EnvVar.__or__(other: Any)

Support chaining with | to specify default value. Syntax: EnvVar @ "VAR_NAME" | default_value Note: Using `or` instead of `|` will NOT work because `or` has lower precedence than @ and evaluates truthiness instead of calling __or__.

Parameters

Parameter	Type / default	Description
`other`	`Any` required	Default value to use if env var is not set

Returns

New _EnvVar instance with both template(s) and default

#### `EnvVar.__call__`

method params_proto.envvar.EnvVar.__call__ Source ↗

EnvVar.__call__(*templates: str, default: Any = None, dtype: type = None)

Support EnvVar("VAR_NAME", ..., default=...) function call syntax. **Examples** ```python EnvVar("DATABASE_URL", default="localhost") EnvVar("API_KEY", "SECRET_KEY", default="fallback") # OR operation EnvVar("PORT", dtype=int, default=8080) # With type conversion ```

Parameters

Parameter	Type / default	Description
`*templates`	`str` variadic	One or more environment variable names or template strings
`default`	`Any` = None	Default value if no environment variable is set
`dtype`	`type` = None	Optional type to convert the value to

Returns

New _EnvVar instance configured with the given parameters

#### `EnvVar.invalidate_cache`

method params_proto.envvar.EnvVar.invalidate_cache Source ↗

EnvVar.invalidate_cache()

Clear the cached value, forcing re-read from environment on next access.

### Public imports These symbols are available from this module. Their definitions are documented in the linked modules. - [`parse_env_template`](/reference/environment#params_proto.parse_env_template--parse_env_template) — `params_proto.parse_env_template.parse_env_template` ## params_proto.parse_env_template ### `parse_env_template`

function params_proto.parse_env_template.parse_env_template Source ↗

parse_env_template(template: str) → List[str]

Extract and return the environment variable names from a given string template.

Parameters

Parameter	Type / default	Description
`template`	`str` required	A string template that potentially contains environment variables in the format $VAR_NAME, ${VAR_NAME}, or similar.

Returns

List[str] — A list of environment variable names found in the template.

### `all_available`

function params_proto.parse_env_template.all_available Source ↗

all_available(template: str, strict = True) → bool

Check if all environment variables in the template are available in the current environment.

Parameters

Parameter	Type / default	Description
`template`	`str` required	A string template that potentially contains environment variables in the format $VAR_NAME, ${VAR_NAME}, or similar.
`strict`	`—` = True	If True, treat empty environment variables as undefined. Otherwise, treat them as defined.

Returns

bool — True if all environment variables are available, False otherwise.