0
# Validators
1

2
Python Data Validation for Humans™ - a comprehensive validation library providing 58+ validation functions for various data types without requiring schema definitions or form definitions. Simply call a function to validate data with immediate True/False results or detailed error information.
3

4
## Package Information
5

6
- **Package Name**: validators
7
- **Language**: Python
8
- **Installation**: `pip install validators`
9
- **Optional Dependencies**: `pip install validators[crypto-eth-addresses]` for advanced Ethereum validation
10

11
## Core Imports
12

13
Standard import pattern for validators:
14

15
```python
16
import validators
17
```
18

19
Direct function imports:
20

21
```python
22
from validators import email, url, ipv4, ValidationError
23
```
24

25
## Basic Usage
26

27
```python
28
import validators
29

30
# Basic validation - returns True or ValidationError
31
result = validators.email('user@example.com')
32
print(result)  # True
33

34
# Invalid input returns ValidationError (which evaluates to False)
35
result = validators.email('invalid-email')
36
print(bool(result))  # False
37
print(result)  # ValidationError(func=email, args={'value': 'invalid-email'})
38

39
# Force exceptions instead of ValidationError objects  
40
try:
41
    validators.url('not-a-url', r_ve=True)  # r_ve = raise ValidationError
42
except validators.ValidationError as e:
43
    print(f"Validation failed: {e}")
44

45
# Alternative: Set environment variable for global exception mode
46
import os
47
os.environ['RAISE_VALIDATION_ERROR'] = 'True'
48
try:
49
    validators.email('invalid-email')  # Now raises instead of returning ValidationError
50
except validators.ValidationError as e:
51
    print(f"Global exception mode: {e}")
52

53
# Multiple validations
54
data = {
55
    'email': 'user@example.com',
56
    'website': 'https://example.com',
57
    'uuid': '550e8400-e29b-41d4-a716-446655440000'
58
}
59

60
for field, value in data.items():
61
    if field == 'email' and validators.email(value):
62
        print(f"✓ Valid {field}")
63
    elif field == 'website' and validators.url(value):
64
        print(f"✓ Valid {field}")
65
    elif field == 'uuid' and validators.uuid(value):
66
        print(f"✓ Valid {field}")
67
```
68

69
## Architecture
70

71
The validators package follows a consistent design pattern:
72

73
- **Decorator Pattern**: All validators use the `@validator` decorator that standardizes return behavior
74
- **ValidationError Class**: Unified error handling with function name and argument details
75
- **Return Convention**: Functions return `True` for valid input or `ValidationError` for invalid input
76
- **Boolean Context**: `ValidationError` evaluates to `False` in boolean contexts
77
- **Exception Mode**: All validators accept an implicit `r_ve=True` parameter to raise `ValidationError` exceptions instead of returning them
78
- **Global Exception Mode**: Set `RAISE_VALIDATION_ERROR=True` environment variable to enable exception raising globally
79

80
This architecture enables simple, predictable validation across all data types while providing detailed error information when needed.
81

82
## Capabilities
83

84
### Basic Data Validation
85

86
Core validators for common data types including ranges, lengths, formats, and identifiers.
87

88
```python { .api }
89
def between(value, *, min_val=None, max_val=None): ...
90
def length(value: str, *, min_val=None, max_val=None): ...  
91
def uuid(value: Union[str, UUID]): ...
92
def slug(value: str): ...
93
```
94

95
[Basic Data Validation](./basic-validation.md)
96

97
### Network and Web Validation
98

99
Validators for internet-related data including domains, emails, URLs, hostnames, and IP addresses.
100

101
```python { .api }
102
def domain(value: str, *, consider_tld=False, rfc_1034=False, rfc_2782=False): ...
103
def email(value: str, *, ipv6_address=False, ipv4_address=False, simple_host=False, rfc_1034=False, rfc_2782=False): ...
104
def url(value: str, *, skip_ipv6_addr=False, skip_ipv4_addr=False, may_have_port=True, simple_host=False, strict_query=True, consider_tld=False, private=None, rfc_1034=False, rfc_2782=False): ...
105
def hostname(value: str, **kwargs): ...
106
def ipv4(value: str, *, cidr=True, strict=False, private=None, host_bit=True): ...
107
def ipv6(value: str, *, cidr=True, strict=False, host_bit=True): ...
108
def mac_address(value: str): ...
109
```
110

111
[Network and Web Validation](./network-validation.md)
112

113
### Financial Validation
114

115
Validators for financial instruments including credit cards, banking codes, and securities identifiers.
116

117
```python { .api }
118
def card_number(value: str): ...
119
def visa(value: str): ...
120
def mastercard(value: str): ...
121
def amex(value: str): ...
122
def unionpay(value: str): ...
123
def diners(value: str): ...
124
def jcb(value: str): ...
125
def discover(value: str): ...
126
def mir(value: str): ...
127
def iban(value: str): ...
128
def cusip(value: str): ...
129
def isin(value: str): ...
130
def sedol(value: str): ...
131
```
132

133
[Financial Validation](./financial-validation.md)
134

135
### Encoding and Hash Validation
136

137
Validators for various encoding formats and cryptographic hash functions.
138

139
```python { .api }
140
def base16(value: str): ...
141
def base32(value: str): ...
142
def base58(value: str): ...
143
def base64(value: str): ...
144
def md5(value: str): ...
145
def sha1(value: str): ...
146
def sha224(value: str): ...
147
def sha256(value: str): ...
148
def sha384(value: str): ...
149
def sha512(value: str): ...
150
```
151

152
[Encoding and Hash Validation](./encoding-validation.md)
153

154
### Cryptocurrency Address Validation
155

156
Validators for blockchain addresses across major cryptocurrency networks.
157

158
```python { .api }
159
def btc_address(value: str): ...
160
def eth_address(value: str): ...
161
def bsc_address(value: str): ...
162
def trx_address(value: str): ...
163
```
164

165
[Cryptocurrency Validation](./crypto-validation.md)
166

167
### Country and Regional Validation
168

169
Validators for country-specific identifiers, codes, and formats.
170

171
```python { .api }
172
def country_code(value: str, *, iso_format="auto", ignore_case=False): ...
173
def calling_code(value: str): ...
174
def currency(value: str, *, skip_symbols=True, ignore_case=False): ...
175
```
176

177
[Country and Regional Validation](./country-validation.md)
178

179
### Internationalization Validation
180

181
Validators for country-specific personal and business identifiers.
182

183
```python { .api }
184
def es_cif(value: str): ...
185
def es_nif(value: str): ...
186
def es_nie(value: str): ...
187
def es_doi(value: str): ...
188
def fi_business_id(value: str): ...
189
def fi_ssn(value: str, *, allow_temporal_ssn=True): ...
190
def fr_department(value: Union[str, int]): ...
191
def fr_ssn(value: str): ...
192
def ind_aadhar(value: str): ...
193
def ind_pan(value: str): ...
194
def ru_inn(value: str): ...
195
```
196

197
[Internationalization Validation](./i18n-validation.md)
198

199
### System and Time Validation
200

201
Validators for system-related formats and time expressions.
202

203
```python { .api }
204
def cron(value: str): ...
205
```
206

207
[System Validation](./system-validation.md)
208

209
## Core Types
210

211
```python { .api }
212
class ValidationError(Exception):
213
    """Exception class for validation failures."""
214
    
215
    def __init__(self, function: Callable[..., Any], arg_dict: Dict[str, Any], message: str = ""):
216
        """Initialize validation failure with function and arguments."""
217
    
218
    def __bool__(self) -> bool:
219
        """Always returns False in boolean context."""
220
        return False
221

222
def validator(func: Callable[..., Any]) -> Callable[..., Union[ValidationError, Literal[True]]]:
223
    """
224
    Decorator that makes a function return ValidationError on False, True on success.
225
    
226
    The decorated function will:
227
    - Return Literal[True] for valid inputs
228
    - Return ValidationError for invalid inputs (evaluates to False in boolean context)
229
    - Raise ValidationError if r_ve=True parameter is passed or RAISE_VALIDATION_ERROR env var is set
230
    
231
    All decorated functions implicitly accept an r_ve parameter:
232
    - r_ve=True: Raise ValidationError instead of returning it
233
    - r_ve=False (default): Return ValidationError object
234
    """
235
```