typesAdded in version 3.2.0.
This module contains the internal type definitions and utility functions for working with them.
Take a native Python value and convert it to a value of a data type which can be represented by a Rule Engine
DataType. This function is useful for converting native Python values at the engine boundaries such as
when resolving a symbol from an object external to the engine.
Added in version 2.0.0.
value – The value to convert.
verify_type (bool) – Whether or not to verify the converted value’s type.
The converted value.
Check whether value is an integer number (i.e. a whole, number). This can, for example, be used to check if a
floating point number such as 3.0 can safely be converted to an integer without loss of information.
Added in version 2.1.0.
value – The value to check. This value is a native Python type.
Whether or not the value is an integer number.
Check whether value is a natural number (i.e. a whole, non-negative number). This can, for example, be used to
check if a floating point number such as 3.0 can safely be converted to an integer without loss of information.
value – The value to check. This value is a native Python type.
Whether or not the value is a natural number.
Check whether value is a numeric value (i.e. capable of being represented as a floating point value without loss of information).
value – The value to check. This value is a native Python type.
Whether or not the value is numeric.
Check whether value is a real number (i.e. capable of being represented as a floating point value without loss of
information as well as being finite). Despite being able to be represented as a float, NaN is not considered a
real number for the purposes of this function.
value – The value to check. This value is a native Python type.
Whether or not the value is a natural number.
Take a native python_value and return the corresponding data type of each of its members if the types are either the same or NULL. NULL is considered a special case to allow nullable-values. This by extension means that an iterable may not be defined as only capable of containing NULL values.
The data type of the sequence members. This will never be NULL, because that is considered a special case. It will either be UNSPECIFIED or one of the other types.
Bases: object
A collection of constants representing the different supported data types. There are three ways to compare data types. All three are effectively the same when dealing with scalars.
dt == DataType.TYPE
This is the most explicit form of testing and when dealing with compound data types, it recursively checks that all of the member types are also equal.
DataType.is_type(dt, DataType.TYPE)
This checks that the data type belongs to the same family as the given sentinel. For scalar types this is
equivalent to an equality check; for compound types (e.g. ARRAY, MAPPING) it matches
any parameterization of that type without inspecting member types. When used in an if branch mypy narrows
the type of dt to the matching concrete class (e.g. after DataType.is_type(dt, DataType.NULLABLE) mypy
knows dt is a _NullableDataTypeDef).
DataType.is_compatible(dt, DataType.TYPE)
This checks that the types are compatible without any kind of conversion. When dealing with compound data types,
this ensures that the member types are either the same or UNDEFINED.
value_type – The type of the members.
value_type_nullable (bool) –
Whether or not members are allowed to be NULL.
Deprecated since version 5.0.0: Wrap nullable element types with DataType.NULLABLE() instead; this kwarg will
be removed in v6.0.0.
Added in version 4.0.0.
If argument_types is specified and minimum_arguments is not, then minimum_arguments will default to the length of argument_types effectively meaning that every defined argument is required. If
key_type – The type of the mapping keys.
value_type – The type of the mapping values.
value_type_nullable (bool) –
Whether or not mapping values are allowed to be NULL.
Deprecated since version 5.0.0: Wrap nullable value types with DataType.NULLABLE() instead; this kwarg will
be removed in v6.0.0.
inner_type – The non-null data type this slot may hold. Passing an already-nullable type collapses
(i.e. NULLABLE(NULLABLE(T)) is NULLABLE(T)); passing NULL or
UNDEFINED raises EngineError.
Added in version 5.0.0.
Added in version 5.0.0.
name (str) – The name of the object schema.
attributes (dict) – A mapping of attribute names to their data type definitions. A
reference() placeholder with the same name (or the
self sentinel) resolves to the new type itself,
enabling self-referential schemas.
accessor – A callable of the form accessor(value, attribute_name) used to fetch an attribute’s
value at evaluation time. Defaults to getattr().
Build an OBJECT schema from a Python
dataclass(). Each field of cls becomes an attribute in the resulting OBJECT schema,
with its type derived from the field annotation via DataType.from_type(). Stringified annotations
(e.g. from from __future__ import annotations) are resolved using typing.get_type_hints().
Fields annotated with typing.Optional (or the PEP 604 T | None form) are surfaced as
NULLABLE wrappers around the non-None type; non-Optional fields
are recorded unwrapped. See the NULLABLE section for how nullability propagates through
the grammar and how to discharge it.
Fields whose annotation is itself a dataclass (or contains one inside a list/set/dict generic)
produce nested OBJECT schemas. Self-references resolve to the enclosing schema via the
self sentinel; references to a dataclass already on the build
stack (mutual recursion) become unresolved reference()
placeholders that the caller must resolve via the Context type_resolver.
Added in version 5.0.0.
name (str) – The name of the resulting OBJECT schema.
cls (type) – A class decorated with dataclass().
accessor – An optional accessor callable forwarded to the new schema. Defaults to getattr(),
which matches normal dataclass attribute access.
strict (bool) – When True (the default), a field annotated with a type that cannot be mapped to a
Rule Engine data type raises ValueError. When False, such fields fall back to
DataType.UNDEFINED so the attribute remains selectable without parse-time type checking.
Build an OBJECT schema from a SQLAlchemy ORM mapped class. Each
mapped column of cls becomes an attribute in the resulting OBJECT schema, with its type derived from the
column’s python_type() via DataType.from_type(). Columns
with nullable set to True are surfaced as
NULLABLE wrappers around the column type; scalar relationships whose
local foreign-key columns are nullable are wrapped the same way.
By default (strict=True) a column whose python_type raises NotImplementedError
(typically dialect-specific types such as PostgreSQL CIDR or INET) or resolves to a Python type
Rule Engine cannot map raises ValueError; pass strict=False to record such columns as
DataType.UNDEFINED so they remain selectable without parse-time type checking.
Enum columns are surfaced as DataType.STRING unless the enum class is
an int subclass, in which case they become DataType.FLOAT.
JSON columns report dict as their python_type and therefore map to
DataType.MAPPING with untyped keys and values; the nested values remain untyped.
Relationships declared on cls are expanded into nested OBJECT schemas. Collection relationships
(uselist=True) are wrapped in DataType.ARRAY. Back-references to the enclosing class
resolve to self; references to a class already on the build
stack (mutual recursion across more than two classes) become unresolved
reference() placeholders that the caller must resolve via the
Context type_resolver.
SQLAlchemy is an optional dependency. The library imports cleanly without it; import sqlalchemy is
deferred until this method is actually called and propagates ImportError if SQLAlchemy is not
installed.
Added in version 5.0.0.
name (str) – The name of the resulting OBJECT schema.
cls (type) – A SQLAlchemy ORM mapped class.
accessor – An optional accessor callable forwarded to the new schema. Defaults to getattr(),
which matches normal attribute access on a mapped instance.
strict (bool) – When True (the default), a column whose python_type raises
NotImplementedError or cannot be mapped to a Rule Engine data type raises
ValueError. When False, such columns fall back to DataType.UNDEFINED so
the attribute remains selectable without parse-time type checking. This is useful for dialect-
specific column types whose values can not be statically described.
Construct a forward-reference placeholder for use inside an OBJECT
schema. This is not itself a data type — it is a placeholder that resolves to an
OBJECT either at construction time (for self references within the
same schema) or at rule parse time (for cross-type references) via a
Context’s type_resolver.
For self-references within a schema, prefer the self sentinel,
which avoids repeating the enclosing schema’s name.
Added in version 5.0.0.
name (str) – The name of the referenced OBJECT schema.
Sentinel value for use inside an OBJECT attribute schema to denote
“the enclosing OBJECT schema”, resolved automatically when the schema is constructed. Prefer this over
reference() for self-references, since it avoids repeating the
schema’s own name.
Added in version 5.0.0.
value_type – The type of the members.
value_type_nullable (bool) –
Whether or not members are allowed to be NULL.
Deprecated since version 5.0.0: Wrap nullable element types with DataType.NULLABLE() instead; this kwarg will
be removed in v6.0.0.
Undefined values. This constant can be used to indicate that a particular symbol is valid, but it’s data type is currently unknown.
Get the data type from its name.
Added in version 2.0.0.
name (str) – The name of the data type to retrieve.
One of the constants.
Get the supported data type constant for the specified Python type/type hint. If the type or typehint can not be
mapped to a supported data type, then a ValueError exception will be raised. This function will not
return UNDEFINED.
python_type (type) – The native Python type or type hint to retrieve the corresponding type constant for.
One of the constants.
Changed in version 4.1.0: Added support for typehints.
Get the supported data type constant for the specified Python value. If the value can not be mapped to a
supported data type, then a TypeError exception will be raised. This function will not return
UNDEFINED.
python_value – The native Python value to retrieve the corresponding data type constant for.
One of the constants.
Check if two data type definitions are compatible without any kind of conversion. This evaluates to True
when one or both are UNDEFINED or both types are the same. In the case of compound data types (such
as ARRAY) the member types are checked recursively in the same manner.
Added in version 2.1.0.
dt1 – The first data type to compare.
dt2 – The second data type to compare.
Whether or not the two types are compatible.
Check if value is a data type definition.
Added in version 2.1.0.
value – The value to check.
True if value is a data type definition.
Check if dt is the same base type as kind, ignoring member types for compound types. This is the
preferred replacement for isinstance(dt, DataType.TYPE.__class__).
For scalar types (e.g. STRING, BOOLEAN) kind is a singleton so this is
equivalent to an equality check. For compound types (e.g. ARRAY, MAPPING,
OBJECT) it checks the type family without inspecting member / key / value types — use
is_compatible() when those matter.
Added in version 5.0.0.
dt – The data type to test.
kind – The base type to test against (e.g. DataType.ARRAY).
True if dt belongs to the same type family as kind.