Types API Reference

BaseType

Bases: ABC

Abstract base class for all NLQL types.

Types must implement comparison methods to support WHERE clause operations.

Source code in src/nlql/types/core.py

class BaseType(ABC):
    """Abstract base class for all NLQL types.

    Types must implement comparison methods to support WHERE clause operations.
    """

    def __init__(self, value: Any) -> None:
        self.value = value

    @abstractmethod
    def __lt__(self, other: Any) -> bool:
        """Less than comparison."""
        pass

    @abstractmethod
    def __le__(self, other: Any) -> bool:
        """Less than or equal comparison."""
        pass

    @abstractmethod
    def __gt__(self, other: Any) -> bool:
        """Greater than comparison."""
        pass

    @abstractmethod
    def __ge__(self, other: Any) -> bool:
        """Greater than or equal comparison."""
        pass

    @abstractmethod
    def __eq__(self, other: Any) -> bool:
        """Equality comparison."""
        pass

    def __ne__(self, other: Any) -> bool:
        """Not equal comparison."""
        return not self.__eq__(other)

    def __repr__(self) -> str:
        return f"{self.__class__.__name__}({self.value!r})"

__lt__(other) abstractmethod

Less than comparison.

Source code in src/nlql/types/core.py

@abstractmethod
def __lt__(self, other: Any) -> bool:
    """Less than comparison."""
    pass

__le__(other) abstractmethod

Less than or equal comparison.

Source code in src/nlql/types/core.py

@abstractmethod
def __le__(self, other: Any) -> bool:
    """Less than or equal comparison."""
    pass

__gt__(other) abstractmethod

Greater than comparison.

Source code in src/nlql/types/core.py

@abstractmethod
def __gt__(self, other: Any) -> bool:
    """Greater than comparison."""
    pass

__ge__(other) abstractmethod

Greater than or equal comparison.

Source code in src/nlql/types/core.py

@abstractmethod
def __ge__(self, other: Any) -> bool:
    """Greater than or equal comparison."""
    pass

__eq__(other) abstractmethod

Equality comparison.

Source code in src/nlql/types/core.py

@abstractmethod
def __eq__(self, other: Any) -> bool:
    """Equality comparison."""
    pass

__ne__(other)

Not equal comparison.

Source code in src/nlql/types/core.py

def __ne__(self, other: Any) -> bool:
    """Not equal comparison."""
    return not self.__eq__(other)

NumberType

Bases: BaseType

Numeric type supporting arithmetic comparisons.

Source code in src/nlql/types/core.py

class NumberType(BaseType):
    """Numeric type supporting arithmetic comparisons."""

    def __init__(self, value: int | float) -> None:
        super().__init__(float(value))

    def __lt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value < float(other_val)

    def __le__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value <= float(other_val)

    def __gt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value > float(other_val)

    def __ge__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value >= float(other_val)

    def __eq__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value == float(other_val)

TextType

Bases: BaseType

Text type supporting lexicographic comparisons.

Source code in src/nlql/types/core.py

class TextType(BaseType):
    """Text type supporting lexicographic comparisons."""

    def __init__(self, value: str) -> None:
        super().__init__(str(value))

    def __lt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value < str(other_val)

    def __le__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value <= str(other_val)

    def __gt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value > str(other_val)

    def __ge__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value >= str(other_val)

    def __eq__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, BaseType) else other
        return self.value == str(other_val)

DateType

Bases: BaseType

Date/datetime type supporting temporal comparisons.

Source code in src/nlql/types/core.py

class DateType(BaseType):
    """Date/datetime type supporting temporal comparisons."""

    def __init__(self, value: datetime | str) -> None:
        if isinstance(value, str):
            # Simple ISO format parsing, can be extended
            value = datetime.fromisoformat(value)
        super().__init__(value)

    def __lt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, DateType) else other
        if isinstance(other_val, str):
            other_val = datetime.fromisoformat(other_val)
        return self.value < other_val

    def __le__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, DateType) else other
        if isinstance(other_val, str):
            other_val = datetime.fromisoformat(other_val)
        return self.value <= other_val

    def __gt__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, DateType) else other
        if isinstance(other_val, str):
            other_val = datetime.fromisoformat(other_val)
        return self.value > other_val

    def __ge__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, DateType) else other
        if isinstance(other_val, str):
            other_val = datetime.fromisoformat(other_val)
        return self.value >= other_val

    def __eq__(self, other: Any) -> bool:
        other_val = other.value if isinstance(other, DateType) else other
        if isinstance(other_val, str):
            other_val = datetime.fromisoformat(other_val)
        return self.value == other_val

MetaFieldRegistry

Registry for META field type information.

This allows users to register type information for metadata fields, enabling type-safe comparisons in WHERE clauses.

Source code in src/nlql/types/meta.py

class MetaFieldRegistry:
    """Registry for META field type information.

    This allows users to register type information for metadata fields,
    enabling type-safe comparisons in WHERE clauses.
    """

    def __init__(self) -> None:
        self._field_types: dict[str, Type[BaseType]] = {}

    def register(self, field_name: str, type_class: Type[BaseType]) -> None:
        """Register a META field with its type class.

        Args:
            field_name: Name of the metadata field
            type_class: Type class (e.g., NumberType, TextType, DateType)

        Raises:
            NLQLTypeError: If type_class is not a valid BaseType subclass
        """
        if not issubclass(type_class, BaseType):
            raise NLQLTypeError(
                f"Type class must be a subclass of BaseType, got {type_class}"
            )
        self._field_types[field_name] = type_class

    def get_type(self, field_name: str) -> Type[BaseType] | None:
        """Get the registered type class for a field.

        Args:
            field_name: Name of the metadata field

        Returns:
            Type class if registered, None otherwise
        """
        return self._field_types.get(field_name)

    def wrap_value(self, field_name: str, value: Any) -> BaseType:
        """Wrap a raw value in its registered type class.

        Args:
            field_name: Name of the metadata field
            value: Raw value from data source

        Returns:
            Wrapped value as a BaseType instance

        Raises:
            NLQLTypeError: If field is not registered or wrapping fails
        """
        type_class = self.get_type(field_name)
        if type_class is None:
            # Default to TextType if not registered
            type_class = TextType

        try:
            return type_class(value)
        except Exception as e:
            raise NLQLTypeError(
                f"Failed to wrap value {value!r} for field '{field_name}' "
                f"with type {type_class.__name__}: {e}"
            ) from e

    def clear(self) -> None:
        """Clear all registered field types."""
        self._field_types.clear()

register(field_name, type_class)

Register a META field with its type class.

Parameters:

Name	Type	Description	Default
field_name	str	Name of the metadata field	required
type_class	Type[BaseType]	Type class (e.g., NumberType, TextType, DateType)	required

Raises:

Type	Description
NLQLTypeError	If type_class is not a valid BaseType subclass

Source code in src/nlql/types/meta.py

def register(self, field_name: str, type_class: Type[BaseType]) -> None:
    """Register a META field with its type class.

    Args:
        field_name: Name of the metadata field
        type_class: Type class (e.g., NumberType, TextType, DateType)

    Raises:
        NLQLTypeError: If type_class is not a valid BaseType subclass
    """
    if not issubclass(type_class, BaseType):
        raise NLQLTypeError(
            f"Type class must be a subclass of BaseType, got {type_class}"
        )
    self._field_types[field_name] = type_class

get_type(field_name)

Get the registered type class for a field.

Parameters:

Name	Type	Description	Default
field_name	str	Name of the metadata field	required

Returns:

Type	Description
Type[BaseType] | None	Type class if registered, None otherwise

Source code in src/nlql/types/meta.py

def get_type(self, field_name: str) -> Type[BaseType] | None:
    """Get the registered type class for a field.

    Args:
        field_name: Name of the metadata field

    Returns:
        Type class if registered, None otherwise
    """
    return self._field_types.get(field_name)

wrap_value(field_name, value)

Wrap a raw value in its registered type class.

Parameters:

Name	Type	Description	Default
field_name	str	Name of the metadata field	required
value	Any	Raw value from data source	required

Returns:

Type	Description
BaseType	Wrapped value as a BaseType instance

Raises:

Type	Description
NLQLTypeError	If field is not registered or wrapping fails

Source code in src/nlql/types/meta.py

def wrap_value(self, field_name: str, value: Any) -> BaseType:
    """Wrap a raw value in its registered type class.

    Args:
        field_name: Name of the metadata field
        value: Raw value from data source

    Returns:
        Wrapped value as a BaseType instance

    Raises:
        NLQLTypeError: If field is not registered or wrapping fails
    """
    type_class = self.get_type(field_name)
    if type_class is None:
        # Default to TextType if not registered
        type_class = TextType

    try:
        return type_class(value)
    except Exception as e:
        raise NLQLTypeError(
            f"Failed to wrap value {value!r} for field '{field_name}' "
            f"with type {type_class.__name__}: {e}"
        ) from e

clear()

Clear all registered field types.

Source code in src/nlql/types/meta.py

def clear(self) -> None:
    """Clear all registered field types."""
    self._field_types.clear()