hbutils.expression.native

This module provides native expression utilities for the hbutils library.

It aggregates and exports functionalities from three main submodules:

base: Base expression classes and utilities
feature: Feature-related expression components
general: General-purpose expression utilities

This module serves as a convenient entry point to access all native expression functionalities without needing to import from individual submodules.

Example::

>>> from hbutils.expression.native import *
>>> # Now you can use all exported classes and functions from base, feature, and general

efunc

hbutils.expression.native.efunc(e: Any) → Callable[source]

Get callable object from any types.

Parameters:: e (Any) – Original object.
Returns:: Callable object. If given e is an Expression, its callable method will be returned. If given e is a function, an equivalent method will be returned. Otherwise, a method which always return e will be returned.
Return type:: Callable

Note

This is the key feature of the native expressions, you need to use efunc() function to transform expressions to callable functions.

Examples::

>>> from hbutils.expression import keep, efunc, expr
>>>
>>> e1 = keep()
>>> efunc(e1 == 1)(1)
True
>>> efunc(e1 == 1)(2)
False
>>>
>>> e2 = expr(lambda x: x + 2)
>>> efunc(e2 == 1)(-1)
True
>>> efunc(e2 == 1)(1)
False

expr

hbutils.expression.native.expr(v, cls: Type[Expression] | None = None)[source]

Transform any objects to Expression.

This function intelligently converts different types of values into expressions: - If the given v is already an Expression, it returns v unchanged. - If the given v is a callable object, it creates an expression with v as the transformation function. - Otherwise, it creates an expression with lambda x: v as the transformation function (constant expression).

Parameters:

v (Any) – Original value to be converted into an expression. Can be an Expression, callable, or any other value.
cls (Optional[Type[Expression]]) – Class of expression, should be a subclass of Expression. Default is None which means GeneralExpression will be used.

Returns:

Generated expression object.

Return type:

Expression

Example::

>>> # Create expression from callable
>>> e1 = expr(lambda x: x * 2)
>>> # Create expression from constant
>>> e2 = expr(42)
>>> # Pass through existing expression
>>> e3 = expr(e1)

keep

hbutils.expression.native.keep(cls: Type[Expression] | None = None)[source]

Create an identity expression that returns the input unchanged.

This is an alias for expr(lambda x: x, cls), which creates an expression that simply passes through its input without any transformation.

Parameters:: cls (Optional[Type[Expression]]) – Class of expression, should be a subclass of Expression. Default is None which means GeneralExpression will be used.
Returns:: Generated identity expression.
Return type:: Expression

Example::

>>> identity = keep()
>>> # The expression will return input unchanged

raw

hbutils.expression.native.raw(v, cls: Type[Expression] | None = None)[source]

Create a constant expression that always returns the same value.

This is an alias for expr(lambda x: v, cls), which creates an expression that ignores its input and always returns the constant value v.

Parameters:

v (Any) – Raw value to be returned by the expression, regardless of input.
cls (Optional[Type[Expression]]) – Class of expression, should be a subclass of Expression. Default is None which means GeneralExpression will be used.

Returns:

Generated constant expression.

Return type:

Expression

Example::

>>> constant = raw(42)
>>> # The expression will always return 42, regardless of input

Expression

class hbutils.expression.native.Expression(func: Callable | None = None)[source]

Base class of expressions.

This class provides the foundation for building composable expressions. It wraps a callable function and provides methods to combine expressions into more complex ones.

The Expression class can be subclassed to create custom expression types with specialized operators and methods.

__init__(func: Callable | None = None)[source]

Constructor of Expression.

Parameters:: func (Optional[Callable]) – Callable function, default is None which means a lambda x: x will be used.

classmethod _expr(v: Any) → Expression[source]

Build expression with this class.

This class method converts any value into an Expression object: - If v is already an Expression, return it as-is - If v is callable, wrap it in an Expression - Otherwise, create an Expression that returns the constant value v

Parameters:: v (Any) – Any types of value.
Returns:: An expression object.
Return type:: Expression

_func(func: Callable, *args, **kwargs) → Expression[source]

Expression building based on given func and arguments.

This method creates a new expression by composing the given function with the provided arguments. Each argument is converted to a callable using efunc, allowing for nested expression composition.

Parameters:

func (Callable) – Logical function to apply to the evaluated arguments.
args (Any) – Positional arguments, can be expressions, callables, or constants.
kwargs (Any) – Key-word arguments, can be expressions, callables, or constants.

Returns:

New expression with current class.

Return type:

Expression

Examples::

>>> from hbutils.expression import efunc, Expression
>>>
>>> class MyExpression(Expression):
...     def add(self, other):
...         return self._func(lambda x, y: x + y, self, other)
...
>>>
>>> e1 = MyExpression()
>>> efunc(e1.add(1))(5)  # 5 + 1 = 6
6
>>> efunc(e1.add(e1.add(1)))(5)  # 5 + (5 + 1) = 11
11

CheckExpression

class hbutils.expression.native.CheckExpression(func: Callable | None = None)[source]

Check expression.

Features:

__eq__, which means x == y.
__ne__, which means x != y.

ComparableExpression

class hbutils.expression.native.ComparableExpression(func: Callable | None = None)[source]

Comparable expression.

Features:

__eq__, which means x == y (the same as CheckExpression).
__ne__, which means x != y (the same as CheckExpression).
__ge__, which means x >= y.
__gt__, which means x > y.
__le__, which means x <= y.
__lt__, which means x < y.

IndexedExpression

class hbutils.expression.native.IndexedExpression(func: Callable | None = None)[source]

Indexed expression.

Features:

__getitem__, which means x[y].

ObjectExpression

class hbutils.expression.native.ObjectExpression(func: Callable | None = None)[source]

Object-like expression.

Features:

__getattr__, which means x.y.
__call__, which means x(*args, **kwargs).

LogicalExpression

class hbutils.expression.native.LogicalExpression(func: Callable | None = None)[source]

Logic expression.

Features:

__and__, which means x and y (written as x & y).
__or__, which means x or y (written as x | y).
__invert__, which means not x (written as ~x).

Note

Do not use this with BitwiseExpression, or unexpected conflict will be caused.

MathExpression

class hbutils.expression.native.MathExpression(func: Callable | None = None)[source]

Math calculation expression.

Features:

__add__, which means x + y.
__sub__, which means x - y.
__mul__, which means x * y.
__truediv__, which means x / y.
__floordiv__, which means x // y.
__mod__, which means x % y.
__pow__, which means x ** y.
__pos__, which means +x.
__neg__, which means -x.

BitwiseExpression

class hbutils.expression.native.BitwiseExpression(func: Callable | None = None)[source]

Bitwise expression class.

Features:

__and__, which means x & y (bitwise).
__or__, which means x | y (bitwise).
__xor__, which means x ^ y (bitwise).
__lshift__, which means x << y (bitwise).
__rshift__, which means x >> y (bitwise).
__invert__, which means ~x (bitwise).

Note

Do not use this with LogicalExpression, or unexpected conflict will be caused.

GeneralExpression

class hbutils.expression.native.GeneralExpression(func: Callable | None = None)[source]

A general-purpose expression class that combines multiple expression features.

This class inherits from multiple expression base classes to provide a comprehensive set of operations including comparisons, indexing, object operations, logical operations, and mathematical operations.

Features:

Inherited from ComparableExpression, IndexedExpression, ObjectExpression, LogicalExpression and MathExpression.

Example::

>>> expr_obj = GeneralExpression._expr(lambda x: x + 1)
>>> # Use the expression object for various operations