reset gh-pages docs

_sources/api.rst.txt

@@ -0,0 +1,341 @@
+.. _asteval_api:
+
+========================
+asteval reference
+========================
+
+.. _numpy: https://numpy.org
+
+.. module:: asteval
+
+The asteval module has a pretty simple interface, providing an
+:class:`Interpreter` class which creates an Interpreter of expressions and
+code.  There are a few options available to control what language features
+to support, how to deal with writing to standard output and standard error,
+and specifying the symbol table.  There are also a few convenience
+functions: :func:`valid_symbol_name` is useful for testing the validity of
+symbol names, and :func:`make_symbol_table` is useful for creating symbol
+tables that may be pre-loaded with custom symbols and functions.
+
+
+The :class:`Interpreter` class
+=========================================
+
+.. autoclass:: Interpreter
+
+
+By default, the symbol table will be created with :func:`make_symbol_table`
+that will include several standard python builtin functions, several
+functions from the :py:mod:`math` module and (if available and not turned off)
+several functions from `numpy`_.
+
+The ``writer`` argument can be used to provide a place to send all output
+that would normally go to :py:data:`sys.stdout`.  The default is, of
+course, to send output to :py:data:`sys.stdout`.  Similarly, ``err_writer``
+will be used for output that will otherwise be sent to
+:py:data:`sys.stderr`.
+
+The ``use_numpy`` argument can be used to control whether functions from
+`numpy`_ are loaded into the symbol table.
+
+Whether the user-code is able to overwrite the entries in the symbol table can
+be controlled with the ``readonly_symbols`` and ``builtins_readonly`` keywords.
+
+Configuring which features the Interpreter recognizes
+========================================================
+
+The interpreter can be configured to enable or disable many language
+constructs, named according to the AST node in the Python language definition.
+
+.. _node_table:
+
+**Table of optional Python AST nodes used asteval.** The minimal configuration
+excludes all of the nodes listed, to give a bare-bones mathematical language
+but will full support for Python data types and array slicing.
+
+  +----------------+----------------------+-------------------+-------------------+
+  | node name      | description          | in default config | in minimal config |
+  +================+======================+===================+===================+
+  | import         | import statements    |  False            | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | importfrom     | from x import y      |  False            | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | assert         | assert statements    |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | augassign      | x += 1               |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | delete         | delete statements    |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | if             | if/then blocks       |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | ifexp          | a = b if c else d    |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | for            | for loops            |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | formattedvalue | f-strings            |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | functiondef    | define functions     |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | print          | print function       |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | raise          | raise statements     |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | listcomp       | list comprehension   |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | dictcomp       | dict comprehension   |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | setcomp        | set comprehension    |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | try            | try/except blocks    |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | while          | while blocks         |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+  | with           | with blocks          |  True             | False             |
+  +----------------+----------------------+-------------------+-------------------+
+
+
+The ``minimal`` configuration for the Interpreter will support many basic
+Python language constructs including all basic data types, operators, slicing.
+The ``default`` configuration adds many language constructs, including
+
+  *  if-elif-else conditionals
+  *  for loops, with ``else``
+  *  while loops, with ``else``
+  *  try-except-finally blocks
+  *  with blocks
+  *  augmented assignments:  ``x += 1``
+  *  if-expressions:      ``x = a if TEST else b``
+  *  list comprehension:  ``out = [sqrt(i) for i in values]``
+  *  set and dict comprehension, too.
+  *  print formatting with ``%``, ``str.format()``, or f-strings.
+  *  function definitions
+
+The nodes listed in Table :ref:`Table of optional Python AST nodes used asteval
+<node_table>` can be enabled and disabled individually with the appropriate
+``no_NODE`` or ``with_NODE`` argument when creating the interpreter, or
+specifying a ``config`` dictionary.
+
+That is, you might construct an Interpreter as::
+
+    >>> from asteval import Interpreter
+    >>>
+    >>> aeval_nowhile = Interpreter(no_while=True)
+    >>>
+    >>> config = {'while': False, 'if': False, 'try': False,
+                 'for': False, 'with': False}
+    >>> aveal_noblocks = Interpreter(config=config)
+
+
+Passing, ``minimal=True`` will turn off all the nodes listed in Table
+:ref:`Table of optional Python AST nodes used asteval <node_table>`::
+
+    >>> from asteval import Interpreter
+    >>>
+    >>> aeval_min = Interpreter(minimal=True)
+    >>> aeval_min.config
+    {'import': False, 'importfrom': False, 'assert': False, 'augassign': False,
+    'delete': False, 'if': False, 'ifexp': False, 'for': False,
+    'formattedvalue': False, 'functiondef': False, 'print': False,
+    'raise': False, 'listcomp': False, 'dictcomp': False, 'setcomp': False,
+    'try': False, 'while': False, 'with': False}
+
+As shown above, importing Python modules with ``import module`` or ``from
+module import method`` can be enabled, but is disabled by default.  To enable
+these, use ``with_import=True`` and ``with_importfrom=True``, as ::
+
+    >>> from asteval import Interpreter
+    >>> aeval_max = Interpreter(with_import=True, with_importfrom=True)
+
+or by setting the config dictionary as described above:
+
+Interpreter methods and attributes
+====================================
+
+An Interpreter instance has many methods, but most of them are
+implementation details for how to handle particular AST nodes, and should
+not be considered as part of the usable API.  The methods described be low,
+and the examples elsewhere in this documentation should be used as the
+stable API.
+
+.. method:: eval(expression[, lineno=0[, show_errors=True[, raise_errors=False]]])
+
+   evaluate the expression, returning the result.
+
+
+   :param expression: code to evaluate.
+   :type expression: string
+   :param lineno: line number (for error messages).
+   :type lineno: int
+   :param show_errors: whether to print error messages or leave them
+                       in the :attr:`errors` list.
+   :type show_errors:  bool
+   :param raise_errors: whether to re-raise exceptions or leave them
+                       in the :attr:`errors` list.
+   :type raise_errors:  bool
+
+.. method:: __call__(expression[, lineno=0[, show_errors=True[, raise_errors=False]]])
+
+   same as :meth:`eval`.  That is::
+
+      >>> from asteval import Interpreter
+      >>> a = Interpreter()
+      >>> a('x = 1')
+
+   instead of::
+
+      >>> a.eval('x = 1')
+
+.. attribute:: symtable
+
+   the symbol table where all data and functions for the Interpreter are stored
+   and looked up. By default, this is a simple dictionary with symbol names as
+   keys, and values of data and functions. If the ``nested_symtable``
+   option is used, the symbol tables will be a subclass of a dictionary with
+   more features, as discussed in :ref:`symtable_section`.
+
+   In either case, the symbol table can be accessed from the calling program
+   using the  :attr:`symtable` attribute of the Interpreter.  This allows the
+   calling program to read, insert, replace, or remove symbols to
+   alter what symbols are known to your interpreter.
+
+
+.. attribute:: error
+
+   a list of error information, filled on exceptions. You can test this
+   after each call of the interpreter. It will be empty if the last
+   execution was successful.  If an error occurs, this will contain a liste
+   of Exceptions raised.
+
+.. attribute:: error_msg
+
+   the most recent error message.
+
+.. _symtable_section:
+
+Symbol Tables used in asteval
+====================================
+
+The symbol table holds all of the data used by the Interpreter.  That is, when
+you execute ``a = b * cos(pi/3)``, the Interpreter sees that it needs to lookup
+values for ``b``, ``cos``, and ``pi`` (it already knows ``=``, ``*``, ``/``,
+``(``, and ``)`` mean), and then set the value for ``a``.  The place where it
+looks up and then sets those values for these assigned variables is the symbol
+table.
+
+Historically, and by default, the symbol table in Asteval is a simple
+dictionary with variable names as the keys, and their values as the
+corresponding values.  This is slightly simpler than in Python or roughly
+equivalent to everything being "global".  This isn't exactly true, and what
+happens inside an Asteval Procedure (basically, a function) is a little
+different as a special local symbol table (or Frame) is created for that
+function, but it is mostly true.
+
+Symbol names are limited to being valid Python object names, and must match
+``[a-zA-Z_][a-zA-Z0-9_]*`` and not be a reserved word.  The symbol table is held
+in the :attr:`symtable` attribute of the Interpreter, and can be accessed and
+manipulated from the containing Python program.  This allows the calling
+program to read, insert, replace, or remove symbols to alter what symbols are
+known to your interpreter.  That is, it is perfectly valid to do something like
+this::
+
+      >>> from asteval import Interpreter
+      >>> aeval = Interpreter()
+      >>> aeval.symtable['x'] = 10
+      >>> aeval('sqrt(x)')
+      3.1622776601683795
+
+
+By default, the symbol table will be pre-loaded with many Python builtins,
+functions from the ``math`` module, and functions from ``numpy`` if available.
+You can control some of these settings or add symbols into the symbol table
+with the ``use_numpy`` and ``user_symbols`` arguments when creating an Interpreter.
+You can also build your own symbol table and pass that it, and use the
+``readonly_symbols`` and ``builtins_readonly`` options to prevent some symbols to
+be writeable from within the Interpreter.  You can also create your own symbol
+table, either as a plain dict, or with the :func:`make_symbol_table` function,
+and alter that to use as the ``symtable`` option when creating an Interpreter.
+That is, the calling program can fully control the symbol table, either
+pre-loading custom variables and functions or removing default functions.
+
+.. versionadded:: 0.9.31
+
+
+New Style Symbol Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Beginning with version 0.9.31, there is an option to use a more complex and
+nested symbol table. This symbol table uses a ``"Group"`` object which is a
+subclass of a Python dict that can also be used with ``object.attribute`` syntax::
+
+      >>> from asteval import Interpreter
+      >>> aeval = Interpreter(nested_symtable=True)
+      >>> aeval('x = 3')
+      >>> aeval.symtable['x']  # as with default dictionary
+      3
+      >>> aeval.symtable.x     # new
+      3
+      >>> aeval.symtable.y = 7  # new
+      >>> aeval('print(x+y)')
+      10
+
+As with the plain-dictionary symbol table, all symbols must be valid Python
+identifiers, and cannot be reserved words.
+
+In addition, this symbol table can be nested -- not flat -- and may have a
+special attribute called ``_searchgroups`` that give the name of sub-Groups to
+search for symbols.  By default, when using this new-style symbol table, the
+mathematical functions imported from the ``math`` and ``numpy`` modules) are
+placed in a subgroup named ``math`` (with more that 350 named functions and
+variables), and the ``_searchgroups`` variable is set to the tuple
+``('math',)``.  When looking for the a symbol in an expression like ``a = b *
+cos( pi /3)``, the Interpreter will have to find and use the symbols names for
+``b``, ``cos`` and ``pi``.  With the old-style symbol table, all of these
+must be in the flat dictionary, which makes it difficult to browse through the
+symbol table.  With the new, nested symbol table, the names ``b``, ``cos``
+and ``pi`` are first looked for in the top-level Group. If not found there,
+they are looked for in the subgroups named in ``_searchgroups``, in order and
+returned as soon as one is found.  That is the expectation is that `b` would be
+found in the "top-level user Group", while ``cos`` and ``pi`` would be found in the
+``math`` Group, and that::
+
+      >>> aeval('a = b * cos( pi /3)')
+      >>> aeval('a = b * math.cos(math.pi /3)')
+
+would be equivalent, as if you had imported a module that would automatically
+be searched: something between ``import math`` and ``from math import *``.  Though
+different from how Python works, if using Asteval as a domain-specific
+language, this nesting and automated searching can be quite useful.
+
+
+Utility Functions
+====================
+
+.. autofunction:: valid_symbol_name
+
+
+
+.. autofunction:: make_symbol_table
+
+
+To make and use a custom symbol table, one might do this::
+
+    from asteval import Interpreter, make_symbol_table
+    import numpy as np
+    def cosd(x):
+        "cos with angle in degrees"
+        return np.cos(np.radians(x))
+
+    def sind(x):
+        "sin with angle in degrees"
+        return np.sin(np.radians(x))
+
+    def tand(x):
+        "tan with angle in degrees"
+        return np.tan(np.radians(x))
+
+    syms = make_symbol_table(use_numpy=True, cosd=cosd, sind=sind, tand=tand)
+
+    aeval = Interpreter(symtable=syms)
+    print(aeval("sind(30)")))
+
+which will print ``0.5``.