Network Types

The networks module contains types for common network-related fields.

AnyUrl `module-attribute` ¶

AnyUrl = Url

Base type for all URLs.

Any scheme allowed
Top-level domain (TLD) not required
Host required

Assuming an input URL of http://samuel:[email protected]:8000/the/path/?query=here#fragment=is;this=bit, the types export the following properties:

scheme: the URL scheme (http), always set.
host: the URL host (example.com), always set.
username: optional username if included (samuel).
password: optional password if included (pass).
port: optional port (8000).
path: optional path (/the/path/).
query: optional URL query (for example, GET arguments or "search string", such as query=here).
fragment: optional fragment (fragment=is;this=bit).

AnyHttpUrl `module-attribute` ¶

AnyHttpUrl = Annotated[
    Url, UrlConstraints(allowed_schemes=["http", "https"])
]

A type that will accept any http or https URL.

TLD not required
Host required

HttpUrl `module-attribute` ¶

HttpUrl = Annotated[
    Url,
    UrlConstraints(
        max_length=2083, allowed_schemes=["http", "https"]
    ),
]

A type that will accept any http or https URL.

TLD not required
Host required
Max length 2083

from pydantic import BaseModel, HttpUrl, ValidationError

class MyModel(BaseModel):
    url: HttpUrl

m = MyModel(url='http://www.example.com')  # (1)!
print(m.url)
#> http://www.example.com/

try:
    MyModel(url='ftp://invalid.url')
except ValidationError as e:
    print(e)
    '''
    1 validation error for MyModel
    url
      URL scheme should be 'http' or 'https' [type=url_scheme, input_value='ftp://invalid.url', input_type=str]
    '''

try:
    MyModel(url='not a url')
except ValidationError as e:
    print(e)
    '''
    1 validation error for MyModel
    url
      Input should be a valid URL, relative URL without a base [type=url_parsing, input_value='not a url', input_type=str]
    '''

Note: mypy would prefer m = MyModel(url=HttpUrl('http://www.example.com')), but Pydantic will convert the string to an HttpUrl instance anyway.

"International domains" (e.g. a URL where the host or TLD includes non-ascii characters) will be encoded via punycode (see this article for a good description of why this is important):

from pydantic import BaseModel, HttpUrl

class MyModel(BaseModel):
    url: HttpUrl

m1 = MyModel(url='http://puny£code.com')
print(m1.url)
#> http://xn--punycode-eja.com/
m2 = MyModel(url='https://www.аррӏе.com/')
print(m2.url)
#> https://www.xn--80ak6aa92e.com/
m3 = MyModel(url='https://www.example.珠宝/')
print(m3.url)
#> https://www.example.xn--pbt977c/

Underscores in Hostnames

In Pydantic, underscores are allowed in all parts of a domain except the TLD. Technically this might be wrong - in theory the hostname cannot have underscores, but subdomains can.

To explain this; consider the following two cases:

exam_ple.co.uk: the hostname is exam_ple, which should not be allowed since it contains an underscore.
foo_bar.example.com the hostname is example, which should be allowed since the underscore is in the subdomain.

Without having an exhaustive list of TLDs, it would be impossible to differentiate between these two. Therefore underscores are allowed, but you can always do further validation in a validator if desired.

Also, Chrome, Firefox, and Safari all currently accept http://exam_ple.com as a URL, so we're in good (or at least big) company.

AnyWebsocketUrl `module-attribute` ¶

AnyWebsocketUrl = Annotated[
    Url, UrlConstraints(allowed_schemes=["ws", "wss"])
]

A type that will accept any ws or wss URL.

TLD not required
Host required

WebsocketUrl `module-attribute` ¶

WebsocketUrl = Annotated[
    Url,
    UrlConstraints(
        max_length=2083, allowed_schemes=["ws", "wss"]
    ),
]

A type that will accept any ws or wss URL.

TLD not required
Host required
Max length 2083

FileUrl `module-attribute` ¶

FileUrl = Annotated[
    Url, UrlConstraints(allowed_schemes=["file"])
]

A type that will accept any file URL.

Host not required

FtpUrl `module-attribute` ¶

FtpUrl = Annotated[
    Url, UrlConstraints(allowed_schemes=["ftp"])
]

A type that will accept ftp URL.

TLD not required
Host required

PostgresDsn `module-attribute` ¶

PostgresDsn = Annotated[
    MultiHostUrl,
    UrlConstraints(
        host_required=True,
        allowed_schemes=[
            "postgres",
            "postgresql",
            "postgresql+asyncpg",
            "postgresql+pg8000",
            "postgresql+psycopg",
            "postgresql+psycopg2",
            "postgresql+psycopg2cffi",
            "postgresql+py-postgresql",
            "postgresql+pygresql",
        ],
    ),
]

A type that will accept any Postgres DSN.

User info required
TLD not required
Host required
Supports multiple hosts

If further validation is required, these properties can be used by validators to enforce specific behaviour:

from pydantic import (
    BaseModel,
    HttpUrl,
    PostgresDsn,
    ValidationError,
    field_validator,
)

class MyModel(BaseModel):
    url: HttpUrl

m = MyModel(url='http://www.example.com')

# the repr() method for a url will display all properties of the url
print(repr(m.url))
#> Url('http://www.example.com/')
print(m.url.scheme)
#> http
print(m.url.host)
#> www.example.com
print(m.url.port)
#> 80

class MyDatabaseModel(BaseModel):
    db: PostgresDsn

    @field_validator('db')
    def check_db_name(cls, v):
        assert v.path and len(v.path) > 1, 'database must be provided'
        return v

m = MyDatabaseModel(db='postgres://user:pass@localhost:5432/foobar')
print(m.db)
#> postgres://user:pass@localhost:5432/foobar

try:
    MyDatabaseModel(db='postgres://user:pass@localhost:5432')
except ValidationError as e:
    print(e)
    '''
    1 validation error for MyDatabaseModel
    db
      Assertion failed, database must be provided
    assert (None)
     +  where None = MultiHostUrl('postgres://user:pass@localhost:5432').path [type=assertion_error, input_value='postgres://user:pass@localhost:5432', input_type=str]
    '''

CockroachDsn `module-attribute` ¶

CockroachDsn = Annotated[
    Url,
    UrlConstraints(
        host_required=True,
        allowed_schemes=[
            "cockroachdb",
            "cockroachdb+psycopg2",
            "cockroachdb+asyncpg",
        ],
    ),
]

A type that will accept any Cockroach DSN.

User info required
TLD not required
Host required

AmqpDsn `module-attribute` ¶

AmqpDsn = Annotated[
    Url, UrlConstraints(allowed_schemes=["amqp", "amqps"])
]

A type that will accept any AMQP DSN.

User info required
TLD not required
Host required

RedisDsn `module-attribute` ¶

RedisDsn = Annotated[
    Url,
    UrlConstraints(
        allowed_schemes=["redis", "rediss"],
        default_host="localhost",
        default_port=6379,
        default_path="/0",
    ),
]

A type that will accept any Redis DSN.

User info required
TLD not required
Host required (e.g., rediss://:pass@localhost)

MongoDsn `module-attribute` ¶

MongoDsn = Annotated[
    MultiHostUrl,
    UrlConstraints(
        allowed_schemes=["mongodb", "mongodb+srv"],
        default_port=27017,
    ),
]

A type that will accept any MongoDB DSN.

User info not required
Database name not required
Port not required
User info may be passed without user part (e.g., mongodb://mongodb0.example.com:27017).

KafkaDsn `module-attribute` ¶

KafkaDsn = Annotated[
    Url,
    UrlConstraints(
        allowed_schemes=["kafka"],
        default_host="localhost",
        default_port=9092,
    ),
]

A type that will accept any Kafka DSN.

User info required
TLD not required
Host required

NatsDsn `module-attribute` ¶

NatsDsn = Annotated[
    MultiHostUrl,
    UrlConstraints(
        allowed_schemes=["nats", "tls", "ws"],
        default_host="localhost",
        default_port=4222,
    ),
]

A type that will accept any NATS DSN.

NATS is a connective technology built for the ever increasingly hyper-connected world. It is a single technology that enables applications to securely communicate across any combination of cloud vendors, on-premise, edge, web and mobile, and devices. More: https://nats.io

MySQLDsn `module-attribute` ¶

MySQLDsn = Annotated[
    Url,
    UrlConstraints(
        allowed_schemes=[
            "mysql",
            "mysql+mysqlconnector",
            "mysql+aiomysql",
            "mysql+asyncmy",
            "mysql+mysqldb",
            "mysql+pymysql",
            "mysql+cymysql",
            "mysql+pyodbc",
        ],
        default_port=3306,
    ),
]

A type that will accept any MySQL DSN.

User info required
TLD not required
Host required

MariaDBDsn `module-attribute` ¶

MariaDBDsn = Annotated[
    Url,
    UrlConstraints(
        allowed_schemes=[
            "mariadb",
            "mariadb+mariadbconnector",
            "mariadb+pymysql",
        ],
        default_port=3306,
    ),
]

A type that will accept any MariaDB DSN.

User info required
TLD not required
Host required

ClickHouseDsn `module-attribute` ¶

ClickHouseDsn = Annotated[
    Url,
    UrlConstraints(
        allowed_schemes=[
            "clickhouse+native",
            "clickhouse+asynch",
        ],
        default_host="localhost",
        default_port=9000,
    ),
]

A type that will accept any ClickHouse DSN.

User info required
TLD not required
Host required

MAX_EMAIL_LENGTH `module-attribute` ¶

MAX_EMAIL_LENGTH = 2048

Maximum length for an email. A somewhat arbitrary but very generous number compared to what is allowed by most implementations.

UrlConstraints `dataclass` ¶

UrlConstraints(
    max_length: int | None = None,
    allowed_schemes: list[str] | None = None,
    host_required: bool | None = None,
    default_host: str | None = None,
    default_port: int | None = None,
    default_path: str | None = None,
)

Bases: PydanticMetadata

Url constraints.

Attributes:

Name	Type	Description
`max_length`	`int \| None`	The maximum length of the url. Defaults to `None`.
`allowed_schemes`	`list[str] \| None`	The allowed schemes. Defaults to `None`.
`host_required`	`bool \| None`	Whether the host is required. Defaults to `None`.
`default_host`	`str \| None`	The default host. Defaults to `None`.
`default_port`	`int \| None`	The default port. Defaults to `None`.
`default_path`	`str \| None`	The default path. Defaults to `None`.

EmailStr ¶

Info

To use this type, you need to install the optional email-validator package:

pip install email-validator

Validate email addresses.

from pydantic import BaseModel, EmailStr

class Model(BaseModel):
    email: EmailStr

print(Model(email='[email protected]'))
#> email='[email protected]'

NameEmail ¶

NameEmail(name: str, email: str)

Bases: Representation

Info

To use this type, you need to install the optional email-validator package:

pip install email-validator

Validate a name and email address combination, as specified by RFC 5322.

The NameEmail has two properties: name and email. In case the name is not provided, it's inferred from the email address.

from pydantic import BaseModel, NameEmail

class User(BaseModel):
    email: NameEmail

user = User(email='Fred Bloggs <[email protected]>')
print(user.email)
#> Fred Bloggs <[email protected]>
print(user.email.name)
#> Fred Bloggs

user = User(email='[email protected]')
print(user.email)
#> fred.bloggs <[email protected]>
print(user.email.name)
#> fred.bloggs

Source code in pydantic/networks.py

def __init__(self, name: str, email: str):
    self.name = name
    self.email = email

IPvAnyAddress ¶

Validate an IPv4 or IPv6 address.

from pydantic import BaseModel
from pydantic.networks import IPvAnyAddress

class IpModel(BaseModel):
    ip: IPvAnyAddress

print(IpModel(ip='127.0.0.1'))
#> ip=IPv4Address('127.0.0.1')

try:
    IpModel(ip='http://www.example.com')
except ValueError as e:
    print(e.errors())
    '''
    [
        {
            'type': 'ip_any_address',
            'loc': ('ip',),
            'msg': 'value is not a valid IPv4 or IPv6 address',
            'input': 'http://www.example.com',
        }
    ]
    '''

IPvAnyInterface ¶

Validate an IPv4 or IPv6 interface.

IPvAnyNetwork ¶

Validate an IPv4 or IPv6 network.

validate_email ¶

validate_email(value: str) -> tuple[str, str]

Email address validation using email-validator.

Note

Note that:

Raw IP address (literal) domain parts are not allowed.
"John Doe <[email protected]>" style "pretty" email addresses are processed.
Spaces are striped from the beginning and end of addresses, but no error is raised.

Source code in pydantic/networks.py

def validate_email(value: str) -> tuple[str, str]:
    """Email address validation using [email-validator](https://pypi.org/project/email-validator/).

    Note:
        Note that:

        * Raw IP address (literal) domain parts are not allowed.
        * `"John Doe <[email protected]>"` style "pretty" email addresses are processed.
        * Spaces are striped from the beginning and end of addresses, but no error is raised.
    """
    if email_validator is None:
        import_email_validator()

    if len(value) > MAX_EMAIL_LENGTH:
        raise PydanticCustomError(
            'value_error',
            'value is not a valid email address: {reason}',
            {'reason': f'Length must not exceed {MAX_EMAIL_LENGTH} characters'},
        )

    m = pretty_email_regex.fullmatch(value)
    name: str | None = None
    if m:
        unquoted_name, quoted_name, value = m.groups()
        name = unquoted_name or quoted_name

    email = value.strip()

    try:
        parts = email_validator.validate_email(email, check_deliverability=False)
    except email_validator.EmailNotValidError as e:
        raise PydanticCustomError(
            'value_error', 'value is not a valid email address: {reason}', {'reason': str(e.args[0])}
        ) from e

    email = parts.normalized
    assert email is not None
    name = name or parts.local_part
    return name, email

Network Types

AnyUrl module-attribute ¶

AnyHttpUrl module-attribute ¶

HttpUrl module-attribute ¶

AnyWebsocketUrl module-attribute ¶

WebsocketUrl module-attribute ¶

FileUrl module-attribute ¶

FtpUrl module-attribute ¶

PostgresDsn module-attribute ¶

CockroachDsn module-attribute ¶

AmqpDsn module-attribute ¶

RedisDsn module-attribute ¶

MongoDsn module-attribute ¶

KafkaDsn module-attribute ¶

NatsDsn module-attribute ¶

MySQLDsn module-attribute ¶

MariaDBDsn module-attribute ¶

ClickHouseDsn module-attribute ¶

MAX_EMAIL_LENGTH module-attribute ¶

UrlConstraints dataclass ¶