hare-orm 0.9.0__py3-none-any.whl

hare/fields/validators/formats/e164_phone_validator.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from hare.fields.constants import E164_PHONE_PATTERN
+from hare.fields.validators.exceptions import InvalidPhoneNumber
+from hare.fields.validators.validator import Validator
+
+
+class E164PhoneValidator(Validator):
+    """Validates a phone number in E.164 form: ``+``, a country code not starting with 0 and at most
+    15 digits in all, with nothing between them (``+16502530000``).
+
+    Args:
+        message: Replaces the default error message.
+
+    Raises:
+        InvalidPhoneNumber: The value isn't an E.164 number.
+    """
+
+    regex = re.compile(E164_PHONE_PATTERN)
+
+    def __call__(self, value: Any) -> None:
+        if not isinstance(value, str) or self.regex.fullmatch(value) is None:
+            raise InvalidPhoneNumber(self.message)
+
+
+validate_e164_phone = E164PhoneValidator()
+
+
+validate_e164_phone.__doc__ = "Pre-configured E164PhoneValidator instance."

hare/fields/validators/formats/email_validator.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+from functools import cached_property
+
+from hare.exceptions import ValidationError
+from hare.fields.constants import DOMAIN_REGEX, HOSTNAME_REGEX, TLD_NO_FQDN_REGEX
+from hare.fields.validators.exceptions import InvalidEmailAddress
+from hare.fields.validators.formats.ipv46_validator import validate_ipv46_address
+from hare.fields.validators.validator import Validator
+
+
+class EmailValidator(Validator):
+    """Validates an email address by RFC 3696.
+
+    Args:
+        allowed_domains: Domains accepted as they are, even ones the domain pattern refuses (``localhost``);
+            any other domain is checked as usual.
+        message: Replaces the default error message.
+
+    Raises:
+        InvalidEmailAddress: The value isn't a valid email address.
+    """
+
+    # The maximum length of an email is 320 characters per RFC 3696 section 3
+    MAX_EMAIL_LENGTH = 320
+
+    USER_REGEX = (
+        # dot-atom
+        r"(^[-!#$%&'*+/=?^_`{}|~0-9A-Z]+(\.[-!#$%&'*+/=?^_`{}|~0-9A-Z]+)*\Z"
+        # quoted-string
+        r'|^"([\001-\010\013\014\016-\037!#-\[\]-\177]|\\[\001-\011\013\014\016-\177])'
+        r'*"\Z)'
+    )
+    LITERAL_REGEX = (
+        # literal form, ipv4 or ipv6 address (SMTP 4.1.3)
+        r"\[([A-F0-9:.]+)\]\Z"
+    )
+
+    @cached_property
+    def _user_regex(self) -> re.Pattern[str]:
+        return re.compile(self.USER_REGEX, re.IGNORECASE)
+
+    @cached_property
+    def _domain_regex(self) -> re.Pattern[str]:
+        return re.compile(r"^" + HOSTNAME_REGEX + DOMAIN_REGEX + TLD_NO_FQDN_REGEX + r"\Z", re.IGNORECASE)
+
+    @cached_property
+    def _literal_regex(self) -> re.Pattern[str]:
+        return re.compile(self.LITERAL_REGEX, re.IGNORECASE)
+
+    def _validate_domain_part(self, domain_part: str) -> bool:
+        if self._domain_regex.match(domain_part):
+            return True
+
+        if literal_match := self._literal_regex.match(domain_part):
+            ip_address = literal_match[1]
+            try:
+                validate_ipv46_address(ip_address)
+                return True
+            except ValidationError:
+                pass
+        return False
+
+    def __init__(self, allowed_domains: list[str] | None = None, message: str | None = None) -> None:
+        self.allowed_domains: list[str] = allowed_domains or []
+        super().__init__(message)
+
+    def __call__(self, value: str) -> None:
+        if value is None:
+            raise InvalidEmailAddress(self.message)
+        if "@" not in value or len(value) > self.MAX_EMAIL_LENGTH:
+            raise InvalidEmailAddress(self.message)
+
+        user_part, domain_part = value.rsplit("@", 1)
+
+        if not self._user_regex.match(user_part):
+            raise InvalidEmailAddress(self.message)
+
+        if domain_part not in self.allowed_domains and not self._validate_domain_part(domain_part):
+            raise InvalidEmailAddress(self.message)
+
+
+validate_email = EmailValidator()
+
+
+validate_email.__doc__ = "Pre-configured EmailValidator instance."

hare/fields/validators/formats/ipv46_validator.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.exceptions import ValidationError
+from hare.fields.validators.formats.ipv4_validator import validate_ipv4_address
+from hare.fields.validators.formats.ipv6_validator import validate_ipv6_address
+from hare.fields.validators.validator import Validator
+
+
+class IPv46Validator(Validator):
+    """Checks a value is an IPv4 or an IPv6 address."""
+
+    def __call__(self, value: Any) -> None:
+        try:
+            validate_ipv4_address(value)
+        except ValidationError:
+            try:
+                validate_ipv6_address(value)
+            except ValidationError:
+                self._raise(f"'{ValueDescriptions.get_shown_text(value)}' is not a valid IPv4 or IPv6 address.")
+
+
+validate_ipv46_address = IPv46Validator()
+
+
+validate_ipv46_address.__doc__ = "Pre-configured IPv46Validator instance."

hare/fields/validators/formats/ipv4_validator.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import ipaddress
+from typing import Any
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.fields.validators.validator import Validator
+
+
+class IPv4Validator(Validator):
+    """Checks a value is an IPv4 address."""
+
+    def __call__(self, value: Any) -> None:
+        try:
+            ipaddress.IPv4Address(value)
+        except ValueError:
+            self._raise(f"'{ValueDescriptions.get_shown_text(value)}' is not a valid IPv4 address.")
+
+
+validate_ipv4_address = IPv4Validator()
+
+
+validate_ipv4_address.__doc__ = "Pre-configured IPv4Validator instance."

hare/fields/validators/formats/ipv6_validator.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import ipaddress
+from typing import Any
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.fields.validators.validator import Validator
+
+
+class IPv6Validator(Validator):
+    """Checks a value is an IPv6 address."""
+
+    def __call__(self, value: Any) -> None:
+        try:
+            ipaddress.IPv6Address(value)
+        except ValueError:
+            self._raise(f"'{ValueDescriptions.get_shown_text(value)}' is not a valid IPv6 address.")
+
+
+validate_ipv6_address = IPv6Validator()
+
+
+validate_ipv6_address.__doc__ = "Pre-configured IPv6Validator instance."

hare/fields/validators/formats/regex_validator.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.exceptions import ConfigurationError, ValidationError
+from hare.fields.validators.validator import Validator
+
+
+class RegexValidator(Validator):
+    """Checks a text matches a regular expression from its start.
+
+    Args:
+        pattern: The regular expression.
+        flags: Its ``re`` flags.
+        message: Replaces the default error message.
+
+    Raises:
+        ConfigurationError: The pattern doesn't compile.
+    """
+
+    def __init__(self, pattern: str, flags: int | re.RegexFlag, message: str | None = None) -> None:
+        try:
+            self.regex = re.compile(pattern, flags)
+        except (re.error, ValueError, OverflowError) as error:
+            raise ConfigurationError(
+                f"RegexValidator: {pattern!r} with flags {flags!r} doesn't compile: {error}"
+            ) from error
+        super().__init__(message)
+
+    def __call__(self, value: Any) -> None:
+        if value is None:
+            raise ValidationError("Value must not be None")
+        if not self.regex.match(value):
+            self._raise(
+                f"Value '{ValueDescriptions.get_shown_text(value)}' does not match regex '{self.regex.pattern}'"
+            )

hare/fields/validators/formats/slug_validator.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from hare.fields.constants import SLUG_PATTERN, UNICODE_SLUG_PATTERN
+from hare.fields.validators.exceptions import InvalidSlug
+from hare.fields.validators.validator import Validator
+
+
+class SlugValidator(Validator):
+    """Validates a slug: ASCII letters, digits, hyphens and underscores - any Unicode letter or digit
+    too with ``allow_unicode``.
+
+    Args:
+        allow_unicode: Accept any Unicode letter or digit.
+        message: Replaces the default error message.
+
+    Raises:
+        InvalidSlug: The value isn't a slug.
+    """
+
+    def __init__(self, allow_unicode: bool = False, message: str | None = None) -> None:
+        self.allow_unicode = allow_unicode
+        self.regex = re.compile(UNICODE_SLUG_PATTERN if allow_unicode else SLUG_PATTERN)
+        super().__init__(message)
+
+    def __call__(self, value: Any) -> None:
+        if not isinstance(value, str) or self.regex.fullmatch(value) is None:
+            raise InvalidSlug(self.message)
+
+
+validate_slug = SlugValidator()
+
+
+validate_slug.__doc__ = "Pre-configured SlugValidator instance."

hare/fields/validators/formats/url_validator.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import re
+from functools import cached_property
+from urllib.parse import urlsplit
+
+from hare.exceptions import ValidationError
+from hare.fields.constants import DOMAIN_REGEX, HOSTNAME_REGEX, TLD_REGEX
+from hare.fields.validators.exceptions import InvalidScheme, InvalidURL
+from hare.fields.validators.formats.ipv6_validator import validate_ipv6_address
+from hare.fields.validators.validator import Validator
+
+
+class URLValidator(Validator):
+    """
+    Validator for URLs.
+
+    Validates URLs according to RFC 3986. Checks scheme, host, port, and path
+    components. Supports HTTP, HTTPS, FTP, and FTPS schemes by default.
+
+    Args:
+        allowed_schemes: List of allowed URL schemes. Defaults to ["http", "https", "ftp", "ftps"].
+        message: Overrides InvalidURL's and InvalidScheme's default error messages.
+
+    Raises:
+        InvalidURL: if the value is not a valid URL.
+        InvalidScheme: if the URL scheme is not in the allowed list.
+    """
+
+    IPV4_REGEX = (
+        r"(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)"
+        r"(?:\.(?:0|25[0-5]|2[0-4][0-9]|1[0-9]?[0-9]?|[1-9][0-9]?)){3}"
+    )
+    SIMPLE_IPV6_REGEX = r"\[[0-9a-f:.]+\]"  # (simple regex, validated later)
+    ADVANCED_IPV6_REGEX = r"^\[(.+)\](?::[0-9]{1,5})?$"
+    HOST_REGEX = "(" + HOSTNAME_REGEX + DOMAIN_REGEX + TLD_REGEX + "|localhost)"
+    URL_REGEX = (
+        r"^(?:[a-z0-9.+-]*)://"  # scheme is validated separately
+        r"(?:[^\s:@/]+(?::[^\s:@/]*)?@)?"  # user:pass authentication
+        r"(?:" + IPV4_REGEX + "|" + SIMPLE_IPV6_REGEX + "|" + HOST_REGEX + ")"
+        r"(?::[0-9]{1,5})?"  # port
+        r"(?:[/?#][^\s]*)?"  # resource path
+        r"\Z"
+    )
+    UNSAFE_CHARS = frozenset("\t\r\n")
+    MAX_URL_LENGTH = 2048
+
+    # The longest host name, by RFC 1034 section 3.1.
+    MAX_HOSTNAME_LENGTH = 253
+
+    @cached_property
+    def _url_regex(self) -> re.Pattern[str]:
+        return re.compile(self.URL_REGEX, re.IGNORECASE)
+
+    def __init__(self, allowed_schemes: list[str] | None = None, message: str | None = None) -> None:
+        self.allowed_schemes = allowed_schemes or ["http", "https", "ftp", "ftps"]
+        super().__init__(message)
+
+    def __call__(self, value: str) -> None:
+        if value is None:
+            raise InvalidURL(self.message)
+        if len(value) > self.MAX_URL_LENGTH:
+            raise InvalidURL(self.message)
+
+        if self.UNSAFE_CHARS.intersection(value):
+            raise InvalidURL(self.message)
+
+        try:
+            split_url = urlsplit(value)
+        except ValueError:
+            raise InvalidURL(self.message)
+
+        if split_url.scheme.lower() not in self.allowed_schemes:
+            raise InvalidScheme(split_url.scheme.lower(), self.message)
+
+        if split_url.hostname is None or len(split_url.hostname) > self.MAX_HOSTNAME_LENGTH:
+            raise InvalidURL(self.message)
+
+        if not self._url_regex.search(value):
+            raise InvalidURL(self.message)
+
+        # Now verify IPv6 in the netloc part
+        host_match = re.search(self.ADVANCED_IPV6_REGEX, split_url.netloc)
+        if host_match:
+            potential_ip = host_match[1]
+            try:
+                validate_ipv6_address(potential_ip)
+            except ValidationError:
+                raise InvalidURL(self.message)
+
+
+validate_url = URLValidator()
+
+
+validate_url.__doc__ = "Pre-configured URLValidator instance."

hare/fields/validators/limits/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

hare/fields/validators/limits/length_validator.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any
+
+from hare.exceptions import ValidationError
+from hare.fields.validators.validator import Validator
+
+
+class LengthValidator(Validator):
+    """The base of the validators of a length: of a text, or of a list, a tuple or bytes (the number of
+    elements of an array field)."""
+
+    types = (str, list, tuple, bytes)
+
+    def _validate_type(self, value: Any) -> None:
+        if not isinstance(value, self.types):
+            raise ValidationError("Value must be a string, list, tuple, or bytes, and is required")

hare/fields/validators/limits/max_digits_validator.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.exceptions import ValidationError
+from hare.fields.validators.validator import Validator
+
+
+class MaxDigitsValidator(Validator):
+    """Checks a ``Decimal`` has at most ``max_digits`` digits, at most ``decimal_places`` of them after
+    the point.
+
+    Args:
+        max_digits: The most digits.
+        decimal_places: How many of them come after the decimal point.
+        message: Replaces each of the three default error messages (too many digits, too many decimal
+            places, too many whole digits).
+    """
+
+    def __init__(self, max_digits: int, decimal_places: int, message: str | None = None) -> None:
+        self.max_digits = max_digits
+        self.decimal_places = decimal_places
+        super().__init__(message)
+
+    def __call__(self, value: Decimal) -> None:
+        if value is None:
+            raise ValidationError("Value must not be None")
+        sign, digit_tuple, exponent = value.as_tuple()
+        if not isinstance(exponent, int):
+            raise ValidationError(f"Value {ValueDescriptions.get_shown_value(value)} is not a finite decimal")
+        if exponent >= 0:
+            digits = len(digit_tuple)
+            if digit_tuple != (0,):
+                # A positive exponent adds that many trailing zeros.
+                digits += exponent
+            decimals = 0
+        else:
+            # A negative exponent past every digit adds leading zeros after the decimal point.
+            if abs(exponent) > len(digit_tuple):
+                digits = decimals = abs(exponent)
+            else:
+                digits = len(digit_tuple)
+                decimals = abs(exponent)
+        whole_digits = digits - decimals
+
+        shown_value = ValueDescriptions.get_shown_text(value)
+        if digits > self.max_digits:
+            self._raise(f"Value '{shown_value}' has {digits} digits, more than max_digits={self.max_digits}")
+        if decimals > self.decimal_places:
+            self._raise(
+                f"Value '{shown_value}' has {decimals} decimal places, more than decimal_places={self.decimal_places}"
+            )
+        if whole_digits > (self.max_digits - self.decimal_places):
+            self._raise(
+                f"Value '{shown_value}' has {whole_digits} digits before the decimal point, more than "
+                f"{self.max_digits - self.decimal_places} allowed"
+            )

hare/fields/validators/limits/max_length_validator.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.exceptions import ValidationError
+from hare.fields.validators.limits.length_validator import LengthValidator
+
+
+class MaxLengthValidator(LengthValidator):
+    """Checks the length of a text, a list, a tuple or bytes is at most ``max_length``."""
+
+    def __init__(self, max_length: int, message: str | None = None) -> None:
+        self.max_length = max_length
+        super().__init__(message)
+
+    def __call__(self, value: str) -> None:
+        if value is None:
+            raise ValidationError("Value must not be None")
+        self._validate_type(value)
+        if len(value) > self.max_length:
+            self._raise(f"Length of '{ValueDescriptions.get_shown_text(value)}' {len(value)} > {self.max_length}")

hare/fields/validators/limits/max_value_validator.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from hare.fields.validators.limits.numeric_validator import NumericValidator
+
+
+class MaxValueValidator(NumericValidator):
+    """Checks a number - an int, a float or a ``Decimal`` - is at most ``max_value``."""
+
+    def __init__(self, max_value: int | float | Decimal, message: str | None = None) -> None:
+        self._validate_type(max_value)
+        self.max_value = max_value
+        super().__init__(message)
+
+    def __call__(self, value: int | float | Decimal) -> None:
+        self._validate_type(value)
+        if value > self.max_value:
+            self._raise(f"Value should be less or equal to {self.max_value}")

hare/fields/validators/limits/min_length_validator.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from hare.classes.value_descriptions import ValueDescriptions
+from hare.exceptions import ValidationError
+from hare.fields.validators.limits.length_validator import LengthValidator
+
+
+class MinLengthValidator(LengthValidator):
+    """Checks the length of a text, a list, a tuple or bytes is at least ``min_length``."""
+
+    def __init__(self, min_length: int, message: str | None = None) -> None:
+        self.min_length = min_length
+        super().__init__(message)
+
+    def __call__(self, value: str) -> None:
+        if value is None:
+            raise ValidationError("Value must not be None")
+        self._validate_type(value)
+        if len(value) < self.min_length:
+            self._raise(f"Length of '{ValueDescriptions.get_shown_text(value)}' {len(value)} < {self.min_length}")

hare/fields/validators/limits/min_value_validator.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from decimal import Decimal
+
+from hare.fields.validators.limits.numeric_validator import NumericValidator
+
+
+class MinValueValidator(NumericValidator):
+    """Checks a number - an int, a float or a ``Decimal`` - is at least ``min_value``."""
+
+    def __init__(self, min_value: int | float | Decimal, message: str | None = None) -> None:
+        self._validate_type(min_value)
+        self.min_value = min_value
+        super().__init__(message)
+
+    def __call__(self, value: int | float | Decimal) -> None:
+        self._validate_type(value)
+        if value < self.min_value:
+            self._raise(f"Value should be greater or equal to {self.min_value}")

hare/fields/validators/limits/numeric_validator.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import Any
+
+from hare.exceptions import ValidationError
+from hare.fields.validators.validator import Validator
+
+
+class NumericValidator(Validator):
+    """The base of the validators of a number: an int, a float or a ``Decimal``."""
+
+    types = (int, float, Decimal)
+
+    def _validate_type(self, value: Any) -> None:
+        if value is None:
+            raise ValidationError("Value must not be None")
+        if not isinstance(value, self.types):
+            raise ValidationError(f"Value must be a number, got a {type(value).__name__}")

hare/fields/validators/validator.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import abc
+from typing import Any
+
+from hare.exceptions import ValidationError
+
+
+class Validator(metaclass=abc.ABCMeta):
+    """The base of the validators a field runs on its values: a callable raising ``ValidationError``
+    for a value it refuses."""
+
+    def __init__(self, message: str | None = None) -> None:
+        """Keeps the message the validator's errors use.
+
+        Args:
+            message: Replaces the validator's default error message when given.
+        """
+        self.message = message
+
+    def _raise(self, default_message: str) -> None:
+        """Raises ``ValidationError`` with the validator's message, else ``default_message``."""
+        raise ValidationError(self.message or default_message)
+
+    @abc.abstractmethod
+    def __call__(self, value: Any) -> None:
+        """Checks a value.
+
+        Args:
+            value: The value.
+
+        Raises:
+            ValidationError: The validator refuses it.
+        """

hare/gis/__init__.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hare.classes.lazy_exports import LazyExports
+from hare.gis.constants import EXPORTED_MODULES
+
+if TYPE_CHECKING:
+    from hare.gis.enums import GeometryType
+    from hare.gis.fields import (
+        GeometryCollectionField,
+        GeometryField,
+        LineStringField,
+        MultiLineStringField,
+        MultiPointField,
+        MultiPolygonField,
+        PointField,
+        PolygonField,
+    )
+    from hare.gis.geometries import (
+        Geometry,
+        GeometryCollection,
+        LineString,
+        MultiLineString,
+        MultiPoint,
+        MultiPolygon,
+        Point,
+        Polygon,
+    )
+
+__all__ = [
+    "GeometryType",
+    "Geometry",
+    "Point",
+    "LineString",
+    "Polygon",
+    "MultiPoint",
+    "MultiLineString",
+    "MultiPolygon",
+    "GeometryCollection",
+    "GeometryField",
+    "PointField",
+    "LineStringField",
+    "PolygonField",
+    "MultiPointField",
+    "MultiLineStringField",
+    "MultiPolygonField",
+    "GeometryCollectionField",
+]
+
+
+__getattr__, __dir__ = LazyExports(__name__, EXPORTED_MODULES).get_module_hooks()

hare/gis/aggregates/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from hare.gis.aggregates.declarations import Collect, Extent, MakeLine, UnionAggregate
+
+__all__ = ["Collect", "Extent", "MakeLine", "UnionAggregate"]