openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/attributes/general/integer_attribute.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List, Optional
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.validation import RegexValidator
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class IntegerAttribute(BaseAttribute):
+    """Represents a generic integer attribute.
+
+    This class extends BaseAttribute and provides functionality for working with
+    integer fields. It recognizes "Integer" as a valid alias for this attribute type.
+
+    The attribute performs normalization on input values by trimming whitespace
+    and validates that the input is a valid integer.
+    """
+
+    NAME = "Integer"
+    ALIASES = [NAME]
+
+    # Regular expression pattern for validating integer format with optional sign
+    VALIDATION_PATTERN = r"^\s*[+-]?\d+\s*$"
+
+    def __init__(self, additional_validators: Optional[List[SerializableAttributeValidator]] = None):
+        """
+        Initialize the IntegerAttribute with optional additional validators.
+
+        Args:
+            additional_validators: Optional list of additional validators to apply
+        """
+        validation_rules: List[SerializableAttributeValidator] = [RegexValidator(self.VALIDATION_PATTERN)]
+        if additional_validators:
+            validation_rules.extend(additional_validators)
+        super().__init__(validation_rules)
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "Integer"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """Normalize the integer value by trimming whitespace and parsing.
+
+        Args:
+            value: The integer string to normalize
+
+        Returns:
+            str: The normalized integer value
+
+        Raises:
+            ValueError: If the integer is not valid or empty
+        """
+        if value is None:
+            raise ValueError("Integer value cannot be null")
+        if not value:
+            raise ValueError("Invalid integer format: empty or whitespace")
+
+        trimmed = value.strip()
+
+        # Validate it's a valid integer
+        try:
+            int_value = int(trimmed)
+            return str(int_value)
+        except ValueError:
+            raise ValueError(f"Invalid integer format: {value}")

openlinktoken/attributes/general/record_id_attribute.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.general.string_attribute import StringAttribute
+
+
+class RecordIdAttribute(StringAttribute):
+    """Represents a record identifier attribute.
+
+    This class extends StringAttribute and provides functionality for working with
+    record ID fields. It recognizes "RecordId" as a valid alias for this
+    attribute type.
+
+    The attribute normalizes values by trimming whitespace (inherited from StringAttribute).
+    It validates that the value is not null or empty using the default BaseAttribute
+    validation rules.
+    """
+
+    NAME = "RecordId"
+    ALIASES = [NAME, "Id"]
+
+    def __init__(self):
+        # Use validation rules from StringAttribute
+        super().__init__()
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "RecordId"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()

openlinktoken/attributes/general/string_attribute.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+
+
+class StringAttribute(BaseAttribute):
+    """Represents a generic string attribute.
+
+    This class extends BaseAttribute and provides functionality for working with
+    string fields. It normalizes values by trimming whitespace.
+
+    The attribute validates that the value is not null or empty using the
+    default BaseAttribute validation rules.
+    """
+
+    NAME = "String"
+    ALIASES = [NAME, "Text"]
+
+    def __init__(self):
+        # Use default validation rules from BaseAttribute (not null or empty)
+        super().__init__()
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "String"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """Normalize the string value by trimming whitespace.
+
+        Args:
+            value: The string value to normalize
+
+        Returns:
+            str: The trimmed string value
+
+        Raises:
+            ValueError: If value is None
+        """
+        if value is None:
+            raise ValueError("String value cannot be null")
+        return value.strip()

openlinktoken/attributes/general/year_attribute.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+
+import re
+from typing import List
+
+from openlinktoken.attributes.general.integer_attribute import IntegerAttribute
+from openlinktoken.attributes.validation import RegexValidator
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class YearAttribute(IntegerAttribute):
+    """Represents a generic year attribute.
+
+    This class extends IntegerAttribute and provides functionality for working with
+    year fields. It recognizes "Year" as a valid alias for this attribute type.
+
+    The attribute performs normalization on input values by trimming whitespace
+    and validates that the year is a 4-digit year format.
+    """
+
+    NAME = "Year"
+    ALIASES = [NAME]
+
+    # Regular expression pattern for validating 4-digit year format with optional whitespace
+    VALIDATION_PATTERN = re.compile(r"^\s*\d{4}\s*$")
+    # Pattern for extracting just the 4 digits
+    YEAR_PATTERN = re.compile(r"\d{4}")
+
+    def __init__(self, additional_validators: List[SerializableAttributeValidator] = None):
+        """
+        Initialize the YearAttribute with optional additional validators.
+
+        Args:
+            additional_validators: Optional list of additional validators to apply
+        """
+        validation_rules = [RegexValidator(self.VALIDATION_PATTERN)]
+        if additional_validators:
+            validation_rules.extend(additional_validators)
+        super().__init__(validation_rules)
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "Year"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """Normalize the year value by trimming whitespace.
+
+        Args:
+            value: The year string to normalize
+
+        Returns:
+            str: The normalized year value as a string (leading zeros removed)
+
+        Raises:
+            ValueError: If the year is not a valid 4-digit year or empty
+        """
+        if not value:
+            raise ValueError(f"Invalid year format: {value}")
+
+        trimmed = value.strip()
+
+        # Validate it's exactly 4 digits using the pattern before delegating normalization
+        if not self.YEAR_PATTERN.match(trimmed):
+            raise ValueError(f"Invalid year format: {value}")
+
+        return super().normalize(trimmed)

openlinktoken/attributes/person/__init__.py

@@ -0,0 +1,25 @@
+"""Person attribute implementations."""
+
+from .age_attribute import AgeAttribute
+from .birth_date_attribute import BirthDateAttribute
+from .birth_year_attribute import BirthYearAttribute
+from .canadian_postal_code_attribute import CanadianPostalCodeAttribute
+from .first_name_attribute import FirstNameAttribute
+from .last_name_attribute import LastNameAttribute
+from .postal_code_attribute import PostalCodeAttribute
+from .sex_attribute import SexAttribute
+from .social_security_number_attribute import SocialSecurityNumberAttribute
+from .us_postal_code_attribute import USPostalCodeAttribute
+
+__all__ = [
+    "AgeAttribute",
+    "BirthDateAttribute",
+    "BirthYearAttribute",
+    "CanadianPostalCodeAttribute",
+    "FirstNameAttribute",
+    "LastNameAttribute",
+    "PostalCodeAttribute",
+    "SexAttribute",
+    "SocialSecurityNumberAttribute",
+    "USPostalCodeAttribute",
+]

openlinktoken/attributes/person/age_attribute.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.general.integer_attribute import IntegerAttribute
+from openlinktoken.attributes.validation.age_range_validator import AgeRangeValidator
+
+
+class AgeAttribute(IntegerAttribute):
+    """Represents the age attribute.
+
+    This class extends IntegerAttribute and provides functionality for working with
+    age fields. It recognizes "Age" as a valid alias for this attribute type.
+
+    The attribute performs normalization on input values by trimming whitespace
+    and validates that the age is a valid integer between 0 and 120 (inherited from
+    IntegerAttribute for format validation).
+    """
+
+    NAME = "Age"
+    ALIASES = [NAME]
+
+    def __init__(self):
+        """Initialize the AgeAttribute with age range validation."""
+        super().__init__([AgeRangeValidator()])
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "Age"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()

openlinktoken/attributes/person/birth_date_attribute.py

@@ -0,0 +1,40 @@
+# src/openlinktoken/attributes/person/birth_date_attribute.py
+from datetime import date
+from typing import List
+
+from openlinktoken.attributes.general.date_attribute import DateAttribute
+from openlinktoken.attributes.validation.date_range_validator import DateRangeValidator
+
+
+class BirthDateAttribute(DateAttribute):
+    """Represents the birth date attribute.
+
+    This class extends DateAttribute and provides functionality for working with
+    birth date fields. It recognizes "BirthDate" as a valid alias for this
+    attribute type.
+
+    The attribute performs normalization on input values, converting them to a
+    standard format (yyyy-MM-dd).
+
+    Supported formats:
+    - yyyy-MM-dd
+    - yyyy/MM/dd
+    - MM/dd/yyyy
+    - MM-dd-yyyy
+    - dd.MM.yyyy
+    """
+
+    NAME = "BirthDate"
+    ALIASES = [NAME]
+
+    def __init__(self):
+        # Birth dates must be between 1910-01-01 and today
+        min_date = date(1910, 1, 1)
+        validator = DateRangeValidator(min_date=min_date, use_current_as_max=True)
+        super().__init__(additional_validators=[validator])
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()

openlinktoken/attributes/person/birth_year_attribute.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: MIT
+
+from typing import List
+
+from openlinktoken.attributes.general.year_attribute import YearAttribute
+from openlinktoken.attributes.validation.year_range_validator import YearRangeValidator
+
+
+class BirthYearAttribute(YearAttribute):
+    """Represents the birth year attribute.
+
+    This class extends YearAttribute and provides functionality for working with
+    birth year fields. It recognizes "BirthYear" as a valid alias for this attribute type.
+
+    The attribute performs normalization on input values by trimming whitespace
+    and validates that the birth year is a 4-digit year between 1910 and the current year.
+    """
+
+    NAME = "BirthYear"
+    ALIASES = [NAME, "YearOfBirth"]
+
+    def __init__(self):
+        super().__init__(additional_validators=[YearRangeValidator()])
+
+    def get_name(self) -> str:
+        """Get the name of the attribute.
+
+        Returns:
+            str: The name "BirthYear"
+        """
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute.
+
+        Returns:
+            List[str]: A list containing the aliases for this attribute
+        """
+        return self.ALIASES.copy()

openlinktoken/attributes/person/canadian_postal_code_attribute.py

@@ -0,0 +1,165 @@
+# 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 CanadianPostalCodeAttribute(BaseAttribute):
+    """
+    Represents Canadian postal codes.
+
+    This class handles validation and normalization of Canadian postal codes,
+    supporting the A1A 1A1 format (letter-digit-letter space digit-letter-digit).
+    """
+
+    NAME = "CanadianPostalCode"
+    ALIASES = [NAME, "CanadianZipCode"]
+
+    # Regular expression pattern for validating Canadian postal codes
+    # Supports 3-character (ZIP-3), partial (4-5 char), and full 6-character formats
+    CANADIAN_POSTAL_REGEX = r"^\s*[A-Za-z]\d[A-Za-z](\s?\d([A-Za-z]\d?)?)?\s*$"
+
+    # Full 6-character invalid postal codes
+    INVALID_ZIP_CODES = {
+        # 6-character Canadian postal code placeholders
+        "A1A 1A1",
+        "X0X 0X0",
+        "Y0Y 0Y0",
+        "Z0Z 0Z0",
+        "A0A 0A0",
+        "B1B 1B1",
+        "C2C 2C2",
+        "K1A 0A6",  # Canadian government address
+        "H0H 0H0",  # Santa Claus postal code
+    }
+
+    # 3-character codes that are invalid when standalone (not when part of full codes)
+    INVALID_ZIP3_CODES = {
+        "K1A",  # Canadian government
+        "M7A",  # Government of Ontario
+        "H0H",  # Santa Claus
+    }
+
+    def __init__(self, min_length: int = 6):
+        """
+        Initialize CanadianPostalCodeAttribute.
+
+        Args:
+            min_length: Minimum length for postal codes (default: 6)
+        """
+        validation_rules = []
+        super().__init__(validation_rules)
+        self.min_length = min_length
+        self.regex_validator = RegexValidator(self.CANADIAN_POSTAL_REGEX)
+        self.not_starts_with_validator = NotStartsWithValidator(self.INVALID_ZIP_CODES)
+
+    def validate(self, value: str) -> bool:
+        """
+        Validate the Canadian postal code value.
+
+        Args:
+            value: The postal code value to validate
+
+        Returns:
+            True if the value is a valid Canadian postal code, False otherwise
+        """
+        if value is None:
+            return False
+
+        # First, check the regex pattern on the ORIGINAL value
+        # This ensures the format is valid before normalization
+        if not self.regex_validator.eval(value):
+            return False
+
+        # Normalize the value to ensure idempotency
+        # This converts to uppercase and formats consistently
+        normalized_value = self.normalize(value)
+
+        # Validate the NORMALIZED value against the full invalid codes
+        # This ensures "k1a 0a6" and "K1A 0A6" are treated consistently
+        for invalid_code in self.INVALID_ZIP_CODES:
+            if normalized_value.upper() == invalid_code.upper():
+                return False
+
+        # Additionally check for codes starting with invalid ZIP-3 prefixes
+        # But ONLY for padded partial codes (normalized length is 7 and ends with padding)
+        # Full 6-character codes (without padding) are checked against the exact invalid list above
+        if len(normalized_value) == 7 and " " in normalized_value:
+            zip3 = normalized_value[:3].upper()
+            for invalid_zip3 in self.INVALID_ZIP3_CODES:
+                if zip3 == invalid_zip3.upper():
+                    # Check if this is a padded partial code
+                    # Padded codes end with "000" (3-char), "A0" (4-char), or "0" (5-char after last letter)
+                    last_part = normalized_value[4:]  # After "K1A "
+                    if (
+                        last_part == "000"  # K1A → K1A 000
+                        or re.match(r"\dA0$", last_part)  # K1A1 → K1A 1A0
+                        or re.match(r"\d[A-Z]0$", last_part)
+                    ):  # K1A1A → K1A 1A0
+                        return False
+
+        return True
+
+    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 Canadian postal code to standard A1A 1A1 format.
+
+        For Canadian postal codes:
+        - Codes shorter than min_length are rejected (return original)
+        - 3-character format (e.g., "J1X") is padded with " 000" to create full format
+          (e.g., "J1X 000") if min_length <= 3
+        - 4-character format (e.g., "J1X1") is padded with "A0" to create full format
+          (e.g., "J1X 1A0") if min_length <= 4
+        - 5-character format (e.g., "J1X1A") is padded with "0" to create full format
+          (e.g., "J1X 1A0") if min_length <= 5
+        - 6-character format returns uppercase format with space (e.g., "k1a0a6" becomes "K1A 0A6")
+        If the input value is null or doesn't match Canadian postal pattern, the original
+        trimmed value is returned.
+        """
+        if not value:
+            return value
+
+        trimmed = AttributeUtilities.remove_whitespace(value.strip())
+
+        # Check if it's a 3-character Canadian postal code (ZIP-3) - pad with " 000" if min_length allows
+        if re.match(r"^[A-Za-z]\d[A-Za-z]$", trimmed):
+            if self.min_length <= 3:
+                upper = trimmed.upper()
+                return f"{upper} 000"
+            # If min_length > 3, reject this by returning original
+            return value.strip()
+
+        # Check if it's a 4-character partial postal code (e.g., "A1A1") - pad with "A0" if min_length allows
+        if re.match(r"^[A-Za-z]\d[A-Za-z]\d$", trimmed):
+            if self.min_length <= 4:
+                upper = trimmed.upper()
+                return f"{upper[:3]} {upper[3]}A0"
+            # If min_length > 4, reject this by returning original
+            return value.strip()
+
+        # Check if it's a 5-character partial postal code (e.g., "A1A1A") - pad with "0" if min_length allows
+        if re.match(r"^[A-Za-z]\d[A-Za-z]\d[A-Za-z]$", trimmed):
+            if self.min_length <= 5:
+                upper = trimmed.upper()
+                return f"{upper[:3]} {upper[3:]}0"
+            # If min_length > 5, reject this by returning original
+            return value.strip()
+
+        # Check if it's a Canadian postal code (6 alphanumeric characters)
+        if re.match(r"[A-Za-z]\d[A-Za-z]\d[A-Za-z]\d", trimmed):
+            upper = trimmed.upper()
+            return f"{upper[:3]} {upper[3:6]}"
+
+        # For values that don't match Canadian postal patterns, return trimmed original
+        return value.strip()

openlinktoken/attributes/person/first_name_attribute.py

@@ -0,0 +1,112 @@
+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
+
+
+class FirstNameAttribute(BaseAttribute):
+    """Represents the first name of a person.
+
+    This class extends BaseAttribute and provides functionality for working with
+    first name fields. It recognizes "FirstName" and "GivenName" as valid aliases
+    for this attribute type.
+
+    The attribute performs no normalization on input values, returning them
+    unchanged.
+    """
+
+    NAME = "FirstName"
+    ALIASES = [NAME, "GivenName"]
+
+    # Pattern to match and remove common titles
+    TITLE_PATTERN = re.compile(
+        r"(?i)^\s*(mr|mrs|ms|miss|dr|prof|capt|sir|col|gen|cmdr|lt|"
+        r"rabbi|father|brother|sister|hon|honorable|reverend|rev|doctor)\.?\s+",
+        re.IGNORECASE,
+    )
+
+    # Pattern to match trailing periods and middle initials in names.
+    #
+    # This pattern matches:
+    #  - A space, followed by a single non-space character (middle initial),
+    #    optionally followed by a period, at the end of the string.
+    #
+    # Breakdown of the regex:
+    #   \s           A space
+    #   [^\s]        Any single non-space character (middle initial)
+    #   \.?          Optional period
+    #   $            End of string
+    TRAILING_PERIOD_AND_INITIAL_PATTERN = re.compile(r"\s[^\s]\.?$")
+
+    def __init__(self):
+        placeholder_values = AttributeUtilities.COMMON_PLACEHOLDER_NAMES
+        validation_rules = [NotInValidator(placeholder_values)]
+        super().__init__(validation_rules)
+
+    def validate(self, value: str) -> bool:
+        """
+        Validate the first name value.
+
+        Args:
+            value: The first name value to validate
+
+        Returns:
+            True if the value is a valid first 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 validation
+        # This ensures that validate(normalize(x)) == validate(normalize(normalize(x)))
+        normalized_value = self.normalize(value)
+
+        # Check that normalized value is not empty
+        if normalized_value is None or not normalized_value.strip():
+            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
+
+        return True
+
+    def get_name(self) -> str:
+        return self.NAME
+
+    def get_aliases(self) -> List[str]:
+        return self.ALIASES.copy()
+
+    def normalize(self, value: str) -> str:
+        """Returns the value unchanged after removing titles."""
+        if not value:
+            return value
+
+        normalized = AttributeUtilities.normalize_diacritics(value)
+
+        without_title = re.sub(self.TITLE_PATTERN, "", normalized).strip()
+
+        if without_title:
+            normalized = without_title
+
+        without_suffix = AttributeUtilities.remove_generational_suffix(normalized)
+
+        if without_suffix:
+            normalized = without_suffix
+
+        normalized = re.sub(self.TRAILING_PERIOD_AND_INITIAL_PATTERN, "", normalized).strip()
+
+        # Remove non-alphabetic characters
+        normalized = AttributeUtilities.NON_ALPHABETIC_PATTERN.sub("", normalized)
+
+        # Normalize whitespace
+        normalized = AttributeUtilities.WHITESPACE_PATTERN.sub(" ", normalized)
+
+        return normalized