0
# URL and Network Types
1

2
Specialized validation and handling for URLs and multi-host URLs commonly used in database connections and network configurations. These types provide robust URL parsing and validation with support for various URL schemes and formats.
3

4
## Capabilities
5

6
### URL Type
7

8
Standard URL validation and parsing for single-host URLs.
9

10
```python { .api }
11
class Url:
12
    """
13
    URL validation and parsing class for single-host URLs.
14
    
15
    Provides parsing and validation of URLs with access to individual
16
    components like scheme, host, port, path, query, and fragment.
17
    """
18
    
19
    scheme: str
20
    """The URL scheme (e.g., 'http', 'https', 'ftp')"""
21
    
22
    username: str | None
23
    """The username part of the URL, or None if not present"""
24
    
25
    password: str | None
26
    """The password part of the URL, or None if not present"""
27
    
28
    host: str | None
29
    """The host part of the URL, or None if not present"""
30
    
31
    port: int | None
32
    """The port number, or None if not specified"""
33
    
34
    path: str | None
35
    """The path part of the URL, or None if not present"""
36
    
37
    query: str | None
38
    """The query string, or None if not present"""
39
    
40
    fragment: str | None
41
    """The fragment (hash) part of the URL, or None if not present"""
42
    
43
    def __str__(self) -> str:
44
        """Return the complete URL as a string"""
45
    
46
    def __repr__(self) -> str:
47
        """Return a detailed representation of the URL"""
48
    
49
    def unicode_string(self) -> str:
50
        """Return the URL as a Unicode string"""
51
    
52
    def query_params(self) -> list[tuple[str, str]]:
53
        """
54
        Parse query string into list of key-value pairs.
55
        
56
        Returns:
57
            List of tuples containing query parameter names and values
58
        """
59
```
60

61
### MultiHostUrl Type
62

63
Multi-host URL validation for database connections and clustered services.
64

65
```python { .api }
66
class MultiHostUrl:
67
    """
68
    Multi-host URL validation class for database connections and clustered services.
69
    
70
    Supports URLs with multiple hosts, commonly used for database clusters,
71
    load balancers, and distributed systems.
72
    """
73
    
74
    scheme: str
75
    """The URL scheme (e.g., 'mongodb', 'redis', 'postgresql')"""
76
    
77
    username: str | None
78
    """The username for authentication, or None if not present"""
79
    
80
    password: str | None
81
    """The password for authentication, or None if not present"""
82
    
83
    hosts: list[MultiHostHost]
84
    """List of host specifications"""
85
    
86
    path: str | None
87
    """The path part of the URL, or None if not present"""
88
    
89
    query: str | None
90
    """The query string, or None if not present"""
91
    
92
    fragment: str | None
93
    """The fragment (hash) part of the URL, or None if not present"""
94
    
95
    def __str__(self) -> str:
96
        """Return the complete multi-host URL as a string"""
97
    
98
    def __repr__(self) -> str:
99
        """Return a detailed representation of the multi-host URL"""
100
    
101
    def unicode_string(self) -> str:
102
        """Return the URL as a Unicode string"""
103
    
104
    def query_params(self) -> list[tuple[str, str]]:
105
        """
106
        Parse query string into list of key-value pairs.
107
        
108
        Returns:
109
            List of tuples containing query parameter names and values
110
        """
111

112
MultiHostHost = TypedDict('MultiHostHost', {
113
    'username': str | None,  # Username for this specific host
114
    'password': str | None,  # Password for this specific host
115
    'host': str | None,      # Hostname or IP address
116
    'port': int | None       # Port number
117
})
118
```
119

120
### URL Schema Functions
121

122
Schema building functions for URL validation.
123

124
```python { .api }
125
def url_schema(*, max_length=None, allowed_schemes=None, host_required=None, default_host=None, default_port=None, default_path=None, strict=None, serialization=None, ref=None) -> UrlSchema:
126
    """
127
    Create a URL validation schema.
128
    
129
    Args:
130
        max_length: Maximum allowed URL length
131
        allowed_schemes: List of allowed URL schemes (e.g., ['http', 'https'])
132
        host_required: Whether the host component is required
133
        default_host: Default host if not provided in URL
134
        default_port: Default port if not provided in URL
135
        default_path: Default path if not provided in URL
136
        strict: Whether to use strict URL validation
137
        serialization: Custom serialization schema
138
        ref: Reference name for schema reuse
139
        
140
    Returns:
141
        URL validation schema
142
    """
143

144
def multi_host_url_schema(*, allowed_schemes=None, host_required=None, default_host=None, default_port=None, default_path=None, strict=None, serialization=None, ref=None) -> MultiHostUrlSchema:
145
    """
146
    Create a multi-host URL validation schema.
147
    
148
    Args:
149
        allowed_schemes: List of allowed URL schemes
150
        host_required: Whether at least one host is required
151
        default_host: Default host if no hosts provided
152
        default_port: Default port for hosts without explicit ports
153
        default_path: Default path if not provided in URL
154
        strict: Whether to use strict URL validation
155
        serialization: Custom serialization schema
156
        ref: Reference name for schema reuse
157
        
158
    Returns:
159
        Multi-host URL validation schema
160
    """
161
```
162

163
## Usage Examples
164

165
### Basic URL Validation
166

167
```python
168
from pydantic_core import SchemaValidator
169
from pydantic_core.core_schema import url_schema
170

171
# Create URL validator
172
url_validator = SchemaValidator(url_schema())
173

174
# Validate different URL formats
175
urls = [
176
    'https://example.com',
177
    'http://user:pass@api.example.com:8080/path?query=value#fragment',
178
    'ftp://files.example.com/uploads/',
179
    'mailto:contact@example.com'
180
]
181

182
for url_str in urls:
183
    try:
184
        url = url_validator.validate_python(url_str)
185
        print(f"URL: {url}")
186
        print(f"  Scheme: {url.scheme}")
187
        print(f"  Host: {url.host}")
188
        print(f"  Port: {url.port}")
189
        print(f"  Path: {url.path}")
190
        print(f"  Query: {url.query}")
191
        print()
192
    except Exception as e:
193
        print(f"Invalid URL '{url_str}': {e}")
194
```
195

196
### URL with Constraints
197

198
```python
199
from pydantic_core import SchemaValidator, ValidationError
200
from pydantic_core.core_schema import url_schema
201

202
# Create validator with constraints
203
https_validator = SchemaValidator(
204
    url_schema(
205
        allowed_schemes=['https'],
206
        host_required=True,
207
        max_length=2000
208
    )
209
)
210

211
# Test various URLs
212
test_urls = [
213
    'https://secure.example.com',     # Valid
214
    'http://insecure.example.com',    # Invalid scheme
215
    'https://',                       # Missing host
216
    'https://' + 'x' * 2000          # Too long
217
]
218

219
for url_str in test_urls:
220
    try:
221
        result = https_validator.validate_python(url_str)
222
        print(f"✓ Valid: {result}")
223
    except ValidationError as e:
224
        print(f"✗ Invalid '{url_str[:50]}...': {e.errors()[0]['msg']}")
225
```
226

227
### Working with URL Components
228

229
```python
230
from pydantic_core import SchemaValidator
231
from pydantic_core.core_schema import url_schema
232

233
validator = SchemaValidator(url_schema())
234

235
# Parse a complex URL
236
complex_url = 'https://api:secret@service.example.com:8443/v1/users?page=1&limit=10#results'
237
url = validator.validate_python(complex_url)
238

239
print(f"Full URL: {url}")
240
print(f"Scheme: {url.scheme}")
241
print(f"Username: {url.username}")
242
print(f"Password: {url.password}")
243
print(f"Host: {url.host}")
244
print(f"Port: {url.port}")
245
print(f"Path: {url.path}")
246
print(f"Query: {url.query}")
247
print(f"Fragment: {url.fragment}")
248

249
# Parse query parameters
250
if url.query:
251
    params = url.query_params()
252
    print(f"Query parameters: {params}")
253
    # Output: [('page', '1'), ('limit', '10')]
254
```
255

256
### Multi-Host URL Validation
257

258
```python
259
from pydantic_core import SchemaValidator
260
from pydantic_core.core_schema import multi_host_url_schema
261

262
# Create multi-host URL validator
263
multi_host_validator = SchemaValidator(multi_host_url_schema())
264

265
# Database cluster URLs
266
cluster_urls = [
267
    'mongodb://user:pass@db1.example.com:27017,db2.example.com:27017,db3.example.com:27017/mydb',
268
    'redis://cache1.example.com:6379,cache2.example.com:6379',
269
    'postgresql://user:pass@primary.db.com:5432,secondary.db.com:5432/myapp'
270
]
271

272
for url_str in cluster_urls:
273
    try:
274
        multi_url = multi_host_validator.validate_python(url_str)
275
        print(f"Multi-host URL: {multi_url}")
276
        print(f"  Scheme: {multi_url.scheme}")
277
        print(f"  Username: {multi_url.username}")
278
        print(f"  Number of hosts: {len(multi_url.hosts)}")
279
        
280
        for i, host in enumerate(multi_url.hosts):
281
            print(f"  Host {i+1}: {host['host']}:{host['port']}")
282
        
283
        print(f"  Path: {multi_url.path}")
284
        print()
285
    except Exception as e:
286
        print(f"Invalid multi-host URL '{url_str}': {e}")
287
```
288

289
### Database Connection Examples
290

291
```python
292
from pydantic_core import SchemaValidator
293
from pydantic_core.core_schema import multi_host_url_schema, dict_schema, str_schema
294

295
# Schema for database configuration
296
db_config_schema = dict_schema({
297
    'connection_url': multi_host_url_schema(
298
        allowed_schemes=['postgresql', 'mysql', 'mongodb', 'redis']
299
    ),
300
    'name': str_schema(min_length=1)
301
})
302

303
validator = SchemaValidator(db_config_schema)
304

305
# Database configurations
306
configs = [
307
    {
308
        'name': 'MongoDB Cluster',
309
        'connection_url': 'mongodb://admin:secret@mongo1.prod.com:27017,mongo2.prod.com:27017,mongo3.prod.com:27017/app_db?replicaSet=rs0'
310
    },
311
    {
312
        'name': 'PostgreSQL Primary/Replica',
313
        'connection_url': 'postgresql://app_user:app_pass@pg-primary.prod.com:5432,pg-replica.prod.com:5432/app_db'
314
    },
315
    {
316
        'name': 'Redis Cluster',
317
        'connection_url': 'redis://redis1.cache.com:6379,redis2.cache.com:6379,redis3.cache.com:6379'
318
    }
319
]
320

321
for config in configs:
322
    try:
323
        validated = validator.validate_python(config)
324
        url = validated['connection_url']
325
        
326
        print(f"Database: {validated['name']}")
327
        print(f"  Type: {url.scheme}")
328
        print(f"  Hosts: {len(url.hosts)} servers")
329
        
330
        for host in url.hosts:
331
            print(f"    - {host['host']}:{host['port']}")
332
        
333
        if url.path and url.path != '/':
334
            print(f"  Database: {url.path.lstrip('/')}")
335
        
336
        if url.query:
337
            params = url.query_params()
338
            print(f"  Options: {dict(params)}")
339
        
340
        print()
341
        
342
    except Exception as e:
343
        print(f"Invalid config: {e}")
344
```
345

346
### URL Serialization
347

348
```python
349
from pydantic_core import SchemaValidator, SchemaSerializer
350
from pydantic_core.core_schema import url_schema, dict_schema, str_schema
351

352
# Schema with URL field
353
schema = dict_schema({
354
    'name': str_schema(),
355
    'website': url_schema(allowed_schemes=['https', 'http'])
356
})
357

358
validator = SchemaValidator(schema)
359
serializer = SchemaSerializer(schema)
360

361
# Validate and serialize data with URL
362
data = {
363
    'name': 'Example Company',
364
    'website': 'https://www.example.com/about?source=api'
365
}
366

367
# Validate
368
validated = validator.validate_python(data)
369
print(f"Validated URL type: {type(validated['website'])}")
370
print(f"URL: {validated['website']}")
371

372
# Serialize back to Python objects
373
serialized = serializer.to_python(validated)
374
print(f"Serialized URL type: {type(serialized['website'])}")
375
print(f"Serialized: {serialized}")
376

377
# Serialize to JSON
378
json_result = serializer.to_json(validated)
379
print(f"JSON: {json_result.decode()}")
380
```
381

382
### Custom URL Validation
383

384
```python
385
from pydantic_core import SchemaValidator, ValidationError
386
from pydantic_core.core_schema import (
387
    with_info_after_validator_function, 
388
    url_schema, 
389
    PydanticCustomError
390
)
391

392
def validate_api_url(url):
393
    """Custom validator for API URLs."""
394
    # Must be HTTPS
395
    if url.scheme != 'https':
396
        raise PydanticCustomError(
397
            'api_url_insecure',
398
            'API URLs must use HTTPS for security'
399
        )
400
    
401
    # Must have /api/ in path
402
    if not url.path or '/api/' not in url.path:
403
        raise PydanticCustomError(
404
            'api_url_path',
405
            'API URLs must contain /api/ in the path'
406
        )
407
    
408
    # Host must end with .api.com
409
    if not url.host or not url.host.endswith('.api.com'):
410
        raise PydanticCustomError(
411
            'api_url_host',
412
            'API URLs must use hosts ending with .api.com'
413
        )
414
    
415
    return url
416

417
# Create schema with custom validation
418
api_url_schema = with_info_after_validator_function(
419
    validate_api_url,
420
    url_schema()
421
)
422

423
validator = SchemaValidator(api_url_schema)
424

425
# Test URLs
426
test_urls = [
427
    'https://service.api.com/api/v1/users',      # Valid
428
    'http://service.api.com/api/v1/users',       # Invalid: not HTTPS
429
    'https://service.com/api/v1/users',          # Invalid: wrong host
430
    'https://service.api.com/v1/users',          # Invalid: no /api/ in path
431
]
432

433
for url_str in test_urls:
434
    try:
435
        result = validator.validate_python(url_str)
436
        print(f"✓ Valid API URL: {result}")
437
    except ValidationError as e:
438
        print(f"✗ Invalid: {e.errors()[0]['msg']}")
439
```