Rule Engine

https://github.com/zerosteiner/rule-engine
Admin
Rule Engine is a system designed to define, evaluate, and execute business rules based on specific...
Tokens:25,317
Snippets:187
Trust Score:10
License:BSD-3-Clause
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Debug REPL example with --edit-console

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/debug_repl.rst

Starts the Debug REPL with an interactive console to define the 'thing' object, then evaluates rules against it. The example shows defining a comic book dictionary, exiting the console, and evaluating two rules with their results.

```text
python -m rule_engine.debug_repl --edit-console
edit the 'context' and 'thing' objects as necessary
>>> thing = dict(title='Batman', publisher='DC', issue=1)
>>> exit()
exiting the edit console...
rule > title == 'Superman'
result:
False
rule > issue < 5
result:
True
rule >
```

--------------------------------

### ARRAY | BYTES | STRING starts_with(ARRAY | BYTES | STRING prefix) -> BOOLEAN

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/attributes.rst

Checks whether the value starts with the specified prefix. The prefix data type must match the object type.

```APIDOC
## ARRAY | BYTES | STRING starts_with(ARRAY | BYTES | STRING prefix) -> BOOLEAN

### Description
Checks whether the value starts with the specified prefix. The prefix data type must match the object type.

### Method
Function

### Signature
`ARRAY | BYTES | STRING starts_with(ARRAY | BYTES | STRING prefix) -> BOOLEAN`

### Parameters
- **prefix** (ARRAY | BYTES | STRING) - Required - The prefix to check for. The data type must match the object type.

### Returns
- **BOOLEAN** - Whether the value starts with the prefix.

### Version Added
4.5.0
```

--------------------------------

### split function example

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Shows the behavior of the split function with and without a separator. Without sep, consecutive whitespace is collapsed; with a single space, consecutive spaces produce empty strings.

```default
$split("A    B")      # => ('A', 'B')
$split("A    B", ' ') # => ('A', '', '', '', 'B')
```

--------------------------------

### Basic rule creation and matching with rule_engine.Rule

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/index.rst

Shows how to create a Rule from a logical expression string and apply it to dictionaries with .matches(). The example matches a literal first name and a regex on the email field, returning True for Luke and False for Darth.

```python
import rule_engine
# match a literal first name and applying a regex to the email
rule = rule_engine.Rule(
    'first_name == "Luke" and email =~ ".*@rebels.org$"'
) # => <Rule text='first_name == "Luke" and email =~ ".*@rebels.org$"' >
rule.matches({
    'first_name': 'Luke', 'last_name': 'Skywalker', 'email': 'luke@rebels.org'
}) # => True
rule.matches({
   'first_name': 'Darth', 'last_name': 'Vader', 'email': 'dvader@empire.net'
}) # => False
```

--------------------------------

### Add custom builtin symbols with Builtins.from_defaults

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Shows how to add custom builtin symbols by subclassing Context and using Builtins.from_defaults. The values dictionary can override defaults and add new symbols. The example exposes the $version symbol and uses the default timezone.

```python
class CustomBuiltinsContext(rule_engine.Context):
    def __init__(self, *args, **kwargs):
        # call the parent class's __init__ method first to set the
        # default_timezone attribute
        super(CustomBuiltinsContext, self).__init__(*args, **kwargs)
        self.builtins = rule_engine.builtins.Builtins.from_defaults(
            # expose the $version symbol
            {'version': rule_engine.__version__},
            # use the specified default timezone
            timezone=self.default_timezone
        )
```

--------------------------------

### range(FLOAT start, [FLOAT stop, FLOAT step])

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Function to generate a range of numbers.

```APIDOC
## range(FLOAT start, [FLOAT stop, FLOAT step]) -> ARRAY[FLOAT]

### Description
Generate a sequence of `FLOAT`'s between *start* (inclusive) and *stop* (exclusive) by *step*.

### Parameters
- **start** (FLOAT) - Required - The value of the start parameter.
- **stop** (FLOAT) - Optional - The value of the stop parameter. If not supplied, start value will be used as stop instead.
- **step** (FLOAT) - Optional - The value of the step parameter (or 1 if the parameter was not supplied).

### Returns
- **ARRAY** of FLOAT - The generated sequence.
```

--------------------------------

### Create rule using regular expression matching

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Matches titles starting with 'Captain ' using the =~ operator with a regex pattern.

```python
rule = rule_engine.Rule(
  # match books with a title starting with 'Captain '
  'title =~ "Captain\s\S+"'
)
```

--------------------------------

### Define types from a dataclass with type_resolver_from_dataclass()

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Builds a type_resolver from a dataclass using type_resolver_from_dataclass(). Optional annotations are unwrapped and marked nullable; nested dataclasses become OBJECT types and list/dict containers are expanded. The example shows a rule matching a Hero instance.

```python
import dataclasses
import datetime
import typing
import rule_engine

@dataclasses.dataclass
class Hero:
    name: str
    publisher: str
    first_appearance: datetime.datetime
    sidekick: typing.Optional[str] = None

context = rule_engine.Context(
    resolver=rule_engine.resolve_attribute,
    type_resolver=rule_engine.type_resolver_from_dataclass(Hero),
)

rule = rule_engine.Rule('name == "Batman" and sidekick == "Robin"', context=context)
batman = Hero('Batman', 'DC', datetime.datetime(1939, 5, 1), sidekick='Robin')
rule.matches(batman)  # => True
```

--------------------------------

### Define attribute-backed Comic class and instances

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Defines a Comic class with attributes and a list of Comic instances. This example is used to illustrate an attribute-backed data structure where symbols are resolved from object attributes instead of dictionary keys.

```python
class Comic(object):
    def __init__(self, title, publisher, issue, released)
        self.title = title
        self.publisher = publisher
        self.issue = issue
        self.released = released

comics = [
  Comic('Batman',         'DC',     89,  datetime.date(2020, 4, 28)),
  Comic('Flash',          'DC',     753, datetime.date(2020, 4, 28)),
  Comic('Captain Marvel', 'Marvel', 18,  datetime.date(2020, 5, 6))
]
```

--------------------------------

### Create type resolver from SQLAlchemy mapped class

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Use this snippet to create a type resolver from a SQLAlchemy mapped class. Requires SQLAlchemy >= 2.0 installed separately. The resolver copies column nullability, honors Mapped[T | None], and expands relationships into nested OBJECT schemas.

```python
import datetime
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
import rule_engine

class Base(DeclarativeBase):
    pass

class Hero(Base):
    __tablename__ = 'heroes'
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    alias: Mapped[str | None]
    first_appearance: Mapped[datetime.datetime]
    active: Mapped[bool]

context = rule_engine.Context(
    resolver=rule_engine.resolve_attribute,
    type_resolver=rule_engine.type_resolver_from_sqlalchemy(Hero),
)

rule = rule_engine.Rule('name == "Batman" and active', context=context)
batman = Hero(id=1, name='Batman', alias='Bruce Wayne',
              first_appearance=datetime.datetime(1939, 5, 1), active=True)
rule.matches(batman)  # => True
```

--------------------------------

### Define comic book collection

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Example data structure representing a collection of comic books with attributes like title, publisher, issue, and released date.

```python
comics = [
  {
    'title': 'Batman',
    'publisher': 'DC',
    'issue': 89,
    'released': datetime.date(2020, 4, 28)
  },
  {
    'title': 'Flash',
    'publisher': 'DC',
    'issue': 753,
    'released': datetime.date(2020, 5, 5)
  },
  {
    'title': 'Captain Marvel',
    'publisher': 'Marvel',
    'issue': 18,
    'released': datetime.date(2020, 5, 6)
  }
]
```

--------------------------------

### Create simple rule matching publisher

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Initializes a Rule object that matches comic books where the publisher equals 'DC'.

```python
rule = rule_engine.Rule(
  # match books published by DC
  'publisher == "DC"'
)
```

--------------------------------

### Set default_value in Context to handle unknown symbols

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Shows how to set a default value for unknown symbols by passing default_value=None to Context. Without it, rule_engine.Rule raises SymbolResolutionError; with it, unknown symbols resolve to None and comparisons evaluate to False or True as shown.

```python
# this fails because title is not defined and there is no default_value
rule_engine.Rule('title').matches({})
# => SymbolResolutionError: title

context = rule_engine.Context(default_value=None)
# this evaluates successfully to False because title is null (from the default value)
rule_engine.Rule('title', context=context).matches({})
# => False

# this evaluates successfully to True because title is a non-empty string
rule_engine.Rule('title', context=context).matches({'title': 'Batman'})
# => True
```

--------------------------------

### Custom context with type hints

Source: https://github.com/zerosteiner/rule-engine/blob/master/README.rst

Creates a custom context defining two symbols (first_name as STRING, age as FLOAT). Using an unknown symbol raises SymbolResolutionError, and using an invalid operation raises EvaluationError.

```python
import rule_engine
# define the custom context with two symbols
context = rule_engine.Context(type_resolver=rule_engine.type_resolver_from_dict({
    'first_name': rule_engine.DataType.STRING,
    'age': rule_engine.DataType.FLOAT
}))

# receive an error when an unknown symbol is used
rule = rule_engine.Rule('last_name == "Vader"', context=context)
# => SymbolResolutionError: last_name

# receive an error when an invalid operation is used
rule = rule_engine.Rule('first_name + 1', context=context)
# => EvaluationError: data type mismatch
```

--------------------------------

### Calling the builtin split function with optional arguments

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Shows how to call the builtin $split function with up to three arguments: a required string, an optional delimiter, and an optional maximum split count. The first call splits on spaces, the second uses a custom delimiter, and the third limits the number of splits. The last two calls demonstrate errors: passing a non-string second argument raises FunctionCallError, and specifying the third argument without the second is not allowed.

```default
# only the required argument performs an unlimited number of splits on spaces
$split("Star Wars")         # => ("Star", "Wars")

# the optional second argument specifies an alternative string to split on
$split("Star Wars", "r")    # => ('Sta', ' Wa', 's')

# the optional third argument specifies the maximum number of times to split the string
$split("Star Wars", "r", 1) # => ('Sta', ' Wars')

# raises FunctionCallError because the second argument must be a string, the third argument
# can not be specified without the second
$split("Star Wars", 1)      # => FunctionCallError: data type mismatch (argument #2)
$split("Star Wars", ' ', 1) # => ("Star", "Wars")
```

--------------------------------

### Apply rule with matches() and filter()

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Shows how to check a single object with matches() and filter an iterable with filter(), which returns a generator.

```python
# check if the first object matches
rule.matches(comics[0]) # => True

# filter the iterable "comics" and return matching objects
rule.filter(comics) # => <generator object Rule.filter at 0x7f2bdafbe650>
```

--------------------------------

### Create rule using attribute access

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Uses the built-in attribute as_upper to normalize case in the publisher field.

```python
rule = rule_engine.Rule(
  # normalize potential variations in the publisher case such as 'Dc'
  'publisher.as_upper == "DC"'
)
```

--------------------------------

### Use self-referential OBJECT attributes

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Demonstrates self-referential attribute chains in rules and matching against a Hero instance, returning True.

```python
rule = rule_engine.Rule('hero.nemesis.name == "Joker"', context=context)

batman = Hero('Batman', 'DC', datetime.date(1939, 5, 1))
joker = Hero('Joker', 'DC', datetime.date(1940, 4, 25), nemesis=batman)
batman.nemesis = joker

rule.matches({'hero': batman})  # => True
```

--------------------------------

### Type hinting with Context: valid and invalid symbols

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Demonstrates type hinting behavior: with a type_resolver, unknown symbols raise SymbolResolutionError, while valid symbols are accepted. Omitting context disables type checking and allows any symbol.

```python
# this is valid: issue is defined as a valid symbol
rule = rule_engine.Rule('issue == 1', context=context)
# => <Rule text='issue == 1' >

# this is invalid: author is not defined as a valid symbol
rule = rule_engine.Rule('author == "Stan Lee"', context=context)
# => SymbolResolutionError: author

# this is valid: no type information is defined (context is omitted)
rule = rule_engine.Rule('author == "Stan Lee"')
# => <Rule text='author == "Stan Lee"' >
```

--------------------------------

### Define OBJECT type and context

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Creates an OBJECT type with named attributes and registers it in a Context's type_resolver, using 'self' for the self-referential nemesis attribute.

```python
HeroType = rule_engine.DataType.OBJECT('Hero', attributes={
    'name': rule_engine.DataType.STRING,
    'publisher': rule_engine.DataType.STRING,
    'first_appearance': rule_engine.DataType.DATETIME,
    'nemesis': rule_engine.DataType.OBJECT.self,
})

context = rule_engine.Context(type_resolver={
    'hero': HeroType,
    'Hero': HeroType,
})
```

--------------------------------

### split(STRING string, [STRING sep, FLOAT maxsplit])

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Function to split a string into substrings.

```APIDOC
## split(STRING string, [STRING sep, FLOAT maxsplit]) -> ARRAY[STRING]

### Description
Split a string value into sub strings. If *sep* is not specified, the *string* will be split by all whitespace. If *sep* is specified, *string* will be split by that value. This alters how consecutive spaces are handled. When *sep* is not specified, consecutive whitespace is handled as a single unit and reduced, where as if *sep* is a single space, consecutive spaces will result in empty strings being returned.

### Parameters
- **string** (STRING) - Required - The string value to split into substrings.
- **sep** (STRING) - Optional - The value to split *string* on.
- **maxsplit** (FLOAT) - Optional - The maximum number of times to split *string*.

### Returns
- **ARRAY** of STRING - The resulting substrings.

### Example
```default
$split("A    B")      # => ('A', 'B')
$split("A    B", ' ') # => ('A', '', '', '', 'B')
```
```

--------------------------------

### Create custom Context with resolve_attribute resolver

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Creates a custom Context with the resolve_attribute resolver and defines a rule using that context. This is required to resolve symbols from object attributes instead of dictionary keys.

```python
# define the custom context to set the resolver
context = rule_engine.Context(resolver=rule_engine.resolve_attribute)
# then define a rule using the custom context
rule = rule_engine.Rule('publisher == "DC"', context=context)
```

--------------------------------

### Create rule with datetime literals and conditionals

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/getting_started.rst

Defines a rule that matches DC books released in May 2020 using datetime literals and logical operators.

```python
rule = rule_engine.Rule(
  # match DC books released in May 2020
  'released >= d"2020-05-01" and released < d"2020-06-01" and publisher == "DC"'
)
```

--------------------------------

### Math Constants

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Mathematical constants available in the rule engine.

```APIDOC
## Math Constants

### Description
Mathematical constants available in the rule engine.

### Constants
- **e** (FLOAT) - The mathematical constant *e* (2.71828…).
- **pi** (FLOAT) - The mathematical constant *pi* (3.14159…).
```

--------------------------------

### Define an OBJECT type with attributes

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/types.rst

Creates an OBJECT type with a fixed attribute schema. The name 'Hero' is used for nominal type compatibility; two OBJECT types are compatible only when their names match.

```python
import rule_engine

Hero = rule_engine.DataType.OBJECT('Hero', attributes={
    'name': rule_engine.DataType.STRING,
    'publisher': rule_engine.DataType.STRING,
    'first_appearance': rule_engine.DataType.DATETIME,
})
```

--------------------------------

### Check data type family with DataType.is_type()

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/types.rst

Shows how to use the DataType.is_type() classmethod to check whether a data type belongs to the same family as a sentinel, ignoring member types for compound types. The comments indicate expected results for ARRAY, MAPPING, and STRING sentinels.

```python
DataType.is_type(dt, DataType.ARRAY)    # True for ARRAY(STRING), ARRAY(FLOAT), bare ARRAY, …
DataType.is_type(dt, DataType.MAPPING)  # True for any parameterized or bare MAPPING
DataType.is_type(dt, DataType.STRING)   # True only for STRING itself (scalars are singletons)
```

--------------------------------

### map(FUNCTION function, ARRAY[??] values)

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Function to apply a mapping function to each array element.

```APIDOC
## map(FUNCTION function, ARRAY[??] values) -> ARRAY[??]

### Description
Returns an array containing the results of applying *function* to each member of *values*.

### Parameters
- **function** (FUNCTION) - Required - The function to call on each of the values.
- **values** (ARRAY of anything) - Required - The array of values to apply *function* to.

### Returns
- **ARRAY** of anything - The mapped array.
```

--------------------------------

### min(ARRAY[FLOAT] values) -> FLOAT

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Function to find the minimum value in an array.

```APIDOC
## min(ARRAY[FLOAT] values) -> FLOAT

### Description
Returns the smallest value from the array of values. If *values* is empty, a `FunctionCallError` is raised.

### Parameters
- **values** (ARRAY of FLOAT) - Required - An array of values to check.

### Returns
- **FLOAT** - The smallest value.
```

--------------------------------

### STRING encode(STRING encoding) -> BYTES

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/attributes.rst

Encodes a STRING value to BYTES using the specified encoding. Supports standard Python encodings as well as special names 'hex', 'base16', and 'base64'.

```APIDOC
## STRING encode(STRING encoding) -> BYTES

### Description
Encodes a STRING value to BYTES using the specified encoding. Supports standard Python encodings as well as special names 'hex', 'base16', and 'base64'.

### Method
Function

### Signature
`STRING encode(STRING encoding) -> BYTES`

### Parameters
- **encoding** (STRING) - Required - The encoding name to use.

### Returns
- **BYTES** - The encoded value.

### Version Added
4.5.0
```

--------------------------------

### Custom accessor for dict-backed objects

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/types.rst

Provides a custom accessor to fetch attribute values from a dict-backed object instead of using getattr(). The accessor receives the object and attribute name and returns the value.

```python
# use a dict-backed object instead of an attribute-backed one
Hero = rule_engine.DataType.OBJECT('Hero',
    attributes={'name': rule_engine.DataType.STRING},
    accessor=lambda obj, name: obj[name]
)
```

--------------------------------

### random([FLOAT boundary]) -> FLOAT

Source: https://github.com/zerosteiner/rule-engine/blob/master/docs/source/syntax.rst

Function to generate a random number.

```APIDOC
## random([FLOAT boundary]) -> FLOAT

### Description
Generate a random number. If *boundary* is not specified, the random number returned will be between 0 and 1. If *boundary* is specified, it must be a natural number and the random number returned will be between 0 and *boundary*, including *boundary*.

### Parameters
- **boundary** (FLOAT) - Optional - The upper boundary to generate a random number for.

### Returns
- **FLOAT** - A random number.
```
Tokens:
Raw