跳转至

Types#

nlql.types —— 类型系统：TypeTag 枚举（TEXT / NUMBER / DATE 等）+ 函数 Signature（arity 校验）+ 操作数强转（as_number / as_date，含快速拒绝优化）。

types #

NLQL type system: type tags, function signatures, and custom type registration.

__all__ module-attribute #

__all__ = ['TypeTag', 'Signature', 'TypeHandler', 'register_type', 'get_type_handler']

TypeHandler dataclass #

TypeHandler(parse: Callable[[str], Any], compare: Callable[[Any, Any, str], bool] | None = None)

Parser + optional comparator for a user-registered type.

parse converts a raw string (from DATE '...' or metadata) into the runtime value used in comparisons. compare overrides the default compare_values when non-None, receiving (left, right, op).

parse instance-attribute #

parse: Callable[[str], Any]

compare class-attribute instance-attribute #

compare: Callable[[Any, Any, str], bool] | None = None

TypeTag #

Bases: StrEnum

Coarse value types flowing through query evaluation.

ANY class-attribute instance-attribute #

ANY = 'any'

TEXT class-attribute instance-attribute #

TEXT = 'text'

NUMBER class-attribute instance-attribute #

NUMBER = 'number'

BOOL class-attribute instance-attribute #

BOOL = 'bool'

DATE class-attribute instance-attribute #

DATE = 'date'

VECTOR class-attribute instance-attribute #

VECTOR = 'vector'

NULL class-attribute instance-attribute #

NULL = 'null'

Signature dataclass #

Signature(args: tuple[TypeTag, ...], returns: TypeTag, variadic: bool = False)

Declared argument and return types of a registered function.

参数：

名称 类型 描述 默认
args tuple[TypeTag, ...]

Expected argument types, in order.

 必需
returns TypeTag

Result type.

 必需
variadic bool

When True the last args entry may repeat zero or more times (so arity becomes "at least len(args) - 1").

 False

args instance-attribute #

args: tuple[TypeTag, ...]

returns instance-attribute #

returns: TypeTag

variadic class-attribute instance-attribute #

variadic: bool = False

arity_ok #

arity_ok(n: int) -> bool

Whether n positional arguments satisfy this signature.

源代码位于： src/nlql/types/core.py 
43
44
45
46
47
def arity_ok(self, n: int) -> bool:
    """Whether ``n`` positional arguments satisfy this signature."""
    if self.variadic:
        return n >= max(0, len(self.args) - 1)
    return n == len(self.args)

get_type_handler #

get_type_handler(name: str, type_handlers: dict[str, TypeHandler] | None = None) -> TypeHandler | None

Look up a registered TypeHandler by name (case-insensitive). Checks the optional instance-level dict first, then the global registry.

源代码位于： src/nlql/types/core.py 
 99
100
101
102
103
104
105
106
107
108
109
def get_type_handler(
    name: str, type_handlers: dict[str, TypeHandler] | None = None
) -> TypeHandler | None:
    """Look up a registered TypeHandler by name (case-insensitive).
    Checks the optional instance-level dict first, then the global registry."""
    if name is None:
        return None
    key = name.upper() if isinstance(name, str) else str(name).upper()
    if type_handlers and key in type_handlers:
        return type_handlers[key]
    return _TYPE_HANDLERS.get(key)

register_type #

register_type(name: str, handler: TypeHandler | None = None, *, registry: dict[str, TypeHandler] | None = None) -> Any

Register a custom type. Two modes:

  1. Direct: register_type("EMAIL", TypeHandler(parse=...))
  2. Decorator: @register_type("EMAIL") on a class (with parse/compare methods) or a bare function (used as parse).
源代码位于： src/nlql/types/core.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
def register_type(
    name: str, handler: TypeHandler | None = None, *, registry: dict[str, TypeHandler] | None = None
) -> Any:
    """Register a custom type. Two modes:

    1. Direct: ``register_type("EMAIL", TypeHandler(parse=...))``
    2. Decorator: ``@register_type("EMAIL")`` on a class (with parse/compare methods)
       or a bare function (used as parse).
    """
    store = registry if registry is not None else _TYPE_HANDLERS
    if handler is not None:
        store[name.upper()] = handler
        return handler

    def decorator(cls_or_fn: Any) -> Any:
        if isinstance(cls_or_fn, TypeHandler):
            h = cls_or_fn
        elif isinstance(cls_or_fn, type):
            obj = cls_or_fn()
            h = TypeHandler(parse=obj.parse, compare=getattr(obj, "compare", None))
        else:
            h = TypeHandler(parse=cls_or_fn)
        store[name.upper()] = h
        return cls_or_fn

    return decorator