CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pydantic-core

Core functionality for Pydantic validation and serialization

—

Pending
Overview
Eval results
Files

url-network.mddocs/

URL and Network Types

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.

Capabilities

URL Type

Standard URL validation and parsing for single-host URLs.

class Url:
    """
    URL validation and parsing class for single-host URLs.
    
    Provides parsing and validation of URLs with access to individual
    components like scheme, host, port, path, query, and fragment.
    """
    
    scheme: str
    """The URL scheme (e.g., 'http', 'https', 'ftp')"""
    
    username: str | None
    """The username part of the URL, or None if not present"""
    
    password: str | None
    """The password part of the URL, or None if not present"""
    
    host: str | None
    """The host part of the URL, or None if not present"""
    
    port: int | None
    """The port number, or None if not specified"""
    
    path: str | None
    """The path part of the URL, or None if not present"""
    
    query: str | None
    """The query string, or None if not present"""
    
    fragment: str | None
    """The fragment (hash) part of the URL, or None if not present"""
    
    def __str__(self) -> str:
        """Return the complete URL as a string"""
    
    def __repr__(self) -> str:
        """Return a detailed representation of the URL"""
    
    def unicode_string(self) -> str:
        """Return the URL as a Unicode string"""
    
    def query_params(self) -> list[tuple[str, str]]:
        """
        Parse query string into list of key-value pairs.
        
        Returns:
            List of tuples containing query parameter names and values
        """

MultiHostUrl Type

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

class MultiHostUrl:
    """
    Multi-host URL validation class for database connections and clustered services.
    
    Supports URLs with multiple hosts, commonly used for database clusters,
    load balancers, and distributed systems.
    """
    
    scheme: str
    """The URL scheme (e.g., 'mongodb', 'redis', 'postgresql')"""
    
    username: str | None
    """The username for authentication, or None if not present"""
    
    password: str | None
    """The password for authentication, or None if not present"""
    
    hosts: list[MultiHostHost]
    """List of host specifications"""
    
    path: str | None
    """The path part of the URL, or None if not present"""
    
    query: str | None
    """The query string, or None if not present"""
    
    fragment: str | None
    """The fragment (hash) part of the URL, or None if not present"""
    
    def __str__(self) -> str:
        """Return the complete multi-host URL as a string"""
    
    def __repr__(self) -> str:
        """Return a detailed representation of the multi-host URL"""
    
    def unicode_string(self) -> str:
        """Return the URL as a Unicode string"""
    
    def query_params(self) -> list[tuple[str, str]]:
        """
        Parse query string into list of key-value pairs.
        
        Returns:
            List of tuples containing query parameter names and values
        """

MultiHostHost = TypedDict('MultiHostHost', {
    'username': str | None,  # Username for this specific host
    'password': str | None,  # Password for this specific host
    'host': str | None,      # Hostname or IP address
    'port': int | None       # Port number
})

URL Schema Functions

Schema building functions for URL validation.

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:
    """
    Create a URL validation schema.
    
    Args:
        max_length: Maximum allowed URL length
        allowed_schemes: List of allowed URL schemes (e.g., ['http', 'https'])
        host_required: Whether the host component is required
        default_host: Default host if not provided in URL
        default_port: Default port if not provided in URL
        default_path: Default path if not provided in URL
        strict: Whether to use strict URL validation
        serialization: Custom serialization schema
        ref: Reference name for schema reuse
        
    Returns:
        URL validation schema
    """

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:
    """
    Create a multi-host URL validation schema.
    
    Args:
        allowed_schemes: List of allowed URL schemes
        host_required: Whether at least one host is required
        default_host: Default host if no hosts provided
        default_port: Default port for hosts without explicit ports
        default_path: Default path if not provided in URL
        strict: Whether to use strict URL validation
        serialization: Custom serialization schema
        ref: Reference name for schema reuse
        
    Returns:
        Multi-host URL validation schema
    """

Usage Examples

Basic URL Validation

from pydantic_core import SchemaValidator
from pydantic_core.core_schema import url_schema

# Create URL validator
url_validator = SchemaValidator(url_schema())

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

for url_str in urls:
    try:
        url = url_validator.validate_python(url_str)
        print(f"URL: {url}")
        print(f"  Scheme: {url.scheme}")
        print(f"  Host: {url.host}")
        print(f"  Port: {url.port}")
        print(f"  Path: {url.path}")
        print(f"  Query: {url.query}")
        print()
    except Exception as e:
        print(f"Invalid URL '{url_str}': {e}")

URL with Constraints

from pydantic_core import SchemaValidator, ValidationError
from pydantic_core.core_schema import url_schema

# Create validator with constraints
https_validator = SchemaValidator(
    url_schema(
        allowed_schemes=['https'],
        host_required=True,
        max_length=2000
    )
)

# Test various URLs
test_urls = [
    'https://secure.example.com',     # Valid
    'http://insecure.example.com',    # Invalid scheme
    'https://',                       # Missing host
    'https://' + 'x' * 2000          # Too long
]

for url_str in test_urls:
    try:
        result = https_validator.validate_python(url_str)
        print(f"✓ Valid: {result}")
    except ValidationError as e:
        print(f"✗ Invalid '{url_str[:50]}...': {e.errors()[0]['msg']}")

Working with URL Components

from pydantic_core import SchemaValidator
from pydantic_core.core_schema import url_schema

validator = SchemaValidator(url_schema())

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

print(f"Full URL: {url}")
print(f"Scheme: {url.scheme}")
print(f"Username: {url.username}")
print(f"Password: {url.password}")
print(f"Host: {url.host}")
print(f"Port: {url.port}")
print(f"Path: {url.path}")
print(f"Query: {url.query}")
print(f"Fragment: {url.fragment}")

# Parse query parameters
if url.query:
    params = url.query_params()
    print(f"Query parameters: {params}")
    # Output: [('page', '1'), ('limit', '10')]

Multi-Host URL Validation

from pydantic_core import SchemaValidator
from pydantic_core.core_schema import multi_host_url_schema

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

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

for url_str in cluster_urls:
    try:
        multi_url = multi_host_validator.validate_python(url_str)
        print(f"Multi-host URL: {multi_url}")
        print(f"  Scheme: {multi_url.scheme}")
        print(f"  Username: {multi_url.username}")
        print(f"  Number of hosts: {len(multi_url.hosts)}")
        
        for i, host in enumerate(multi_url.hosts):
            print(f"  Host {i+1}: {host['host']}:{host['port']}")
        
        print(f"  Path: {multi_url.path}")
        print()
    except Exception as e:
        print(f"Invalid multi-host URL '{url_str}': {e}")

Database Connection Examples

from pydantic_core import SchemaValidator
from pydantic_core.core_schema import multi_host_url_schema, dict_schema, str_schema

# Schema for database configuration
db_config_schema = dict_schema({
    'connection_url': multi_host_url_schema(
        allowed_schemes=['postgresql', 'mysql', 'mongodb', 'redis']
    ),
    'name': str_schema(min_length=1)
})

validator = SchemaValidator(db_config_schema)

# Database configurations
configs = [
    {
        'name': 'MongoDB Cluster',
        'connection_url': 'mongodb://admin:secret@mongo1.prod.com:27017,mongo2.prod.com:27017,mongo3.prod.com:27017/app_db?replicaSet=rs0'
    },
    {
        'name': 'PostgreSQL Primary/Replica',
        'connection_url': 'postgresql://app_user:app_pass@pg-primary.prod.com:5432,pg-replica.prod.com:5432/app_db'
    },
    {
        'name': 'Redis Cluster',
        'connection_url': 'redis://redis1.cache.com:6379,redis2.cache.com:6379,redis3.cache.com:6379'
    }
]

for config in configs:
    try:
        validated = validator.validate_python(config)
        url = validated['connection_url']
        
        print(f"Database: {validated['name']}")
        print(f"  Type: {url.scheme}")
        print(f"  Hosts: {len(url.hosts)} servers")
        
        for host in url.hosts:
            print(f"    - {host['host']}:{host['port']}")
        
        if url.path and url.path != '/':
            print(f"  Database: {url.path.lstrip('/')}")
        
        if url.query:
            params = url.query_params()
            print(f"  Options: {dict(params)}")
        
        print()
        
    except Exception as e:
        print(f"Invalid config: {e}")

URL Serialization

from pydantic_core import SchemaValidator, SchemaSerializer
from pydantic_core.core_schema import url_schema, dict_schema, str_schema

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

validator = SchemaValidator(schema)
serializer = SchemaSerializer(schema)

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

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

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

# Serialize to JSON
json_result = serializer.to_json(validated)
print(f"JSON: {json_result.decode()}")

Custom URL Validation

from pydantic_core import SchemaValidator, ValidationError
from pydantic_core.core_schema import (
    with_info_after_validator_function, 
    url_schema, 
    PydanticCustomError
)

def validate_api_url(url):
    """Custom validator for API URLs."""
    # Must be HTTPS
    if url.scheme != 'https':
        raise PydanticCustomError(
            'api_url_insecure',
            'API URLs must use HTTPS for security'
        )
    
    # Must have /api/ in path
    if not url.path or '/api/' not in url.path:
        raise PydanticCustomError(
            'api_url_path',
            'API URLs must contain /api/ in the path'
        )
    
    # Host must end with .api.com
    if not url.host or not url.host.endswith('.api.com'):
        raise PydanticCustomError(
            'api_url_host',
            'API URLs must use hosts ending with .api.com'
        )
    
    return url

# Create schema with custom validation
api_url_schema = with_info_after_validator_function(
    validate_api_url,
    url_schema()
)

validator = SchemaValidator(api_url_schema)

# Test URLs
test_urls = [
    'https://service.api.com/api/v1/users',      # Valid
    'http://service.api.com/api/v1/users',       # Invalid: not HTTPS
    'https://service.com/api/v1/users',          # Invalid: wrong host
    'https://service.api.com/v1/users',          # Invalid: no /api/ in path
]

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

Install with Tessl CLI

npx tessl i tessl/pypi-pydantic-core

docs

error-handling.md

index.md

json-processing.md

schema-building.md

special-values.md

url-network.md

validation-serialization.md

tile.json