Environment Variables
Commandline arguments are great and that, but remember the last time
when you wanted to use environment variables? Here we provide the EnvVar
class to help you define default values via environment flags.
params-proto' EnvVar automatically handles type conversion and template expansion.
Enjoy!
Quick Start
Usage:
Usage Patterns
1. Matmul Operator (@)
The cleanest syntax uses the @ operator:
CLI usage:
2. Function Call Syntax
Use function call syntax for explicit keyword arguments:
CLI usage:
3. Pipe Operator for Defaults
The pipe operator (|) provides a clean syntax for fallback values:
Behavior:
- If environment variable exists: uses its value (with type conversion)
- If environment variable missing: uses the fallback value
Template Expansion
EnvVar supports template strings with environment variable substitution.
Basic Template Syntax
Two syntaxes are supported:
Example:
Multiple Variables in Templates
Combine multiple environment variables in a single template:
Example:
Missing Variables in Templates
When a variable in a template is not set, it's replaced with an empty string:
Example:
Type Conversion
EnvVar automatically converts string values from environment variables to the annotated type:
Example:
Boolean conversion rules:
"true","True","1","yes"→True"false","False","0","no",""→False
Override Precedence
Environment variables are resolved during decoration and follow the params-proto override hierarchy:
- CLI arguments (highest priority)
proto.bind()context- Direct assignment (
train.lr = 0.01) - Environment variables ← EnvVar resolution
- Default values (lowest priority)
Common Patterns
Pattern 1: Configuration from Environment
Production deployments often use environment variables for secrets and configuration:
Pattern 2: Path Configuration
Use templates for flexible path configuration:
Pattern 3: Development vs Production
Use environment variables to switch between development and production configurations:
Development:
Production:
Pattern 4: Container Orchestration
Kubernetes and Docker Compose often inject configuration via environment variables:
Pattern 5: Inheritance with EnvVar
EnvVar fields work correctly with class inheritance. Inherited fields are resolved and type-converted:
Both inherited and child EnvVar fields:
- Resolve from environment variables at decoration time
- Convert to the annotated type (
str,int,bool,float) - Use fallback defaults when the env var is not set
Usage:
Security Considerations
1. Never Log Secrets
Be careful not to log environment variables that contain secrets:
2. Require Secrets in Production
Use assertions to ensure required secrets are set:
3. Validate Environment Variables
Add validation for critical configuration:
Testing with Environment Variables
When testing code that uses EnvVar, manage environment variables in test fixtures:
Better approach with pytest fixtures:
Related
- Core Concepts - Decorators and basic usage
- CLI Fundamentals - Basic CLI features
- Configuration Patterns - Function vs class configurations
- Type System - Type conversion rules
- Parameter Overrides - Override precedence and context managers