openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/__init__.py

@@ -0,0 +1,15 @@
+"""
+Open Link Token Python Package
+
+
+This package provides utilities for tokenizing and processing person attributes
+using various cryptographic transformations.
+"""
+
+__version__ = "2.0.0"
+__author__ = "Open Link Token Contributors"
+
+__all__ = [
+    "__version__",
+    "__author__",
+]

openlinktoken/attributes/__init__.py

@@ -0,0 +1,17 @@
+"""Base attribute types and loader utilities."""
+
+from .attribute import Attribute
+from .attribute_expression import AttributeExpression
+from .attribute_loader import AttributeLoader
+from .base_attribute import BaseAttribute
+from .combined_attribute import CombinedAttribute
+from .serializable_attribute import SerializableAttribute
+
+__all__ = [
+    "Attribute",
+    "AttributeExpression",
+    "AttributeLoader",
+    "BaseAttribute",
+    "CombinedAttribute",
+    "SerializableAttribute",
+]

openlinktoken/attributes/attribute.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class Attribute(ABC):
+    """Base interface for all attributes."""
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """Get the name of the attribute."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def get_aliases(self) -> List[str]:
+        """Get the aliases for the attribute."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def normalize(self, value: str) -> str:
+        """Normalize the attribute value."""
+        ...  # pragma: no cover
+
+    @abstractmethod
+    def validate(self, value: str) -> bool:
+        """Validate the attribute value."""
+        ...  # pragma: no cover

openlinktoken/attributes/attribute_expression.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: MIT
+"""
+An attribute expression determines how the value of an attribute is normalized for consumption.
+
+Below are the components used to compose the attribute expression:
+- `T` - trim
+- `U` - convert to upper case
+- `S(start_index, end_index)` - substring of value
+- `D` - treat as date
+- `M(regex)` - match the regular expression
+- `R(oldString, newString)` - replace old string with new string
+- `|` - expression separator
+
+Examples of attribute expressions:
+- `T|S(0,3)|U` - trim the value, then take first 3 characters, and then convert to upper case.
+- `T|D` - trim the value, treat the value as a date in the yyyy-MM-dd format.
+- `T|M("\\d+")` - trim the value, then make sure that the value matches the regular expression.
+"""
+
+import re
+from datetime import datetime
+from typing import TYPE_CHECKING, Optional, Type
+
+if TYPE_CHECKING:
+    from openlinktoken.attributes.attribute import Attribute
+
+
+class AttributeExpression:
+    """
+    An attribute expression determines how the value of an attribute is normalized for consumption.
+    """
+
+    EXPRESSION_PATTERN = re.compile(r"\s*(?P<expr>[^ (]+)(?:\((?P<args>[^\)]+)\))?")
+
+    def __init__(self, attribute_class: Type["Attribute"], expressions: Optional[str]):
+        """
+        Initialize the AttributeExpression.
+
+        Args:
+            attribute_class: The class of the attribute being processed.
+            expressions: The string of expressions to apply.
+        """
+        self.attribute_class = attribute_class
+        self.expressions = expressions
+
+    def get_effective_value(self, value: Optional[str]) -> str:
+        """
+        Get the effective value for an attribute after application of the attribute expression.
+
+        Args:
+            value: The attribute value.
+
+        Returns:
+            The effective value after applying the attribute expression.
+        """
+        if value is None or value.strip() == "":
+            return ""
+
+        if self.expressions is None or self.expressions.strip() == "":
+            return value
+
+        result = value
+        expression_parts = self.expressions.split("|")
+        for expression in expression_parts:
+            result = self._eval(result, expression)
+        return result
+
+    @staticmethod
+    def _eval_error(value: str, expression: str, inner_exception: Optional[Exception] = None) -> ValueError:
+        """
+        Create an error for failed expression evaluation.
+
+        Args:
+            value: The value being processed.
+            expression: The expression being applied.
+            inner_exception: The exception that occurred.
+
+        Returns:
+            The error with a detailed message.
+        """
+        message = f"Unable to evaluate expression [{expression}] over value [{value}]."
+        if inner_exception:
+            raise ValueError(message) from inner_exception
+        return ValueError(message)
+
+    @classmethod
+    def _eval(cls, value: str, expression: str) -> str:
+        """
+        Evaluate a single expression on the given value.
+
+        Args:
+            value: The value to process.
+            expression: The expression to apply.
+
+        Returns:
+            The processed value.
+        """
+        if value is None or expression is None:
+            raise cls._eval_error(value, expression)
+
+        matcher = cls.EXPRESSION_PATTERN.match(expression)
+        if not matcher:
+            raise cls._eval_error(value, expression)
+
+        expr = matcher.group("expr")
+        args = None
+        if matcher.group("args"):
+            args = matcher.group("args").strip().split(",")
+
+        expr_upper = expr.upper()
+
+        if expr_upper == "U":
+            return value.upper()
+        elif expr_upper == "T":
+            return value.strip()
+        elif expr_upper == "S":
+            if args is None:
+                raise cls._eval_error(value, expression)
+            return cls._substring(value, expression, args)
+        elif expr_upper == "R":
+            if args is None:
+                raise cls._eval_error(value, expression)
+            return cls._replace(value, expression, args)
+        elif expr_upper == "M":
+            if args is None:
+                raise cls._eval_error(value, expression)
+            return cls._match(value, expression, args)
+        elif expr_upper == "D":
+            return cls._date(value, expression)
+        else:
+            raise cls._eval_error(value, expression)
+
+    @classmethod
+    def _substring(cls, value: str, expression: str, args: list[str]) -> str:
+        """
+        Substring expression S(start, end).
+
+        Args:
+            value: The value to process.
+            expression: The expression being applied.
+            args: The arguments for the substring operation.
+
+        Returns:
+            The extracted substring.
+        """
+        if len(args) != 2:
+            raise cls._eval_error(value, expression)
+
+        try:
+            start = max(0, int(args[0]))
+            end = min(len(value), int(args[1]))
+            return value[start:end]
+        except (ValueError, IndexError) as ex:
+            raise cls._eval_error(value, expression, ex)
+
+    @classmethod
+    def _replace(cls, value: str, expression: str, args: list[str]) -> str:
+        """
+        Replace expression R(oldString, newString).
+
+        Args:
+            value: The value to process.
+            expression: The expression being applied.
+            args: The arguments for the replace operation.
+
+        Returns:
+            The value with replacements applied.
+        """
+        if len(args) != 2:
+            raise cls._eval_error(value, expression)
+
+        if len(args[0]) < 2 or len(args[1]) < 2:
+            raise cls._eval_error(value, expression, ValueError("Arguments must be quoted strings."))
+
+        try:
+            # Remove quotes from the arguments
+            old_val = args[0][1:-1] if len(args[0]) >= 2 else args[0]
+            new_val = args[1][1:-1] if len(args[1]) >= 2 else args[1]
+            return value.replace(old_val, new_val)
+        except Exception as ex:
+            raise cls._eval_error(value, expression, ex)
+
+    @classmethod
+    def _match(cls, value: str, expression: str, args: list[str]) -> str:
+        """
+        RegEx match M(regex).
+
+        Args:
+            value: The value to process.
+            expression: The expression being applied.
+            args: The arguments for the match operation.
+
+        Returns:
+            The concatenated matching parts.
+        """
+        if len(args) != 1:
+            raise cls._eval_error(value, expression)
+
+        try:
+            pattern = re.compile(args[0])
+            matches = pattern.findall(value)
+            return "".join(matches)
+        except re.error as ex:
+            raise cls._eval_error(value, expression, ex)
+
+    @classmethod
+    def _date(cls, value: str, expression: str) -> str:
+        """
+        Date expression D.
+
+        Supported date formats, and will be changed to "yyyy-MM-dd".
+        If the date is not in the supported formats, an exception will be thrown.
+
+        Args:
+            value: The value to process.
+            expression: The expression being applied.
+
+        Returns:
+            The formatted date string.
+        """
+        # Supported date formats
+        possible_formats = ["%Y-%m-%d"]
+
+        for fmt in possible_formats:
+            try:
+                date = datetime.strptime(value, fmt)
+                return date.strftime("%Y-%m-%d")
+            except ValueError:
+                continue
+
+        # If no format worked, raise an error
+        raise cls._eval_error(value, expression)

openlinktoken/attributes/attribute_loader.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Set
+
+from openlinktoken.attributes.attribute import Attribute
+from openlinktoken.attributes.general.date_attribute import DateAttribute
+from openlinktoken.attributes.general.decimal_attribute import DecimalAttribute
+from openlinktoken.attributes.general.integer_attribute import IntegerAttribute
+from openlinktoken.attributes.general.record_id_attribute import RecordIdAttribute
+from openlinktoken.attributes.general.string_attribute import StringAttribute
+from openlinktoken.attributes.general.year_attribute import YearAttribute
+from openlinktoken.attributes.person.age_attribute import AgeAttribute
+from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
+from openlinktoken.attributes.person.birth_year_attribute import BirthYearAttribute
+from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
+from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
+from openlinktoken.attributes.person.postal_code_attribute import PostalCodeAttribute
+from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.attributes.person.social_security_number_attribute import SocialSecurityNumberAttribute
+
+
+class AttributeLoader:
+    """
+    Loads all available attribute implementations.
+    """
+
+    def __init__(self):
+        raise RuntimeError("AttributeLoader should not be instantiated.")
+
+    @staticmethod
+    def load() -> Set[Attribute]:
+        """Load all attribute implementations."""
+        return {
+            RecordIdAttribute(),
+            StringAttribute(),
+            DateAttribute(),
+            DecimalAttribute(),
+            IntegerAttribute(),
+            YearAttribute(),
+            FirstNameAttribute(),
+            LastNameAttribute(),
+            BirthDateAttribute(),
+            AgeAttribute(),
+            BirthYearAttribute(),
+            SexAttribute(),
+            SocialSecurityNumberAttribute(),
+            PostalCodeAttribute(),
+        }

openlinktoken/attributes/base_attribute.py

@@ -0,0 +1,31 @@
+from typing import List
+
+from openlinktoken.attributes.serializable_attribute import SerializableAttribute
+from openlinktoken.attributes.validation.not_null_or_empty_validator import NotNullOrEmptyValidator
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class BaseAttribute(SerializableAttribute):
+    """A base implementation of the SerializableAttribute interface.
+
+    This class provides a default implementation of the validate method
+    that validates the attribute value against a set of validation rules.
+
+    The default validation rules are:
+    - Not null or empty
+    """
+
+    def __init__(self, validation_rules: List[SerializableAttributeValidator] = None):
+        if validation_rules is None:
+            validation_rules = []
+
+        rule_list = [NotNullOrEmptyValidator()]
+        rule_list.extend(validation_rules)
+        self.validation_rules = rule_list
+
+    def validate(self, value: str) -> bool:
+        """Validates the attribute value against a set of validation rules."""
+        if value is None:
+            return False
+
+        return all(rule.eval(value) for rule in self.validation_rules)

openlinktoken/attributes/combined_attribute.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from openlinktoken.attributes.serializable_attribute import SerializableAttribute
+
+
+class CombinedAttribute(SerializableAttribute, ABC):
+    """
+    Abstract base class for attributes that combine multiple attribute implementations.
+
+    This class allows for combining multiple attribute implementations where each
+    implementation handles a specific subset of validation and normalization logic.
+    The combined attribute will iterate through all implementations until it finds
+    one that reports the string as valid for validation, and uses the first
+    implementation that can normalize the value for normalization.
+
+    Subclasses must implement get_attribute_implementations() to provide
+    the list of attribute implementations to combine.
+    """
+
+    @abstractmethod
+    def get_attribute_implementations(self) -> List[SerializableAttribute]:
+        """
+        Get the list of attribute implementations to combine.
+
+        Returns:
+            List[SerializableAttribute]: The list of attribute implementations
+        """
+        pass
+
+    def validate(self, value: str) -> bool:
+        """
+        Validate the attribute value by checking if any of the combined
+        implementations consider the value valid.
+
+        Args:
+            value: The attribute value to validate
+
+        Returns:
+            True if any implementation validates the value successfully, False otherwise
+        """
+        if value is None:
+            return False
+
+        return any(impl.validate(value) for impl in self.get_attribute_implementations())
+
+    def normalize(self, value: str) -> str:
+        """
+        Normalize the attribute value using the first implementation that
+        successfully validates the value.
+
+        Args:
+            value: The attribute value to normalize
+
+        Returns:
+            The normalized value from the first validating implementation,
+            or the original trimmed value if no implementation validates it
+        """
+        if value is None:
+            return None
+
+        for impl in self.get_attribute_implementations():
+            if impl.validate(value):
+                return impl.normalize(value)
+
+        # If no implementation validates the value, return trimmed original
+        return value.strip()

openlinktoken/attributes/general/__init__.py

@@ -0,0 +1,17 @@
+"""General-purpose attribute implementations."""
+
+from .date_attribute import DateAttribute
+from .decimal_attribute import DecimalAttribute
+from .integer_attribute import IntegerAttribute
+from .record_id_attribute import RecordIdAttribute
+from .string_attribute import StringAttribute
+from .year_attribute import YearAttribute
+
+__all__ = [
+    "DateAttribute",
+    "DecimalAttribute",
+    "IntegerAttribute",
+    "RecordIdAttribute",
+    "StringAttribute",
+    "YearAttribute",
+]

openlinktoken/attributes/general/date_attribute.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MIT
+
+import re
+from datetime import datetime
+from typing import List
+
+from openlinktoken.attributes.base_attribute import BaseAttribute
+from openlinktoken.attributes.validation import RegexValidator
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class DateAttribute(BaseAttribute):
+    """Represents a generic date attribute.
+
+    This class extends BaseAttribute and provides functionality for working with
+    date fields. It recognizes "Date" 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
+    - ISO 8601 timestamps (yyyy-MM-ddTHH:mm:ss.sssZ or yyyy-MM-ddTHH:mm:ssZ)
+    """
+
+    NAME = "Date"
+    ALIASES = [NAME]
+
+    # Regular expression pattern for validating date formats
+    # Supports: yyyy-MM-dd, yyyy/MM/dd, MM/dd/yyyy, MM-dd-yyyy, dd.MM.yyyy,
+    # and ISO 8601 timestamps
+    VALIDATION_PATTERN = re.compile(
+        r"^(?:\d{4}[-/]\d{2}[-/]\d{2}|\d{2}[-./]\d{2}[-./]\d{4}|"
+        r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})?)$"
+    )
+
+    def __init__(self, additional_validators: List[SerializableAttributeValidator] = None):
+        """
+        Initialize the DateAttribute 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 "Date"
+        """
+        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:
+        """Normalizes date to yyyy-MM-dd format.
+
+        Args:
+            value: The date string to normalize
+
+        Returns:
+            str: The normalized date in yyyy-MM-dd format
+
+        Raises:
+            ValueError: If the date format is invalid
+        """
+        value = value.strip()
+
+        if not value:
+            raise ValueError("Invalid date format: empty or whitespace")
+
+        # Try ISO 8601 timestamp formats first
+        iso_formats = [
+            "%Y-%m-%dT%H:%M:%S.%fZ",  # yyyy-MM-ddTHH:mm:ss.sssZ
+            "%Y-%m-%dT%H:%M:%SZ",  # yyyy-MM-ddTHH:mm:ssZ
+            "%Y-%m-%dT%H:%M:%S.%f%z",  # yyyy-MM-ddTHH:mm:ss.sss+/-HH:MM
+            "%Y-%m-%dT%H:%M:%S%z",  # yyyy-MM-ddTHH:mm:ss+/-HH:MM
+        ]
+
+        for fmt in iso_formats:
+            try:
+                parsed_date = datetime.strptime(value, fmt)
+                return parsed_date.strftime("%Y-%m-%d")
+            except ValueError:
+                continue
+
+        # Try different date formats
+        date_formats = [
+            "%Y-%m-%d",  # yyyy-MM-dd
+            "%Y/%m/%d",  # yyyy/MM/dd
+            "%m/%d/%Y",  # MM/dd/yyyy
+            "%m-%d-%Y",  # MM-dd-yyyy
+            "%d.%m.%Y",  # dd.MM.yyyy
+        ]
+
+        for format in date_formats:
+            try:
+                parsed_date = datetime.strptime(value, format)
+                return parsed_date.strftime("%Y-%m-%d")
+            except ValueError:
+                continue
+
+        raise ValueError(f"Invalid date format: {value}")

openlinktoken/attributes/general/decimal_attribute.py

@@ -0,0 +1,86 @@
+# 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 DecimalAttribute(BaseAttribute):
+    """Represents a generic decimal (floating-point) attribute.
+
+    This class extends BaseAttribute and provides functionality for working with
+    decimal fields. It recognizes "Decimal" 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 decimal number.
+
+    Supported formats include:
+    - Standard decimals: 123, -45.67, +89.0
+    - Decimals without leading digit: .5
+    - Decimals without trailing digits: 1.
+    - Scientific notation: 1.5e10, -3.14E-2
+    """
+
+    NAME = "Decimal"
+    ALIASES = [NAME]
+
+    # Regular expression pattern for validating decimal format
+    # Supports: optional sign, digits with optional decimal, scientific notation
+    VALIDATION_PATTERN = r"^\s*[+-]?(\d+\.\d*|\d*\.\d+|\d+)([eE][+-]?\d+)?\s*$"
+
+    def __init__(self, additional_validators: Optional[List[SerializableAttributeValidator]] = None):
+        """
+        Initialize the DecimalAttribute 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 "Decimal"
+        """
+        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 decimal value by trimming whitespace and parsing.
+
+        Args:
+            value: The decimal string to normalize
+
+        Returns:
+            str: The normalized decimal value
+
+        Raises:
+            ValueError: If the decimal is not valid or empty
+        """
+        if value is None:
+            raise ValueError("Decimal value cannot be null")
+
+        value_stripped = value.strip() if value else ""
+
+        if not value_stripped:
+            raise ValueError("Invalid decimal format: empty or whitespace")
+
+        # Parse and normalize the decimal value
+        try:
+            decimal_value = float(value_stripped)
+            return str(decimal_value)
+        except ValueError:
+            raise ValueError(f"Invalid decimal format: {value}")