Class NumExpr

numexpr3/ne3compiler.py:306–890

The :code:`NumExpr` class is the core encapsulation of the :code:`numexpr3` module. It encapsulates a `CompiledExec` object which is the virtual machine object from the C-api. It also handles all of the parsing of string statements via a functional dictionary that uses :code:`ast

    # End of ne3.evaluate()

class NumExpr(object):
    '''
    The :code:`NumExpr` class is the core encapsulation of the :code:`numexpr3` 
    module. It encapsulates a `CompiledExec` object which is the virtual 
    machine object from the C-api. It also handles all of the parsing of 
    string statements via a functional dictionary that uses :code:`ast` module 
    Nodes as keys.  This approach results in the Abstract Syntax Tree being 
    parsed in a single-pass, whereas NumExpr 2 required multiple passes for 
    different tasks.  See the :code:`_ASTAssembler` dictionary and its 
    associated functions for implementation details.

    Attributes
    ^^^^^^^^^^

    * :code:`program`: The self.program attribute is a `bytes` object and consists of operations 
      followed by registers with the form::
    
        opcode + return_reg + arg1_reg + arg2_reg + arg3_reg
        
      Currently opcode is a uint16 and the register numbers are uint8. This means
      there can be up to 64k operations in the virtual machine and up to 254 
      registers/arguments (255 is reserved) in a code block. However,
      note that the NumPy code :code:`#define NPY_MAXARGS 32` limits the maximum 
      number of arguments to 32.

    * :code:`_codeStream`: a :code:`BytesIO` buffer that is used to build the 
      program. This was found to be the fastest way to construct the large byte
      strings formed.

    TODO: other NumExpr attribs
    '''

    
    def __init__(self, expr, lib=LIB_STD, casting=CAST_SAFE, local_dict=None, 
                 stackDepth=1):
        '''
        Evaluate a mutli-line expression element-wise, using NumPy broadcasting 
        rules::

            neObj = NumExpr('c=2*a+3*b') # Builds an NumExpr object
            neObj()                      # Executes with original arrays
            neObj(verify=True)           # Checks the calling frame for the array names
            neObj(a=foo, b=bar, c=moo)   # Executes the calculation with new arrays
            neObj(**local_dict)          # Unpack a dictionary with variable names as keys

        Multi-line statements, typically using triple-quote strings, or semi-colon 
        seperated statements, are supported. If an intermediate assignment target 
        exists in the calling frame, it is treated by convention as a second 
        (or third, ...) output.  Otherwise it is a named temporary, and it will 
        never be a full-size array::

            big = NumExpr('')
            
        TODO: example
        
        Arguments
        ^^^^^^^^^