0
# Core Environment Parsing
1

2
Basic type parsing functionality that forms the foundation of environs' environment variable handling. These parsers handle the most common data types with automatic type conversion, optional default values, and validation support.
3

4
## Core Imports
5

6
```python
7
from environs import Env, env
8
from environs import validate, ValidationError, EnvError, EnvValidationError
9
```
10

11
## Capabilities
12

13
### Raw Value Parsing
14

15
Parses environment variables as raw strings without type conversion, providing the foundation for all other parsing methods.
16

17
```python { .api }
18
def __call__(self, name: str, default=..., subcast=None, *, validate=None, **kwargs):
19
    """
20
    Parse environment variable as raw value.
21
    
22
    Parameters:
23
    - name: str, environment variable name
24
    - default: any, default value if variable not set (optional)
25
    - subcast: type or callable for type conversion (optional)
26
    - validate: callable or list of callables for validation (optional)
27
    - **kwargs: additional marshmallow field arguments
28
    
29
    Returns:
30
    Raw value from environment or default
31
    """
32
```
33

34
### String Parsing
35

36
Explicitly parse environment variables as strings with validation and processing options.
37

38
```python { .api }
39
def str(self, name: str, default=..., *, validate=None, **kwargs):
40
    """
41
    Parse environment variable as string.
42
    
43
    Parameters:
44
    - name: str, environment variable name  
45
    - default: str, default value if variable not set (optional)
46
    - validate: callable or list of callables for validation (optional)
47
    - **kwargs: additional marshmallow field arguments
48
    
49
    Returns:
50
    str: String value from environment or default
51
    """
52
```
53

54
### Integer Parsing
55

56
Parse environment variables as integers with validation for numeric format and range constraints.
57

58
```python { .api }
59
def int(self, name: str, default=..., *, validate=None, **kwargs):
60
    """
61
    Parse environment variable as integer.
62
    
63
    Parameters:
64
    - name: str, environment variable name
65
    - default: int, default value if variable not set (optional)  
66
    - validate: callable or list of callables for validation (optional)
67
    - **kwargs: additional marshmallow field arguments
68
    
69
    Returns:
70
    int: Integer value from environment or default
71
    
72
    Raises:
73
    EnvValidationError: If value cannot be converted to integer
74
    """
75
```
76

77
Usage example:
78

79
```python
80
import os
81
from environs import env
82

83
os.environ["PORT"] = "8080"
84
os.environ["MAX_WORKERS"] = "4"
85

86
port = env.int("PORT")  # => 8080
87
max_workers = env.int("MAX_WORKERS", 1)  # => 4
88
default_timeout = env.int("TIMEOUT", 30)  # => 30 (default)
89
```
90

91
### Boolean Parsing
92

93
Parse environment variables as booleans with support for common boolean representations.
94

95
```python { .api }
96
def bool(self, name: str, default=..., *, validate=None, **kwargs):
97
    """
98
    Parse environment variable as boolean.
99
    
100
    Parameters:
101
    - name: str, environment variable name
102
    - default: bool, default value if variable not set (optional)
103
    - validate: callable or list of callables for validation (optional)
104
    - **kwargs: additional marshmallow field arguments
105
    
106
    Returns:
107
    bool: Boolean value from environment or default
108
    
109
    Notes:
110
    Truthy values: 'true', 'True', 'TRUE', '1', 'yes', 'Yes', 'YES', 'on', 'On', 'ON'
111
    Falsy values: 'false', 'False', 'FALSE', '0', 'no', 'No', 'NO', 'off', 'Off', 'OFF', ''
112
    """
113
```
114

115
Usage example:
116

117
```python
118
import os
119
from environs import env
120

121
os.environ["DEBUG"] = "true"
122
os.environ["ENABLE_CACHE"] = "false"
123

124
debug = env.bool("DEBUG")  # => True
125
enable_cache = env.bool("ENABLE_CACHE")  # => False
126
enable_logging = env.bool("ENABLE_LOGGING", True)  # => True (default)
127
```
128

129
### Float Parsing
130

131
Parse environment variables as floating-point numbers with precision handling.
132

133
```python { .api }
134
def float(self, name: str, default=..., *, validate=None, **kwargs):
135
    """
136
    Parse environment variable as float.
137
    
138
    Parameters:
139
    - name: str, environment variable name
140
    - default: float, default value if variable not set (optional)
141
    - validate: callable or list of callables for validation (optional)
142
    - **kwargs: additional marshmallow field arguments
143
    
144
    Returns:
145
    float: Float value from environment or default
146
    
147
    Raises:
148
    EnvValidationError: If value cannot be converted to float
149
    """
150
```
151

152
### Decimal Parsing
153

154
Parse environment variables as high-precision decimal numbers using Python's decimal module.
155

156
```python { .api }
157
def decimal(self, name: str, default=..., *, validate=None, **kwargs):
158
    """
159
    Parse environment variable as Decimal.
160
    
161
    Parameters:
162
    - name: str, environment variable name
163
    - default: Decimal, default value if variable not set (optional)
164
    - validate: callable or list of callables for validation (optional)
165
    - **kwargs: additional marshmallow field arguments
166
    
167
    Returns:
168
    decimal.Decimal: High-precision decimal value from environment or default
169
    
170
    Raises:
171
    EnvValidationError: If value cannot be converted to Decimal
172
    """
173
```
174

175
Usage example:
176

177
```python
178
import os
179
from environs import env
180
from decimal import Decimal
181

182
os.environ["PRICE"] = "19.99"
183
os.environ["PI"] = "3.141592653589793238462643383279"
184

185
price = env.decimal("PRICE")  # => Decimal('19.99')
186
pi = env.decimal("PI")        # => Decimal('3.141592653589793238462643383279')
187
default_rate = env.decimal("TAX_RATE", Decimal("0.08"))  # => Decimal('0.08') (default)
188
```
189

190
## Error Handling
191

192
All parsing methods can raise validation errors when environment variables cannot be converted to the expected type:
193

194
```python
195
from environs import env, EnvValidationError
196
import os
197

198
os.environ["INVALID_NUMBER"] = "not_a_number"
199

200
try:
201
    value = env.int("INVALID_NUMBER")
202
except EnvValidationError as e:
203
    print(f"Validation failed: {e}")
204
    print(f"Error details: {e.error_messages}")
205
```
206

207
## Common Parameters
208

209
All core parsing methods support these common parameters:
210

211
- **name**: Environment variable name to parse
212
- **default**: Default value if variable not set (use `...` for required variables)
213
- **validate**: Single validator or list of validators (from `environs.validate`)
214
- **kwargs**: Additional marshmallow field arguments for advanced configuration
215

216
## Types
217

218
```python { .api }
219
from decimal import Decimal
220
from typing import Any, Callable, Union
221

222
Subcast = Union[type, Callable[[Any], Any]]
223
ValidationFunction = Callable[[Any], Any]
224
```