Change Log

This document contains notes on the major changes for each version of the Rule Engine. In comparison to the git log, this list is curated by the development team for note worthy changes.

Version 5.x.x

Version 5.2.0

Released v5.2.0 on October 28th, 2026

  • Added the int_max_digits parameter to Context to limit the number of digits an integer can have when it is converted to a FLOAT value. The conversion takes time that grows quadratically with the size of the integer, so a short rule could hang the process. Larger integers now raise an ArithmeticError. The default of None uses the interpreter’s limit from sys.get_int_max_str_digits() and 0 disables the limit. coerce_value() and parse_float() accept it as a keyword-only argument.

  • The parser tables are now generated when the wheel is built and are shipped in it, instead of being generated at runtime. Nothing is written to the installation directory, so installs work the same way for root and non-root users. Building the package now requires python-dateutil.

  • The ==, !=, and and or operators now accept BYTES and FUNCTION values, and and and or now accept OBJECT values, as documented. Rules such as b"ab" == b"ab" previously raised an EvaluationError.

  • from_type() now maps T | None type hints to NULLABLE(T) on Python versions 3.10 to 3.13, where it previously raised a TypeError.

  • The to_int and to_flt attributes of STRING values now accept leading zeros, e.g. "02134".to_int is 2134, where they previously raised Python’s SyntaxError.

  • parse_float() and the $parse_float builtin function now raise a FloatSyntaxError for binary, octal and hexadecimal values followed by a comment or line continuation, such as "0x10 # c", and no longer cause Python to emit warnings for invalid strings.

  • The $re_groups builtin symbol no longer raises a SymbolTypeError when an optional group didn’t take part in the match. The member for that group is null.

  • The ARRAY, SET, MAPPING and FUNCTION data types can now be pickled and copied, as can the OBJECT types, Context and Rule objects that contain them. The DataType constants keep their identity when they are pickled or copied.

  • Fixed some edge cases of from_dataclass() and type_resolver_from_dataclass()

    • With strict=True, dataclasses nested in the members of a field, such as list[Hero | None] and list[list[Address]], are now mapped, where they previously raised a ValueError.

    • With strict=False, fields that can’t be mapped now map to UNDEFINED as documented, where some of them previously raised. These include unsupported member types such as set[Address], forward references that can’t be resolved and sets of dataclasses that the schema refers to.

    • The values of Literal type hints are no longer evaluated as code in the dataclass’s module.

  • SymbolTypeError and AttributeTypeError messages now spell out compound data types, e.g. ARRAY(FLOAT) instead of ARRAY. When an ARRAY or SET value has None members, the is_type attribute of a SymbolTypeError now wraps the member type in NULLABLE.

  • Calling str() on a EngineError now returns its message instead of the arguments it was created with. SymbolTypeError, AttributeTypeError and RegexSyntaxError errors can now be pickled and copied.

  • Deprecated: A typed symbol whose value has a None member where the member type is not nullable, such as {'a': None} for MAPPING(STRING, STRING), now emits a DeprecationWarning. These values will raise a SymbolTypeError in v6.0. Wrap the member type in NULLABLE to allow None.

Version 5.1.0

Released v5.1.0 on October 20th, 2026

  • Added the Chain class for evaluating an object against an ordered list of rules and returning the value of the first one that matches, similar to a chain in iptables. See Rule Chains for details.

    • find() returns the ChainEntry that matched, which can be used to determine which rule was applied, and index() returns its position in the chain.

    • When no rule matches and no default value is set, the new ChainExhaustedError is raised.

    • Chains can be modified with append(), insert(), delete() and flush() while other threads evaluate them, and can be pickled.

    • Slicing a chain returns a new chain with the same default value and context.

  • Fixed the UNDEFINED sentinel losing its identity when pickled or copied. A restored Context using the default default_value would return a stand-in object for missing symbols and attributes instead of raising a SymbolResolutionError or AttributeResolutionError. Contexts that were pickled by an earlier version are corrected when they are loaded.

Version 5.0.0

Released v5.0.0 on May 17th, 2026

  • Breaking: Dropped support for Python versions 3.6, 3.7, 3.8 and 3.9.

  • Breaking: Changed the precedence of operators to be more aligned with common programming languages.

  • Breaking: The Debug REPL utility now requires development dependencies to be installed.

  • Breaking: BYTES literals now throw exceptions for invalid escape sequences

  • Breaking: Removed setup.py; project metadata now lives entirely in pyproject.toml (PEP 517/621).

  • Breaking: The rule_engine.ast module no longer re-exports names from rule_engine.types (e.g. DataType, coerce_value); import them from rule_engine or rule_engine.types directly.

  • Breaking: A symbol typed by a type_resolver as an ARRAY or SET with a member type no longer accepts None members unless that type is wrapped in NULLABLE. Before 5.0.0, the value_type_nullable kwarg defaulted to True, so a symbol typed as ARRAY(STRING) could resolve to ('a', None). Now that value raises a SymbolTypeError when the symbol is resolved. To accept None members, use ARRAY(NULLABLE(STRING)) (or the deprecated value_type_nullable=True until v6.0). Rules must then handle the nullable members, for example with ??, before using them with operators that reject NULLABLE operands. See the NULLABLE section in the Data Types page for details.

  • Migrated the development workflow and CI from pipenv to uv.

  • Added support for raw STRING literals using the r prefix (e.g. r'\w+').

  • Vendored the PLY dependency under rule_engine._vendor.ply — the upstream project is unmaintained, so the copy removes an external install requirement and silences third-party vulnerability reports targeting it.

  • Made Rule and Context objects serializable with pickle. Transient, unpicklable state (thread-local storage, locks and the builtins table) is recreated on restore. Any type_resolver or resolver callable must itself be picklable, so lambdas and other local functions can not be used on a context that needs to be serialized.

  • Added the new OBJECT compound data type for user-defined schemas with named, typed attributes. See the OBJECT section in the Data Types page for details.

    • Use reference() (or the self shorthand sentinel) for self-referential and mutually-recursive schemas.

    • Attribute access is validated at parse time against the declared schema.

    • Item access (obj["name"]) and containment checks ("name" in obj) on OBJECT values are rejected at parse time.

    • SET(OBJECT(...)) is rejected at construction; use ARRAY(OBJECT(...)) instead

    • A custom accessor callable can be specified per OBJECT type (default: getattr()).

    • Added from_dataclass() and type_resolver_from_dataclass() for deriving OBJECT schemas and type_resolvers automatically from Python dataclass() definitions, including nullability for Optional fields and self / mutually-recursive references (closes #55).

    • Added from_sqlalchemy() and type_resolver_from_sqlalchemy() for deriving OBJECT schemas and type_resolvers from SQLAlchemy ORM mapped classes. Columns, relationships, and cycles between mutually-related classes are all expanded automatically. SQLAlchemy is an optional dependency; the import is deferred until these entry points are called.

    • The from_dataclass and from_sqlalchemy entry points (and their type_resolver_from_* companions) accept a strict keyword argument. The default strict=True raises ValueError on any field / column whose type cannot be mapped to a Rule Engine data type; strict=False falls back to UNDEFINED.

  • Added ObjectAttributeError, a subclass of AttributeResolutionError, raised when an attribute is not found in an OBJECT schema

  • Promoted nullability to a first-class type-system construct via the new NULLABLE one-argument type constructor. See the NULLABLE section in the Data Types page for the full semantics.

    • from_type() maps Python’s Optional[T] / T | None to NULLABLE(from_type(T)).

    • from_dataclass() and from_sqlalchemy() wrap nullable fields, columns, and scalar relationships in NULLABLE(T); type_resolver_from_dataclass() and type_resolver_from_sqlalchemy() preserve the wrappers through to the top-level symbol types.

    • Compound element and value types (ARRAY, SET, MAPPING) store NULLABLE(T) directly when the member may be None.

    • AST operators reject NULLABLE operands at parse time wherever None has no meaningful semantics: arithmetic, ordered comparisons, the regex operators, bitwise and bitwise-shift operators, unary minus, containment, attribute access, item access, slicing, and function arguments all raise EvaluationError (or FunctionCallError for function arguments) with a message pointing at the discharge operators. Equality (==, !=), logical connectives (and, or, not), ternary expressions, and safe-navigation operators remain lenient.

    • A new null-coalesce operator left ?? right discharges NULLABLE(T) to T. Existing safe attribute (&.) and item (&[) accessors still apply to nullable receivers and are the only access forms that do.

  • Deprecated: The value_type_nullable kwarg on ARRAY, SET, and MAPPING now emits DeprecationWarning. Wrap the relevant element or value type in NULLABLE instead. The kwarg will be removed in v6.0.

  • Deprecated: Accessing MAPPING keys via dot syntax (mapping.key) now emits a MappingAttributeLookupDeprecation warning. Use bracket syntax (mapping["key"]) instead. This fallback will be removed in v6.0. Set Context(mapping_attribute_lookup=False) to opt out now.

Version 4.x.x

Version 4.5.0

Released v4.5.0 on June 19th, 2024

  • StringSyntaxError is now raised for invalid string literals

  • FunctionCallError is now raised when a typed function returns an incompatible value

  • Added the new BYTES data type

  • Added some new data attributes

Version 4.4.0

Released v4.4.0 on April 5th, 2024

  • Added the $range builtin function

  • Added the rule_engine.parser.utilities module with a few functions and documentation

Version 4.3.0

Released v4.3.0 on January 15th, 2024

  • Added the is_nan attribute for FLOAT values

Version 4.2.0

Released v4.2.0 on December 11th, 2023

  • Added attributes for coercion of types to themselves, e.g. to_str for STRING values

Version 4.1.0

Released v4.1.0 on August 3rd, 2023

  • Added the $abs builtin function

  • Added support to from_type to handle Python’s type hints

Version 4.0.0

Released v4.0.0 on July 15th, 2023

  • Breaking: Changed STRING.to_ary to return an array of characters instead of splitting the string

    • Use the new builtin $split function to split a string on whitespace into an array of words

  • Breaking: Changed Context to use keyword-only arguments

  • Breaking: Dropped support for Python versions 3.4 and 3.5

  • Breaking: Invalid floating point literals now raise FloatSyntaxError instead of RuleSyntaxError

  • Breaking: Moved rule_engine.engine.Builtins to rule_engine.builtins.Builtins

  • Added the new FUNCTION data type

Version 3.x.x

Version 3.6.0

Released v3.6.0 on June 16th, 2023

  • Removed testing for Python versions 3.4 and 3.5 on GitHub Actions

  • Add regex error details to the Debug REPL utility

  • Add support for Python-style comments

Version 3.5.0

Released v3.5.0 on July 16th, 2022

Version 3.4.0

Released v3.4.0 on March 19th, 2022

  • Add support for string concatenation via the + operator

Version 3.3.0

Released v3.3.0 on July 20th, 2021

Version 3.2.0

Released v3.2.0 on April 3rd, 2021

Version 3.1.0

Released v3.1.0 on March 15th, 2021

  • Added the new SET data type

Version 3.0.0

Released v3.0.0 on March 1st, 2021

  • Switched the FLOAT datatype to use Python’s Decimal from float internally

  • Reserved the if, elif, else, for and while keywords for future use, they can no longer be used as symbol names

  • Added some new data attributes

    • Added ceiling, floor and to_str to FLOAT

Version 2.x.x

Version 2.4.0

Released v2.4.0 on November 7th, 2020

  • Added the Debug REPL utility

  • Added the safe navigation version of the attribute, item and slice operators

  • Added the new MAPPING data type

  • Switched from Travis-CI to GitHub Actions for continuous integration

  • Added support for iterables to have multiple member types

Version 2.3.0

Released v2.3.0 on October 11th, 2020

  • Added support for arithmetic comparisons for all currently supported data types

  • Added support for proper type hinting of builtin symbols

  • Added the $re_groups builtin symbol for extracting groups from a regular expression match

  • Added some new data attributes

Version 2.2.0

Released v2.2.0 on September 9th, 2020

  • Added script entries to the Pipfile for development

  • Added support for slices on sequence data types

Version 2.1.0

Released v2.1.0 on August 3rd, 2020

  • Added coverage reporting to Travis-CI

  • Changed DataType. from an enum to a custom class

  • Improvements for the ARRAY data type

    • Added get[item] support for arrays, allowing items to be retrieved by index

    • Added ability for specifying the member type and optionally null

Version 2.0.0

Released v2.0.0 on October 2nd, 2019

  • Added proper support for attributes

  • Added a change log

  • Added additional information to the Graphviz output

  • Added the new ARRAY data type

  • Started using Travis-CI

    • Added automatic unit testing using Travis-CI

    • Added automatic deployment of documentation using Travis-CI

  • Removed the resolver conversion functions

    • Removed to_recursive_resolver in favor of attributes

    • Removed to_default_resolver in favor of the default_value kwarg to __init__()

Version 1.x.x

Version 1.1.0

Released v1.1.0 on March 27th, 2019

  • Added the to_default_dict() function

  • Added the to_recursive_resolver() function

Version 1.0.0

Released v1.0.0 on December 15th, 2018

  • First major release