0
# Configuration
1

2
Comprehensive configuration system for customizing dateparser's parsing behavior including date order preferences, timezone handling, language detection settings, and parsing strategies.
3

4
## Capabilities
5

6
### Settings Class
7

8
Main configuration class that controls all aspects of date parsing behavior with extensive customization options.
9

10
```python { .api }
11
class Settings:
12
    """
13
    Control and configure default parsing behavior of dateparser.
14
    
15
    Currently supported settings:
16
    - DATE_ORDER: Order preference for ambiguous dates ('MDY', 'DMY', 'YMD')
17
    - PREFER_LOCALE_DATE_ORDER: Use locale-specific date order
18
    - TIMEZONE: Default timezone for parsing
19
    - TO_TIMEZONE: Convert parsed dates to this timezone
20
    - RETURN_AS_TIMEZONE_AWARE: Return timezone-aware datetime objects
21
    - PREFER_MONTH_OF_YEAR: Prefer specific months ('current', 'last', 'next')
22
    - PREFER_DAY_OF_MONTH: Prefer specific days ('first', 'last', 'current')
23
    - PREFER_DATES_FROM: Prefer past or future dates ('past', 'future')
24
    - RELATIVE_BASE: Base date for relative date parsing
25
    - STRICT_PARSING: Enable strict parsing mode
26
    - REQUIRE_PARTS: Require specific date parts (['day', 'month', 'year'])
27
    - SKIP_TOKENS: Tokens to skip during parsing
28
    - NORMALIZE: Enable text normalization
29
    - RETURN_TIME_AS_PERIOD: Return time ranges as periods
30
    - PARSERS: List of parsers to use
31
    - DEFAULT_LANGUAGES: Default languages for detection
32
    - LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD: Confidence threshold for language detection
33
    - CACHE_SIZE_LIMIT: Maximum cache size for parsed results
34
    """
35
    
36
    def __init__(self, settings=None):
37
        """
38
        Initialize Settings with custom configuration.
39
        
40
        Parameters:
41
        - settings (dict, optional): Dictionary of setting key-value pairs
42
        """
43
    
44
    def replace(self, mod_settings=None, **kwds):
45
        """
46
        Create new Settings instance with modified values.
47
        
48
        Parameters:
49
        - mod_settings (dict, optional): Modified settings dictionary
50
        - **kwds: Individual setting key-value pairs
51
        
52
        Returns:
53
        Settings: New Settings instance with updated values
54
        
55
        Raises:
56
        TypeError: Invalid setting value type
57
        """
58
```
59

60
**Usage Examples:**
61

62
```python
63
from dateparser.conf import Settings
64
import dateparser
65
from datetime import datetime
66

67
# Basic settings configuration
68
settings = Settings({
69
    'PREFER_DATES_FROM': 'future',
70
    'TIMEZONE': 'UTC',
71
    'STRICT_PARSING': True
72
})
73

74
date = dateparser.parse('tomorrow', settings=settings)
75

76
# Date order preferences
77
settings = Settings({'DATE_ORDER': 'DMY'})
78
date = dateparser.parse('15/01/2023', settings=settings)  # January 15, 2023
79

80
settings = Settings({'DATE_ORDER': 'MDY'})  
81
date = dateparser.parse('01/15/2023', settings=settings)  # January 15, 2023
82

83
# Timezone handling
84
settings = Settings({
85
    'TIMEZONE': 'America/New_York',
86
    'TO_TIMEZONE': 'UTC',
87
    'RETURN_AS_TIMEZONE_AWARE': True
88
})
89
date = dateparser.parse('2023-01-15 15:30', settings=settings)
90

91
# Language preferences
92
settings = Settings({
93
    'DEFAULT_LANGUAGES': ['es', 'en', 'fr'],
94
    'LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD': 0.7
95
})
96
date = dateparser.parse('15 de enero', settings=settings)
97

98
# Strict parsing with required parts
99
settings = Settings({
100
    'STRICT_PARSING': True,
101
    'REQUIRE_PARTS': ['day', 'month', 'year']
102
})
103
date = dateparser.parse('January 2023', settings=settings)  # Returns None
104

105
# Relative date base
106
base_date = datetime(2023, 6, 15)
107
settings = Settings({'RELATIVE_BASE': base_date})
108
date = dateparser.parse('next week', settings=settings)
109

110
# Parser selection
111
settings = Settings({
112
    'PARSERS': ['timestamp', 'absolute-time', 'relative-time']
113
})
114
date = dateparser.parse('1674123456', settings=settings)
115

116
# Text normalization and token skipping
117
settings = Settings({
118
    'NORMALIZE': True,
119
    'SKIP_TOKENS': ['on', 'at', 'the']
120
})
121
date = dateparser.parse('on the 15th of January', settings=settings)
122
```
123

124
### Settings Validation
125

126
Error handling and validation for settings configuration to ensure proper setup and helpful error messages.
127

128
```python { .api }
129
class SettingValidationError(ValueError):
130
    """
131
    Exception raised when a provided setting is not valid.
132
    
133
    Inherits from ValueError and provides detailed error messages
134
    about which setting is invalid and why.
135
    """
136

137
class UnknownTokenError(Exception):
138
    """
139
    Exception raised when an unknown token is encountered during parsing.
140
    
141
    This exception is raised when the parser encounters a token that
142
    cannot be recognized or processed by the language dictionary system.
143
    """
144

145
def check_settings(settings):
146
    """
147
    Validate settings dictionary for correctness.
148
    
149
    Parameters:
150
    - settings (Settings): Settings instance to validate
151
    
152
    Raises:
153
    SettingValidationError: When settings contain invalid values
154
    """
155
```
156

157
**Usage Examples:**
158

159
```python
160
from dateparser.conf import Settings, SettingValidationError, check_settings
161

162
# Handling validation errors
163
try:
164
    settings = Settings({
165
        'DATE_ORDER': 'INVALID',  # Invalid date order
166
        'PARSERS': ['unknown-parser'],  # Unknown parser
167
        'REQUIRE_PARTS': ['invalid-part']  # Invalid required part
168
    })
169
except SettingValidationError as e:
170
    print(f"Settings validation failed: {e}")
171

172
# Manual settings validation
173
settings = Settings({'PREFER_DATES_FROM': 'future'})
174
try:
175
    check_settings(settings)
176
    print("Settings are valid")
177
except SettingValidationError as e:
178
    print(f"Invalid settings: {e}")
179

180
# Valid settings examples
181
valid_settings = Settings({
182
    'DATE_ORDER': 'DMY',  # Valid: 'MDY', 'DMY', 'YMD'
183
    'PARSERS': ['timestamp', 'absolute-time', 'relative-time'],  # Valid parsers
184
    'REQUIRE_PARTS': ['day', 'month'],  # Valid parts: 'day', 'month', 'year'
185
    'PREFER_DATES_FROM': 'past',  # Valid: 'past', 'future'
186
    'LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD': 0.8  # Valid: 0.0-1.0
187
})
188
```
189

190
### Settings Decorators
191

192
Decorator functions for applying settings to parsing functions and managing configuration context.
193

194
```python { .api }
195
def apply_settings(f):
196
    """
197
    Decorator that applies settings to parsing functions.
198
    
199
    Automatically handles settings parameter processing and validation,
200
    ensuring proper Settings instance is passed to wrapped functions.
201
    
202
    Parameters:
203
    - f (function): Function to wrap with settings application
204
    
205
    Returns:
206
    function: Wrapped function with settings handling
207
    """
208
```
209

210
**Usage Examples:**
211

212
```python
213
from dateparser.conf import apply_settings, Settings
214

215
# Using apply_settings decorator for custom parsing functions
216
@apply_settings
217
def custom_parse_function(date_string, settings=None):
218
    # settings is automatically processed and validated
219
    # Use settings.TIMEZONE, settings.DATE_ORDER, etc.
220
    print(f"Parsing with timezone: {settings.TIMEZONE}")
221
    print(f"Date order preference: {settings.DATE_ORDER}")
222
    return None
223

224
# Call with dict settings (automatically converted to Settings)
225
custom_parse_function("2023-01-15", settings={'TIMEZONE': 'UTC'})
226

227
# Call with Settings instance
228
settings = Settings({'DATE_ORDER': 'DMY'})
229
custom_parse_function("15/01/2023", settings=settings)
230

231
# Call with no settings (uses defaults)
232
custom_parse_function("January 15, 2023")
233
```
234

235
## Available Settings Reference
236

237
### Date Order and Preferences
238

239
```python { .api }
240
# Date order for ambiguous dates
241
DATE_ORDER: str  # 'MDY', 'DMY', 'YMD'
242
PREFER_LOCALE_DATE_ORDER: bool  # Use locale-specific order
243

244
# Date preference when ambiguous
245
PREFER_DATES_FROM: str  # 'past', 'future'  
246
PREFER_MONTH_OF_YEAR: str  # 'current', 'last', 'next'
247
PREFER_DAY_OF_MONTH: str  # 'first', 'last', 'current'
248
```
249

250
### Timezone Configuration
251

252
```python { .api }
253
TIMEZONE: str  # Default timezone (e.g., 'UTC', 'America/New_York')
254
TO_TIMEZONE: str  # Convert results to this timezone
255
RETURN_AS_TIMEZONE_AWARE: bool  # Return timezone-aware datetimes
256
```
257

258
### Parsing Behavior
259

260
```python { .api }
261
STRICT_PARSING: bool  # Enable strict parsing mode
262
REQUIRE_PARTS: list  # Required date parts: ['day', 'month', 'year']
263
NORMALIZE: bool  # Enable text normalization
264
RETURN_TIME_AS_PERIOD: bool  # Return time ranges as periods
265
RELATIVE_BASE: datetime  # Base date for relative parsing
266
```
267

268
### Language and Detection
269

270
```python { .api }
271
DEFAULT_LANGUAGES: list  # Default language codes for detection
272
LANGUAGE_DETECTION_CONFIDENCE_THRESHOLD: float  # 0.0-1.0 threshold
273
```
274

275
### Parser Configuration
276

277
```python { .api }
278
PARSERS: list  # Available: ['timestamp', 'relative-time', 'custom-formats', 
279
              #           'absolute-time', 'no-spaces-time', 'negative-timestamp']
280
SKIP_TOKENS: list  # Tokens to skip during parsing
281
CACHE_SIZE_LIMIT: int  # Maximum cache size for results
282
```