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 for template expansion and defaults. parse_env_template and all_available are lower-level template helpers.

API index

Name	Kind	Defined in
`get_var`	function	`params_proto.envvar`
`Field`	function	`params_proto.envvar`
`EnvVar`	singleton	`params_proto.envvar`
`parse_env_template`	function	`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`

functionparams_proto.envvar.get_varSource ↗

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`

functionparams_proto.envvar.FieldSource ↗

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 singletonparams_proto.envvar.EnvVarSource ↗

EnvVar = _EnvVar()

Environment variable reader that supports three syntaxes:

Matmul operator with env var name:
python
```
batch_size: int = EnvVar @ "BATCH_SIZE"
```

Matmul operator with pipe for default:

python

learning_rate: float = EnvVar @ "LR" | 0.001

Function call syntax:

python

db_url: str = EnvVar("DATABASE_URL", default="localhost")
data_dir: str = EnvVar("$DATA_DIR/models", default="/tmp/models")

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`

methodparams_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`

propertyparams_proto.envvar.EnvVar.templateSource ↗

EnvVar.template

Backward compatibility: return first template or None.

`EnvVar.matmul`

methodparams_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`

methodparams_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`

methodparams_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`

methodparams_proto.envvar.EnvVar.invalidate_cacheSource ↗

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 — params_proto.parse_env_template.parse_env_template

params_proto.parse_env_template

`parse_env_template`

functionparams_proto.parse_env_template.parse_env_templateSource ↗

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`

functionparams_proto.parse_env_template.all_availableSource ↗

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.