feat(spider-py): Define TDL types; Add support for converting Python types into TDL types.

python/spider-py/pyproject.toml

@@ -67,6 +67,7 @@ ignore = [
   "UP015",  # Explicit open modes are helpful
 ]
 isort.order-by-type = false
+typing-extensions = false  # Disable type extensions for 3.10 compatibility
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = [
@@ -75,3 +76,6 @@ isort.order-by-type = false
   "S603",  # Allow use of `subprocess.Popen` (security warning)
   "T201",  # Allow use of `print` (testing)
 ]
+
+[tool.ruff.lint.pydocstyle]
+ignore-decorators = ["typing.override"]

python/spider-py/src/spider_py/__init__.py

@@ -1 +1,12 @@
 """Spider package root."""
+
+from spider_py.type import Double, Float, Int8, Int16, Int32, Int64
+
+__all__ = [
+    "Double",
+    "Float",
+    "Int8",
+    "Int16",
+    "Int32",
+    "Int64",
+]

python/spider-py/src/spider_py/type/__init__.py

@@ -0,0 +1,6 @@
+"""Spider type package."""
+
+from spider_py.type.tdl_convert import to_tdl_type_str
+from spider_py.type.type import Double, Float, Int8, Int16, Int32, Int64
+
+__all__ = ["Double", "Float", "Int8", "Int16", "Int32", "Int64", "to_tdl_type_str"]

python/spider-py/src/spider_py/type/tdl_convert.py

@@ -0,0 +1,100 @@
+"""Converts native types to TDL types."""
+
+from collections.abc import Collection
+from types import GenericAlias
+from typing import get_args, get_origin
+
+from spider_py.type.tdl_type import (
+    BoolType,
+    ClassType,
+    DoubleType,
+    FloatType,
+    Int8Type,
+    Int16Type,
+    Int32Type,
+    Int64Type,
+    ListType,
+    MapType,
+    TdlType,
+)
+from spider_py.type.type import Double, Float, Int8, Int16, Int32, Int64
+from spider_py.type.utils import get_class_name
+
+
+def to_primitive_tdl_type(native_type: type | GenericAlias) -> TdlType | None:
+    """
+    Converts a native type to primitive TDL type.
+    :param native_type:
+    :return: Converted TDL primitive. None if `native_type` is not a supported primitive type.
+    """
+    tdl_type: TdlType | None = None
+    if native_type is Int8:
+        tdl_type = Int8Type()
+    elif native_type is Int16:
+        tdl_type = Int16Type()
+    elif native_type is Int32:
+        tdl_type = Int32Type()
+    elif native_type is Int64:
+        tdl_type = Int64Type()
+    elif native_type is Float:
+        tdl_type = FloatType()
+    elif native_type is Double:
+        tdl_type = DoubleType()
+    elif native_type is bool:
+        tdl_type = BoolType()
+    return tdl_type
+
+
+def to_tdl_type(native_type: type | GenericAlias) -> TdlType:
+    """
+    Converts a Python type to TDL type.
+    :param native_type:
+    :return:
+    :raise: TypeError if `native_type` is not a valid TDL type.
+    """
+    primitive_tdl_type = to_primitive_tdl_type(native_type)
+    if primitive_tdl_type is not None:
+        return primitive_tdl_type
+
+    if native_type in (int, float, str, complex, bytes):
+        msg = f"{native_type} is not a valid TDL type."
+        raise TypeError(msg)
+
+    if isinstance(native_type, GenericAlias):
+        origin = get_origin(native_type)
+        if origin is list:
+            arg = get_args(native_type)
+            if arg is None:
+                msg = "List does not have a key type."
+                raise TypeError(msg)
+            arg = arg[0]
+            return ListType(to_tdl_type(arg))
+
+        if origin is dict:
+            arg = get_args(native_type)
+            msg = "Dict does not have a key/value type."
+            if arg is None:
+                raise TypeError(msg)
+            if len(arg) != 2:  # noqa: PLR2004
+                raise TypeError(msg)
+            key = arg[0]
+            value = arg[1]
+            return MapType(to_tdl_type(key), to_tdl_type(value))
+
+        msg = f"{native_type} is not a valid TDL type."
+        raise TypeError(msg)
+
+    if issubclass(native_type, Collection):
+        msg = f"{native_type} is not a valid TDL type."
+        raise TypeError(msg)
+
+    return ClassType(get_class_name(native_type))
+
+
+def to_tdl_type_str(native_type: type | GenericAlias) -> str:
+    """
+    :param native_type: A Python native type.
+    :return: A string representation of the TDL type.
+    :raise: TypeError if `native_type` is not a valid TDL type.
+    """
+    return to_tdl_type(native_type).type_str()

python/spider-py/src/spider_py/type/tdl_type.py

@@ -0,0 +1,130 @@
+"""Spider TDL types."""
+
+from abc import ABC, abstractmethod
+
+from typing_extensions import override
+
+
+class TdlType(ABC):
+    """Abstract base class for all TDL types."""
+
+    @abstractmethod
+    def type_str(self) -> str:
+        """:return: String representation of the TDL type."""
+
+
+class DoubleType(TdlType):
+    """TDL double type."""
+
+    @override
+    def type_str(self) -> str:
+        return "double"
+
+
+class FloatType(TdlType):
+    """TDL float type."""
+
+    @override
+    def type_str(self) -> str:
+        return "float"
+
+
+class Int8Type(TdlType):
+    """TDL int8 type."""
+
+    @override
+    def type_str(self) -> str:
+        return "int8"
+
+
+class Int16Type(TdlType):
+    """TDL int16 type."""
+
+    @override
+    def type_str(self) -> str:
+        return "int16"
+
+
+class Int32Type(TdlType):
+    """TDL int32 type."""
+
+    @override
+    def type_str(self) -> str:
+        return "int32"
+
+
+class Int64Type(TdlType):
+    """TDL int64 type."""
+
+    @override
+    def type_str(self) -> str:
+        return "int64"
+
+
+class BoolType(TdlType):
+    """TDL bool type."""
+
+    @override
+    def type_str(self) -> str:
+        return "bool"
+
+
+class ClassType(TdlType):
+    """TDL Custom class type."""
+
+    def __init__(self, name: str) -> None:
+        """
+        Creates a TDL custom class type.
+        :param name: The name of the class.
+        """
+        self._name = name
+
+    @override
+    def type_str(self) -> str:
+        return self._name
+
+
+class ListType(TdlType):
+    """TDL List type."""
+
+    def __init__(self, element_type: TdlType) -> None:
+        """Creates a TDL list type."""
+        self.element_type = element_type
+
+    @override
+    def type_str(self) -> str:
+        return f"List<{self.element_type.type_str()}>"
+
+
+def is_integral(tdl_type: TdlType) -> bool:
+    """:return: If TDL type is an integral type."""
+    return isinstance(tdl_type, (Int8Type, Int16Type, Int32Type, Int64Type))
+
+
+def is_string(tdl_type: TdlType) -> bool:
+    """:return: If TDL type is a string type, i.e. List<int8>."""
+    return isinstance(tdl_type, ListType) and isinstance(tdl_type.element_type, Int8Type)
+
+
+def is_map_key(tdl_type: TdlType) -> bool:
+    """:return: If TDL type is a valid type for map key."""
+    return is_integral(tdl_type) or is_string(tdl_type)
+
+
+class MapType(TdlType):
+    """TDL Map type."""
+
+    def __init__(self, key_type: TdlType, value_type: TdlType) -> None:
+        """
+        Creates a TDL map type.
+        :raises TypeError: If key is not a supported type.
+        """
+        if not is_map_key(key_type):
+            msg = f"{key_type} is not a supported type for map key."
+            raise TypeError(msg)
+        self.key_type = key_type
+        self.value_type = value_type
+
+    @override
+    def type_str(self) -> str:
+        return f"Map<{self.key_type.type_str()},{self.value_type.type_str()}>"

python/spider-py/src/spider_py/type/type.py

@@ -0,0 +1,72 @@
+"""Custom type module for Spider."""
+
+from __future__ import annotations
+
+from typing import cast
+
+
+class BoundedInt(int):
+    """Bounded integer type."""
+
+    def __new__(cls, value: int, bits: int = 32) -> BoundedInt:
+        """Creates a bounded integer."""
+        min_val = -(1 << (bits - 1))
+        max_val = (1 << (bits - 1)) - 1
+
+        if bits not in (8, 16, 32, 64):
+            msg = f"Unsupported bits size: {bits}. Supported sizes are 8, 16, 32, or 64."
+            raise ValueError(msg)
+
+        if not (min_val <= value and value <= max_val):
+            msg = f"Bounded integer value ({value}) must be between {min_val} and {max_val}"
+            raise ValueError(msg)
+
+        return super().__new__(cls, value)
+
+
+class Int8(BoundedInt):
+    """8 bits integer type."""
+
+    def __new__(cls, value: int) -> Int8:
+        """Creates an int8 integer."""
+        return cast("Int8", super().__new__(cls, value, bits=8))
+
+
+class Int16(BoundedInt):
+    """16 bits integer type."""
+
+    def __new__(cls, value: int) -> Int16:
+        """Creates an int16 integer."""
+        return cast("Int16", super().__new__(cls, value, bits=16))
+
+
+class Int32(BoundedInt):
+    """32 bits integer type."""
+
+    def __new__(cls, value: int) -> Int32:
+        """Creates an int32 integer."""
+        return cast("Int32", super().__new__(cls, value, bits=32))
+
+
+class Int64(BoundedInt):
+    """64 bits integer type."""
+
+    def __new__(cls, value: int) -> Int64:
+        """Creates an int64 integer."""
+        return cast("Int64", super().__new__(cls, value, bits=64))
+
+
+class Float(float):
+    """Float type."""
+
+    def __new__(cls, value: float) -> Float:
+        """Creates a float number."""
+        return super().__new__(cls, value)
+
+
+class Double(float):
+    """Double type."""
+
+    def __new__(cls, value: float) -> Double:
+        """Creates a double number."""
+        return super().__new__(cls, value)

python/spider-py/src/spider_py/type/utils.py

@@ -0,0 +1,9 @@
+"""Utility for TDL types."""
+
+
+def get_class_name(cls: type) -> str:
+    """
+    :param cls:
+    :return: Full name of `cls`.
+    """
+    return f"{cls.__module__}.{cls.__qualname__}"