taghound 0.2.0__py3-none-any.whl

taghound/__init__.py

@@ -0,0 +1,5 @@
+"""TagHound: rule-based tagging for dicts and pandas DataFrames."""
+
+from taghound.taghound import TagHound
+
+__all__ = ["TagHound"]

taghound/constants.py

@@ -0,0 +1,87 @@
+"""Shared enums, type aliases, and defaults for rule definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from enum import Enum
+from typing import Any
+
+import pandas as pd
+
+PyEvalFn = Callable[[Mapping[str, Any]], bool]
+PdEvalFn = Callable[[pd.DataFrame], pd.Series]
+
+
+class LogicalOperator(Enum):
+    """Logical operators combining condition lists."""
+
+    AND = "and"
+    OR = "or"
+
+
+class ComparisonOperator(Enum):
+    """Comparison operators usable in a condition's `op` field."""
+
+    EQUAL = "="
+    NOT_EQUAL = "!="
+    GREATER_THAN = ">"
+    GREATER_THAN_OR_EQUAL = ">="
+    LESS_THAN = "<"
+    LESS_THAN_OR_EQUAL = "<="
+    IS = "is"
+    IS_NOT = "is_not"
+    IN = "in"
+    NOT_IN = "not_in"
+    REGEX_MATCH = "~"
+    REGEX_NOT_MATCH = "!~"
+
+
+ComparisonOperatorRegexOnly = {
+    ComparisonOperator.REGEX_MATCH,
+    ComparisonOperator.REGEX_NOT_MATCH,
+}
+ComparisonOperatorNumericOnly = {
+    ComparisonOperator.GREATER_THAN,
+    ComparisonOperator.GREATER_THAN_OR_EQUAL,
+    ComparisonOperator.LESS_THAN,
+    ComparisonOperator.LESS_THAN_OR_EQUAL,
+}
+ComparisonOperatorBoolOnly = {
+    ComparisonOperator.IS,
+    ComparisonOperator.IS_NOT,
+}
+ComparisonOperatorListOnly = {
+    ComparisonOperator.IN,
+    ComparisonOperator.NOT_IN,
+}
+
+
+class RuleKey(Enum):
+    """Top-level keys of a rule definition."""
+
+    ID = "id"
+    LABEL = "label"
+    WEIGHT = "weight"
+    INFO = "info"
+    ROOT_AND = LogicalOperator.AND.value
+    ROOT_OR = LogicalOperator.OR.value
+
+
+class ComparisonKey(Enum):
+    """Keys of a single comparison condition."""
+
+    KEY = "key"
+    OPERATOR = "op"
+    VALUE = "value"
+
+
+DEFAULT_COMPARISON_OPERATOR = ComparisonOperator.EQUAL
+""" Default comparison operator to use when not specified """
+
+DEFAULT_WEIGHT = 0.0
+""" Default weight to use when not specified """
+
+# - This is better than \b...\b because it also matches cases like `C++`
+# - Limitations: does not work when we need to match `.python` with `python` pattern
+DEFAULT_REGEX_MERGE_PATTERN = r"(?<!\w)(?:{pattern})(?!\w)"
+""" Pattern used to merge list of patterns into a single regex pattern """

taghound/exceptions.py

@@ -0,0 +1,13 @@
+"""Exceptions raised while parsing rule definitions."""
+
+
+class InvalidOperatorError(Exception):
+    """A logical node uses an operator other than `and`/`or`."""
+
+
+class RuleAndOrTogetherError(Exception):
+    """A rule's root condition has both `and` and `or`."""
+
+
+class MissingRootConditionError(Exception):
+    """A rule's root condition has neither `and` nor `or`."""

taghound/models.py

@@ -0,0 +1,38 @@
+"""Data model for tag rules."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from taghound.constants import PdEvalFn, PyEvalFn
+
+
+@dataclass(frozen=True, eq=True, slots=True)
+class TagRule:
+    """A single tag rule: identity, metadata, and its prebuilt check functions."""
+
+    id: str
+    """ Unique identifier for the rule. """
+
+    label: str = field(compare=False)
+    """ The label for the rule. No uniqueness is enforced. """
+
+    weight: float = field(compare=False)
+    """ The weight of the rule. """
+
+    required_fields: set[str] = field(compare=False)
+    """ The required fields for the rule. """
+
+    info: str | None = field(compare=False, default=None)
+    """ Internal comments for the rule. """
+
+    scalar_check: PyEvalFn | None = field(compare=False, default=None)
+    """ Scalar function used to check if the rule is satisfied. """
+
+    vector_check: PdEvalFn | None = field(compare=False, default=None)
+    """ Vector function used to check if the rule is satisfied. """
+
+    data: Mapping[str, Any] = field(compare=False, default_factory=dict)
+    """ The original data used to create the TagRule object. """

taghound/scalar/__init__.py

@@ -0,0 +1 @@
+"""Scalar (one mapping at a time) rule evaluation."""

taghound/scalar/function_builder.py

@@ -0,0 +1,218 @@
+"""Build per-rule check functions that evaluate one data mapping at a time."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from collections.abc import Callable, Mapping, Sequence
+
+from taghound.constants import (
+    DEFAULT_COMPARISON_OPERATOR,
+    ComparisonKey,
+    ComparisonOperator,
+    ComparisonOperatorListOnly,
+    ComparisonOperatorNumericOnly,
+    ComparisonOperatorRegexOnly,
+    LogicalOperator,
+    PyEvalFn,
+    RuleKey,
+)
+from taghound.exceptions import InvalidOperatorError, MissingRootConditionError
+from taghound.scalar.operators import ComparisonOperatorMap, LogicalOperatorMap
+
+
+def create_scalar_function(data: Mapping[str, Any], merge_pattern: str) -> PyEvalFn:
+    """Create a function that will evaluate the scalar condition.
+
+    Args:
+        data (Mapping): The data to create the scalar function.
+        merge_pattern (str): The pattern to merge the regex patterns.
+
+    Returns:
+        PyEvalFn: The function that will evaluate the scalar condition.
+    """
+    if RuleKey.ROOT_AND.value in data:
+        condition_fn = _create_logic_function(
+            {LogicalOperator.AND.value: data[RuleKey.ROOT_AND.value]},
+            merge_pattern=merge_pattern,
+        )
+    elif RuleKey.ROOT_OR.value in data:
+        condition_fn = _create_logic_function(
+            {LogicalOperator.OR.value: data[RuleKey.ROOT_OR.value]},
+            merge_pattern=merge_pattern,
+        )
+    else:
+        raise MissingRootConditionError(
+            "Root condition must have either `and` or `or`."
+        )
+    return condition_fn
+
+
+def _create_logic_function(
+    params: Mapping[str, Sequence[Mapping[str, Any]]], merge_pattern: str
+) -> Callable:
+    """Create a function that will evaluate the logical operation (OR/AND).
+
+    Args:
+        params (Mapping): The parameters for the logical operation.
+        merge_pattern (str): The pattern to merge the regex patterns.
+
+    Returns:
+        Callable: The function that will evaluate the logical operation.
+
+    Raises:
+        InvalidOperatorError: If the operator is not valid.
+
+    Example:
+        ```python
+        params = {
+            "and": [
+                {"key": "language", "op": "=", "value": "python"},
+                {"key": "year", "op": ">", "value": 1990},
+            ]
+        }
+        fn = _make_logic_operation_function(params)
+        ```
+    """
+    try:
+        logical_operator = LogicalOperator(next(iter(params.keys())))
+    except (StopIteration, ValueError):
+        raise InvalidOperatorError(
+            f"Invalid operator. Must be one of {LogicalOperator.__members__}"
+        )
+    logical_fn = LogicalOperatorMap[logical_operator]
+
+    condition_fns = _parse_conditions(
+        params[logical_operator.value], merge_pattern=merge_pattern
+    )
+
+    def logic_function(data: Mapping[str, Any]) -> bool:
+        return logical_fn(fn(data) for fn in condition_fns)
+
+    return logic_function
+
+
+def _parse_conditions(
+    conditions: Sequence[Mapping], merge_pattern: str
+) -> list[Callable[[Mapping[str, Any]], bool]]:
+    """Create a list of functions that will evaluate the conditions.
+
+    Args:
+        conditions (list[Mapping]): The list of conditions to be evaluated.
+        merge_pattern (str): The pattern to merge the regex patterns.
+
+    Returns:
+        list[Callable]: The list of functions that will evaluate the conditions.
+
+    Example:
+        ```python
+        elems = [
+            {"key": "language", "op": "=", "value": "python"},
+            {"key": "year", "op": ">", "value": 1990},
+        ]
+        fns = _make_condition_functions(elems)
+        ```
+
+    """
+    if not isinstance(conditions, Sequence):
+        raise TypeError(f"Must be list. Given: `{type(conditions)}`")
+
+    comparison_fns = []
+    for condition in conditions:
+        if not isinstance(condition, Mapping):
+            raise TypeError(f"Expected a Mapping. Given: `{type(condition)}`")
+        if not condition:
+            raise ValueError("Empty Mapping found in logical conditions.")
+
+        if len(condition.keys()) == 1:
+            conditions_fn = _create_logic_function(
+                condition, merge_pattern=merge_pattern
+            )
+            comparison_fns.append(conditions_fn)
+        else:
+            fn = _make_comparison_condition_function(
+                key=condition[ComparisonKey.KEY.value],
+                value=condition[ComparisonKey.VALUE.value],
+                operator=condition.get(
+                    ComparisonKey.OPERATOR.value, DEFAULT_COMPARISON_OPERATOR.value
+                ),
+                merge_pattern=merge_pattern,
+            )
+            comparison_fns.append(fn)
+    return comparison_fns
+
+
+def _make_comparison_condition_function(
+    key: str, value: object, operator: str, merge_pattern: str
+) -> Callable[[Any], bool]:
+    """Create a function that will evaluate the comparison condition.
+
+    Args:
+        key (str): The key in the Mapping to be compared.
+        value (Any): The value to be compared.
+        operator (str): The operator used in the condition e.g `=`, `>`, ...
+        merge_pattern (str): The pattern to merge the regex patterns.
+
+    Returns:
+        Callable: The function that will evaluate the comparison condition.
+    """
+    operator_enum = ComparisonOperator(operator)
+
+    value, operator_enum = _validate_and_normalize_comparison_condition_data(
+        value, operator_enum, merge_pattern
+    )
+
+    def comparison_condition_function(data: Mapping[str, Any]) -> bool:
+        return ComparisonOperatorMap[operator_enum](data, key, value)
+
+    return comparison_condition_function
+
+
+def _validate_and_normalize_comparison_condition_data(
+    value: object,
+    operator_enum: ComparisonOperator,
+    merge_pattern: str,
+) -> tuple[Any, ComparisonOperator]:
+    """Validate and normalize the value based on the operator.
+
+    Args:
+        value (Any): The value to be validated
+        operator_enum (ComparisonOperator): The operator used in the condition
+        merge_pattern (str): The pattern to merge the regex patterns
+
+    Returns:
+        tuple[Any, ComparisonOperator]: The normalized value and operator
+    """
+    if operator_enum in ComparisonOperatorRegexOnly:
+        if isinstance(value, list):
+            pattern_str = "|".join(value)
+        elif isinstance(value, str):
+            pattern_str = value
+        else:
+            raise ValueError(f"Invalid value for regex match: `{value}` ({type(value)}")
+
+        try:
+            value = re.compile(merge_pattern.format(pattern=pattern_str), re.IGNORECASE)
+        except re.error:
+            raise ValueError(f"Invalid regex pattern: `{pattern_str}`")
+
+    elif operator_enum in ComparisonOperatorNumericOnly:
+        if not isinstance(value, (int, float)):
+            raise ValueError(
+                f"Invalid value for number comparison: `{value}` ({type(value)})"
+            )
+
+    elif operator_enum in ComparisonOperatorListOnly:
+        if not isinstance(value, (list, tuple, set)):
+            raise ValueError(
+                f"Invalid value for list comparison: `{value}` ({type(value)}"
+            )
+        value = set(value)
+
+    elif isinstance(value, bool):
+        if operator_enum == ComparisonOperator.EQUAL:
+            operator_enum = ComparisonOperator.IS
+        elif operator_enum == ComparisonOperator.NOT_EQUAL:
+            operator_enum = ComparisonOperator.IS_NOT
+
+    return value, operator_enum

taghound/scalar/operators.py

@@ -0,0 +1,91 @@
+"""Comparison and logical operator implementations for the scalar path."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from collections.abc import Callable, Mapping
+
+from taghound.constants import ComparisonOperator, LogicalOperator
+
+LogicalOperatorMap: dict[LogicalOperator, Callable] = {
+    LogicalOperator.AND: all,
+    LogicalOperator.OR: any,
+}
+
+
+def eval_equal(data: Mapping, key: str, value: bool | str | int | float) -> bool:
+    """Return whether `data[key] == value`."""
+    return data[key] == value
+
+
+def eval_not_equal(data: Mapping, key: str, value: bool | str | int | float) -> bool:
+    """Return whether `data[key] != value`."""
+    return data[key] != value
+
+
+def eval_greater_than(data: Mapping, key: str, value: int | float) -> bool:
+    """Return whether `data[key] > value`."""
+    return data[key] > value
+
+
+def eval_greater_than_or_equal(data: Mapping, key: str, value: int | float) -> bool:
+    """Return whether `data[key] >= value`."""
+    return data[key] >= value
+
+
+def eval_less_than(data: Mapping, key: str, value: int | float) -> bool:
+    """Return whether `data[key] < value`."""
+    return data[key] < value
+
+
+def eval_less_than_or_equal(data: Mapping, key: str, value: int | float) -> bool:
+    """Return whether `data[key] <= value`."""
+    return data[key] <= value
+
+
+def eval_in(data: Mapping, key: str, value: set[bool | str | int | float]) -> bool:
+    """Return whether `data[key]` is a member of `value`."""
+    return data[key] in value
+
+
+def eval_not_in(data: Mapping, key: str, value: set[bool | str | int | float]) -> bool:
+    """Return whether `data[key]` is not a member of `value`."""
+    return data[key] not in value
+
+
+def eval_is(data: Mapping, key: str, value: bool) -> bool:
+    """Return whether `data[key] is value`."""
+    return data[key] is value
+
+
+def eval_is_not(data: Mapping, key: str, value: bool) -> bool:
+    """Return whether `data[key] is not value`."""
+    return data[key] is not value
+
+
+def eval_regex_match(data: Mapping, key: str, value: re.Pattern[str]) -> bool:
+    """Return whether the pattern matches anywhere in `data[key]`."""
+    return value.search(data[key]) is not None
+
+
+def eval_regex_not_match(data: Mapping, key: str, value: re.Pattern[str]) -> bool:
+    """Return whether the pattern matches nowhere in `data[key]`."""
+    return not value.search(data[key])
+
+
+ComparisonOperatorFn = Callable[[Mapping, str, Any], bool]
+ComparisonOperatorMap: Mapping[ComparisonOperator, ComparisonOperatorFn] = {
+    ComparisonOperator.EQUAL: eval_equal,
+    ComparisonOperator.NOT_EQUAL: eval_not_equal,
+    ComparisonOperator.GREATER_THAN: eval_greater_than,
+    ComparisonOperator.GREATER_THAN_OR_EQUAL: eval_greater_than_or_equal,
+    ComparisonOperator.LESS_THAN: eval_less_than,
+    ComparisonOperator.LESS_THAN_OR_EQUAL: eval_less_than_or_equal,
+    ComparisonOperator.IN: eval_in,
+    ComparisonOperator.NOT_IN: eval_not_in,
+    ComparisonOperator.IS: eval_is,
+    ComparisonOperator.IS_NOT: eval_is_not,
+    ComparisonOperator.REGEX_MATCH: eval_regex_match,
+    ComparisonOperator.REGEX_NOT_MATCH: eval_regex_not_match,
+}

taghound/serializers.py

@@ -0,0 +1,129 @@
+"""Serialization of raw rule dicts into TagRule objects."""
+
+from __future__ import annotations
+
+from typing import Any
+from collections.abc import Mapping, Sequence
+
+from taghound.constants import (
+    DEFAULT_REGEX_MERGE_PATTERN,
+    DEFAULT_WEIGHT,
+    ComparisonKey,
+    LogicalOperator,
+    RuleKey,
+)
+from taghound.models import TagRule
+from taghound.exceptions import MissingRootConditionError, RuleAndOrTogetherError
+from taghound.scalar.function_builder import create_scalar_function
+from taghound.vector.function_builder import create_vector_function
+
+
+def to_tag_rule(
+    rule_data: Mapping[str, Any],
+    add_scalar_func: bool = True,
+    add_vector_fn: bool = True,
+    merge_pattern: str = DEFAULT_REGEX_MERGE_PATTERN,
+) -> TagRule:
+    """Create a TagRule object from the given data.
+
+    Args:
+        rule_data (Mapping[str, Any]): The rule definition: `id`, optional `label`,
+            `weight` and `info`, plus a root `and` or `or` condition list.
+        add_scalar_func (bool): Whether to build the scalar check function.
+        add_vector_fn (bool): Whether to build the vector check function.
+        merge_pattern (str): The pattern used to merge regex patterns.
+
+    Returns:
+        TagRule: The TagRule object created from the data.
+
+    Example:
+        >>> rule = to_tag_rule(
+        ...     {
+        ...         "id": "python",
+        ...         "weight": 10,
+        ...         "and": [
+        ...             {"key": "language", "op": "=", "value": "python"},
+        ...             {"key": "year", "op": ">", "value": 1990},
+        ...         ],
+        ...     }
+        ... )
+        >>> rule.id
+        'python'
+        >>> rule.weight
+        10.0
+        >>> sorted(rule.required_fields)
+        ['language', 'year']
+    """
+    tag_name = rule_data[RuleKey.ID.value]
+    weight = rule_data.get(RuleKey.WEIGHT.value, DEFAULT_WEIGHT)
+    label = rule_data.get(RuleKey.LABEL.value, tag_name)
+    info = rule_data.get(RuleKey.INFO.value, None)
+
+    # Validate
+    if not isinstance(tag_name, str):
+        raise ValueError(f"tag_name must be a string. Given: `{type(tag_name)}`")
+
+    if isinstance(weight, int):
+        weight = float(weight)
+    elif not isinstance(weight, float):
+        raise ValueError(f"weight must be a integer or float. Given: {type(weight)}")
+    if RuleKey.ROOT_AND.value in rule_data and RuleKey.ROOT_OR.value in rule_data:
+        raise RuleAndOrTogetherError(
+            "Cannot have both `and` and `or` in the same root condition."
+        )
+
+    try:
+        required_fields = (
+            get_required_keys_from_conditions(rule_data[RuleKey.ROOT_AND.value])
+            if RuleKey.ROOT_AND.value in rule_data
+            else get_required_keys_from_conditions(rule_data[RuleKey.ROOT_OR.value])
+        )
+    except KeyError:
+        raise MissingRootConditionError()
+
+    tag = TagRule(
+        id=tag_name,
+        label=label,
+        weight=weight,
+        info=info,
+        required_fields=required_fields,
+        scalar_check=(
+            create_scalar_function(rule_data, merge_pattern=merge_pattern)
+            if add_scalar_func
+            else None
+        ),
+        vector_check=(
+            create_vector_function(rule_data, merge_pattern=merge_pattern)
+            if add_vector_fn
+            else None
+        ),
+        data=rule_data,
+    )
+    return tag
+
+
+def get_required_keys_from_conditions(
+    conditions: Sequence[Mapping[str, Any]],
+) -> set[str]:
+    """Collect the data keys referenced by the conditions, recursing into nested and/or.
+
+    Args:
+        conditions (Sequence[Mapping[str, Any]]): The conditions to scan.
+
+    Returns:
+        set[str]: The keys the conditions compare against.
+    """
+    keys_set = set()
+    for condition in conditions:
+        if not isinstance(condition, Mapping):
+            raise TypeError(
+                f"Expected a Mapping. Given: `{type(condition)}`. Value: `{condition}`"
+            )
+        if ComparisonKey.KEY.value in condition:
+            keys_set.add(condition[ComparisonKey.KEY.value])
+            continue
+        for logical_operator in LogicalOperator:
+            nested = condition.get(logical_operator.value)
+            if isinstance(nested, Sequence) and not isinstance(nested, str):
+                keys_set.update(get_required_keys_from_conditions(nested))
+    return keys_set