openlinktoken 2.0.0__tar.gz → 2.1.0__tar.gz

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openlinktoken
-Version: 2.0.0
+Version: 2.1.0
 Summary: Open Link Token Python core library for record linkage
 Home-page: https://github.com/TruvetaPublic/OpenLinkToken
 Author: Open Link Token Contributors
@@ -8,8 +8,9 @@ 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: cryptography==49.0.0
 Requires-Dist: jwcrypto==1.5.7
+Requires-Dist: PyYAML==6.0.3
 Dynamic: author
 Dynamic: description
 Dynamic: description-content-type

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openlinktoken"
-version = "2.0.0"
+version = "2.1.0"
 requires-python = ">=3.10"
 dynamic = [
   "authors",
@@ -10,8 +10,9 @@ dynamic = [
   "urls",
 ]
 dependencies = [
-  "cryptography==48.0.1",
+  "cryptography==49.0.0",
   "jwcrypto==1.5.7",
+  "PyYAML==6.0.3",
 ]
 
 [build-system]

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/requirements.txt

@@ -1,5 +1,8 @@
 # Cryptography - mandate secure version to address CVE-2026-44432
-cryptography==48.0.1
+cryptography==49.0.0
 
 # JOSE/JWE for match token format
 jwcrypto==1.5.7
+
+# YAML parsing for tokenization config loader
+PyYAML==6.0.3

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/setup.py

@@ -15,10 +15,9 @@ try:
 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",
+    version="2.1.0",
     author="Open Link Token Contributors",
     description="Open Link Token Python core library for record linkage",
     long_description=long_description,

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/__init__.py

@@ -6,7 +6,7 @@ This package provides utilities for tokenizing and processing person attributes
 using various cryptographic transformations.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 __author__ = "Open Link Token Contributors"
 
 __all__ = [

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/attributes/__init__.py

@@ -2,16 +2,20 @@
 
 from .attribute import Attribute
 from .attribute_expression import AttributeExpression
+from .attribute_field import AttributeField
 from .attribute_loader import AttributeLoader
 from .base_attribute import BaseAttribute
 from .combined_attribute import CombinedAttribute
+from .field_registry import FieldRegistry
 from .serializable_attribute import SerializableAttribute
 
 __all__ = [
     "Attribute",
     "AttributeExpression",
+    "AttributeField",
     "AttributeLoader",
     "BaseAttribute",
     "CombinedAttribute",
+    "FieldRegistry",
     "SerializableAttribute",
 ]

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/attributes/attribute_expression.py

@@ -32,16 +32,39 @@ class AttributeExpression:
 
     EXPRESSION_PATTERN = re.compile(r"\s*(?P<expr>[^ (]+)(?:\((?P<args>[^\)]+)\))?")
 
-    def __init__(self, attribute_class: Type["Attribute"], expressions: Optional[str]):
+    def __init__(
+        self,
+        attribute_class: Type["Attribute"],
+        expressions: Optional[str],
+        field_id: Optional[str] = None,
+    ):
         """
         Initialize the AttributeExpression.
 
         Args:
             attribute_class: The class of the attribute being processed.
             expressions: The string of expressions to apply.
+            field_id: Optional field identifier for field-based lookup. When None,
+                the attribute class is used directly as the identity key (legacy behavior).
         """
         self.attribute_class = attribute_class
         self.expressions = expressions
+        self.field_id = field_id
+
+    @classmethod
+    def of(cls, field_id: str, attribute_class: Type["Attribute"], expressions: Optional[str]) -> "AttributeExpression":
+        """
+        Create an attribute expression using a field ID for identity.
+
+        Args:
+            field_id: Unique field identifier from the FieldRegistry.
+            attribute_class: The class of the attribute providing normalization and validation.
+            expressions: The string of expressions to apply.
+
+        Returns:
+            A new AttributeExpression with field_id set.
+        """
+        return cls(attribute_class, expressions, field_id=field_id)
 
     def get_effective_value(self, value: Optional[str]) -> str:
         """

openlinktoken-2.1.0/src/main/openlinktoken/attributes/attribute_field.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: MIT
+
+from typing import TYPE_CHECKING, Type
+
+if TYPE_CHECKING:
+    from openlinktoken.attributes.attribute import Attribute
+
+
+class AttributeField:
+    """
+    Represents a named field slot in a person record.
+
+    An AttributeField separates two concerns that were previously conflated:
+    - Field identity: "which value from the person record?" (the field_id)
+    - Attribute behavior: "how to normalize/validate?" (the attribute_class)
+
+    This allows multiple fields to share the same attribute type (e.g., two fields
+    both using StringAttribute normalization) while remaining distinct keys in the
+    person attributes map.
+    """
+
+    def __init__(self, field_id: str, attribute_class: Type["Attribute"]):
+        """
+        Create an attribute field with the given identity and attribute type.
+
+        Args:
+            field_id: Unique field identifier (e.g., "LastName", "MotherLastName").
+            attribute_class: The attribute class providing normalization and validation behavior.
+        """
+        if field_id is None:
+            raise ValueError("field_id must not be None")
+        if attribute_class is None:
+            raise ValueError("attribute_class must not be None")
+        self._field_id = field_id
+        self._attribute_class = attribute_class
+
+    @property
+    def field_id(self) -> str:
+        """Get the unique field identifier."""
+        return self._field_id
+
+    @property
+    def attribute_class(self) -> Type["Attribute"]:
+        """Get the attribute class providing normalization and validation behavior."""
+        return self._attribute_class
+
+    def __eq__(self, other: object) -> bool:
+        if self is other:
+            return True
+        if not isinstance(other, AttributeField):
+            return False
+        return self._field_id == other._field_id
+
+    def __hash__(self) -> int:
+        return hash(self._field_id)
+
+    def __repr__(self) -> str:
+        return f"AttributeField(field_id='{self._field_id}', attribute_class={self._attribute_class.__name__})"

openlinktoken-2.1.0/src/main/openlinktoken/attributes/field_registry.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Dict, Optional, Set, Type
+
+from openlinktoken.attributes.attribute import Attribute
+from openlinktoken.attributes.attribute_field import AttributeField
+from openlinktoken.attributes.attribute_loader import AttributeLoader
+
+
+class FieldRegistry:
+    """
+    Registry mapping field identifiers to their corresponding Attribute instances.
+
+    The FieldRegistry is the resolution layer that connects field identifiers
+    (string keys used in person-attribute maps) to the attribute instances that provide
+    normalization and validation behavior.
+
+    Built-in attributes are auto-registered using their canonical name as the field ID.
+    Config-driven fields can register additional mappings (e.g., "MotherLastName" → StringAttribute).
+    """
+
+    def __init__(self, fields: Dict[str, AttributeField], field_to_attribute: Dict[str, Attribute]):
+        """
+        Initialize a FieldRegistry with the given mappings.
+
+        Use FieldRegistry.create_default() or FieldRegistry.Builder for construction.
+
+        Args:
+            fields: Mapping of field ID to AttributeField.
+            field_to_attribute: Mapping of field ID to Attribute instance.
+        """
+        self._fields: Dict[str, AttributeField] = dict(fields)
+        self._field_to_attribute: Dict[str, Attribute] = dict(field_to_attribute)
+
+    @classmethod
+    def create_default(cls) -> "FieldRegistry":
+        """
+        Create a default registry populated with all built-in attributes.
+
+        Each attribute is registered using its canonical name (from get_name()) as the field ID.
+
+        Returns:
+            A new registry with built-in attribute registrations.
+        """
+        builder = cls.Builder()
+        for attribute in AttributeLoader.load():
+            builder.register(attribute.get_name(), type(attribute), attribute)
+        return builder.build()
+
+    def get_attribute(self, field_id: str) -> Optional[Attribute]:
+        """
+        Resolve the attribute instance for a given field ID.
+
+        Args:
+            field_id: The field identifier.
+
+        Returns:
+            The attribute if registered, None otherwise.
+        """
+        return self._field_to_attribute.get(field_id)
+
+    def get_field(self, field_id: str) -> Optional[AttributeField]:
+        """
+        Resolve the attribute field definition for a given field ID.
+
+        Args:
+            field_id: The field identifier.
+
+        Returns:
+            The AttributeField if registered, None otherwise.
+        """
+        return self._fields.get(field_id)
+
+    def get_field_ids(self) -> Set[str]:
+        """
+        Return all registered field IDs.
+
+        Returns:
+            A set of field identifiers.
+        """
+        return set(self._fields.keys())
+
+    def size(self) -> int:
+        """
+        Return the number of registered fields.
+
+        Returns:
+            The registry size.
+        """
+        return len(self._fields)
+
+    class Builder:
+        """Builder for constructing a FieldRegistry with custom registrations."""
+
+        def __init__(self):
+            self._fields: Dict[str, AttributeField] = {}
+            self._field_to_attribute: Dict[str, Attribute] = {}
+
+        @classmethod
+        def from_defaults(cls) -> "FieldRegistry.Builder":
+            """
+            Create a builder pre-populated with all built-in attribute registrations.
+
+            Returns:
+                A new builder with defaults loaded.
+            """
+            builder = cls()
+            for attribute in AttributeLoader.load():
+                builder.register(attribute.get_name(), type(attribute), attribute)
+            return builder
+
+        def register(
+            self, field_id: str, attribute_class: Type[Attribute], attribute: Attribute
+        ) -> "FieldRegistry.Builder":
+            """
+            Register a field ID with its attribute class and instance.
+
+            Args:
+                field_id: The unique field identifier.
+                attribute_class: The attribute class providing behavior.
+                attribute: The attribute instance for normalization/validation.
+
+            Returns:
+                This builder for chaining.
+            """
+            self._fields[field_id] = AttributeField(field_id, attribute_class)
+            self._field_to_attribute[field_id] = attribute
+            return self
+
+        def build(self) -> "FieldRegistry":
+            """
+            Build an immutable FieldRegistry from the current registrations.
+
+            Returns:
+                The constructed registry.
+            """
+            return FieldRegistry(self._fields, self._field_to_attribute)

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/metadata.py

@@ -22,7 +22,7 @@ class Metadata:
     METADATA_FILE_EXTENSION = ".metadata.json"
     SYSTEM_PYTHON_VERSION = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
 
-    DEFAULT_VERSION = "2.0.0"
+    DEFAULT_VERSION = "2.1.0"
 
     # Output format values
     OUTPUT_FORMAT_JSON = "JSON"

openlinktoken-2.1.0/src/main/openlinktoken/tokens/definitions/field_ids.py

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+
+
+class FieldIds:
+    """
+    Field identifiers referenced by the built-in T1-T5 token definitions.
+
+    Centralizing these values avoids duplicating the same field-id strings across
+    multiple token definition modules.
+    """
+
+    LAST_NAME = "LastName"
+    FIRST_NAME = "FirstName"
+    SEX = "Sex"
+    BIRTH_DATE = "BirthDate"
+    POSTAL_CODE = "PostalCode"
+    SOCIAL_SECURITY_NUMBER = "SocialSecurityNumber"

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/definitions/t1_token.py

@@ -7,6 +7,7 @@ from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttrib
 from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
 from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
 from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.definitions.field_ids import FieldIds
 from openlinktoken.tokens.token import Token
 
 
@@ -24,10 +25,10 @@ class T1Token(Token):
     def __init__(self):
         """Initialize the T1 token definition."""
         self._definition = [
-            AttributeExpression(LastNameAttribute, "T|U"),
-            AttributeExpression(FirstNameAttribute, "T|S(0,1)|U"),
-            AttributeExpression(SexAttribute, "T|U"),
-            AttributeExpression(BirthDateAttribute, "T|D"),
+            AttributeExpression(LastNameAttribute, "T|U", field_id=FieldIds.LAST_NAME),
+            AttributeExpression(FirstNameAttribute, "T|S(0,1)|U", field_id=FieldIds.FIRST_NAME),
+            AttributeExpression(SexAttribute, "T|U", field_id=FieldIds.SEX),
+            AttributeExpression(BirthDateAttribute, "T|D", field_id=FieldIds.BIRTH_DATE),
         ]
 
     def get_identifier(self) -> str:

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/definitions/t2_token.py

@@ -7,6 +7,7 @@ from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttrib
 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.tokens.definitions.field_ids import FieldIds
 from openlinktoken.tokens.token import Token
 
 
@@ -24,10 +25,10 @@ class T2Token(Token):
     def __init__(self):
         """Initialize the T2 token definition."""
         self._definition = [
-            AttributeExpression(LastNameAttribute, "T|U"),
-            AttributeExpression(FirstNameAttribute, "T|U"),
-            AttributeExpression(BirthDateAttribute, "T|D"),
-            AttributeExpression(PostalCodeAttribute, "T|S(0,3)|U"),
+            AttributeExpression(LastNameAttribute, "T|U", field_id=FieldIds.LAST_NAME),
+            AttributeExpression(FirstNameAttribute, "T|U", field_id=FieldIds.FIRST_NAME),
+            AttributeExpression(BirthDateAttribute, "T|D", field_id=FieldIds.BIRTH_DATE),
+            AttributeExpression(PostalCodeAttribute, "T|S(0,3)|U", field_id=FieldIds.POSTAL_CODE),
         ]
 
     def get_identifier(self) -> str:

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/definitions/t3_token.py

@@ -7,6 +7,7 @@ from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttrib
 from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
 from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
 from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.definitions.field_ids import FieldIds
 from openlinktoken.tokens.token import Token
 
 
@@ -24,10 +25,10 @@ class T3Token(Token):
     def __init__(self):
         """Initialize the T3 token definition."""
         self._definition = [
-            AttributeExpression(LastNameAttribute, "T|U"),
-            AttributeExpression(FirstNameAttribute, "T|U"),
-            AttributeExpression(SexAttribute, "T|U"),
-            AttributeExpression(BirthDateAttribute, "T|D"),
+            AttributeExpression(LastNameAttribute, "T|U", field_id=FieldIds.LAST_NAME),
+            AttributeExpression(FirstNameAttribute, "T|U", field_id=FieldIds.FIRST_NAME),
+            AttributeExpression(SexAttribute, "T|U", field_id=FieldIds.SEX),
+            AttributeExpression(BirthDateAttribute, "T|D", field_id=FieldIds.BIRTH_DATE),
         ]
 
     def get_identifier(self) -> str:

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/definitions/t4_token.py

@@ -6,6 +6,7 @@ from openlinktoken.attributes.attribute_expression import AttributeExpression
 from openlinktoken.attributes.person.birth_date_attribute import BirthDateAttribute
 from openlinktoken.attributes.person.sex_attribute import SexAttribute
 from openlinktoken.attributes.person.social_security_number_attribute import SocialSecurityNumberAttribute
+from openlinktoken.tokens.definitions.field_ids import FieldIds
 from openlinktoken.tokens.token import Token
 
 
@@ -23,9 +24,9 @@ class T4Token(Token):
     def __init__(self):
         """Initialize the T4 token definition."""
         self._definition = [
-            AttributeExpression(SocialSecurityNumberAttribute, "T|M(\\d+)"),
-            AttributeExpression(SexAttribute, "T|U"),
-            AttributeExpression(BirthDateAttribute, "T|D"),
+            AttributeExpression(SocialSecurityNumberAttribute, "T|M(\\d+)", field_id=FieldIds.SOCIAL_SECURITY_NUMBER),
+            AttributeExpression(SexAttribute, "T|U", field_id=FieldIds.SEX),
+            AttributeExpression(BirthDateAttribute, "T|D", field_id=FieldIds.BIRTH_DATE),
         ]
 
     def get_identifier(self) -> str:

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/definitions/t5_token.py

@@ -6,6 +6,7 @@ from openlinktoken.attributes.attribute_expression import AttributeExpression
 from openlinktoken.attributes.person.first_name_attribute import FirstNameAttribute
 from openlinktoken.attributes.person.last_name_attribute import LastNameAttribute
 from openlinktoken.attributes.person.sex_attribute import SexAttribute
+from openlinktoken.tokens.definitions.field_ids import FieldIds
 from openlinktoken.tokens.token import Token
 
 
@@ -23,9 +24,9 @@ class T5Token(Token):
     def __init__(self):
         """Initialize the T5 token definition."""
         self._definition = [
-            AttributeExpression(LastNameAttribute, "T|U"),
-            AttributeExpression(FirstNameAttribute, "T|S(0,3)|U"),
-            AttributeExpression(SexAttribute, "T|U"),
+            AttributeExpression(LastNameAttribute, "T|U", field_id=FieldIds.LAST_NAME),
+            AttributeExpression(FirstNameAttribute, "T|S(0,3)|U", field_id=FieldIds.FIRST_NAME),
+            AttributeExpression(SexAttribute, "T|U", field_id=FieldIds.SEX),
         ]
 
     def get_identifier(self) -> str:

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken/tokens/token_generator.py

@@ -5,6 +5,7 @@ from typing import Dict, List, Optional, Set, Type
 
 from openlinktoken.attributes.attribute import Attribute
 from openlinktoken.attributes.attribute_loader import AttributeLoader
+from openlinktoken.attributes.field_registry import FieldRegistry
 from openlinktoken.tokens.base_token_definition import BaseTokenDefinition
 from openlinktoken.tokens.token import Token
 from openlinktoken.tokens.token_generation_exception import TokenGenerationException
@@ -35,13 +36,20 @@ class TokenGenerator:
         """
         return cls(token_definition, SHA256Tokenizer(token_transformer_list))
 
-    def __init__(self, token_definition: BaseTokenDefinition, tokenizer: Tokenizer):
+    def __init__(
+        self,
+        token_definition: BaseTokenDefinition,
+        tokenizer: Tokenizer,
+        field_registry: Optional[FieldRegistry] = None,
+    ):
         """
         Initialize the token generator with an explicit tokenizer.
 
         Args:
             token_definition: The token definition.
             tokenizer: Tokenizer implementation. Use PassthroughTokenizer for plain mode.
+            field_registry: Optional custom field registry for field-ID-based lookups.
+                When None, a default registry is created from built-in attributes.
         """
         self.token_definition = token_definition
         self.attribute_instance_map: Dict[Type[Attribute], Attribute] = {}
@@ -51,19 +59,20 @@ class TokenGenerator:
             self.attribute_instance_map[type(attribute)] = attribute
 
         self.tokenizer = tokenizer
+        self.field_registry = field_registry or FieldRegistry.create_default()
 
     def _get_token_signature(
         self, token_id: str, person_attributes: Dict[Type[Attribute], str], result: TokenGeneratorResult
     ) -> Optional[str]:
         """
-        Get the token signature for a given token identifier.
+        Get the token signature using a class-keyed person attributes map.
 
-        Populates the invalid_attributes list in the result object with the attributes
-        that are invalid.
+        .. deprecated::
+            Use :meth:`_get_token_signature_via_field_id` with a field-ID-keyed map instead.
 
         Args:
             token_id: The token identifier.
-            person_attributes: The person attributes map.
+            person_attributes: The person attributes map, keyed by attribute class.
             result: The token generator result.
 
         Returns:
@@ -107,12 +116,13 @@ class TokenGenerator:
 
     def get_all_token_signatures(self, person_attributes: Dict[Type[Attribute], str]) -> Dict[str, str]:
         """
-        Get the token signatures for all token/rule identifiers.
+        Get the token signatures for all token/rule identifiers using a class-keyed map.
 
-        This is mostly a debug/logging/test method.
+        .. deprecated::
+            Use :meth:`get_all_token_signatures_via_field_id` with a field-ID-keyed map instead.
 
         Args:
-            person_attributes: The person attributes map.
+            person_attributes: The person attributes map, keyed by attribute class.
 
         Returns:
             A map of token/rule identifier to the token signature.
@@ -133,18 +143,10 @@ class TokenGenerator:
         self, token_id: str, person_attributes: Dict[Type[Attribute], str], result: TokenGeneratorResult
     ) -> Optional[str]:
         """
-        Get token for a given token identifier.
-
-        Args:
-            token_id: The token identifier.
-            person_attributes: The person attributes map.
-            result: The token generator result.
+        Get token for a given token identifier using a class-keyed person attributes map.
 
-        Returns:
-            The token using the token definition for the given token identifier.
-
-        Raises:
-            TokenGenerationException: In case of failure to generate the token.
+        .. deprecated::
+            Use :meth:`get_all_tokens_via_field_id` with a field-ID-keyed map instead.
         """
         signature = self._get_token_signature(token_id, person_attributes, result)
         logger.debug(f"Token signature for token id {token_id}: {signature}")
@@ -161,10 +163,13 @@ class TokenGenerator:
 
     def get_all_tokens(self, person_attributes: Dict[Type[Attribute], str]) -> TokenGeneratorResult:
         """
-        Get the tokens for all token/rule identifiers.
+        Get the tokens for all token/rule identifiers using a class-keyed person attributes map.
+
+        .. deprecated::
+            Use :meth:`get_all_tokens_via_field_id` with a field-ID-keyed ``Dict[str, str]`` map instead.
 
         Args:
-            person_attributes: The person attributes map.
+            person_attributes: The person attributes map, keyed by attribute class.
 
         Returns:
             A TokenGeneratorResult object containing the tokens and invalid attributes.
@@ -185,8 +190,11 @@ class TokenGenerator:
         """
         Get invalid person attribute names.
 
+        .. deprecated::
+            Use field-ID-keyed person attributes with :meth:`get_all_tokens_via_field_id` instead.
+
         Args:
-            person_attributes: The person attributes map.
+            person_attributes: The person attributes map, keyed by attribute class.
 
         Returns:
             A set of invalid person attribute names.
@@ -199,3 +207,124 @@ class TokenGenerator:
                 response.add(attribute.get_name())
 
         return response
+
+    # ===== Primary API =====
+
+    def _get_token_signature_via_field_id(
+        self, token_id: str, person_attributes: Dict[str, str], result: TokenGeneratorResult
+    ) -> Optional[str]:
+        """
+        Get the token signature for a given token identifier.
+
+        Args:
+            token_id: The token identifier.
+            person_attributes: Person attributes keyed by field ID (e.g., "LastName" → "Smith").
+            result: The token generator result.
+
+        Returns:
+            The token signature, or None if required fields are missing or invalid.
+        """
+        definition = self.token_definition.get_token_definition(token_id)
+
+        if person_attributes is None:
+            raise ValueError("Person attributes cannot be null.")
+
+        values = []
+
+        for attribute_expression in definition:
+            resolved_field_id = self._resolve_field_id(attribute_expression)
+            if resolved_field_id is None or resolved_field_id not in person_attributes:
+                return None
+
+            attribute = self._resolve_attribute(attribute_expression, resolved_field_id)
+            if attribute is None:
+                return None
+
+            attribute_value = person_attributes[resolved_field_id]
+
+            if not attribute.validate(attribute_value):
+                result.invalid_attributes.add(attribute.get_name())
+                return None
+
+            attribute_value = attribute.normalize(attribute_value)
+
+            try:
+                attribute_value = attribute_expression.get_effective_value(attribute_value)
+                values.append(attribute_value)
+            except ValueError as e:
+                logger.error(str(e))
+                return None
+
+        filtered_values = [v for v in values if v is not None and v.strip() != ""]
+        return "|".join(filtered_values)
+
+    def get_all_tokens_via_field_id(self, person_attributes: Dict[str, str]) -> TokenGeneratorResult:
+        """
+        Get the tokens for all token/rule identifiers.
+
+        This is the preferred API. It natively supports multiple fields sharing the same
+        attribute type (e.g., "MotherLastName" and "FatherLastName" both backed by StringAttribute).
+
+        Args:
+            person_attributes: Person attributes keyed by field ID (e.g., "LastName" → "Smith").
+
+        Returns:
+            A TokenGeneratorResult object containing the tokens and invalid attributes.
+        """
+        result = TokenGeneratorResult()
+
+        for token_id in self.token_definition.get_token_identifiers():
+            try:
+                signature = self._get_token_signature_via_field_id(token_id, person_attributes, result)
+                logger.debug(f"Token signature for token id {token_id}: {signature}")
+                try:
+                    token = self.tokenizer.tokenize(signature)
+                    if Token.BLANK == token:
+                        result.blank_tokens_by_rule.add(token_id)
+                    if token is not None:
+                        result.tokens[token_id] = token
+                except Exception as e:
+                    logger.error(f"Error generating token for token id: {token_id}", exc_info=e)
+            except Exception as e:
+                logger.error(f"Error generating token for token id: {token_id}", exc_info=e)
+
+        return result
+
+    def get_all_token_signatures_via_field_id(self, person_attributes: Dict[str, str]) -> Dict[str, str]:
+        """
+        Get the token signatures for all token/rule identifiers. Mostly useful for debugging.
+
+        Args:
+            person_attributes: Person attributes keyed by field ID.
+
+        Returns:
+            A map of token/rule identifier to the token signature.
+        """
+        signatures = {}
+
+        for token_id in self.token_definition.get_token_identifiers():
+            try:
+                signature = self._get_token_signature_via_field_id(token_id, person_attributes, TokenGeneratorResult())
+                if signature is not None:
+                    signatures[token_id] = signature
+            except Exception as e:
+                logger.error(f"Error generating token signature for token id: {token_id}", exc_info=e)
+
+        return signatures
+
+    def _resolve_field_id(self, expression) -> Optional[str]:
+        """Resolve the effective field ID from an AttributeExpression."""
+        if expression.field_id is not None:
+            return expression.field_id
+        # Legacy fallback: derive field ID from attribute class name
+        attribute = self.attribute_instance_map.get(expression.attribute_class)
+        return attribute.get_name() if attribute else None
+
+    def _resolve_attribute(self, expression, resolved_field_id: str) -> Optional[Attribute]:
+        """Resolve the attribute instance for an expression and field ID."""
+        # Try field registry first
+        from_registry = self.field_registry.get_attribute(resolved_field_id)
+        if from_registry is not None:
+            return from_registry
+        # Fallback to class-based lookup
+        return self.attribute_instance_map.get(expression.attribute_class)

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openlinktoken
-Version: 2.0.0
+Version: 2.1.0
 Summary: Open Link Token Python core library for record linkage
 Home-page: https://github.com/TruvetaPublic/OpenLinkToken
 Author: Open Link Token Contributors
@@ -8,8 +8,9 @@ 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: cryptography==49.0.0
 Requires-Dist: jwcrypto==1.5.7
+Requires-Dist: PyYAML==6.0.3
 Dynamic: author
 Dynamic: description
 Dynamic: description-content-type

{openlinktoken-2.0.0 → openlinktoken-2.1.0}/src/main/openlinktoken.egg-info/SOURCES.txt

@@ -18,9 +18,11 @@ src/main/openlinktoken.egg-info/top_level.txt
 src/main/openlinktoken/attributes/__init__.py
 src/main/openlinktoken/attributes/attribute.py
 src/main/openlinktoken/attributes/attribute_expression.py
+src/main/openlinktoken/attributes/attribute_field.py
 src/main/openlinktoken/attributes/attribute_loader.py
 src/main/openlinktoken/attributes/base_attribute.py
 src/main/openlinktoken/attributes/combined_attribute.py
+src/main/openlinktoken/attributes/field_registry.py
 src/main/openlinktoken/attributes/serializable_attribute.py
 src/main/openlinktoken/attributes/general/__init__.py
 src/main/openlinktoken/attributes/general/date_attribute.py
@@ -60,6 +62,7 @@ src/main/openlinktoken/tokens/token_generation_exception.py
 src/main/openlinktoken/tokens/token_generator.py
 src/main/openlinktoken/tokens/token_generator_result.py
 src/main/openlinktoken/tokens/token_registry.py
+src/main/openlinktoken/tokens/definitions/field_ids.py
 src/main/openlinktoken/tokens/definitions/t1_token.py
 src/main/openlinktoken/tokens/definitions/t2_token.py
 src/main/openlinktoken/tokens/definitions/t3_token.py

openlinktoken-2.1.0/src/main/openlinktoken.egg-info/requires.txt

@@ -0,0 +1,3 @@
+cryptography==49.0.0
+jwcrypto==1.5.7
+PyYAML==6.0.3

openlinktoken-2.0.0/src/main/openlinktoken.egg-info/requires.txt

@@ -1,2 +0,0 @@
-cryptography==48.0.1
-jwcrypto==1.5.7