openlinktoken 2.0.0__tar.gz

openlinktoken-2.0.0/MANIFEST.in

@@ -0,0 +1,15 @@
+# Include requirements files (must be in same directory as setup.py)
+include requirements.txt
+include dev-requirements.txt
+
+# Include root README and LICENSE (relative to this file)
+include ../../../README.md
+include ../../../LICENSE
+
+# Include all Python source files
+recursive-include src *.py
+
+# Exclude test files from distribution
+recursive-exclude src/test *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]

openlinktoken-2.0.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: openlinktoken
+Version: 2.0.0
+Summary: Open Link Token Python core library for record linkage
+Home-page: https://github.com/TruvetaPublic/OpenLinkToken
+Author: Open Link Token Contributors
+Project-URL: Source, https://github.com/TruvetaPublic/OpenLinkToken
+Project-URL: Documentation, https://github.com/TruvetaPublic/OpenLinkToken/blob/main/README.md
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography==48.0.1
+Requires-Dist: jwcrypto==1.5.7
+Dynamic: author
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-python
+Dynamic: summary
+
+Open Link Token Python implementation for record linkage.

openlinktoken-2.0.0/dev-requirements.txt

@@ -0,0 +1,3 @@
+# Use consolidated dev requirements from parent directory
+# Install with: uv pip install -r ../dev-requirements.txt
+-r ../dev-requirements.txt

openlinktoken-2.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "openlinktoken"
+version = "2.0.0"
+requires-python = ">=3.10"
+dynamic = [
+  "authors",
+  "description",
+  "optional-dependencies",
+  "readme",
+  "urls",
+]
+dependencies = [
+  "cryptography==48.0.1",
+  "jwcrypto==1.5.7",
+]
+
+[build-system]
+requires = ["setuptools==82.0.1", "wheel"]
+build-backend = "setuptools.build_meta"

openlinktoken-2.0.0/requirements.txt

@@ -0,0 +1,5 @@
+# Cryptography - mandate secure version to address CVE-2026-44432
+cryptography==48.0.1
+
+# JOSE/JWE for match token format
+jwcrypto==1.5.7

openlinktoken-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openlinktoken-2.0.0/setup.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""Setup script for Open Link Token Python package."""
+
+import os
+
+from setuptools import find_packages, setup
+
+# Read the contents of the project README file.
+this_directory = os.path.abspath(os.path.dirname(__file__))
+root_readme = os.path.abspath(os.path.join(this_directory, "..", "..", "README.md"))
+readme_path = root_readme if os.path.exists(root_readme) else os.path.join(this_directory, "README.md")
+try:
+    with open(readme_path, encoding="utf-8") as f:
+        long_description = f.read()
+except FileNotFoundError:
+    # Fallback to a short description if README is unavailable
+    long_description = "Open Link Token Python implementation for record linkage."
+
+setup(
+    name="openlinktoken",
+    version="2.0.0",
+    author="Open Link Token Contributors",
+    description="Open Link Token Python core library for record linkage",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/TruvetaPublic/OpenLinkToken",
+    project_urls={
+        "Source": "https://github.com/TruvetaPublic/OpenLinkToken",
+        "Documentation": "https://github.com/TruvetaPublic/OpenLinkToken/blob/main/README.md",
+    },
+    package_dir={"": "src/main"},
+    packages=find_packages(where="src/main"),
+    python_requires=">=3.10",
+)

openlinktoken-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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-2.0.0/src/main/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",
+]