openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/attributes/person/last_name_attribute.py

@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.utilities.attribute_utilities import AttributeUtilities
+from openlinktoken.attributes.validation.not_in_validator import NotInValidator
+from openlinktoken.attributes.validation.regex_validator import RegexValidator
+
+
+class LastNameAttribute(BaseAttribute):
+    """
+    Represents the last name of a person.
+
+    This class extends BaseAttribute and provides functionality for working with
+    last name fields. It recognizes "LastName" and "Surname" as valid aliases for
+    this attribute type.
+
+    The attribute normalizes values by removing diacritics, generational suffixes,
+    and non-alphabetic characters. It validates that names are either:
+    - Longer than 2 characters, or
+    - Exactly 2 characters containing at least one vowel (including names with two vowels), or
+    - The specific last name "Ng"
+    """
+
+    NAME = "LastName"
+    ALIASES = [NAME, "Surname"]
+
+    # Regular expression pattern for validating last names.
+    #
+    # This pattern matches:
+    #  - Any name with 3 or more characters (including spaces within)
+    #  - 2-character names with at least one vowel (consonant+vowel, vowel+consonant, or two vowels)
+    #  - The special case "Ng" (case-insensitive)
+    #  - Allows optional leading and trailing whitespace
+    #
+    # Breakdown of the regex:
+    #   ^\s*                                 Start of string, optional leading whitespace
+    #   (?:                                  Start of non-capturing group:
+    #     (?:.{3,})                          Any name with 3+ characters
+    #     |                                  OR
+    #     (?:[^aeiouAEIOU\s][aeiouAEIOU])    2-char: consonant + vowel (no spaces)
+    #     |                                  OR
+    #     (?:[aeiouAEIOU][^aeiouAEIOU\s])    2-char: vowel + consonant (no spaces)
+    #     |                                  OR
+    #     (?:[aeiouAEIOU]{2})                2-char: two vowels (no spaces)
+    #     |                                  OR
+    #     (?:[Nn][Gg])                       Special case: "Ng" (case-insensitive)
+    #   )
+    #   \s*$                                 Optional trailing whitespace, end of string
+    LAST_NAME_REGEX = (
+        r"^\s*(?:(?:.{3,})|(?:[^aeiouAEIOU\s][aeiouAEIOU])|"
+        r"(?:[aeiouAEIOU][^aeiouAEIOU\s])|(?:[aeiouAEIOU]{2})|(?:[Nn][Gg]))\s*$"
+    )
+
+    def __init__(self):
+        """Initialize the LastNameAttribute with validation rules."""
+        validation_rules = [NotInValidator(AttributeUtilities.COMMON_PLACEHOLDER_NAMES)]
+        super().__init__(validation_rules)
+        self.regex_validator = RegexValidator(self.LAST_NAME_REGEX)
+
+    def validate(self, value: str) -> bool:
+        """
+        Validate the last name value.
+
+        Args:
+            value: The last name value to validate
+
+        Returns:
+            True if the value is a valid last name, False otherwise
+        """
+        if value is None:
+            return False
+
+        # First, check placeholder values on the ORIGINAL value using built-in validators
+        # This ensures "N/A", "<masked>", etc. are properly rejected
+        if not super().validate(value):
+            return False
+
+        # Normalize the value for pattern matching
+        # This ensures that validate(normalize(x)) == validate(normalize(normalize(x)))
+        normalized_value = self.normalize(value)
+
+        # Reject single letters after normalization
+        if len(normalized_value) == 1:
+            return False
+
+        # Check that normalized value is not a placeholder
+        # This ensures idempotency: values like "TEST16" normalize to "TEST" which is a placeholder
+        if not super().validate(normalized_value):
+            return False
+
+        # Validate the normalized value against the regex pattern
+        # Use the pre-created regex validator instance to avoid creating new instances on each call
+        return self.regex_validator.eval(normalized_value)
+
+    def get_name(self) -> str:
+        """
+        Get the name of the attribute.
+
+        Returns:
+            The name of the attribute ("LastName")
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """
+        Get the aliases for the attribute.
+
+        Returns:
+            List of aliases for the attribute (["LastName", "Surname"])
+        """
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """
+        Normalize the last name value.
+
+        This method performs the following normalization steps:
+        1. Remove diacritics (accents)
+        2. Remove generational suffixes (Jr, Sr, III, etc.)
+        3. Remove non-alphabetic characters (spaces, dashes, etc.)
+
+        Args:
+            value: The last name value to normalize
+
+        Returns:
+            The normalized last name value
+        """
+
+        # Step 1: Remove diacritics (é → e, ñ → n, etc.)
+        normalized_value = AttributeUtilities.normalize_diacritics(value)
+
+        # Step 2: Remove generational suffixes (Jr, Sr, III, etc.)
+        value_without_suffix = AttributeUtilities.GENERATIONAL_SUFFIX_PATTERN.sub("", normalized_value)
+
+        # If the generational suffix removal doesn't result in an empty string,
+        # continue with the value without suffix, otherwise use the value with suffix
+        # as last name
+        if value_without_suffix.strip():
+            normalized_value = value_without_suffix
+
+        # Step 4: Remove dashes, spaces and other non-alphanumeric characters
+        normalized_value = AttributeUtilities.NON_ALPHABETIC_PATTERN.sub("", normalized_value)
+
+        return normalized_value

openlinktoken/attributes/person/postal_code_attribute.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.combined_attribute import CombinedAttribute
+from openlinktoken.attributes.person.canadian_postal_code_attribute import CanadianPostalCodeAttribute
+from openlinktoken.attributes.person.us_postal_code_attribute import USPostalCodeAttribute
+from openlinktoken.attributes.serializable_attribute import SerializableAttribute
+
+
+class PostalCodeAttribute(CombinedAttribute):
+    """
+    Represents the postal code of a person.
+
+    This class combines US and Canadian postal code implementations to provide
+    functionality for working with postal code fields. It recognizes "PostalCode",
+    "ZipCode", "ZIP3", "ZIP4", and "ZIP5" as valid aliases for this attribute type.
+
+    The attribute performs normalization on input values, converting them to a
+    standard format. Supports both US ZIP codes (3, 4, or 5 digits) and Canadian
+    postal codes (3, 4, 5, or 6 characters in A1A 1A1 format). ZIP-3 codes (3 digits/characters)
+    are automatically padded to full length during normalization.
+
+    This class instantiates postal code attributes with min_length=3 to support
+    partial postal codes (ZIP-3, ZIP-4, and partial Canadian formats).
+    """
+
+    NAME = "PostalCode"
+    ALIASES = [NAME, "ZipCode", "ZIP3", "ZIP4", "ZIP5"]
+
+    def __init__(self):
+        self._implementations = [USPostalCodeAttribute(min_length=3), CanadianPostalCodeAttribute(min_length=3)]
+        super().__init__()
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()
+
+    def get_attribute_implementations(self) -> List[SerializableAttribute]:
+        return self._implementations

openlinktoken/attributes/person/sex_attribute.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.validation.regex_validator import RegexValidator
+
+
+class SexAttribute(BaseAttribute):
+    """
+    Represents an assigned sex of a person.
+
+    This class extends BaseAttribute and provides functionality for working with
+    these type of fields. It recognizes "Sex" or "Gender" as valid aliases for
+    this attribute type.
+
+    The attribute performs normalization on input values, converting them to a
+    standard format (Male or Female).
+    """
+
+    NAME = "Sex"
+    ALIASES = [NAME, "Gender"]
+
+    # Regular expression pattern for validating sex/gender values
+    VALIDATE_REGEX = r"^\s*([Mm](ale)?|[Ff](emale)?)\s*$"
+
+    def __init__(self):
+        validation_rules = [RegexValidator(self.VALIDATE_REGEX)]
+        super().__init__(validation_rules)
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """Normalize sex value to 'Male' or 'Female'."""
+        if not value:
+            return None
+
+        first_char = value.strip()[0].lower()
+        if first_char == "m":
+            return "Male"
+        elif first_char == "f":
+            return "Female"
+        else:
+            return None  # Return None if can't normalize

openlinktoken/attributes/person/social_security_number_attribute.py

@@ -0,0 +1,119 @@
+# src/openlinktoken/attributes/person/social_security_number_attribute.py
+# SPDX-License-Identifier: MIT
+
+import locale
+import re
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.utilities.attribute_utilities import AttributeUtilities
+from openlinktoken.attributes.validation.not_in_validator import NotInValidator
+from openlinktoken.attributes.validation.regex_validator import RegexValidator
+
+
+class SocialSecurityNumberAttribute(BaseAttribute):
+    """
+    Represents the social security number attribute.
+
+    This class extends BaseAttribute and provides functionality for working with
+    social security number fields. It recognizes "SocialSecurityNumber" and
+    "NationalIdentificationNumber" as valid aliases for this attribute type.
+
+    The attribute performs normalization on input values, converting them to a
+    standard format (xxx-xx-xxxx).
+    """
+
+    NAME = "SocialSecurityNumber"
+    ALIASES = [NAME, "NationalIdentificationNumber"]
+    DASH = "-"
+    SSN_FORMAT = "{:09d}"
+
+    MIN_SSN_LENGTH = 7
+    SSN_LENGTH = 9
+
+    # Get decimal separator for current locale
+    try:
+        DECIMAL_SEPARATOR = locale.localeconv()["decimal_point"]
+    except Exception:
+        DECIMAL_SEPARATOR = "."
+
+    # Regular expression to validate Social Security Numbers
+    SSN_REGEX = (
+        rf"^(?:\d{{7,9}}(?:[{DECIMAL_SEPARATOR}]0*)?)$"
+        rf"|(?:^(?!000|666|9\d\d)(\d{{3}})-?(?!00)(\d{{2}})-?(?!0000)(\d{{4}})$)"
+    )
+
+    DIGITS_ONLY_PATTERN = re.compile(r"\d+")
+
+    INVALID_SSNS = {
+        "111-11-1111",
+        "222-22-2222",
+        "333-33-3333",
+        "444-44-4444",
+        "555-55-5555",
+        "777-77-7777",
+        "888-88-8888",
+        "001-23-4567",
+        "010-10-1010",
+        "012-34-5678",
+        "087-65-4321",
+        "098-76-5432",
+        "099-99-9999",
+        "111-22-3333",
+        "121-21-2121",
+        "123-45-6789",
+    }
+
+    def __init__(self):
+        validation_rules = [NotInValidator(self.INVALID_SSNS), RegexValidator(self.SSN_REGEX)]
+        super().__init__(validation_rules)
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()
+
+    def normalize(self, original_value: str) -> str:
+        """
+        Normalize the social security number value. Remove any dashes and format the
+        value as xxx-xx-xxxx. If not possible return the original but trimmed value.
+        """
+        if not original_value:
+            return original_value
+
+        # Remove any whitespace
+        trimmed_value = AttributeUtilities.remove_whitespace(original_value.strip())
+
+        # Remove any dashes for now
+        normalized_value = trimmed_value.replace(self.DASH, "")
+
+        # Remove decimal point/separator and all following numbers if present
+        decimal_index = normalized_value.find(self.DECIMAL_SEPARATOR)
+        if decimal_index != -1:
+            normalized_value = normalized_value[:decimal_index]
+
+        # Check if the string contains only digits
+        if not self.DIGITS_ONLY_PATTERN.fullmatch(normalized_value):
+            return original_value  # Return original if contains non-numeric characters
+
+        if len(normalized_value) < self.MIN_SSN_LENGTH or len(normalized_value) > self.SSN_LENGTH:
+            return original_value  # Invalid length for SSN
+
+        normalized_value = self._pad_with_zeros(normalized_value)
+        return self._format_with_dashes(normalized_value)
+
+    def _pad_with_zeros(self, ssn: str) -> str:
+        """Pad SSN with leading zeros if between 7-8 digits."""
+        if self.MIN_SSN_LENGTH <= len(ssn) < self.SSN_LENGTH:
+            return self.SSN_FORMAT.format(int(ssn))
+        return ssn
+
+    def _format_with_dashes(self, value: str) -> str:
+        """Format 9-digit SSN with dashes (123-45-6789)."""
+        if len(value) == self.SSN_LENGTH:
+            area_number = value[:3]
+            group_number = value[3:5]
+            serial_number = value[5:]
+            return self.DASH.join([area_number, group_number, serial_number])
+        return value

openlinktoken/attributes/person/us_postal_code_attribute.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MIT
+
+import re
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.utilities.attribute_utilities import AttributeUtilities
+from openlinktoken.attributes.validation.not_starts_with_validator import NotStartsWithValidator
+from openlinktoken.attributes.validation.regex_validator import RegexValidator
+
+
+class USPostalCodeAttribute(BaseAttribute):
+    """
+    Represents US postal codes (ZIP codes).
+
+    This class handles validation and normalization of US ZIP codes, supporting
+    both 5-digit format (12345) and 5+4 format (12345-6789).
+    """
+
+    NAME = "USPostalCode"
+    ALIASES = [NAME, "USZipCode"]
+
+    # Regular expression pattern for validating US postal (ZIP) codes
+    # Supports 3-digit (ZIP-3), 4-digit (ZIP-4), 5-digit, and 9-digit formats
+    US_ZIP_REGEX = r"^\s*(\d{3}|\d{4}|\d{5}(-\d{4})?|\d{9})\s*$"
+
+    INVALID_ZIP_CODES = {
+        # 5-digit invalid codes
+        "11111",
+        "22222",
+        "33333",
+        "66666",
+        "77777",
+        "99999",
+        # Commonly used placeholders
+        "01234",
+        "12345",
+        "54321",
+        "98765",
+        # 3-digit invalid codes (ZIP-3 prefixes that should be invalidated)
+        # Note: "000" invalidates "00000" and all codes starting with "000"
+        # Note: "555" invalidates "55555" and all codes starting with "555"
+        # Note: "888" invalidates "88888" and all codes starting with "888"
+        "000",
+        "555",
+        "888",
+    }
+
+    def __init__(self, min_length: int = 5):
+        """
+        Initialize USPostalCodeAttribute.
+
+        Args:
+            min_length: Minimum length for postal codes (default: 5)
+        """
+        validation_rules = [RegexValidator(self.US_ZIP_REGEX), NotStartsWithValidator(self.INVALID_ZIP_CODES)]
+        super().__init__(validation_rules)
+        self.min_length = min_length
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """
+        Normalize a US ZIP code to standard 5-digit format.
+
+        For US ZIP codes:
+        - Codes shorter than min_length are rejected (return original)
+        - 3-digit ZIP code (ZIP-3) is padded with "00" to create 5-digit format
+          (e.g., "951" becomes "95100") if min_length <= 3
+        - 4-digit ZIP code (ZIP-4) is padded with "0" to create 5-digit format
+          (e.g., "1234" becomes "12340") if min_length <= 4
+        - 5-digit or longer ZIP codes return the first 5 digits (e.g., "12345-6789" becomes "12345")
+        If the input value is null or doesn't match US ZIP pattern, the original
+        trimmed value is returned.
+        """
+        if not value:
+            return value
+
+        trimmed = AttributeUtilities.remove_whitespace(value.strip())
+
+        # Check if it's a 3-digit ZIP code (ZIP-3) - pad with "00" if min_length allows
+        if re.match(r"^\d{3}$", trimmed):
+            if self.min_length <= 3:
+                return trimmed + "00"
+            # If min_length > 3, reject this by returning original
+            return value.strip()
+
+        # Check if it's a 4-digit ZIP code (ZIP-4) - pad with "0" if min_length allows
+        if re.match(r"^\d{4}$", trimmed):
+            if self.min_length <= 4:
+                return trimmed + "0"
+            # If min_length > 4, reject this by returning original
+            return value.strip()
+
+        # Check if it's a US ZIP code (5 digits, 5+4 with dash, or 9 digits without dash)
+        if re.match(r"\d{5}(-?\d{4})?", trimmed) or re.match(r"\d{9}", trimmed):
+            return trimmed[:5]
+
+        # For values that don't match US ZIP patterns, return trimmed original
+        return value.strip()

openlinktoken/attributes/serializable_attribute.py

@@ -0,0 +1,7 @@
+from openlinktoken.attributes.attribute import Attribute
+
+
+class SerializableAttribute(Attribute):
+    """Serializable attribute interface extending Attribute."""
+
+    pass

openlinktoken/attributes/utilities/__init__.py

@@ -0,0 +1,7 @@
+"""Utility helpers for attribute processing."""
+
+from .attribute_utilities import AttributeUtilities
+
+__all__ = [
+    "AttributeUtilities",
+]