0
# Network and Web Validation
1

2
Validators for internet-related data including domains, email addresses, URLs, hostnames, IP addresses, and network hardware identifiers. These validators support various RFC standards and provide extensive configuration options.
3

4
## Capabilities
5

6
### Domain Name Validation
7

8
Validates domain names with support for TLD checking and various RFC standards.
9

10
```python { .api }
11
def domain(value: str, /, *, consider_tld: bool = False, rfc_1034: bool = False, rfc_2782: bool = False) -> Union[Literal[True], ValidationError]:
12
    """
13
    Validate domain names.
14
    
15
    Parameters:
16
    - value: Domain name string to validate
17
    - consider_tld: Restrict to IANA-approved top-level domains
18
    - rfc_1034: Allow trailing dot in domain name (RFC 1034)
19
    - rfc_2782: Domain name is service record type (RFC 2782)
20
    
21
    Returns:
22
    True if valid domain, ValidationError otherwise
23
    """
24
```
25

26
### Email Address Validation
27

28
Comprehensive email validation supporting IPv4/IPv6 addresses and various hostname formats.
29

30
```python { .api }
31
def email(value: str, /, *, ipv6_address: bool = False, ipv4_address: bool = False, simple_host: bool = False, rfc_1034: bool = False, rfc_2782: bool = False) -> Union[Literal[True], ValidationError]:
32
    """
33
    Validate email addresses per RFC standards.
34
    
35
    Parameters:
36
    - value: Email address string to validate
37
    - ipv6_address: Allow IPv6 addresses in domain part
38
    - ipv4_address: Allow IPv4 addresses in domain part  
39
    - simple_host: Allow simple hostnames (no dots)
40
    - rfc_1034: Allow trailing dot in domain (RFC 1034)
41
    - rfc_2782: Domain is service record type (RFC 2782)
42
    
43
    Returns:
44
    True if valid email, ValidationError otherwise
45
    
46
    Supports extended Latin characters in local part.
47
    Validates both domain names and IP addresses in domain part.
48
    """
49
```
50

51
### URL Validation
52

53
Full URL validation with scheme checking, authentication, and query parameter validation.
54

55
```python { .api }
56
def url(value: str, /, *, skip_ipv6_addr: bool = False, skip_ipv4_addr: bool = False, may_have_port: bool = True, simple_host: bool = False, strict_query: bool = True, consider_tld: bool = False, private: Optional[bool] = None, rfc_1034: bool = False, rfc_2782: bool = False, validate_scheme: Callable[[str], bool] = _validate_scheme) -> Union[Literal[True], ValidationError]:
57
    """
58
    Validate URLs with comprehensive scheme and component checking.
59
    
60
    Parameters:
61
    - value: URL string to validate
62
    - skip_ipv6_addr: Reject IPv6 addresses in hostname
63
    - skip_ipv4_addr: Reject IPv4 addresses in hostname
64
    - may_have_port: Allow port numbers in hostname
65
    - simple_host: Allow simple hostnames without dots
66
    - strict_query: Strict query string parsing
67
    - consider_tld: Restrict to IANA TLDs
68
    - private: Require private/public IP addresses (IPv4/IPv6 only)
69
    - rfc_1034: Allow trailing dots (RFC 1034)
70
    - rfc_2782: Service record hostnames (RFC 2782)
71
    - validate_scheme: Custom scheme validation function
72
    
73
    Returns:
74
    True if valid URL, ValidationError otherwise
75
    
76
    Supported schemes: http, https, ftp, ftps, ssh, sftp, git, irc, rtmp, rtmps, rtsp, telnet
77
    Validates authentication segments, paths, query parameters, and fragments.
78
    """
79
```
80

81
### Hostname Validation
82

83
Validates hostnames including IPv4/IPv6 addresses, ports, and various hostname formats.
84

85
```python { .api }
86
def hostname(value: str, /, *, skip_ipv6_addr: bool = False, skip_ipv4_addr: bool = False, may_have_port: bool = True, maybe_simple: bool = True, consider_tld: bool = False, private: Optional[bool] = None, rfc_1034: bool = False, rfc_2782: bool = False) -> Union[Literal[True], ValidationError]:
87
    """
88
    Validate hostnames including domain names and IP addresses.
89
    
90
    Parameters:
91
    - value: Hostname string to validate
92
    - skip_ipv6_addr: Reject IPv6 addresses
93
    - skip_ipv4_addr: Reject IPv4 addresses
94
    - may_have_port: Allow port numbers
95
    - maybe_simple: Allow simple hostnames (no dots)
96
    - consider_tld: Restrict to IANA TLDs
97
    - private: Require private/public IP addresses
98
    - rfc_1034: Allow trailing dots (RFC 1034)
99
    - rfc_2782: Service record format (RFC 2782)
100
    
101
    Returns:
102
    True if valid hostname, ValidationError otherwise
103
    """
104
```
105

106
### IPv4 Address Validation
107

108
Validates IPv4 addresses with CIDR notation support and private/public classification.
109

110
```python { .api }
111
def ipv4(value: str, /, *, cidr: bool = True, strict: bool = False, private: Optional[bool] = None, host_bit: bool = True) -> Union[Literal[True], ValidationError]:
112
    """
113
    Validate IPv4 addresses.
114
    
115
    Parameters:
116
    - value: IPv4 address string to validate
117
    - cidr: Allow CIDR notation (e.g., 192.168.1.0/24)
118
    - strict: Strict validation mode
119
    - private: Require private (True) or public (False) addresses
120
    - host_bit: Allow host bits in CIDR notation
121
    
122
    Returns:
123
    True if valid IPv4, ValidationError otherwise
124
    
125
    Supports standard dotted decimal notation.
126
    Validates CIDR blocks when enabled.
127
    Distinguishes private vs public address spaces.
128
    """
129
```
130

131
### IPv6 Address Validation
132

133
Validates IPv6 addresses with CIDR notation support.
134

135
```python { .api }
136
def ipv6(value: str, /, *, cidr: bool = True, strict: bool = False, host_bit: bool = True) -> Union[Literal[True], ValidationError]:
137
    """
138
    Validate IPv6 addresses.
139
    
140
    Parameters:
141
    - value: IPv6 address string to validate
142
    - cidr: Allow CIDR notation (e.g., 2001:db8::/32)
143
    - strict: Strict validation mode
144
    - host_bit: Allow host bits in CIDR notation
145
    
146
    Returns:
147
    True if valid IPv6, ValidationError otherwise
148
    
149
    Supports full and compressed IPv6 notation.
150
    Handles IPv4-mapped IPv6 addresses.
151
    Validates CIDR blocks when enabled.
152
    """
153
```
154

155
### MAC Address Validation
156

157
Validates MAC (Media Access Control) addresses in standard formats.
158

159
```python { .api }
160
def mac_address(value: str, /) -> Union[Literal[True], ValidationError]:
161
    """
162
    Validate MAC addresses.
163
    
164
    Parameters:
165
    - value: MAC address string to validate
166
    
167
    Returns:
168
    True if valid MAC address, ValidationError otherwise
169
    
170
    Supports formats:
171
    - Colon-separated: 01:23:45:67:89:ab
172
    - Hyphen-separated: 01-23-45-67-89-ab
173
    - Dot-separated: 0123.4567.89ab
174
    - No separators: 0123456789ab
175
    """
176
```
177

178

179
## Usage Examples
180

181
```python
182
import validators
183

184
# Domain validation
185
validators.domain('example.com')  # True
186
validators.domain('sub.example.com')  # True
187
validators.domain('example.co.uk', consider_tld=True)  # True
188

189
# Email validation
190
validators.email('user@example.com')  # True
191
validators.email('user@[192.168.1.1]', ipv4_address=True)  # True
192
validators.email('user@[2001:db8::1]', ipv6_address=True)  # True
193

194
# URL validation
195
validators.url('https://example.com')  # True
196
validators.url('https://user:pass@example.com:8080/path?query=1#frag')  # True
197
validators.url('ftp://ftp.example.com/file.txt')  # True
198

199
# IP address validation
200
validators.ipv4('192.168.1.1')  # True
201
validators.ipv4('192.168.1.0/24')  # True (CIDR)
202
validators.ipv4('10.0.0.1', private=True)  # True (private IP)
203

204
validators.ipv6('2001:db8::1')  # True
205
validators.ipv6('::1')  # True (loopback)
206
validators.ipv6('2001:db8::/32')  # True (CIDR)
207

208
# MAC address validation
209
validators.mac_address('01:23:45:67:89:ab')  # True
210
validators.mac_address('01-23-45-67-89-ab')  # True
211
validators.mac_address('0123.4567.89ab')     # True
212
```