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 asquery=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 isexam_ple
, which should not be allowed since it contains an underscore.foo_bar.example.com
the hostname isexample
, 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", "wss"],
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
SnowflakeDsn
module-attribute
¶
SnowflakeDsn = Annotated[
Url,
UrlConstraints(
allowed_schemes=["snowflake"], host_required=True
),
]
A type that will accept any Snowflake 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 |
allowed_schemes |
list[str] | None
|
The allowed schemes. Defaults to |
host_required |
bool | None
|
Whether the host is required. Defaults to |
default_host |
str | None
|
The default host. Defaults to |
default_port |
int | None
|
The default port. Defaults to |
default_path |
str | None
|
The default path. Defaults to |
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 ¶
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
513 514 515 |
|
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 ¶
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
737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 |
|