Metadata-Version: 2.1
Name: ASTFormula
Version: 0.0.2
Summary: A simple and extensible AST-based Python formula engine to execute string calculation statements
Home-page: https://github.com/oryba/astformula
Author: Oleh Rybalchenko
Author-email: rv.oleg.ua@gmail.com
License: OSI Approved (BSD)
Download-URL: https://github.com/oryba/astformula/archive/v0.0.2.zip
Description: # ASTFormula – simple and safe formula engine
        
        ## Description
        
        This package is simple and extensible formula engine with python-like 
        syntax. **No eval usages under the hood** – it's a safe way to work
        with formulas and variables from untrusted sources like user input.  
        
        ## Usage
        
        ### Quick start
        
        ```python
        from astformula import ASTFormula
        
        engine = ASTFormula()
        executable = engine.get_calc_expression('a + b * 2')
        executable({'a': 2, 'b': 3})  # returns 8
        ```
        
        ### Custom functions
        
        List of available functions can be supplemented by passing dict of 
        function names as keys and executables as values.
        
        ```python
        from astformula import ASTFormula
        
        def exp3(value):
            return pow(value, 3)
        
        engine = ASTFormula(functions={'exp3': exp3})
        executable = engine.get_calc_expression('a + exp3(b * 2)')
        executable({'a': 2, 'b': 3})  # returns 218
        ```
        
        ### Custom node processors
        
        Any AST node processor can be overridden by passing `node_type: callback`
        dict to node_processors argument. Callback must take the following arguments:
         - engine: ASTFormula - engine instance
         - node: ast.AST or core types – current node of type `node_type`
         - variables: dict – all variables passed to the executable
        
        In particular, passed `engine` instance can be used to:
         - get operator by name: `engine.get_operator(name)`
         - get function by name: `engine.get_function(name)`
         - evaluate node: `engine.evaluate(node, variables)`
        
        ```python
        import ast
        from astformula import ASTFormula
        
        def bin_op(engine: 'ASTFormula', node, variables):
            # AST node structure: <node.left=left> <node.op=operator> <node.right=right>
            result = engine.get_operator(node.op)(
                engine.evaluate(node.left, variables),
                engine.evaluate(node.right, variables)
            )
            return engine.evaluate(result)
        
        engine = ASTFormula(node_processors={ast.BinOp: bin_op})
        executable = engine.get_calc_expression('a + b')
        executable({'a': 2, 'b': 3})  # returns 5
        ```
        
        ### Custom constants
        To be implemented
        
        ### Custom operators processing
        Operators processing can be overridden and implemented by passing
        `ast_operator_node: callback` dict to operators argument.
        
        ```python
        import ast
        import operator as op
        from astformula import ASTFormula
        
        custom_operators_proc = {ast.Pow: op.pow}  # **
        
        engine = ASTFormula(operators=custom_operators_proc)
        executable = engine.get_calc_expression('a ** b')
        executable({'a': 2, 'b': 3})  # returns 8
        ```
        
        ### Handling exceptions
        To simulate try..except statement a special function is provided out of
        the box - `iferror(statement, fallback)`. Fallback executes only
        if the main statement fails.
        
        ```python
        from astformula import ASTFormula
        
        engine = ASTFormula()
        executable = engine.get_calc_expression('iferror(a ** b / 0, None)')
        executable({'a': 2, 'b': 3})  # returns None
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
