human-input-validator 0.1.0__py3-none-any.whl

human_input_validator/__init__.py

@@ -0,0 +1,25 @@
+"""Validation and normalization for common human-entered values."""
+
+from .validators import (
+    ValidationError,
+    email,
+    country,
+    username,
+    phonenumber,
+    creditcard,
+    name,
+    lastname,
+    is_valid_url
+)
+
+__all__ = [
+    "ValidationError",
+    "email",
+    "country",
+    "username",
+    "phonenumber",
+    "creditcard",
+    "name",
+    "lastname",
+    "is_valid_url"
+]

human_input_validator/validators.py

@@ -0,0 +1,134 @@
+"""Pure validators for user-entered values.
+
+Each function returns a normalized value or raises :class:`ValidationError`.
+"""
+
+from __future__ import annotations
+
+import functools
+import gettext
+import os
+import re
+import urllib.parse
+import pycountry
+
+
+class ValidationError(ValueError):
+    """Raised when a human-entered value cannot be validated."""
+
+
+_EMAIL_PATTERN = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+_USERNAME_PATTERN = re.compile(r"^[a-zA-Z0-9]+$")
+
+
+@functools.lru_cache(maxsize=1)
+def _localized_country_names() -> dict[str, str]:
+    """Map lower-cased, translated country names (e.g. 'deutschland') to alpha-2 codes."""
+    index: dict[str, str] = {}
+    for locale in os.listdir(pycountry.LOCALES_DIR):
+        try:
+            translation = gettext.translation("iso3166-1", pycountry.LOCALES_DIR, languages=[locale])
+        except FileNotFoundError:
+            continue
+        for entry in pycountry.countries:
+            for candidate in filter(None, (entry.name, getattr(entry, "official_name", None))):
+                translated = translation.gettext(candidate).strip().lower()
+                index.setdefault(translated, entry.alpha_2)
+    return index
+
+
+def email(value: str) -> str:
+    """Return a trimmed, lower-case email address."""
+    normalized = value.strip().lower()
+    if not _EMAIL_PATTERN.fullmatch(normalized):
+        raise ValidationError("Enter a valid email address.")
+    return normalized
+
+
+def country(value: str) -> str:
+    """Return the official name of an ISO 3166-1 country, given its name or code in any supported language."""
+    normalized = value.strip()
+    try:
+        result = pycountry.countries.lookup(normalized)
+        return result.name
+    except LookupError:
+        pass
+
+    alpha_2 = _localized_country_names().get(normalized.lower())
+    if alpha_2 is None:
+        raise ValidationError("Please enter a valid country")
+    result = pycountry.countries.get(alpha_2=alpha_2)
+    if result is None:
+        raise ValidationError("Please enter a valid country")
+    return result.name
+
+
+def username(value: str, max_length: int = 12) -> str:
+    """Checks a username length and allowed characters"""
+    normalized = value.strip()
+    if not _USERNAME_PATTERN.fullmatch(normalized):
+        raise ValidationError("Enter a valid username.")
+    if len(value) > max_length:
+        raise ValidationError(f"Username can be max {max_length} letters long")
+
+    return normalized.lower()
+
+
+def phonenumber(value: str, pattern: str | list[str]) -> str:
+    """Checks a phone number against one or more patterns, where '*' or '#' matches any digit."""
+    normalized = value.strip()
+    patterns = [pattern] if isinstance(pattern, str) else pattern
+    if not any(_matches_phone_pattern(normalized, candidate) for candidate in patterns):
+        raise ValidationError("Enter a valid phone number.")
+    return normalized
+
+
+def _matches_phone_pattern(value: str, pattern: str) -> bool:
+    if len(value) != len(pattern):
+        return False
+    return all(v.isdigit() if p in "*#" else v == p for v, p in zip(value, pattern))
+
+
+def creditcard(value: str) -> str:
+    """Checks a creditcard number to be almost valid."""
+    normalized = re.sub(r"[\s-]", "", value.strip())
+    if not normalized.isdigit():
+        raise ValidationError("Enter a valid creditcard number.")
+    valid = False
+    if len(normalized) >= 13 and len(normalized) <= 19:
+        digits = [int(d) for d in reversed(normalized)]
+        for i in range(1, len(digits), 2):
+            digits[i] = digits[i] * 2 - 9 if digits[i] * 2 > 9 else digits[i] * 2
+        valid = sum(digits) % 10 == 0
+
+    if not valid:
+        raise ValidationError("Enter a valid creditcard number.")
+    return normalized
+
+
+def name(value: str) -> str:
+    """Return a trimmed name with each part capitalized."""
+    normalized = value.strip()
+    if not normalized.replace(" ", "").isalpha():
+        raise ValidationError("Enter a valid name.")
+    return " ".join(part.capitalize() for part in normalized.split())
+
+
+def lastname(value: str) -> str:
+    """Return a trimmed last name with each part capitalized."""
+    normalized = value.strip()
+    if not normalized.replace(" ", "").isalpha():
+        raise ValidationError("Enter a valid last name.")
+    return " ".join(part.capitalize() for part in normalized.split())
+
+
+def is_valid_url(value: str) -> str:
+    """Checks if the given value is a valid HTTP(S) URL."""
+
+    normalized = value.strip()
+    parsed = urllib.parse.urlparse(normalized)
+
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValidationError("Enter a valid URL.")
+
+    return normalized

human_input_validator-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: human-input-validator
+Version: 0.1.0
+Summary: Small validators for common human-entered data.
+Author: Snorlena
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pycountry>=26.2
+
+# Human-input-validator
+
+`Human-input-validator` validates and normalizes common data entered by people. It
+provides validators for email addresses, countries, usernames, phone
+numbers, names, and credit card numbers.
+
+```python
+from human_input_validator import (
+  email,
+  country,
+  username,
+  phonenumber,
+  creditcard,
+  name,
+  lastname,
+  is_valid_url
+)
+
+customer_email = email("Ada.Lovelace@Example.COM")
+customer_country = country("SWEDEN ")
+customer_username = username("JohnDoe ")
+customer_phone = phonenumber("08-0000000", "**-*******")
+customer_card = creditcard("4111 1111 1111 1111")
+customer_name = name("ada lovelace")
+customer_lastname = lastname("lovelace")
+customer_url = is_valid_url("https://example.com ")
+```
+
+Each function returns a normalized value or raises `ValidationError` for
+invalid input.
+
+- `email(value)` — returns a trimmed, lower-cased email address.
+- `country(value)` — returns the official ISO 3166-1 country name, given a
+  name or code.
+- `username(value, max_length=12)` — returns a lower-cased username, checking
+  length and allowed characters.
+- `phonenumber(value, pattern)` — checks a phone number against one or more
+  masks, where `*` or `#` matches any digit and other characters must match
+  literally. `pattern` accepts a single mask or a list of masks.
+- `creditcard(value)` — checks a credit card number's length and Luhn
+  checksum, ignoring spaces and dashes.
+- `name(value)` — returns a trimmed, capitalized name.
+- `lastname(value)` — returns a trimmed, capitalized last name.
+- `is_valid_url` — checks if an http/https url has correct syntax and returns a trimmed one
+
+## Development
+
+Run the test suite without installing the package:
+
+```sh
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+```

human_input_validator-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+human_input_validator/__init__.py,sha256=HLgZ38DP9ZgUw_h415Z20tgMjcNlRg-uiNvq_QvO7OU,396
+human_input_validator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+human_input_validator/validators.py,sha256=ywywVm0RSf64etHoXw-fJuNzmD1NiVNAx7KS-2Zp92k,4668
+human_input_validator-0.1.0.dist-info/METADATA,sha256=nV-GkdFuQY7oMw6QJstUuDEyypRu4GynFL7i_sio5tM,2040
+human_input_validator-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+human_input_validator-0.1.0.dist-info/top_level.txt,sha256=LflQgEAa6I_lUWbGb0SG87GXH2Rb-_r6kVmgHkFa87M,22
+human_input_validator-0.1.0.dist-info/RECORD,,

human_input_validator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

human_input_validator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+human_input_validator