feat: add domain, URL and email validators (#2167)

* Add domain, URL and email validators

* Add docstrings

* Address PR comments

* Fix `CHANGELOG.rst`

Author: seladb

CHANGELOG.rst

@@ -16,6 +16,7 @@ Added
 - ``QuerySet.union()`` — SQL UNION query support for combining results from multiple QuerySets, including support for union across different models, ``union(all=True)`` for duplicates, ``order_by()``, ``limit()``, and ``count()``.
 - ``QuerySet.contains()`` method to check if an object exists in a queryset.
 - Added comprehensive EXPLAIN support for MySQL and PostgreSQL.
+- Built-in ``DomainNameValidator``, ``URLValidator``, and ``EmailValidator`` classes for common validation patterns. (#2162)
 
 Fixed
 ^^^^^

tests/test_validators.py

@@ -4,6 +4,18 @@
 
 from tests.testmodels import ValidatorModel
 from tortoise.exceptions import ValidationError
+from tortoise.validators import (
+    DomainNameValidator,
+    EmailValidator,
+    InvalidDomainName,
+    InvalidEmailAddress,
+    InvalidScheme,
+    InvalidURL,
+    URLValidator,
+    validate_domain_name,
+    validate_email,
+    validate_url,
+)
 
 
 @pytest.mark.asyncio
@@ -116,3 +128,154 @@ async def test_update(db):
     record.min_value_decimal = Decimal("0.9")
     with pytest.raises(ValidationError):
         await record.save()
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "example.com",
+        "sub.example.com",
+        "example.co.uk",
+        "münchen.de",
+        "sub1.sub2.example.org",
+        "UPPER-CASE.is.ok.net",
+        "tortoise.github.io",
+        "example.space",
+        "❤️.website",
+    ],
+)
+def test_domain_name_validator_valid(value):
+    validate_domain_name(value)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "---.com",
+        "example-.com",
+        "under_line.com",
+        "💻.tech",
+    ],
+)
+def test_domain_name_validator_invalid(value):
+    with pytest.raises(InvalidDomainName):
+        validate_domain_name(value)
+
+
+def test_domain_name_validator_invalid_idn_disabled():
+    validator = DomainNameValidator(accept_idna=False)
+    with pytest.raises(InvalidDomainName):
+        validator("münchen.de")
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "http://example.com",
+        "https://www.example.com/path?query=1",
+        "ftp://ftp.example.com/file.txt",
+        "http://localhost:8080",
+        "http://192.168.1.1",
+        "http://8.8.8.8:8080",
+        "https://[::1]",
+        "https://[2001:db8::1]:443",
+        "http://user:pass@example.com",
+        "http://example.com#fragment",
+    ],
+)
+def test_url_validator_valid(value):
+    validate_url(value)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "http://example.com",
+        "https://example.com",
+    ],
+)
+def test_url_validator_valid_custom_schemes(value):
+    validator = URLValidator(allowed_schemes=["http", "https"])
+    validator(value)
+
+
+def test_url_validator_invalid_scheme():
+    validator = URLValidator(allowed_schemes=["http", "https"])
+    with pytest.raises(InvalidScheme):
+        validator("ftp://example.com")
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "not-a-url",
+        "http://",
+        "http:// space.com",
+        "http://[::gggg]",
+        "http://256.1.1.1",
+        "http://" + "a" * 254 + ".com",
+    ],
+)
+def test_url_validator_invalid(value):
+    with pytest.raises(InvalidURL):
+        validate_url(value)
+
+
+def test_url_validator_max_length():
+    long_url = "http://example.com/" + "a" * 2100
+    with pytest.raises(InvalidURL):
+        validate_url(long_url)
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "user@example.com",
+        "user.name@example.com",
+        "user+tag@example.co.uk",
+        "user@sub.domain.com",
+        "user@[192.168.1.1]",
+        "user@[::1]",
+        "a+b@example.com",
+        "a-b@example.com",
+        "a_b@example.com",
+        "test@test.co.uk",
+    ],
+)
+def test_email_validator_valid(value):
+    validate_email(value)
+
+
+def test_email_validator_valid_allowed_domains():
+    validator = EmailValidator(allowed_domains=["example.com", "test.com"])
+    validator("user@example.com")
+    validator("user@test.com")
+
+
+def test_email_validator_invalid_allowed_domains():
+    validator = EmailValidator(allowed_domains=["example.com"])
+    validator("user@example.com")
+    with pytest.raises(InvalidEmailAddress):
+        validator("user@")
+    with pytest.raises(InvalidEmailAddress):
+        validator("user@invalid..com")
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "",
+        "not-an-email",
+        "user@",
+        "@example.com",
+        "user@.com",
+        "user@com.",
+        "user@com..com",
+        "a" * 330 + "@example.com",
+    ],
+)
+def test_email_validator_invalid(value):
+    with pytest.raises(InvalidEmailAddress):
+        validate_email(value)