Mathematical expression parser: cython wrapper around the 'C++ Mathematical Expression Toolkit Library'

`cexprtk` is a cython wrapper around the “C++ Mathematical Expression
Toolkit Library
(ExprTk)” by
Arash Partow. Using `cexprtk` a powerful mathematical expression
engine can be incorporated into your python project.

## Table of Contents

[TOC]

## Installation

The latest version of `cexprtk` can be installed using
pip :

$ pip install cexprtk

**Note:** Installation requires a compatible C++ compiler to be
installed.

## Usage

The following examples show the major features of `cexprtk`.

### Example: Evaluate a simple equation

The following shows how the arithmetic expression `(5+5) * 23` can be
evaluated:

>>> import cexprtk >>> cexprtk.evaluate_expression("(5+5) * 23", {}) 230.0

### Example: Using Variables

Variables can be used within expressions by passing a dictionary to the
`evaluate_expression` function. This maps variable names to their
values. The expression from the previous example can be re-calculated
using variable values:

>>> import cexprtk >>> cexprtk.evaluate_expression("(A+B) * C", {"A" : 5, "B" : 5, "C" : 23}) 230.0

### Example: Re-using expressions

When using the `evaluate_expression()` function, the mathematical
expression is parsed, evaluated and then immediately thrown away. This
example shows how to re-use an `Expression` for multiple evaluations.

An expression will be defined to calculate the circumference of circle, this will then be re-used to calculate the value for several different radii.

First a

`Symbol_Table`is created containing a variable`r`(for radius), it is also populated with some useful constants such as π.>>> import cexprtk >>> st = cexprtk.Symbol_Table({'r' : 1.0}, add_constants= True)

Now an instance of

`Expression`is created, defining our function:>>> circumference = cexprtk.Expression('2*pi*r', st)

The

`Symbol_Table`was initialised with`r=1`, the expression can be evaluated for this radius simply by calling it:>>> circumference() 6.283185307179586

Now update the radius to a value of 3.0 using the dictionary like object returned by the

`Symbol_Table`’s`.variables`property:>>> st.variables['r'] = 3.0 >>> circumference() 18.84955592153876

### Example: Defining an unknown symbol resolver

A callback can be passed to the `Expression` constructor through the
`unknown_symbol_resolver_callback` parameter. This callback is invoked
during expression parsing when a variable or constant is encountered
that isn’t in the `Symbol_Table` associated with the `Expression`.

The callback can be used to provide some logic that leads to a new symbol being registered or for an error condition to be flagged.

**The Problem:** The following example shows a potential use for the
symbol resolver:

- An expression contains variables of the form
`m_VARIABLENAME`and`f_VARIABLENAME`. `m_`or`f_`prefix the actual variable name (perhaps indicating gender).`VARIABLENAME`should be used to look up the desired value in a dictionary.- The dictionary value of
`VARIABLENAME`should then be weighted according to its prefix:`m_`variables should be multiplied by 0.8.`f_`variables should be multiplied by 1.1.

**The Solution:**

First the

`VARIABLENAME`dictionary is defined:variable_values = { 'county_a' : 82, 'county_b' : 76}

Now the callback is defined. This takes a single argument,

*symbol*, which gives the name of the missing variable found in the expression:def callback(symbol): # Tokenize the symbol name into prefix and VARIABLENAME components. prefix,variablename = symbol.split("_", 1) # Get the value for this VARIABLENAME from the variable_values dict value = variable_values[variablename] # Find the correct weight for the prefix if prefix == 'm': weight = 0.8 elif prefix == 'f': weight = 1.1 else: # Flag an error condition if prefix not found. errormsg = "Unknown prefix "+ str(prefix) return (False, cexprtk.USRSymbolType.VARIABLE, 0.0, errormsg) # Apply the weight to the value *= weight # Indicate success and return value to cexprtk return (True, cexprtk.USRSymbolType.VARIABLE, value, "")

All that remains is to register the callback with an instance of

`Expression`and to evaluate an expression. The expression to be evaluated is:`(m_county_a - f_county_b)`- This should give a value of
`(0.8*82) - (1.1*76) = -18`

>>> st = cexprtk.Symbol_Table({}) >>> e = cexprtk.Expression("(m_county_a - f_county_b)", st, callback) >>> e.value() -18.0

## API Reference

For information about expressions supported by `cexprtk` please refer
to the original C++
ExprTK
documentation:

### Class Reference

#### class Expression:

Class representing mathematical expression.

- Following instantiation, the expression is evaluated calling the
expression or invoking its
`value()`method. - The variable values used by the Expression can be modified through
the
`variables`property of the`Symbol_Table`instance associated with the expression. The`Symbol_Table`can be accessed using the`Expression.symbol_table`property.

Defining unknown symbol-resolver:

The `unknown_symbol_resolver_callback` argument to the `Expression`
constructor accepts a callable which is invoked whenever a symbol (i.e.
a variable or a constant), is not found in the `Symbol_Table` given by
the `symbol_table` argument. The `unknown_symbol_resolver_callback`
can be used to provide a value for the missing value or to set an error
condition.

The callable should have following signature:

def callback(symbol_name): ...

Where `symbol_name` is a string identifying the missing symbol.

The callable should return a tuple of the form:

(HANDLED_FLAG, USR_SYMBOL_TYPE, SYMBOL_VALUE, ERROR_STRING)

Where:

`HANDLED_FLAG`is a boolean:`True`indicates that callback was able handle the error condition and that`SYMBOL_VALUE`should be used for the missing symbol.`False`, flags and error condition, the reason why the unknown symbol could not be resolved by the callback is described by`ERROR_STRING`.

`USR_SYMBOL_TYPE`gives type of symbol (constant or variable) that should be added to the`symbol_table`when unkown symbol is resolved. Value should be one of those given in`cexprtk.USRSymbolType`. e.g.`cexprtk.USRSymbolType.VARIABLE``cexprtk.USRSymbolType.CONSTANT`

`SYMBOL_VALUE`, floating point value that should be used when resolving missing symbol.`ERROR_STRING`when`HANDLED_FLAG`is`False`this can be used to describe error condition.

##### def **init**(self, *expression*, *symbol_table*, *unknown_symbol_resolver_callback* = None):

Instantiate `Expression` from a text string giving formula and
`Symbol_Table` instance encapsulating variables and constants used by
the expression.

**Parameters:**

**expression**(*str*) String giving expression to be calculated.**symbol_table**(*Symbol_Table*) Object defining variables and constants.**unknown_symbol_resolver_callback**(*callable*) See description above.

##### def value(self):

Evaluate expression using variable values currently set within
associated `Symbol_Table`

**Returns:**

- (
*float*) Value resulting from evaluation of expression.

##### def **call**(self):

Equivalent to calling `value()` method.

**Returns:**

- (
*float*) Value resulting from evaluation of expression.

##### symbol_table

Read only property that returns `Symbol_Table` instance associated
with this expression.

**Returns:**

- (
*Symbol_Table*)`Symbol_Table`associated with this`Expression`.

#### class Symbol_Table:

Class for providing variable and constant values to `Expression`
instances.

##### def **init**(self, *variables*, *constants* = {}, *add_constants* = False):

Instantiate `Symbol_Table` defining variables and constants for use
with `Expression` class.

**Example:**

To instantiate a

`Symbol_Table`with:`x = 1``y = 5`- define a constant
`k = 1.3806488e-23`

The following code would be used:

st = cexprtk.Symbol_Table({'x' : 1, 'y' : 5}, {'k'= 1.3806488e-23})

**Parameters:**

**variables**(*dict*) Mapping between variable name and initial variable value.**constants**(*dict*) Dictionary containing values that should be added to`Symbol_Table`as constants. These can be used a variables within expressions but their values cannot be updated following`Symbol_Table`instantiation.**add_constants**(*bool*) If`True`, add the standard constants`pi`,`inf`,`epsilon`to the ‘constants’ dictionary before populating the`Symbol_Table`

##### variables

Returns dictionary like object containing variable values.
`Symbol_Table` values can be updated through this object.

**Example:**

>>> import cexprtk >>> st = cexprtk.Symbol_Table({'x' : 5, 'y' : 5}) >>> expression = cexprtk.Expression('x+y', st) >>> expression() 10.0

Update the value of `x` in the symbol table and re-evaluate the
expression:

>>> expression.symbol_table.variables['x'] = 11.0 >>> expression() 16.0

**Returns:**

- Dictionary like giving variables stored in this
`Symbol_Table`. Keys are variables names and these map to variable values.

##### constants

Property giving constants stored in this `Symbol_Table`.

**Returns:**

- Read-only dictionary like object mapping constant names stored in
`Symbol_Table`to their values.

#### class USRSymbolType:

Defines constant values used to determine symbol type returned by
`unknown_symbol_resolver_callback` (see `Expression` constructor
documentation for more).

##### VARIABLE

Value that should be returned by an `unknown_symbol_resolver_callback`
to define a variable.

##### CONSTANT

Value that should be returned by an `unknown_symbol_resolver_callback`
to define a constant.

### Utility Functions

#### def check_expression (*expression*)

Check that expression can be parsed. If successful do nothing, if
unsuccessful raise `ParseException`.

**Parameters:**

*expression*(*str*) Formula to be evaluated

**Raises:**

`ParseException`: If expression is invalid.

#### def evaluate_expression (*expression*, *variables*)

Evaluate a mathematical formula using the exprtk library and return result.

For more information about supported functions and syntax see the exprtk C++ library website.

**Parameters:**

**expression**(*str*) Expression to be evaluated.**variables**(*dict*) Dictionary containing variable name, variable value pairs to be used in expression.

**Returns:**

- (
*float*): Evaluated expression

**Raises:**

`ParseException`: if*expression*is invalid.

## License

`cexprtk` is released under the same terms as the
ExprTK library
the Common Public License Version
1.0 (CPL).

## Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help | Version | File Type | Upload Date |
---|---|---|---|

cexprtk-0.2.0-cp27-none-win_amd64.whl (442.2 kB) Copy SHA256 Checksum SHA256 | 2.7 | Wheel | Dec 30, 2014 |

cexprtk-0.2.0-cp34-none-win_amd64.whl (448.3 kB) Copy SHA256 Checksum SHA256 | 3.4 | Wheel | Dec 30, 2014 |

cexprtk-0.2.0.tar.gz (155.9 kB) Copy SHA256 Checksum SHA256 | – | Source | Jun 23, 2014 |

cexprtk-0.2.0.win-amd64-py2.7.exe (675.3 kB) Copy SHA256 Checksum SHA256 | 2.7 | Windows Installer | Dec 30, 2014 |

cexprtk-0.2.0.win-amd64-py2.7.msi (589.8 kB) Copy SHA256 Checksum SHA256 | 2.7 | Windows MSI Installer | Dec 30, 2014 |

cexprtk-0.2.0.win-amd64-py3.4.exe (679.9 kB) Copy SHA256 Checksum SHA256 | 3.4 | Windows Installer | Dec 30, 2014 |

cexprtk-0.2.0.win-amd64-py3.4.msi (532.5 kB) Copy SHA256 Checksum SHA256 | 3.4 | Windows MSI Installer | Dec 30, 2014 |