openlinktoken 2.0.0__py3-none-any.whl

openlinktoken/attributes/utilities/attribute_utilities.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: MIT
+
+import re
+import unicodedata
+from typing import Dict, Set
+
+
+class AttributeUtilities:
+    """
+    This class includes functions such as normalizing accents,
+    standardizing formats, and other attribute-related transformations.
+    """
+
+    # Pattern that matches any character that is not an alphabetic character (a-z or A-Z).
+    # Used for removing or identifying non-alphabetic characters in strings.
+    NON_ALPHABETIC_PATTERN = re.compile(r"[^a-zA-Z]")
+
+    # Pattern that matches one or more whitespace characters.
+    # This includes spaces, tabs, line breaks, and other Unicode whitespace.
+    #
+    # Examples:
+    # " " -> single space
+    # "\t" -> tab
+    # "\n" -> newline
+    # "\r\n" -> carriage return + newline
+    # "   " -> multiple spaces
+    WHITESPACE_PATTERN = re.compile(r"\s+")
+
+    # Characters from Latin-1 Supplement and Latin Extended blocks that do not
+    # decompose to ASCII-compatible forms with NFD alone.
+    LATIN_EXTENDED_TRANSLITERATION_MAP: Dict[str, str] = {
+        "Æ": "AE",
+        "æ": "ae",
+        "Ð": "D",
+        "ð": "d",
+        "Ø": "O",
+        "ø": "o",
+        "Þ": "TH",
+        "þ": "th",
+        "ß": "ss",
+        "ẞ": "SS",
+        "Đ": "D",
+        "đ": "d",
+        "Ħ": "H",
+        "ħ": "h",
+        "ı": "i",
+        "IJ": "IJ",
+        "ij": "ij",
+        "Ŀ": "L",
+        "ŀ": "l",
+        "Ł": "L",
+        "ł": "l",
+        "ʼn": "n",
+        "Ŋ": "NG",
+        "ŋ": "ng",
+        "Œ": "OE",
+        "œ": "oe",
+        "Ŧ": "T",
+        "ŧ": "t",
+        "ſ": "s",
+        "Ƒ": "F",
+        "ƒ": "f",
+        "DŽ": "DZ",
+        "Dž": "Dz",
+        "dž": "dz",
+        "LJ": "LJ",
+        "Lj": "Lj",
+        "lj": "lj",
+        "NJ": "NJ",
+        "Nj": "Nj",
+        "nj": "nj",
+        "DZ": "DZ",
+        "Dz": "Dz",
+        "dz": "dz",
+        "Ǽ": "AE",
+        "ǽ": "ae",
+        "Ǿ": "O",
+        "ǿ": "o",
+    }
+
+    # Pattern that matches generational suffixes at the end of a string.
+    # Matches case-insensitive suffixes after a whitespace character.
+    #
+    # Matches the following types of generational suffixes:
+    # - Jr, Jr., Junior
+    # - Sr, Sr., Senior
+    # - Roman numerals (I, II, III, IV, V, VI, VII, VIII, IX, X)
+    # - Ordinal numbers (1st, 2nd, 3rd, 4th, etc.)
+    #
+    # Examples:
+    # "John Smith Jr" -> matches " Jr"
+    # "Jane Doe Sr." -> matches " Sr."
+    # "Robert Johnson III" -> matches " III"
+    # "Thomas Wilson 2nd" -> matches " 2nd"
+    GENERATIONAL_SUFFIX_PATTERN = re.compile(
+        r"(?i)\s+(jr\.?|junior|sr\.?|senior|I{1,3}|IV|V|VI{0,3}|IX|X|\d+(st|nd|rd|th))$"
+    )
+
+    # A set of common placeholder names used to identify non-identifying or
+    # placeholder text in data fields.
+    #
+    # This set includes various standard terms and phrases that are commonly used
+    # as placeholders in data records when actual values are unknown, not applicable,
+    # unavailable, or intentionally masked.
+    # These placeholders might be found in production data but don't represent
+    # actual identifying information.
+    #
+    # These values should be treated as non-identifying data and may need special
+    # handling during data processing, anonymization, or when analyzing data quality.
+    COMMON_PLACEHOLDER_NAMES: Set[str] = {
+        "Unknown",  # Placeholder for unknown last names
+        "N/A",  # Not applicable
+        "None",  # No last name provided
+        "Test",  # Commonly used in testing scenarios
+        "Sample",  # Sample data placeholder
+        "Donor",  # Placeholder for donor records
+        "Patient",  # Placeholder for patient records
+        "Automation Test",  # Placeholder for automation tests
+        "Automationtest",  # Another variation of automation test
+        "patient not found",  # Placeholder for cases where patient data is not found
+        "patientnotfound",  # Another variation of patient not found
+        "<masked>",  # Placeholder for masked data
+        "Anonymous",  # Placeholder for anonymous records
+        "zzztrash",  # Placeholder for test or trash data
+        "Missing",  # Placeholder for missing data
+        "Unavailable",  # Placeholder for unavailable data
+        "Not Available",  # Placeholder for data not available
+        "NotAvailable",  # Placeholder for data not available (no spaces)
+    }
+
+    def __init__(self):
+        """Prevent instantiation of utility class."""
+        raise RuntimeError("This is a utility class and cannot be instantiated")
+
+    @staticmethod
+    def normalize_diacritics(value: str) -> str:
+        """
+        Removes diacritic marks from the given string.
+
+        This method performs the following steps:
+        1. Trims the input string
+        2. Normalizes the string using NFD form, which separates characters from
+           their diacritical marks
+        3. Removes all diacritical marks using Unicode category filtering
+
+        Args:
+            value: The string from which to remove diacritical marks
+
+        Returns:
+            A new string with all diacritical marks removed
+
+        Raises:
+            AttributeError: If value is None
+        """
+        if value is None:
+            raise AttributeError("Value cannot be None")
+
+        trimmed_value = value.strip()
+        transliterated_value = "".join(
+            AttributeUtilities.LATIN_EXTENDED_TRANSLITERATION_MAP.get(character, character)
+            for character in trimmed_value
+        )
+
+        # Normalize to NFD (decomposed form) and filter out combining characters
+        normalized = unicodedata.normalize("NFD", transliterated_value)
+        return "".join(character for character in normalized if not unicodedata.category(character).startswith("M"))
+
+    @staticmethod
+    def remove_whitespace(value: str) -> str:
+        """
+        Remove all whitespace characters from the string.
+
+        Args:
+            value: The string from which to remove whitespace
+
+        Returns:
+            String with all whitespace removed
+        """
+        if value is None:
+            return None
+
+        return AttributeUtilities.WHITESPACE_PATTERN.sub("", value)
+
+    @staticmethod
+    def remove_non_alphabetic_characters(value: str) -> str:
+        """
+        Remove all non-alphabetic characters from the string.
+
+        Args:
+            value: The string from which to remove non-alphabetic characters
+
+        Returns:
+            String with only alphabetic characters (a-z, A-Z)
+        """
+        if value is None:
+            return None
+
+        return AttributeUtilities.NON_ALPHABETIC_PATTERN.sub("", value)
+
+    @staticmethod
+    def remove_generational_suffix(value: str) -> str:
+        """
+        Remove generational suffixes (Jr, Sr, III, etc.) from the string.
+
+        Args:
+            value: The string from which to remove generational suffixes
+
+        Returns:
+            String with generational suffixes removed
+        """
+        if value is None:
+            return None
+
+        return AttributeUtilities.GENERATIONAL_SUFFIX_PATTERN.sub("", value).strip()
+
+    @staticmethod
+    def get_common_placeholder_names() -> Set[str]:
+        """
+        Get a copy of the common placeholder names set.
+
+        Returns:
+            A copy of the set containing common placeholder names
+        """
+        return AttributeUtilities.COMMON_PLACEHOLDER_NAMES.copy()

openlinktoken/attributes/validation/__init__.py

@@ -0,0 +1,23 @@
+"""Validation utilities for attributes."""
+
+from .age_range_validator import AgeRangeValidator
+from .attribute_validator import AttributeValidator
+from .date_range_validator import DateRangeValidator
+from .not_in_validator import NotInValidator
+from .not_null_or_empty_validator import NotNullOrEmptyValidator
+from .not_starts_with_validator import NotStartsWithValidator
+from .regex_validator import RegexValidator
+from .serializable_attribute_validator import SerializableAttributeValidator
+from .year_range_validator import YearRangeValidator
+
+__all__ = [
+    "AgeRangeValidator",
+    "AttributeValidator",
+    "DateRangeValidator",
+    "NotInValidator",
+    "NotNullOrEmptyValidator",
+    "NotStartsWithValidator",
+    "RegexValidator",
+    "SerializableAttributeValidator",
+    "YearRangeValidator",
+]

openlinktoken/attributes/validation/age_range_validator.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class AgeRangeValidator(SerializableAttributeValidator):
+    """
+    A validator that asserts that an age value is within an acceptable range (0-120).
+
+    This validator checks that ages are:
+    - Not less than 0
+    - Not greater than 120
+
+    If the age is outside this range, the validation fails.
+    """
+
+    MIN_AGE = 0
+    MAX_AGE = 120
+
+    def __init__(self):
+        """Initialize the validator with default age range (0-120)."""
+        pass
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the age value is within acceptable range.
+
+        Args:
+            value: The age string to validate
+
+        Returns:
+            True if the age is within acceptable range (0-120), False otherwise
+        """
+        if not value or not value.strip():
+            return False
+
+        try:
+            age = int(value.strip())
+            return self.MIN_AGE <= age <= self.MAX_AGE
+        except ValueError:
+            return False

openlinktoken/attributes/validation/attribute_validator.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC, abstractmethod
+
+
+class AttributeValidator(ABC):
+    """
+    A generic interface for attribute validation.
+    """
+
+    @abstractmethod
+    def eval(self, value: str) -> bool:
+        """
+        Validate an attribute value.
+
+        Args:
+            value: The attribute value
+
+        Returns:
+            True if the attribute is valid, False otherwise
+        """
+        pass

openlinktoken/attributes/validation/date_range_validator.py

@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: MIT
+
+from datetime import date, datetime
+from typing import Optional
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class DateRangeValidator(SerializableAttributeValidator):
+    """
+    A generic validator that asserts that a date value is within an acceptable range.
+
+    This validator checks that dates are:
+    - Not before the specified minimum date (if provided)
+    - Not after the specified maximum date (if provided)
+    - If use_current_as_max is True, uses today's date as the maximum
+
+    If the date is outside the specified range, the validation fails.
+    """
+
+    # Supported date formats for parsing
+    POSSIBLE_INPUT_FORMATS = [
+        "%Y-%m-%d",
+        "%Y/%m/%d",
+        "%m/%d/%Y",
+        "%m-%d-%Y",
+        "%d.%m.%Y",
+        # ISO 8601 timestamp formats
+        "%Y-%m-%dT%H:%M:%S.%fZ",
+        "%Y-%m-%dT%H:%M:%SZ",
+        "%Y-%m-%dT%H:%M:%S.%f%z",
+        "%Y-%m-%dT%H:%M:%S%z",
+    ]
+
+    def __init__(
+        self, min_date: Optional[date] = None, max_date: Optional[date] = None, use_current_as_max: bool = False
+    ):
+        """
+        Initialize the validator with a date range.
+
+        Args:
+            min_date: The minimum allowed date (inclusive), or None for no minimum
+            max_date: The maximum allowed date (inclusive), or None for no maximum
+            use_current_as_max: If True, uses today's date as the maximum date
+        """
+        self._min_date = min_date
+        self._use_current_as_max = use_current_as_max
+        self._max_date = max_date
+
+    @property
+    def min_date(self) -> Optional[date]:
+        """Get the minimum allowed date."""
+        return self._min_date
+
+    @property
+    def max_date(self) -> Optional[date]:
+        """Get the maximum allowed date."""
+        if self._use_current_as_max:
+            return date.today()
+        return self._max_date
+
+    @property
+    def use_current_as_max(self) -> bool:
+        """Check if using current date as maximum."""
+        return self._use_current_as_max
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the date value is within acceptable range.
+
+        Args:
+            value: The date string to validate
+
+        Returns:
+            True if the date is within acceptable range, False otherwise
+        """
+        if not value or not value.strip():
+            return False
+
+        parsed_date = self._parse_date(value.strip())
+        if parsed_date is None:
+            return False
+
+        # Check minimum date if specified
+        if self._min_date is not None and parsed_date < self._min_date:
+            return False
+
+        # Check maximum date
+        max_date_to_check = self.max_date
+        if max_date_to_check is not None and parsed_date > max_date_to_check:
+            return False
+
+        return True
+
+    def _parse_date(self, value: str) -> Optional[date]:
+        """
+        Parse the date string using various supported formats.
+
+        Args:
+            value: The date string to parse
+
+        Returns:
+            Parsed date object, or None if parsing fails
+        """
+        for date_format in self.POSSIBLE_INPUT_FORMATS:
+            try:
+                parsed_datetime = datetime.strptime(value, date_format)
+                return parsed_datetime.date()
+            except ValueError:
+                continue
+        return None

openlinktoken/attributes/validation/not_in_validator.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Set
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class NotInValidator(SerializableAttributeValidator):
+    """
+    A Validator that asserts that the attribute value is NOT IN the list of invalid values.
+    """
+
+    def __init__(self, invalid_values: Set[str]):
+        """
+        Initialize the validator with a set of invalid values.
+
+        Args:
+            invalid_values: Set of values that should be considered invalid
+
+        Raises:
+            ValueError: If invalid_values is None
+        """
+        if invalid_values is None:
+            raise ValueError("Invalid values set cannot be None")
+
+        # Convert to lowercase for case-insensitive comparison
+        self._invalid_values = {value.lower() for value in invalid_values}
+
+    @property
+    def invalid_values(self) -> Set[str]:
+        """Get the set of invalid values (in lowercase)."""
+        return self._invalid_values.copy()
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the attribute value is not in the list of invalid values
+        (case-insensitive comparison).
+
+        Args:
+            value: The attribute value to validate
+
+        Returns:
+            True if the value is not in the invalid values list, False otherwise
+        """
+        if value is None:
+            return False
+
+        return value.lower() not in self._invalid_values

openlinktoken/attributes/validation/not_null_or_empty_validator.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class NotNullOrEmptyValidator(SerializableAttributeValidator):
+    """
+    A Validator that asserts the value is NOT None and not blank.
+    """
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the attribute value is not None or blank.
+
+        Args:
+            value: The attribute value to validate
+
+        Returns:
+            True if value is not None and not blank, False otherwise
+        """
+        return value is not None and value.strip() != ""

openlinktoken/attributes/validation/not_starts_with_validator.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from typing import Set
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class NotStartsWithValidator(SerializableAttributeValidator):
+    """
+    A Validator that asserts that the attribute value does NOT START WITH
+    any of the invalid prefixes.
+    """
+
+    def __init__(self, invalid_prefixes: Set[str]):
+        """
+        Initialize the validator with a set of invalid prefixes.
+
+        Args:
+            invalid_prefixes: Set of prefixes that values should not start with
+
+        Raises:
+            ValueError: If invalid_prefixes is None
+        """
+        if invalid_prefixes is None:
+            raise ValueError("Invalid prefixes set cannot be None")
+
+        self._invalid_prefixes = invalid_prefixes.copy()
+
+    @property
+    def invalid_prefixes(self) -> Set[str]:
+        """Get the set of invalid prefixes."""
+        return self._invalid_prefixes.copy()
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the attribute value does not start with any of the invalid prefixes.
+
+        Args:
+            value: The attribute value to validate
+
+        Returns:
+            True if the value doesn't start with any invalid prefix, False otherwise
+        """
+        if value is None:
+            return False
+
+        trimmed_value = value.strip()
+        return not any(trimmed_value.startswith(prefix) for prefix in self._invalid_prefixes)

openlinktoken/attributes/validation/regex_validator.py

@@ -0,0 +1,44 @@
+# SPDX-License-Identifier: MIT
+
+import re
+from typing import Pattern
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class RegexValidator(SerializableAttributeValidator):
+    """
+    A Validator that is designed for validating with regex expressions.
+    """
+
+    def __init__(self, pattern: str):
+        """
+        Initialize the regex validator with a pattern.
+
+        Args:
+            pattern: The regex pattern string to compile and use for validation
+
+        Raises:
+            re.error: If the pattern is invalid
+        """
+        if not pattern:
+            raise ValueError("Pattern cannot be None or empty")
+
+        self._compiled_pattern: Pattern[str] = re.compile(pattern)
+
+    @property
+    def compiled_pattern(self) -> Pattern[str]:
+        """Get the compiled regex pattern."""
+        return self._compiled_pattern
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the value matches the regex pattern.
+
+        Args:
+            value: The attribute value to validate
+
+        Returns:
+            True if the value matches the pattern, False otherwise
+        """
+        return value is not None and bool(self._compiled_pattern.match(value))

openlinktoken/attributes/validation/serializable_attribute_validator.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+
+from abc import ABC
+
+from openlinktoken.attributes.validation.attribute_validator import AttributeValidator
+
+
+class SerializableAttributeValidator(AttributeValidator, ABC):
+    """
+    An extension of the AttributeValidator interface that is also serializable.
+
+    This interface should be implemented by validator classes that need to be
+    serialized, such as when they are part of serializable attributes or need to
+    be transmitted over a network.
+
+    Implementing classes must ensure that all their fields are serializable or
+    handled appropriately if they cannot be serialized.
+
+    Note: In Python, most objects are serializable by default with pickle,
+    but this class serves as a marker for validators that are explicitly
+    designed to be serializable.
+    """
+
+    # This is a marker interface that combines AttributeValidator and serializable capability
+    # No additional methods are required
+    pass

openlinktoken/attributes/validation/year_range_validator.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+from datetime import date
+
+from openlinktoken.attributes.validation.serializable_attribute_validator import SerializableAttributeValidator
+
+
+class YearRangeValidator(SerializableAttributeValidator):
+    """
+    A validator that asserts that a year value is within an acceptable range.
+
+    This validator checks that years are:
+    - Not before 1910
+    - Not after the current year
+
+    If the year is outside this range, the validation fails.
+    """
+
+    MIN_YEAR = 1910
+
+    def __init__(self):
+        """Initialize the validator with default year range (1910-current year)."""
+        pass
+
+    @property
+    def max_year(self) -> int:
+        """Get the maximum allowed year (current year)."""
+        return date.today().year
+
+    def eval(self, value: str) -> bool:
+        """
+        Validate that the year value is within acceptable range.
+
+        Args:
+            value: The year string to validate
+
+        Returns:
+            True if the year is within acceptable range (1910-current year),
+            False otherwise
+        """
+        if not value or not value.strip():
+            return False
+
+        try:
+            year = int(value.strip())
+            return self.MIN_YEAR <= year <= self.max_year
+        except ValueError:
+            return False