pax_global_header00006660000000000000000000000064144630323700014514gustar00rootroot0000000000000052 comment=6131a4a9e9e83dc9ae5493d3313de49e55638e1d rule-engine-4.1.0/000077500000000000000000000000001446303237000137305ustar00rootroot00000000000000rule-engine-4.1.0/.github/000077500000000000000000000000001446303237000152705ustar00rootroot00000000000000rule-engine-4.1.0/.github/FUNDING.yml000066400000000000000000000000231446303237000171000ustar00rootroot00000000000000ko_fi: zerosteiner rule-engine-4.1.0/.github/workflows/000077500000000000000000000000001446303237000173255ustar00rootroot00000000000000rule-engine-4.1.0/.github/workflows/ci.yml000066400000000000000000000074571446303237000204600ustar00rootroot00000000000000name: Continuous Integration on: push: pull_request: jobs: unit-tests: name: Test on Python v${{ matrix.python-version }} runs-on: ubuntu-20.04 strategy: matrix: include: - pipenv-version: '2022.4.8' python-version: '3.6' - pipenv-version: '2022.4.8' python-version: '3.7' - pipenv-version: '2022.4.8' python-version: '3.8' - pipenv-version: '2022.4.8' python-version: '3.9' - pipenv-version: '2023.2.4' python-version: '3.10' - pipenv-version: '2023.2.4' python-version: '3.11' steps: - name: Checkout the repository uses: actions/checkout@v2 with: persist-credentials: false - name: Install build essentials run: sudo apt-get --yes install build-essential - name: Set up Python uses: actions/setup-python@v2 with: python-version: ${{ matrix.python-version }} - name: Install dependencies run: | pip install pipenv==${{ matrix.pipenv-version }} pipenv install --dev - run: pipenv run tests - run: pipenv run tests-coverage test-documentation: name: Test building the documentation if: github.ref != 'refs/heads/master' runs-on: ubuntu-latest steps: - name: Checkout the repository uses: actions/checkout@v2 with: persist-credentials: false - name: Install build essentials run: sudo apt-get --yes install build-essential - name: Set up Python uses: actions/setup-python@v2 - name: Install dependencies run: | pip install pipenv pipenv install --dev - name: Build the documentation run: pipenv run sphinx-build -b html -a -E -v docs/source docs/html publish-documentation: name: Build and publish the documentation if: github.ref == 'refs/heads/master' runs-on: ubuntu-latest steps: - name: Checkout the repository uses: actions/checkout@v2 with: persist-credentials: false - name: Install build essentials run: sudo apt-get --yes install build-essential - name: Set up Python uses: actions/setup-python@v2 - name: Install dependencies run: | pip install pipenv pipenv install --dev - name: Build the documentation run: pipenv run sphinx-build -b html -a -E -v docs/source docs/html - name: Publish the documentation uses: JamesIves/github-pages-deploy-action@3.7.1 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} BRANCH: gh-pages FOLDER: docs/html CLEAN: true publish-release: name: Publish the release if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags') runs-on: ubuntu-latest steps: - name: Checkout the repository uses: actions/checkout@v2 with: persist-credentials: false - name: Install build essentials run: sudo apt-get --yes install build-essential - name: Set up Python uses: actions/setup-python@v2 - name: Install dependencies run: | pip install pipenv pipenv install --dev - name: Create the distribution run: pipenv run python setup.py build sdist - name: Publish the distribution uses: pypa/gh-action-pypi-publish@release/v1 with: user: __token__ password: ${{ secrets.PYPI_TOKEN }} - name: Create the release id: create_release uses: actions/create-release@v1 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: tag_name: ${{ github.ref }} release_name: Release ${{ github.ref }} rule-engine-4.1.0/.gitignore000066400000000000000000000004151446303237000157200ustar00rootroot00000000000000*.ipynb *.py[cod] *.swp .coverage .github/workflows/*.jnj .pylintrc .python-version Pipfile.lock repl_setup.py build/* dist/* docs/build/* docs/coverage docs/html examples/shodan/*.json lib/rule_engine.egg-info/* lib/rule_engine/parser.out lib/rule_engine/parsetab.py rule-engine-4.1.0/LICENSE000066400000000000000000000027251446303237000147430ustar00rootroot00000000000000Copyright (c) 2020, Spencer McIntyre All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the project nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. rule-engine-4.1.0/Makefile000066400000000000000000000005661446303237000153770ustar00rootroot00000000000000VERSION := $(shell ./setup.py --version) .PHONY: build build: python setup.py build sdist .PHONY: clean clean: rm -rf build dist .PHONY: docs docs: pipenv install --dev pipenv run sphinx-build -b html -a -E -v docs/source docs/html .PHONY: release release: build $(eval RELEASE_TAG := v$(VERSION)) git tag -sm "Version $(VERSION)" $(RELEASE_TAG) git push --tags rule-engine-4.1.0/Pipfile000066400000000000000000000006621446303237000152470ustar00rootroot00000000000000[[source]] url = "https://pypi.org/simple" verify_ssl = true name = "pypi" [packages] ply = ">=3.9" python-dateutil = "~=2.7" [dev-packages] sphinx = "*" sphinx-rtd-theme = "*" graphviz = "*" coverage = "*" ipython = "*" [scripts] tests = 'sh -c "PYTHONPATH=$(pwd)/lib python -m unittest -v tests"' tests-coverage = 'sh -c "PYTHONPATH=$(pwd)/lib coverage run -m unittest -v tests && coverage report --include=\"*/rule_engine/*\""' rule-engine-4.1.0/README.rst000066400000000000000000000101371446303237000154210ustar00rootroot00000000000000Rule Engine =========== |badge-build| |badge-pypi| A lightweight, optionally typed expression language with a custom grammar for matching arbitrary Python objects. Documentation is available at https://zeroSteiner.github.io/rule-engine/. Rule Engine expressions are written in their own language, defined as strings in Python. The syntax is most similar to Python with some inspiration from Ruby. Some features of this language includes: - Optional type hinting - Matching strings with regular expressions - Datetime datatypes - Compound datatypes (equivalents for Python dict, list and set types) - Data attributes - Thread safety Example Usage ------------- The following example demonstrates the basic usage of defining a rule object and applying it to two dictionaries, showing that one matches while the other does not. See `Getting Started`_ for more information. .. code-block:: python import rule_engine # match a literal first name and applying a regex to the email rule = rule_engine.Rule( 'first_name == "Luke" and email =~ ".*@rebels.org$"' ) # => rule.matches({ 'first_name': 'Luke', 'last_name': 'Skywalker', 'email': 'luke@rebels.org' }) # => True rule.matches({ 'first_name': 'Darth', 'last_name': 'Vader', 'email': 'dvader@empire.net' }) # => False The next example demonstrates the optional type system. A custom context is created that defines two symbols, one string and one float. Because symbols are defined, an exception will be raised if an unknown symbol is specified or an invalid operation is used. See `Type Hinting`_ for more information. .. code-block:: python import rule_engine # define the custom context with two symbols context = rule_engine.Context(type_resolver=rule_engine.type_resolver_from_dict({ 'first_name': rule_engine.DataType.STRING, 'age': rule_engine.DataType.FLOAT })) # receive an error when an unknown symbol is used rule = rule_engine.Rule('last_name == "Vader"', context=context) # => SymbolResolutionError: last_name # receive an error when an invalid operation is used rule = rule_engine.Rule('first_name + 1', context=context) # => EvaluationError: data type mismatch Want to give the rule expression language a try? Checkout the `Debug REPL`_ that makes experimentation easy. After installing just run ``python -m rule_engine.debug_repl``. Installation ------------ Install the latest release from PyPi using ``pip install rule-engine``. Releases follow `Semantic Versioning`_ to indicate in each new version whether it fixes bugs, adds features or breaks backwards compatibility. See the `Change Log`_ for a curated list of changes. Credits ------- * Spencer McIntyre - zeroSteiner |social-github| License ------- The Rule Engine library is released under the BSD 3-Clause license. It is able to be used for both commercial and private purposes. For more information, see the `LICENSE`_ file. .. |badge-build| image:: https://img.shields.io/github/actions/workflow/status/zeroSteiner/rule-engine/ci.yml?branch=master&style=flat-square :alt: GitHub Workflow Status (branch) :target: https://github.com/zeroSteiner/rule-engine/actions/workflows/ci.yml .. |badge-pypi| image:: https://img.shields.io/pypi/v/rule-engine?style=flat-square :alt: PyPI :target: https://pypi.org/project/rule-engine/ .. |social-github| image:: https://img.shields.io/github/followers/zeroSteiner?style=social :alt: GitHub followers :target: https://github.com/zeroSteiner .. |social-twitter| image:: https://img.shields.io/twitter/follow/zeroSteiner :alt: Twitter Follow :target: https://twitter.com/zeroSteiner .. _Change Log: https://zerosteiner.github.io/rule-engine/change_log.html .. _Debug REPL: https://zerosteiner.github.io/rule-engine/debug_repl.html .. _Getting Started: https://zerosteiner.github.io/rule-engine/getting_started.html .. _LICENSE: https://github.com/zeroSteiner/rule-engine/blob/master/LICENSE .. _Semantic Versioning: https://semver.org/ .. _Type Hinting: https://zerosteiner.github.io/rule-engine/getting_started.html#type-hinting rule-engine-4.1.0/docs/000077500000000000000000000000001446303237000146605ustar00rootroot00000000000000rule-engine-4.1.0/docs/source/000077500000000000000000000000001446303237000161605ustar00rootroot00000000000000rule-engine-4.1.0/docs/source/_static/000077500000000000000000000000001446303237000176065ustar00rootroot00000000000000rule-engine-4.1.0/docs/source/_static/theme_overrides.css000066400000000000000000000005551446303237000235110ustar00rootroot00000000000000/* override table width restrictions */ @media screen and (min-width: 767px) { .wy-table-responsive table td { /* !important prevents the common CSS stylesheets from overriding this as on RTD they are loaded after this stylesheet */ white-space: normal !important; } .wy-table-responsive { overflow: visible !important; } } rule-engine-4.1.0/docs/source/attributes.rst000066400000000000000000000141541446303237000211050ustar00rootroot00000000000000.. py:currentmodule:: rule_engine Data Attributes =============== The attribute operator (``.``) can be used to recursively resolve values from a compound native Python data type such as an object or dictionary. This can be used when the **thing** which the rule is evaluating has members with their own submembers. If the resolver function fails, the attribute will be checked to determine if it is a builtin attribute. .. _builtin-attributes: Builtin Attributes ------------------ The following attributes are builtin to the default :py:class:`~.Context` object. +-------------------+-------------------------------------+ | Attribute Name | Attribute Type | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.ARRAY` **Attributes** | +-------------------+-------------------------------------+ | ``is_empty`` | :py:attr:`~.DataType.BOOLEAN` | +-------------------+-------------------------------------+ | ``length`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``to_set`` | :py:attr:`~.DataType.SET` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.DATETIME` **Attributes** | +-------------------+-------------------------------------+ | ``date`` | :py:attr:`~.DataType.DATETIME` | +-------------------+-------------------------------------+ | ``day`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``hour`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``microsecond`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``millisecond`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``minute`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``month`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``second`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``to_epoch`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``weekday`` | :py:attr:`~.DataType.STRING` | +-------------------+-------------------------------------+ | ``year`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``zone_name`` | :py:attr:`~.DataType.STRING` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.TIMEDELTA` **Attributes** | +-------------------+-------------------------------------+ | ``days`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``seconds`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``microseconds`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``total_seconds`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.FLOAT` **Attributes** :sup:`1` | +-------------------+-------------------------------------+ | ``ceiling`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``floor`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``to_str`` | :py:attr:`~.DataType.STRING` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.MAPPING` **Attributes** | +-------------------+-------------------------------------+ | ``is_empty`` | :py:attr:`~.DataType.BOOLEAN` | +-------------------+-------------------------------------+ | ``keys`` | :py:attr:`~.DataType.ARRAY` | +-------------------+-------------------------------------+ | ``length`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``values`` | :py:attr:`~.DataType.ARRAY` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.SET` **Attributes** | +-------------------+-------------------------------------+ | ``is_empty`` | :py:attr:`~.DataType.BOOLEAN` | +-------------------+-------------------------------------+ | ``length`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``to_ary`` | :py:attr:`~.DataType.ARRAY` | +-------------------+-------------------------------------+ | :py:attr:`~.DataType.STRING` **Attributes** | +-------------------+-------------------------------------+ | ``as_lower`` | :py:attr:`~.DataType.STRING` | +-------------------+-------------------------------------+ | ``as_upper`` | :py:attr:`~.DataType.STRING` | +-------------------+-------------------------------------+ | ``to_ary`` | :py:attr:`~.DataType.ARRAY` | +-------------------+-------------------------------------+ | ``to_flt`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``to_set`` | :py:attr:`~.DataType.SET` | +-------------------+-------------------------------------+ | ``to_int`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ | ``is_empty`` | :py:attr:`~.DataType.BOOLEAN` | +-------------------+-------------------------------------+ | ``length`` | :py:attr:`~.DataType.FLOAT` | +-------------------+-------------------------------------+ FLOAT Attributes :sup:`1` ^^^^^^^^^^^^^^^^^^^^^^^^^ Due to the syntax of floating point literals, the attributes must be accessed using parenthesis. For example ``3.14.to_str`` is invalid while ``(3.14).to_str`` is valid. rule-engine-4.1.0/docs/source/change_log.rst000066400000000000000000000126311446303237000210030ustar00rootroot00000000000000Change Log ========== This document contains notes on the major changes for each version of the Rule Engine. In comparison to the git log, this list is curated by the development team for note worthy changes. Version 4.x.x ------------- Version 4.1.0 ^^^^^^^^^^^^^ Released :release:`4.1.0` on August 3rd, 2023 * Added the ``$abs`` builtin function * Added support to :py:class:`~rule_engine.types.DataType.from_type` to handle Python's type hints Version 4.0.0 ^^^^^^^^^^^^^ Released :release:`4.0.0` on July 15th, 2023 * **Breaking:** Changed ``STRING.to_ary`` to return an array of characters instead of splitting the string * Use the new builtin ``$split`` function to split a string on whitespace into an array of words * **Breaking:** Changed :py:class:`~rule_engine.engine.Context` to use keyword-only arguments * **Breaking:** Dropped support for Python versions 3.4 and 3.5 * **Breaking:** Invalid floating point literals now raise :py:exc:`~.errors.FloatSyntaxError` instead of :py:exc:`~.errors.RuleSyntaxError` * **Breaking:** Moved ``rule_engine.engine.Builtins`` to :py:class:`rule_engine.builtins.Builtins` * Added the new :py:class:`~rule_engine.types.DataType.FUNCTION` data type Version 3.x.x ------------- Version 3.6.0 ^^^^^^^^^^^^^ Released :release:`3.6.0` on June 16th, 2023 * Removed testing for Python versions 3.4 and 3.5 on GitHub Actions * Add regex error details to the debug REPL * Add support for Python-style comments Version 3.5.0 ^^^^^^^^^^^^^ Released :release:`3.5.0` on July 16th, 2022 * Added the new :py:class:`~rule_engine.types.DataType.TIMEDELTA` data type Version 3.4.0 ^^^^^^^^^^^^^ Released :release:`3.4.0` on March 19th, 2022 * Add support for string concatenation via the ``+`` operator Version 3.3.0 ^^^^^^^^^^^^^ Released :release:`3.3.0` on July 20th, 2021 * Added ``to_epoch`` to :py:class:`~rule_engine.types.DataType.DATETIME` Version 3.2.0 ^^^^^^^^^^^^^ Released :release:`3.2.0` on April 3rd, 2021 * Refactored the :py:mod:`~rule_engine.ast` module to move the :py:class:`~rule_engine.types.DataType` class into a new, dedicated :py:mod:`~rule_engine.types` module. * Added the new :py:class:`~rule_engine.ast.ComprehensionExpression` * Added suggestions to :py:class:`~rule_engine.errors.AttributeResolutionError` and :py:class:`~rule_engine.errors.SymbolResolutionError` Version 3.1.0 ^^^^^^^^^^^^^ Released :release:`3.1.0` on March 15th, 2021 * Added the new :py:class:`~rule_engine.types.DataType.SET` data type Version 3.0.0 ^^^^^^^^^^^^^ Released :release:`3.0.0` on March 1st, 2021 * Switched the ``FLOAT`` datatype to use Python's :py:class:`~decimal.Decimal` from :py:class:`float` internally * Reserved the ``if``, ``elif``, ``else``, ``for`` and ``while`` keywords for future use, they can no longer be used as symbol names * Added some new data attributes * Added ``ceiling``, ``floor`` and ``to_str`` to :py:class:`~rule_engine.types.DataType.FLOAT` Version 2.x.x ------------- Version 2.4.0 ^^^^^^^^^^^^^ Released :release:`2.4.0` on November 7th, 2020 * Added the :ref:`debug-repl` utility * Added the safe navigation version of the attribute, item and slice operators * Added the new :py:class:`~rule_engine.types.DataType.MAPPING` data type * Switched from Travis-CI to GitHub Actions for continuous integration * Added support for iterables to have multiple member types Version 2.3.0 ^^^^^^^^^^^^^ Released :release:`2.3.0` on October 11th, 2020 * Added support for arithmetic comparisons for all currently supported data types * Added support for proper type hinting of builtin symbols * Added the ``$re_groups`` builtin symbol for extracting groups from a regular expression match * Added some new data attributes * Added ``to_ary`` to :py:class:`~rule_engine.types.DataType.STRING` * Added ``to_int`` and ``to_flt`` to :py:class:`~rule_engine.types.DataType.STRING` Version 2.2.0 ^^^^^^^^^^^^^ Released :release:`2.2.0` on September 9th, 2020 * Added script entries to the Pipfile for development * Added support for slices on sequence data types Version 2.1.0 ^^^^^^^^^^^^^ Released :release:`2.1.0` on August 3rd, 2020 * Added coverage reporting to Travis-CI * Changed :py:class:`~rule_engine.types.DataType`. from an enum to a custom class * Improvements for the :py:class:`~rule_engine.types.DataType.ARRAY` data type * Added ``get[item]`` support for arrays, allowing items to be retrieved by index * Added ability for specifying the member type and optionally null Version 2.0.0 ^^^^^^^^^^^^^ Released :release:`2.0.0` on October 2nd, 2019 * Added proper support for attributes * Added a change log * Added additional information to the Graphviz output * Added the new :py:class:`~rule_engine.types.DataType.ARRAY` data type * Started using Travis-CI * Added automatic unit testing using Travis-CI * Added automatic deployment of documentation using Travis-CI * Removed the resolver conversion functions * Removed ``to_recursive_resolver`` in favor of attributes * Removed ``to_default_resolver`` in favor of the *default_value* kwarg to :py:meth:`~rule_engine.engine.Context.__init__` Version 1.x.x ------------- Version 1.1.0 ^^^^^^^^^^^^^ Released :release:`1.1.0` on March 27th, 2019 * Added the :py:func:`~rule_engine.engine.to_default_dict` function * Added the :py:func:`~rule_engine.engine.to_recursive_resolver` function Version 1.0.0 ^^^^^^^^^^^^^ Released :release:`1.0.0` on December 15th, 2018 * First major release rule-engine-4.1.0/docs/source/conf.py000066400000000000000000000127721446303237000174700ustar00rootroot00000000000000# -*- coding: utf-8 -*- # # Configuration file for the Sphinx documentation builder. # # This file does only contain a selection of the most common options. For a # full list see the documentation: # http://www.sphinx-doc.org/en/stable/config import datetime import os import sys # -- Path setup -------------------------------------------------------------- _prj_root = os.path.dirname(__file__) _prj_root = os.path.relpath(os.path.join('..', '..', 'lib'), _prj_root) _prj_root = os.path.abspath(_prj_root) sys.path.insert(1, _prj_root) import rule_engine # -- Project information ----------------------------------------------------- project = 'Rule Engine' copyright = "{.year}, Spencer McIntyre".format(datetime.datetime.now()) author = 'Spencer McIntyre' # The short X.Y.Z version version = rule_engine.__version__ # The full version, including alpha/beta/rc tags release = version # -- General configuration --------------------------------------------------- GITHUB_BRANCH = 'master' GITHUB_REPO = 'zeroSteiner/rule-engine' add_module_names = False extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.extlinks', 'sphinx.ext.githubpages', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The master toctree document. master_doc = 'index' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. language = None # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path . exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # # html_theme_options = {} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] # Custom sidebar templates, must be a dictionary that maps document names # to template names. # # The default sidebars (for documents that don't match any pattern) are # defined by theme itself. Builtin themes are using these templates by # default: ``['localtoc.html', 'relations.html', 'sourcelink.html', # 'searchbox.html']``. # # html_sidebars = {} # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. htmlhelp_basename = 'RuleEnginedoc' # -- Options for LaTeX output ------------------------------------------------ latex_elements = { # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', # Additional stuff for the LaTeX preamble. # # 'preamble': '', # Latex figure (float) alignment # # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'RuleEngine.tex', 'Rule Engine Documentation', 'Spencer McIntyre', 'manual'), ] # -- Options for manual page output ------------------------------------------ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ (master_doc, 'ruleengine', 'Rule Engine Documentation', [author], 1) ] # -- Options for Texinfo output ---------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'RuleEngine', 'Rule Engine Documentation', author, 'RuleEngine', 'One line description of project.', 'Miscellaneous'), ] # -- Extension configuration ------------------------------------------------- extlinks = { 'issue': ("https://github.com/{0}/issues/%s".format(GITHUB_REPO), '#%s'), 'release': ("https://github.com/{0}/releases/tag/v%s".format(GITHUB_REPO), 'v%s'), 'wiki': ("https://github.com/{0}/wiki/%s".format(GITHUB_REPO), '%s'), } intersphinx_mapping = { 'dateutil': ('https://dateutil.readthedocs.io/en/stable/', None), 'python': ("https://docs.python.org/{version.major}.{version.minor}".format(version=sys.version_info), None) } def setup(app): app.add_css_file('theme_overrides.css') def linkcode_resolve(domain, info): if domain != 'py': return None if not info['module']: return None file_name = info['module'].replace('.', '/') + '.py' return "https://github.com/{0}/blob/{1}/{2}".format(GITHUB_REPO, GITHUB_BRANCH, file_name) rule-engine-4.1.0/docs/source/debug_repl.rst000066400000000000000000000031121446303237000210170ustar00rootroot00000000000000.. _debug-repl: Debug REPL ========== Since version :release:`2.4.0`, the Rule Engine package includes a module which provides a Read Eval Print Loop (REPL) for debugging and testing purposes. This module can be executed using ``python -m rule_engine.debug_repl``. Once started, the REPL loop can be used to evaluate rule expressions and view the results. CLI Arguments ------------- The module when executed from the command line has the following options available. .. program:: debug_repl .. option:: --edit-console Start an interactive Python console that allows the user to setup the environment for the rule evaluation. .. option:: --edit-file Run the specified file containing Python source code, allowing it to setup the environment for the rule evaluation. Configuration ------------- When configured through either the ``--edit-console`` or ``--edit-file`` options, the ``context`` symbol may be customized using a user-defined :py:class:`~rule_engine.engine.Context` instance. Additionally, the object to evaluate can be configured through the ``thing`` symbol. Example Usage ------------- The following example demonstrates using the Debug REPL with a *thing* (in this case a comic book) defined through the interactive console. .. code-block:: text python -m rule_engine.debug_repl --edit-console edit the 'context' and 'thing' objects as necessary >>> thing = dict(title='Batman', publisher='DC', issue=1) >>> exit() exiting the edit console... rule > title == 'Superman' result: False rule > issue < 5 result: True rule > rule-engine-4.1.0/docs/source/getting_started.rst000066400000000000000000000453601446303237000221110ustar00rootroot00000000000000.. py:currentmodule:: rule_engine Getting Started =============== The Rule Engine is meant to allow developers to filter arbitrary Python objects with a "rule" specified either by them or by an end user. The "rules" that the Rule Engine uses are Python string expressions in a custom language. The syntax that Rule Engine uses is similar to Python but borrows some features from Ruby. The rules are a custom language and no Python ``exec`` or ``eval`` operations are used, allowing developers to safely and securely evaluate rule expressions provided by potentially untrusted sources. Basic Usage ----------- #. The developer needs to identify data that they would like to be filtered. This would be some kind of object with a set of variable attributes. The rest of the usage example will assume that these objects are comic books. * Comic books have various attributes that could be useful for filtering including: +-----------+-----------------------+-----------------------------------+ | Attribute | Python Type | Rule Engine Type | +-----------+-----------------------+-----------------------------------+ | title | ``str`` | :py:attr:`~.DataType.STRING` | +-----------+-----------------------+-----------------------------------+ | publisher | ``str`` | :py:attr:`~.DataType.STRING` | +-----------+-----------------------+-----------------------------------+ | issue | ``int`` | :py:attr:`~.DataType.FLOAT` | +-----------+-----------------------+-----------------------------------+ | released | ``datetime.date`` | :py:attr:`~.DataType.DATETIME` | +-----------+-----------------------+-----------------------------------+ * An example comic book collection might look like: .. code-block:: python comics = [ { 'title': 'Batman', 'publisher': 'DC', 'issue': 89, 'released': datetime.date(2020, 4, 28) }, { 'title': 'Flash', 'publisher': 'DC', 'issue': 753, 'released': datetime.date(2020, 5, 5) }, { 'title': 'Captain Marvel', 'publisher': 'Marvel', 'issue': 18, 'released': datetime.date(2020, 5, 6) } ] #. Now the developer needs to create a rule object to match the target objects. The attributes of the objects will automatically become valid symbols for the rule expression. Creating a rule object is done by initializing an instance of the :py:class:`~engine.Rule` class which requires one argument, and that is the string expression (in Rule Engine syntax) of the rule. * In the case of the comic book collection, these symbols would be: ``title``, ``publisher``, ``issue``, and ``released``. Notice that these attribute names are also valid symbol names, i.e. they start with a letter and contain no whitespace or punctuation. Just like in Python, Rule Engine symbols must follow these rules. For example, ``released`` is a valid symbol while ``Released Date`` is not (because of the space). * A simple rule for the comic book collection which matches the ``publisher`` symbol to the string ``"DC"`` might look like: .. code-block:: python rule = rule_engine.Rule( # match books published by DC 'publisher == "DC"' ) * Rules can contain more complex expressions such as datetime literals and conditionals. .. code-block:: python rule = rule_engine.Rule( # match DC books released in May 2020 'released >= d"2020-05-01" and released < d"2020-06-01" and publisher == "DC"' ) Notice that the datetime expression is a string, prefixed with ``d`` in ``YYYY-MM-DD HH:mm:SS`` format. If the time portion is omitted, it will be normalized to ``00:00:00`` (midnight, zero minutes, zero seconds). See the :ref:`Literal Values` section for more information. * Certain datatypes also have :ref:`attributes` that can be accessed with the dot (``.``) operator. .. code-block:: python rule = rule_engine.Rule( # normalize potential variations in the publisher case such as 'Dc' 'publisher.as_upper == "DC"' ) * Rules can also match strings using regular expressions. When using this type of comparison, the string on the right hand side of the operator is the regular expression, while the left is the string to compare it with. .. code-block:: python rule = rule_engine.Rule( # match books with a title starting with 'Captain ' 'title =~ "Captain\s\S+"' ) #. Once the rule object has been defined, it can be applied to target object(s). Two primary methods are available for applying the rule to the target objects. Those methods are: * :py:meth:`~engine.Rule.matches` -- This method will determine whether the rule matches a single target object, returning ``True`` or ``False``. * :py:meth:`~engine.Rule.filter` -- This method will filter an iterable of target objects, yielding ones for which the rule matches. * Applying the rule to the comic book collection using each of the two methods might look like: .. code-block:: python # check if the first object matches rule.matches(comics[0]) # => True # filter the iterable "comics" and return matching objects rule.filter(comics) # => Attribute-Backed Objects ^^^^^^^^^^^^^^^^^^^^^^^^ In the previous example, the target objects were Python dictionaries. The keys in the dictionary were used as symbols and while this is the default behavior it can be modified to use object attributes instead. This would be necessary if the target objects had variable attributes (like a Python class object) instead of variable items (like a Python dictionary object). * An example comic book collection using an object-based attribute-backed data structure might look like: .. code-block:: python class Comic(object): def __init__(self, title, publisher, issue, released) self.title = title self.publisher = publisher self.issue = issue self.released = released comics = [ Comic('Batman', 'DC', 89, datetime.date(2020, 4, 28)), Comic('Flash', 'DC', 753, datetime.date(2020, 4, 28)), Comic('Captain Marvel', 'Marvel', 18, datetime.date(2020, 5, 6)) ] To resolve symbols from attributes, a custom :py:class:`~engine.Context` object needs to be defined. This object is used for configuration of Rule behavior, one setting of which is the resolver to use. The resolver defines how a rule looks up symbols to their values for comparison given a target object. The following resolver functions are included in Rule Engine: * :py:func:`~engine.resolve_attribute` -- Resolve symbols by looking them up as attributes on an object. * :py:func:`~engine.resolve_item` -- **(Default)** Resolve symbols by looking them up as keys on a dictionary (or dictionary-like) object. To change the resolver, create a :py:class:`~engine.Context` object, and specify the *resolver* function as a keyword argument. .. code-block:: python # define the custom context to set the resolver context = rule_engine.Context(resolver=rule_engine.resolve_attribute) # then define a rule using the custom context rule = rule_engine.Rule('publisher == "DC"', context=context) Once the rule has been defined with the custom context, it can be used in the same way as a rule with a default context. The context object can be shared with other rule objects that are to be applied on the same objects. The context object should not be shared with rule object that are applied to other objects which do not have the same attributes (like artists). Advanced Usage -------------- The Rule Engine has a number of advanced features that contribute to its flexibility. In most use cases they are unnecessary. Setting A Default Value ^^^^^^^^^^^^^^^^^^^^^^^ By default, :py:class:`engine.Rule` will raise a :py:class:`~errors.SymbolResolutionError` for invalid symbols. In some cases, it may be desirable to change the way in which the language behaves to instead treat unknown symbols with a default value (most often ``None`` / :py:attr:`~.DataType.NULL` is used for this purpose, but any value of a supported type can be used). To change this behavior, set the *default_value* parameter when initializing the :py:class:`~engine.Context` instance. .. code-block:: python # this fails because title is not defined and there is no default_value rule_engine.Rule('title').matches({}) # => SymbolResolutionError: title context = rule_engine.Context(default_value=None) # this evaluates successfully to False because title is null (from the default value) rule_engine.Rule('title', context=context).matches({}) # => False # this evaluates successfully to True because title is a non-empty string rule_engine.Rule('title', context=context).matches({'title': 'Batman'}) # => True Custom Resolvers ^^^^^^^^^^^^^^^^ Rule Engine includes resolvers for accessing attributes :py:func:`as keys` on objects (such as dictionaries) and one for resolving symbols :py:func:`as attributes` on objects. If for some reason, neither of those are suitable for the target object then a custom one can be defined and used. The custom resolver should use the signature ``resolver(thing, name)`` where *thing* is the arbitrary object that the rule is being applied to and *name* is the symbol name as a Python string of the attribute that is to be accessed. If the resolver function fails for any reason, it should raise a :py:class:`~errors.SymbolResolutionError`, forwarding *thing* in a keyword argument. This ensures consistency in how exceptions are raised and handled by the engine. Suggestions """"""""""" When raising a :py:class:`~errors.SymbolResolutionError`, a custom resolver can optionally make a suggestion for a valid symbol name. In this case, the resolver may use the :py:class:`~suggestions.suggest_symbol` function, passing it the invalid name and a list of valid names. The result may then be passed as the *suggestion* keyword. This suggestion may then assist rule authors in correcting mistakes. Type Hinting ^^^^^^^^^^^^ Symbol type information can be provided to the :py:class:`~engine.Rule` through the :py:class:`~engine.Context` instance and will be used for compatibility testing. With type information, the engine will raise an :py:class:`~errors.EvaluationError` when an incompatible operation is detected such as a regex match (``=~``) using an integer on either side. This makes it possible to detect errors in a rule's syntax prior to it being applied to an object. When symbol type information is specified, the value resolved from a symbol and object must either match the specified type or be :py:attr:`~ast.NULL`, otherwise a :py:class:`~errors.SymbolTypeError` will be raised when the symbol is resolved. To define type information, a *type_resolver* function must be passed to the :py:class:`~engine.Context` class. The type resolver function is expected to take a single argument, and that is the name of the symbol (as a Python string) whose type needs to be resolved. The return type should be a member of the :py:class:`~ast.DataType` enumeration. .. code-block:: python # define a basic type resolver, that knows about the four attributes of a # comic book def type_resolver(name): if name == 'title': return rule_engine.DataType.STRING elif name == 'publisher': return rule_engine.DataType.STRING elif name == 'issue': return rule_engine.DataType.FLOAT elif name == 'released': return rule_engine.DataType.DATETIME # if the name is none of those, raise a SymbolResolutionError raise rule_engine.errors.SymbolResolutionError(name) context = rule_engine.Context(type_resolver=type_resolver) :py:attr:`~.DataType.UNDEFINED` can be defined as the data type for a valid symbol without specifying explicit type information. In this case, the rule object will know that it is a valid symbol, but will not validate any operations that reference it. In all cases, when a *type_resolver* is defined, the :py:class:`~engine.Rule` object will raise a :py:class:`~errors.SymbolResolutionError` if a symbol is referenced in the rule that is not known to the *type_resolver*. .. code-block:: python # this is valid: issue is defined as a valid symbol rule = rule_engine.Rule('issue == 1', context=context) # => # this is invalid: author is not defined as a valid symbol rule = rule_engine.Rule('author == "Stan Lee"', context=context) # => SymbolResolutionError: author # this is valid: no type information is defined (context is omitted) rule = rule_engine.Rule('author == "Stan Lee"') # => .. _getting-started-compound-data-types: Compound Data Types """"""""""""""""""" Compound data types such as the :py:attr:`~.DataType.ARRAY` and :py:attr:`~.DataType.MAPPING` types can optionally specify member type information by calling their respective type. For example, an array of strings would be defined as ``DataType.ARRAY(DataType.STRING)`` while a mapping with string keys and float values would be defined as ``DataType.MAPPING(DataType.STRING, DataType.FLOAT)``. For more information, see the documentation for the :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.MAPPING` functions. Compound member types can only be a single data type. In some cases the data type can optionally be nullable which means that the member value can be either the specified type or :py:attr:`~.DataType.NULL`. For example, a :py:attr:`~.DataType.MAPPING` type whose values are all nullable strings may be defined, while a :py:attr:`~.DataType.MAPPING` type with one value type of a :py:attr:`~.DataType.STRING` and another of a :py:attr:`~.DataType.BOOLEAN` may not be defined. In this case, the key type may be defined while the value type is set to :py:attr:`~.DataType.UNDEFINED` which is the default value. Function Data Types """"""""""""""""""" Like compound types, functions can include type information by calling the respective type, in this case :py:attr:`~.DataType.FUNCTION`. Functions only support positional arguments and not keyword arguments but positional arguments can be defined as optional through the *minimum_arguments* option. For example, the :ref:`builtin split` can be called with as few as 1 arguments and as many as 3 arguments. The first argument is always required, so *minimum_arguments* is set to 1. This means the remaining 2 arguments are optional, however for the third argument to be defined in a function call, the second must also be defined. For the split function, the first argument is the string to split, followed by the seperator string to split on and finally the maximum number of times to split the string. .. code-block:: python rule_engine.DataType.FUNCTION( # the name of the function is provided for error messages 'split', # the return data type, in this case an array of strings return_type=ast.DataType.ARRAY(ast.DataType.STRING), # the data type of each of the three arguments argument_types=( ast.DataType.STRING, # argument 1, the string to split ast.DataType.STRING, # argument 2, the seperator to split on ast.DataType.FLOAT # argument 3, the maximum times to split the string ), # the minimum number of arguments, in this case the second two arguments are optional minimum_arguments=1 ) If the return type, or argument types are not specified, then no type checking is preformed. Defining Types From A Dictionary """""""""""""""""""""""""""""""" For convenience, the :py:func:`~engine.type_resolver_from_dict` function can be used to generate a *type_resolver* function from a dictionary mapping symbol names to their respective :py:class:`~ast.DataType`. Starting with version :release:`2.1.0` if a :py:class:`dict` is passed as the *type_resolver*, the :py:func:`~engine.type_resolver_from_dict` function will be used automatically. .. code-block:: python context = rule_engine.Context( type_resolver=rule_engine.type_resolver_from_dict({ # map symbol names to their data types 'title': rule_engine.DataType.STRING, 'publisher': rule_engine.DataType.STRING, 'issue': rule_engine.DataType.FLOAT, 'released': rule_engine.DataType.DATETIME }) ) Changing Builtin Symbols ^^^^^^^^^^^^^^^^^^^^^^^^ To remove the default :ref:`builtin symbols` that are provided, simply initialize a :py:class:`~rule_engine.builtins.Builtins` instance with a *values* of an empty dictionary. This will remove all builtin values, and the dictionary can optionally be populated with alternative values. To add additional values, use the :py:class:`~rule_engine.builtins.Builtins.from_defaults` constructor, with a *values* dictionary. In this case, *values* will optionally override any of the default settings, and keys which do not overlap will be added in addition to the default builtin symbols. .. code-block:: python class CustomBuiltinsContext(rule_engine.Context): def __init__(self, *args, **kwargs): # call the parent class's __init__ method first to set the # default_timezone attribute super(CustomBuiltinsContext, self).__init__(*args, **kwargs) self.builtins = rule_engine.engine.Builtins.from_defaults( # expose the $version symbol {'version': rule_engine.__version__}, # use the specified default timezone timezone=self.default_timezone ) Rule Inspection --------------- There are a few techniques that can be used to inspect a rule object. * :py:meth:`~engine.Rule.is_valid` -- This class method can be used to determine if a rule expression is valid. It will return ``False`` if for example there are any syntax errors. * :py:attr:`~engine.Context.symbols` -- Rule objects have a :py:attr:`~engine.Rule.context` attribute, which contains the ``symbols`` attribute. This contains the symbol names which were identified within the rule expression. * :py:meth:`~engine.Rule.to_graphviz` -- This method will create a Graphviz directed-graph of the Rule Engine Abstract Syntax Tree (AST) created by the rule expression. This can be helpful when debugging complex rules. This requires the Python ``graphviz`` package to be available. rule-engine-4.1.0/docs/source/index.rst000066400000000000000000000030131446303237000200160ustar00rootroot00000000000000Rule Engine Documentation ========================= This project provides a library for creating general purpose "Rule" objects from a logical expression which can then be applied to arbitrary objects to evaluate whether or not they match. Documentation is available at https://zeroSteiner.github.io/rule-engine/. Rule Engine expressions are written in their own language, defined as strings in Python. Some features of this language includes: * Optional type hinting * Matching strings with regular expressions * Datetime datatypes * Data attributes Usage Example ------------- .. code-block:: python import rule_engine # match a literal first name and applying a regex to the email rule = rule_engine.Rule( 'first_name == "Luke" and email =~ ".*@rebels.org$"' ) # => rule.matches({ 'first_name': 'Luke', 'last_name': 'Skywalker', 'email': 'luke@rebels.org' }) # => True rule.matches({ 'first_name': 'Darth', 'last_name': 'Vader', 'email': 'dvader@empire.net' }) # => False See the `examples`_ folder for more. .. toctree:: :maxdepth: 2 :caption: Contents: getting_started.rst syntax.rst types.rst attributes.rst rule_engine/index.rst debug_repl.rst change_log.rst Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` .. _examples: https://github.com/zeroSteiner/rule-engine/tree/master/examples .. _GitHub homepage: https://github.com/zeroSteiner/rule-engine rule-engine-4.1.0/docs/source/rule_engine/000077500000000000000000000000001446303237000204545ustar00rootroot00000000000000rule-engine-4.1.0/docs/source/rule_engine/ast.rst000066400000000000000000000110051446303237000217720ustar00rootroot00000000000000:mod:`ast` ========== .. module:: rule_engine.ast :synopsis: This module contains the nodes which comprise the abstract syntax tree generated from parsed grammar text. .. warning:: The content of this module should be treated as private. While the code within this module is documented, it is *not* meant to be used by consumers of the package. Directly accessing and using any object or function within this module should be done with care. Breaking API changes within this module may not always cause a major version bump. The reason for this is that it is often necessary to update the AST in an API breaking way in order to add new features. Classes ------- .. autoclass:: Assignment :members: :show-inheritance: :special-members: __init__ :undoc-members: .. autoclass:: Statement :show-inheritance: Base Classes ~~~~~~~~~~~~ .. autoclass:: ExpressionBase :members: :exclude-members: result_type :show-inheritance: :special-members: __init__ .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: LeftOperatorRightExpressionBase :show-inheritance: .. autoattribute:: compatible_types :annotation: .. automethod:: __init__ .. autoclass:: LiteralExpressionBase :show-inheritance: .. automethod:: __init__ Left-Operator-Right Expressions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. autoclass:: AddExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: SubtractExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: ArithmeticExpression :show-inheritance: .. autoattribute:: result_type :annotation: = FLOAT .. autoclass:: ArithmeticComparisonExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN .. autoclass:: BitwiseExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: BitwiseShiftExpression :show-inheritance: .. autoattribute:: result_type :annotation: = FLOAT .. autoclass:: ComparisonExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN .. autoclass:: LogicExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN .. autoclass:: FuzzyComparisonExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN Literal Expressions ~~~~~~~~~~~~~~~~~~~ .. autoclass:: ArrayExpression :show-inheritance: .. autoattribute:: result_type :annotation: = ARRAY .. autoclass:: BooleanExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN .. autoclass:: DatetimeExpression :show-inheritance: .. autoattribute:: result_type :annotation: = DATETIME .. autoclass:: FloatExpression :show-inheritance: .. autoattribute:: result_type :annotation: = FLOAT .. autoclass:: MappingExpression :show-inheritance: .. autoattribute:: result_type :annotation: = MAPPING .. autoclass:: NullExpression :show-inheritance: .. autoattribute:: result_type :annotation: = NULL .. autoclass:: SetExpression :show-inheritance: .. autoattribute:: result_type :annotation: = SET .. autoclass:: StringExpression :show-inheritance: .. autoattribute:: result_type :annotation: = STRING .. autoclass:: TimedeltaExpression :show-inheritance: .. autoattribute:: result_type :annotation: = TIMEDELTA Miscellaneous Expressions ~~~~~~~~~~~~~~~~~~~~~~~~~ .. autoclass:: ComprehensionExpression :show-inheritance: .. autoattribute:: result_type :annotation: = ARRAY .. autoclass:: ContainsExpression :show-inheritance: .. autoattribute:: result_type :annotation: = BOOLEAN .. autoclass:: GetAttributeExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: GetItemExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: GetSliceExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: SymbolExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: TernaryExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED .. autoclass:: UnaryExpression :show-inheritance: .. autoattribute:: result_type :annotation: = UNDEFINED rule-engine-4.1.0/docs/source/rule_engine/builtins.rst000066400000000000000000000004161446303237000230400ustar00rootroot00000000000000:mod:`builtins` =============== .. module:: rule_engine.builtins :synopsis: This module contains the class which defines the builtin values for the engine. .. autoclass:: Builtins :members: :show-inheritance: :special-members: __init__ :undoc-members: rule-engine-4.1.0/docs/source/rule_engine/engine.rst000066400000000000000000000007761446303237000224650ustar00rootroot00000000000000:mod:`engine` ============= .. module:: rule_engine.engine :synopsis: This module contains the primary externally facing API for the package. Functions --------- .. autofunction:: resolve_attribute .. autofunction:: resolve_item .. autofunction:: type_resolver_from_dict Classes ------- .. autoclass:: Context :members: :show-inheritance: :special-members: __init__ :undoc-members: .. autoclass:: Rule :members: :show-inheritance: :special-members: __init__ :undoc-members: rule-engine-4.1.0/docs/source/rule_engine/errors.rst000066400000000000000000000041431446303237000225240ustar00rootroot00000000000000:mod:`errors` ============= .. module:: rule_engine.errors :synopsis: This module contains the exceptions raised by the package. Data ---- .. autodata:: UNDEFINED Exceptions ---------- .. autoexception:: AttributeResolutionError :members: :show-inheritance: :special-members: __init__ .. autoexception:: AttributeTypeError :members: :show-inheritance: :special-members: __init__ .. autoexception:: DatetimeSyntaxError :members: :show-inheritance: :special-members: __init__ .. autoexception:: FloatSyntaxError :members: :show-inheritance: :special-members: __init__ .. autoexception:: EngineError :members: :show-inheritance: :special-members: __init__ .. autoexception:: EvaluationError :members: :show-inheritance: :special-members: __init__ .. autoexception:: FunctionCallError :members: :show-inheritance: :special-members: __init__ .. autoexception:: LookupError :members: :show-inheritance: :special-members: __init__ .. autoexception:: RegexSyntaxError :members: :show-inheritance: :special-members: __init__ .. autoexception:: RuleSyntaxError :members: :show-inheritance: :special-members: __init__ .. autoexception:: SymbolResolutionError :members: :show-inheritance: :special-members: __init__ .. autoexception:: SymbolTypeError :members: :show-inheritance: :special-members: __init__ .. autoexception:: SyntaxError :members: :show-inheritance: :special-members: __init__ .. autoexception:: TimedeltaSyntaxError :members: :show-inheritance: :special-members: __init__ Exception Hierarchy ------------------- The class hierarchy for Rule Engine exceptions is: .. code-block:: text EngineError +-- EvaluationError +-- AttributeResolutionError +-- AttributeTypeError +-- FunctionCallError +-- LookupError +-- SymbolResolutionError +-- SymbolTypeError +-- SyntaxError +-- DatetimeSyntaxError +-- FloatSyntaxError +-- RegexSyntaxError +-- RuleSyntaxError +-- TimedeltaSyntaxError rule-engine-4.1.0/docs/source/rule_engine/index.rst000066400000000000000000000002721446303237000223160ustar00rootroot00000000000000:mod:`rule_engine` ================== .. toctree:: :maxdepth: 2 :titlesonly: ast.rst builtins.rst engine.rst errors.rst parser.rst suggestions.rst types.rst rule-engine-4.1.0/docs/source/rule_engine/parser.rst000066400000000000000000000006421446303237000225040ustar00rootroot00000000000000:mod:`parser` ============= .. module:: rule_engine.parser :synopsis: This module contains the parsing logic for taking rule text in the specified grammar and converting it to an abstract syntax tree that can later be evaluated. Classes ------- .. autoclass:: Parser :show-inheritance: :special-members: __init__ .. autoclass:: ParserBase :members: :show-inheritance: :special-members: __init__ rule-engine-4.1.0/docs/source/rule_engine/suggestions.rst000066400000000000000000000004011446303237000235530ustar00rootroot00000000000000:mod:`suggestions` ================== .. module:: rule_engine.suggestions :synopsis: .. versionadded:: 3.2.0 This module contains the helper functions needed to make suggestions when errors occur. Functions --------- .. autofunction:: suggest_symbolrule-engine-4.1.0/docs/source/rule_engine/types.rst000066400000000000000000000017311446303237000223540ustar00rootroot00000000000000:mod:`types` ============ .. module:: rule_engine.types :synopsis: .. versionadded:: 3.2.0 This module contains the internal type definitions and utility functions for working with them. Functions --------- .. autofunction:: coerce_value .. autofunction:: is_integer_number .. autofunction:: is_natural_number .. autofunction:: is_numeric .. autofunction:: is_real_number .. autofunction:: iterable_member_value_type Classes ------- .. autoclass:: DataType :members: :exclude-members: ARRAY, MAPPING, SET :show-inheritance: .. automethod:: ARRAY .. autoattribute:: BOOLEAN :annotation: .. autoattribute:: DATETIME :annotation: .. autoattribute:: FLOAT :annotation: .. automethod:: FUNCTION .. automethod:: MAPPING .. autoattribute:: NULL :annotation: .. automethod:: SET .. autoattribute:: STRING :annotation: .. autoattribute:: TIMEDELTA :annotation: .. autoattribute:: UNDEFINED rule-engine-4.1.0/docs/source/syntax.rst000066400000000000000000000761741446303237000202570ustar00rootroot00000000000000.. py:currentmodule:: rule_engine Rule Syntax =========== The syntax for creating rules is based off of logical expressions evaluating to either True (matching) or False (non- matching). Rules support a small set of data types which can be defined as literals or resolved using the Python object on which the rule is being applied. See the :ref:`Data Types` table for a comprehensive list of the supported types. Not all supported operations work with all data types as noted in the table below. Rules follow a standard `order of operations`_. Grammar ------- The expression grammar supports a number of operations including basic arithmetic for numerical data and regular expressions for strings. Operations are type aware and will raise an exception when an incompatible type is used. .. _data-type-operations: Supported Operations ^^^^^^^^^^^^^^^^^^^^ The following table outlines all operators that can be used in Rule Engine expressions. +--------------+------------------------------+-----------------------------------------------------------------+ | Operation | Description | Compatible Data Types | +--------------+------------------------------+-----------------------------------------------------------------+ | **Arithmetic Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``+`` | Addition | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.STRING` | | | | :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.TIMEDELTA` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``-`` | Subtraction | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.DATETIME`, | | | | :py:attr:`~.DataType.TIMEDELTA` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``*`` | Multiplication | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``**`` | Exponent | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``/`` | True division | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``//`` | Floor division | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``%`` | Modulo | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | **Bitwise-Arithmetic Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``&`` | Bitwise-and :sup:`1` | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.SET` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``|`` | Bitwise-or :sup:`1` | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.SET` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``^`` | Bitwise-xor :sup:`1` | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.SET` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``>>`` | Bitwise right shift :sup:`1` | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``<<`` | Bitwise left shift :sup:`1` | :py:attr:`~.DataType.FLOAT` | +--------------+------------------------------+-----------------------------------------------------------------+ | **Comparison Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``==`` | Equal to | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | ``!=`` | Not equal to | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | **Arithmetic-Comparison Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``>`` | Greater than | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.BOOLEAN`, | | | | :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.TIMEDELTA`,| | | | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.NULL`, | | | | :py:attr:`~.DataType.STRING` | | | | :sup:`2` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``>=`` | Greater than or equal to | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.BOOLEAN`, | | | | :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.TIMEDELTA`,| | | | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.NULL`, | | | | :py:attr:`~.DataType.STRING` | | | | :sup:`2` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``<`` | Less than | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.BOOLEAN`, | | | | :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.TIMEDELTA`,| | | | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.NULL`, | | | | :py:attr:`~.DataType.STRING` | | | | :sup:`2` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``<=`` | Less than or equal to | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.BOOLEAN`, | | | | :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.TIMEDELTA`,| | | | :py:attr:`~.DataType.FLOAT`, :py:attr:`~.DataType.NULL`, | | | | :py:attr:`~.DataType.STRING` | | | | :sup:`2` | +--------------+------------------------------+-----------------------------------------------------------------+ | **Fuzzy-Comparison Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``=~`` | Regex match :sup:`3` | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``=~~`` | Regex search :sup:`3` | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``!~`` | Regex match fails :sup:`3` | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``!~~`` | Regex search fails :sup:`3` | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | **Logical Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``and`` | Logical and | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | ``not`` | Logical not | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | ``or`` | Logical or | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | ``?``, ``:`` | Ternary Operator | *ANY* | +--------------+------------------------------+-----------------------------------------------------------------+ | **Accessor Operators** | +--------------+------------------------------+-----------------------------------------------------------------+ | ``.`` | Attribute access | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.DATETIME`, | | | | :py:attr:`~.DataType.TIMEDELTA`, :py:attr:`~.DataType.MAPPING`, | | | | :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``&.`` | Safe attribute access | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.DATETIME`, | | | | :py:attr:`~.DataType.TIMEDELTA`, :py:attr:`~.DataType.MAPPING`, | | | | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``[`` | Item lookup | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.MAPPING`, | | | | :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ | ``&[`` | Safe item lookup | :py:attr:`~.DataType.ARRAY`, :py:attr:`~.DataType.MAPPING`, | | | | :py:attr:`~.DataType.NULL`, :py:attr:`~.DataType.STRING` | +--------------+------------------------------+-----------------------------------------------------------------+ :sup:`1` Bitwise operations support floating point values, but if the value is not a natural number, an :py:class:`~rule_engine.errors.EvaluationError` will be raised. :sup:`2` The arithmetic comparison operators support multiple data types however the data type of the left value must be the same as the data type of the right. For example, a :py:attr:`~.DataType.STRING` can be compared to another :py:attr:`~.DataType.STRING` but not a :py:attr:`~.DataType.FLOAT`. The technique is the same lexicographical ordering based sequence comparison `technique used by Python`_. :sup:`3` When using regular expression operations, the expression on the left is the string to compare and the expression on the right is the regular expression to use for either the match or search operation. Accessor Operators """""""""""""""""" Some data types support accessor operators to obtain sub-values and attributes. One example is the :py:attr:`~.DataType.STRING` which supports both attribute and item lookup operations. For example, "length" is a valid attribute and can be accessed by appending ``.length`` to either a string literal or symbol. Alternatively, a specific character in a string of characters can be accessed by index. For example, the first character in a string can be referenced by appending ``[0]`` to either the string literal or symbol. Attempts to lookup either an invalid attribute or item will raise a :py:class:`~rule_engine.errors.LookupError`. Both attribute and item lookups have "safe" variants which utilize the ``&`` operator prefix (not to be confused with the bit-wise and operator which leverages the same symbol). The safe operator version will evaluate to :py:attr:`~.DataType.NULL` instead of raising an exception when the container value on which the operation is applied is :py:attr:`~.DataType.NULL`. Additionally, the safe version of item lookup operations will evaluate to :py:attr:`~.DataType.NULL` instead of raising a :py:class:`~rule_engine.errors.LookupError` exception when the item is not held within the container. This is analogous the Python's :py:meth:`dict.get` method. The item lookup operation can also evaluate to an array when a stop boundary is provided. For example to reference the first four elements of a string by appending ``[0:4]`` to the end of the value. Alternatively, only the ending index may be specified using ``[:4]``. Finally, just as in Python, negative values can be used to reference the last elements. Array Comprehension """"""""""""""""""" An operation may be able to be applied to each member of an iterable value to generate a new :py:attr:`~.DataType.ARRAY` composed of the resulting expressions. This could for example be used to determine how many values within an array match an arbitrary condition. The syntax is very similar to the list comprehension within Python and is composed of three mandatory components with an optional condition expression. The three required components in order from left to right are the result expression, the variable assignment and the iterable (followed by the optional condition). Each component uses a reserved keyword as a delimiter and the entire expression is wrapped within brackets just like an array literal. For example, to square an array of numbers: ``[ v ** 2 for v in [1, 2, 3] ]``. In this case, the resulting expression is the square operation (``v ** 2``) which uses the variable ``v`` defined in the assignment. Finally, the operation is applied to the array literal ``[1, 2, 3]``, which could have been any iterable value. An optional condition may be applied to the value before the resulting expression is evaluated using the ``if`` keyword. Building on the previous example, if only the squares of each odd number was needed, the expression could be updated to: ``[ v ** 2 for v in [1, 2, 3] if v % 2]``. This example uses the modulo operator to filter out even values. One limitation to the array comprehension syntax when compared to Python's list comprehension is that the variable assignment may not contain more than one value. There is currently no support for unpacking multiple values like Python does, (e.g. ``[ v for k,v in my_dict.items() if test(k) ]``. Ternary Operators """"""""""""""""" The ternary operator can be used in place of a traditional "if-then-else" statement. Like other languages the question mark and colon are used as the expression delimiters. A ternary expression is a combination of a condition followed by an expression used when the condition is true and ending with an expression used when the condition is false. For example: ``condition ? true_case : false_case`` Function Calls ^^^^^^^^^^^^^^ Function calls can be preformed on function symbols by placing parenthesis after them. The parenthesis contain zero or more argument expressions to pass to the function. Functions support optional positional arguments. For example, a function can take two arguments and one or both can specify a default value and then be omitted when called. Functions do not support keyword arguments. Using the :ref:`builtin split` function as an example, it can be called with up to 3 arguments. The first is required while the second two are optional. The ``split`` symbol requires the ``$`` prefix to access the builtin value. .. code-block:: # only the required argument performs an unlimited number of splits on spaces $split("Star Wars") # => ("Star", "Wars") # the optional second argument specifies an alternative string to split on $split("Star Wars", "r") # => ('Sta', ' Wa', 's') # the optional third argument specifies the maximum number of times to split the string $split("Star Wars", "r", 1) # => ('Sta', ' Wars') # raises FunctionCallError because the second argument must be a string, the third argument # can not be specified without the second $split("Star Wars", 1) # => FunctionCallError: data type mismatch (argument #2) $split("Star Wars", ' ', 1) # => ("Star", "Wars") Reserved Keywords ^^^^^^^^^^^^^^^^^ The following keywords are reserved and can not be used as the names of symbols. +-----------+-----------------------------------------------------------------+ | Keyword | Description | +-----------+-----------------------------------------------------------------+ | ``null`` | The :py:class:`~ast.NullExpression` literal value | +-----------+-----------------------------------------------------------------+ | **Array Comprehension** | +-----------+-----------------------------------------------------------------+ | ``for`` | Array comprehension result and assignment delimiter | +-----------+-----------------------------------------------------------------+ | ``if`` | Array comprehension iterable and (optional) condition delimiter | +-----------+-----------------------------------------------------------------+ | **Booleans** (:py:class:`~ast.BooleanExpression` Literals) | +-----------+-----------------------------------------------------------------+ | ``true`` | The "True" boolean value | +-----------+-----------------------------------------------------------------+ | ``false`` | The "False" boolean value | +-----------+-----------------------------------------------------------------+ | **Floats** (:py:class:`~ast.FloatExpression` Literals) | +-----------+-----------------------------------------------------------------+ | ``inf`` | Floating point value for infinity | +-----------+-----------------------------------------------------------------+ | ``nan`` | Floating point value for not-a-number | +-----------+-----------------------------------------------------------------+ | **Logical Operators** | +-----------+-----------------------------------------------------------------+ | ``and`` | Logical "and" operator | +-----------+-----------------------------------------------------------------+ | ``not`` | Logical "not" operator | +-----------+-----------------------------------------------------------------+ | ``or`` | Logical "or" operator | +-----------+-----------------------------------------------------------------+ | **Membership Operators** | +-----------+-----------------------------------------------------------------+ | ``in`` | Checks member is in the container | +-----------+-----------------------------------------------------------------+ | **Reserved For Future Use** | +-----------+-----------------------------------------------------------------+ | ``elif`` | Reserved for future use | +-----------+-----------------------------------------------------------------+ | ``else`` | Reserved for future use | +-----------+-----------------------------------------------------------------+ | ``while`` | Reserved for future use | +-----------+-----------------------------------------------------------------+ .. _literal-values: Literal Values ^^^^^^^^^^^^^^ :py:attr:`~.DataType.DATETIME`, :py:attr:`~.DataType.STRING`, and :py:attr:`TIMEDELTA` literal values are specified in a very similar manner by defining the value as a string of characters enclosed in either single or double quotes. The difference comes in an optional leading character before the opening quote. Either no leading character or a single ``s`` will specify a standard :py:attr:`~.DataType.STRING` value, while a single ``d`` will specify a :py:attr:`~.DataType.DATETIME` value, and a single ``t`` will specify a :py:attr:`~.DataType.TIMEDELTA` value. .. _literal-datetime-values: Literal DATETIME Values """"""""""""""""""""""" :py:attr:`~.DataType.DATETIME` literals must be specified in ISO-8601 format. The underlying parsing logic is provided by :py:meth:`dateutil.parser.isoparse`. :py:attr:`~.DataType.DATETIME` values with no time specified (e.g. ``d"2019-09-23"``) will evaluate to a :py:attr:`~.DataType.DATETIME` of the specified day at exactly midnight. Example rules showing equivalent literal expressions: * ``d"2019-09-23" == d"2019-09-23 00:00:00"`` (dates default to midnight unless a time is specified) * ``d"2019-09-23" == d"2019-09-23 00:00:00-04:00"`` (**only equivalent when the local timezone is EDT**) .. _literal-float-values: Literal FLOAT Values """""""""""""""""""" :py:attr:`~.DataType.FLOAT` literals may be expressed in either binary, octal, decimal, or hexadecimal formats. The binary, octal and hexadecimal formats use the ``0b``, ``0o``, and ``0x`` prefixes respectively. Values in the decimal format require no prefix and is the default base in which values are represented. Only base-10, decimal values may include a decimal place component. Example rules showing equivalent literal expressions: * ``0b10 == 2`` * ``0o10 == 8`` * ``10.0 == 10`` * ``0x10 == 16`` :py:attr:`~.DataType.FLOAT` literals may also be expressed in scientific notation using the letter ``e``. Example rules show equivalent literal expressions: * ``1E0 == 1`` * ``1e0 == 1`` * ``1.0e0 == 1`` .. _literal-timedelta-values: Literal TIMEDELTA Values """""""""""""""""""""""" :py:attr:`~.DataType.TIMEDELTA` literals must be specified in a subset of the ISO-8601 format for durations. Everything except years and months are supported in :py:attr:`~.DataType.TIMEDELTA` values, to match the underlying representation provided by the Python standard library. Example rules showing equivalent literal expressions: * ``t"P1D" == t"PT24H"`` (24 hours in a day) * ``t"P1D" == t"PT1440M"`` (1,440 minutes in a day) Comments ^^^^^^^^ A single ``#`` symbol can be used to create a comment in the rule text. The everything after the first ``#`` occurrence will be ignored. Example rule containing a comment: ``size == 1 # this is a comment`` .. py:currentmodule:: rule_engine .. _builtin-symbols: Builtin Symbols --------------- The following symbols are provided by default using the :py:meth:`~builtins.Builtins.from_defaults` method. These symbols can be accessed through the ``$`` prefix, e.g. ``$pi``. The default values can be overridden by defining a custom subclass of :py:class:`~engine.Context` and setting the :py:attr:`~engine.Context.builtins` attribute. .. _builtin-functions: Functions ^^^^^^^^^ ``FLOAT abs(FLOAT value)`` :returns: :py:attr:`~.DataType.FLOAT` :value: (:py:attr:`~.DataType.FLOAT`) The numeric to get the absolute value of. Returns the absolute value of *value*. .. versionadded:: 4.1.0 ``BOOLEAN all(ARRAY[??] values)`` :returns: :py:attr:`~.DataType.BOOLEAN` :values: (:py:attr:`~.DataType.ARRAY` of *anything*) An array of values to check. Returns true if every member of the array argument is truthy. If *values* is empty, the function returns true. ``BOOLEAN any(ARRAY[??] values)`` :returns: :py:attr:`~.DataType.BOOLEAN` :values: (:py:attr:`~.DataType.ARRAY` of *anything*) An array of values to check. Returns true if any member of the array argument is truthy. If *values* is empty, the function returns false. ``FLOAT sum(ARRAY[FLOAT] values)`` :returns: :py:attr:`~.DataType.FLOAT` :values: (:py:attr:`~.DataType.ARRAY` of :py:attr:`~.DataType.FLOAT`) An array of values to add. Returns the sum of an array of values. If *values* is empty, the function returns 0. ``ARRAY[??] map(FUNCTION function, ARRAY[??] values)`` :returns: :py:attr:`~.DataType.ARRAY` of *anything* :function: (:py:attr:`~.DataType.FUNCTION`) The function to call on each of the values. :values: (:py:attr:`~.DataType.ARRAY` of *anything*) The array of values to apply *function* to. ``FLOAT max(ARRAY[FLOAT] values)`` :returns: :py:attr:`~.DataType.FLOAT` :values: (:py:attr:`~.DataType.ARRAY` of :py:attr:`~.DataType.FLOAT`) An array of values to check. Returns the largest value from the array of values. If *values* is empty, a :py:exc:`~.errors.FunctionCallError` is raised. ``FLOAT min(ARRAY[FLOAT] values)`` :returns: :py:attr:`~.DataType.FLOAT` :values: (:py:attr:`~.DataType.ARRAY` of :py:attr:`~.DataType.FLOAT`) An array of values to check. Returns the smallest value from the array of values. If *values* is empty, a :py:exc:`~.errors.FunctionCallError` is raised. ``ARRAY[??] filter(FUNCTION function, ARRAY[??] values)`` :returns: :py:attr:`~.DataType.ARRAY` of *anything* :function: (:py:attr:`~.DataType.FUNCTION`) The function to call on each of the values. :values: (:py:attr:`~.DataType.ARRAY` of *anything*) The array of values to apply *function* to. Returns an array containing a subset of members from *values* where *function* returns true. ``DATETIME parse_datetime(STRING value)`` :returns: :py:attr:`~.DataType.DATETIME` :value: (:py:attr:`~.DataType.STRING`) The string value to parse into a timestamp. Parses the string value into a :py:attr:`~.DataType.DATETIME` value. The string must be in ISO-8601 format and if it fails to parse, a :py:exc:`~.errors.DatetimeSyntaxError` is raised. ``FLOAT parse_float(STRING value)`` :returns: :py:attr:`~.DataType.FLOAT` :value: (:py:attr:`~.DataType.STRING`) The string value to parse into a numeric. Parses the string value into a :py:attr:`~.DataType.FLOAT` value. The string must be properly formatted and if it fails to parse, a :py:exc:`~.errors.FloatSyntaxError` is raised. ``FLOAT parse_timedelta(STRING value)`` :returns: :py:attr:`~.DataType.TIMEDELTA` :value: (:py:attr:`~.DataType.STRING`) The string value to parse into a time period. Parses the string value into a :py:attr:`~.DataType.TIMEDELTA` value. The string must be properly formatted and if it fails to parse, a :py:exc:`~.errors.TimedeltaSyntaxError` is raised. ``FLOAT random([FLOAT boundary])`` :returns: :py:attr:`~.DataType.FLOAT` :boundary: (Optional :py:attr:`~.DataType.FLOAT`) The upper boundary to generate a random number for. Generate a random number. If *boundary* is not specified, the random number returned will be between 0 and 1. If *boundary* is specified, it must be a natural number and the random number returned will be between 0 and *boundary*, including *boundary*. .. _builtin-function-split: ``ARRAY[STRING] split(STRING string, [STRING sep, FLOAT maxsplit])`` :returns: :py:attr:`~.DataType.ARRAY` of :py:attr:`~.DataType.STRING` :string: (:py:attr:`~.DataType.STRING`) The string value to split into substrings. :sep: (Optional :py:attr:`~.DataType.STRING`) The value to split *string* on. :maxsplit: (Optional :py:attr:`~.DataType.FLOAT`) The maximum number of times tp split *string*. Split a string value into sub strings. If *sep* is not specified, the *string* will be split by all whitespace. If *sep* is specified, *string* will be split by that value. This alters how consecutive spaces are handled. When *sep* is not specified, consecutive whitespace is handled as a single unit and reduced, where as if *sep* is a single space, consecutive spaces will result in empty strings being returned. For example: .. code-block:: $split("A B") # => ('A', 'B') $split("A B", ' ') # => ('A', '', '', '', 'B') If *maxsplit* is specified, it must be a natural number and will be used as the maximum number of times to split *string*. This will guarantee that the resulting array length is less than or equal to *maxsplit* + 1. Math Related ^^^^^^^^^^^^ * ``e`` (type: :py:attr:`~.DataType.FLOAT`) -- The mathematical constant *e* (2.71828...). * ``pi`` (type: :py:attr:`~.DataType.FLOAT`) -- The mathematical constant *pi* (3.14159...). Regular Expression Related ^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``re_groups`` (type: :py:attr:`~.DataType.ARRAY`) -- An array of strings from the last regular expression match as defined by the regular expression itself. See documentation on `grouping`_ for more information. If no match has taken place, this value is :py:attr:`~.DataType.NULL`. .. note:: For technical reasons, this symbol is provided by the default :py:attr:`~engine.Context` and is not included within the :py:meth:`~engine.Builtins.from_defaults`. This means that unlike the other symbols listed here, it will be unavailable if the default builtins are replaced. Timestamp Related ^^^^^^^^^^^^^^^^^ * ``now`` (type: :py:attr:`~.DataType.DATETIME`) -- The current timestamp (including time) using the default timezone from :py:attr:`~engine.Context.default_timezone`. * ``today`` (type: :py:attr:`~.DataType.DATETIME`) -- The current timestamp, (excluding time, normalized to midnight 00:00:00) using the default timezone from :py:attr:`~engine.Context.default_timezone`. .. _grouping: https://docs.python.org/3/howto/regex.html#grouping .. _Order of operations: https://en.wikipedia.org/wiki/Order_of_operations#Programming_languages .. _technique used by Python: https://docs.python.org/3/tutorial/datastructures.html#comparing-sequences-and-other-types rule-engine-4.1.0/docs/source/types.rst000066400000000000000000000150721446303237000200630ustar00rootroot00000000000000.. py:currentmodule:: rule_engine.types Data Types ========== The following table describes the data types supported by the Rule Engine and the Python data types that each is compatible with. For a information regarding supported operations, see the :ref:`Supported Operations` table. .. _data-types: +-------------------------------+-------------------------------+ | Rule Engine Data Type | Compatible Python Types | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.ARRAY` | :py:class:`list`, | | | :py:class:`tuple` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.BOOLEAN` | :py:class:`bool` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.DATETIME` | :py:class:`datetime.date`, | | | :py:class:`datetime.datetime` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.FLOAT` | :py:class:`int`, | | | :py:class:`float` | | | :py:class:`decimal.Decimal` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.FUNCTION` | *anything callable* | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.MAPPING` | :py:class:`dict` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.NULL` | :py:class:`NoneType` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.SET` | :py:class:`set` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.STRING` | :py:class:`str` | +-------------------------------+-------------------------------+ | :py:attr:`~DataType.TIMEDELTA`| :py:class:`datetime.timedelta`| +-------------------------------+-------------------------------+ Compound Types -------------- The compound data types (:py:attr:`~DataType.ARRAY`, :py:attr:`~DataType.SET`, and :py:attr:`~DataType.MAPPING`) are all capable of containing zero or more values of other data types (though it should be noted that :py:attr:`~DataType.MAPPING` keys **must be scalars** while the values can be anything). The member types of compound data types can be defined, but only if the members are all of the same type. For an example, an array containing floats can be defined, and an mapping with string keys to string values can also be defined, but a mapping with string keys to values that are either floats, strings or booleans **may not be completely defined**. For more information, see the section on :ref:`getting-started-compound-data-types` in the Getting Started page. Compound data types are also iterable, meaning that array comprehension operations can be applied to them. Iteration operations apply to the members of :py:attr:`~DataType.ARRAY` and :py:attr:`~DataType.SET` values, and the keys of :py:attr:`~DataType.MAPPING` values. This allows the types to behave in the same was as they do in Python. FLOAT ----- See :ref:`literal-float-values` for syntax. Starting in :release:`3.0.0`, the ``FLOAT`` datatype is backed by Python's :py:class:`~decimal.Decimal` object. This makes the evaluation of arithmetic more intuitive for the audience of rule authors who are not assumed to be familiar with the nuances of binary floating point arithmetic. To take an example from the :py:mod:`decimal` documentation, rule authors should not have to know that ``0.1 + 0.1 + 0.1 - 0.3 != 0``. Internally, Rule Engine conversion values from Python :py:class:`float` and :py:class:`int` objects to :py:class:`~decimal.Decimal` using their string representation (as provided by :py:func:`repr`) **and not** :py:meth:`~decimal.Decimal.from_float`. This is to ensure that a Python :py:class:`float` value of ``0.1`` that is provided by an input will match a Rule Engine literal of ``0.1``. To explicitly pass a binary floating point value, the caller must convert it using :py:meth:`~decimal.Decimal.from_float` themselves. To change the behavior of the floating point arithmetic, a :py:class:`decimal.Context` can be specified by the :py:class:`~rule_engine.engine.Context` object. Since Python's :py:class:`~decimal.Decimal` values are not always equivalent to themselves (e.g. ``0.1 != Decimal('0.1')``) it's important to know that Rule Engine will coerce and normalize these values. That means that while in Python ``0.1 in [ Decimal('0.1') ]`` will evaluate to ``False``, in a rule it will evaluate to ``True`` (e.g. ``Rule('0.1 in numbers').evaluate({'numbers': [Decimal('0.1')]})``). This also affects Python dictionaries that are converted to Rule Engine :py:attr:`~DataType.MAPPING` values. While in Python the value ``{0.1: 'a', Decimal('0.1'): 'a'}`` would have a length of 2 with two unique keys, the same value once converted into a Rule Engine :py:attr:`~DataType.MAPPING` would have a length of 1 with a single unique key. For this reason, developers using Rule Engine should take care to not use compound data types with a mix of Python :py:class:`float` and :py:class:`~decimal.Decimal` values. FUNCTION -------- Version :release:`4.0.0` added the :py:attr:`~DataType.FUNCTION` datatype. This can be used to make functions available to rule authors. Rule Engine contains a few :ref:`builtin functions` that can be used by default. Additional functions can either be added to the evaluated object or by extending the builtin symbols. It is only possible to call a function from within the rule text. Functions can not be defined as other data types can be. TIMEDELTA --------- See :ref:`literal-timedelta-values` for syntax. Version :release:`3.5.0` introduced the :py:attr:`~DataType.TIMEDELTA` datatype, backed by Python's :py:class:`~datetime.timedelta` class. This also comes with the ability to perform arithmetic with both :py:attr:`~DataType.TIMEDELTA` *and* :py:attr:`~DataType.DATETIME` values. This allows you to create rules for things such as "has it been 30 days since this thing happened?" or "how much time passed between two events?". The following mathematical operations are supported: * Adding a timedelta to a datetime (result is a datetime) * Adding a timedelta to another timedelta (result is a timedelta) * Subtracting a timedelta from a datetime (result is a datetime) * Subtracting a datetime from another datetime (result is a timedelta) * Subtracting a timedelta from another timedelta (result is a timedelta) rule-engine-4.1.0/examples/000077500000000000000000000000001446303237000155465ustar00rootroot00000000000000rule-engine-4.1.0/examples/csv_filter.py000066400000000000000000000060551446303237000202660ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/csv_filter.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import csv import functools import os import sys get_path = functools.partial(os.path.join, os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) sys.path.append(get_path('lib')) import rule_engine DESCRIPTION = """\ Apply a rule to the specified CSV file. The first row of the CSV file must be the field names which will be used as the symbols for the rule. """ # specify a custom resolve function that checks if the symbol is a column name # in the csv file and if not replaces underscores with spaces def resolve_item(thing, name): if not name in thing: name = name.replace('_', ' ') return rule_engine.resolve_item(thing, name) def main(): parser = argparse.ArgumentParser( conflict_handler='resolve', description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument('csv_file', type=argparse.FileType('r'), help='the CSV file to filter') parser.add_argument('rule', help='the rule to apply') arguments = parser.parse_args() # need to define a custom context to use a custom resolver function context = rule_engine.Context(resolver=resolve_item) try: rule = rule_engine.Rule(arguments.rule, context=context) except rule_engine.RuleSyntaxError as error: print(error.message) return 0 csv_reader = csv.DictReader(arguments.csv_file) csv_writer = csv.DictWriter(sys.stdout, csv_reader.fieldnames, dialect=csv_reader.dialect) for row in rule.filter(csv_reader): csv_writer.writerow(row) return 0 if __name__ == '__main__': sys.exit(main()) rule-engine-4.1.0/examples/database.py000066400000000000000000000053761446303237000176770ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/database.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import csv import json import rule_engine def isiterable(thing): return isinstance(thing, collections.abc.Iterable) class Database(object): def __init__(self, data): self.data = data self._rule_context = rule_engine.Context(default_value=None) @classmethod def from_csv(cls, file_path, headers=None, skip_first=False): file_h = open(file_path, 'r') reader = csv.DictReader(file_h, headers) if skip_first: next(reader) rows = tuple(reader) file_h.close() return cls(rows) @classmethod def from_json(cls, file_path): with open(file_path, 'r') as file_h: data = json.load(file_h) return cls(data) def select(self, *names, from_=None, where='true', limit=None): data = self.data if from_ is not None: data = rule_engine.Rule(from_, context=self._rule_context).evaluate(data) if isinstance(data, collections.abc.Mapping): data = data.values() if not isiterable(data): raise ValueError('data source is not iterable') rule = rule_engine.Rule(where, context=self._rule_context) count = 0 for match in rule.filter(data): if count == limit: break yield tuple(rule_engine.Rule(name, context=self._rule_context).evaluate(match) for name in names) count += 1 rule-engine-4.1.0/examples/github_filter.py000066400000000000000000000075151446303237000207570ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/github_filter.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import functools import getpass import os import sys try: import github except ImportError: print('this script requires PyGithub', file=sys.stderr) sys.exit(os.EX_UNAVAILABLE) DESCRIPTION = 'Apply a rule to filter pull requests or issues from GitHub.' EPILOG = """\ example rules: * Show all merged pull requests by user zeroSteiner "user.login == 'zeroSteiner' and merged" * Show open issues assigned to user zeroSteiner "state != 'open' and assignee and assignee.login == 'zeroSteiner'" """ get_path = functools.partial(os.path.join, os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) sys.path.append(get_path('lib')) import rule_engine import rule_engine.engine def _get_github(arguments): if arguments.auth_token: gh = github.Github(arguments.auth_token) elif arguments.auth_user: password = getpass.getpass("{0}@github.com: ".format(arguments.auth_user)) gh = github.Github(arguments.auth_user, password) else: gh = github.Github() return gh def main(): parser = argparse.ArgumentParser( conflict_handler='resolve', description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter ) auth_type_parser_group = parser.add_mutually_exclusive_group() auth_type_parser_group.add_argument('--auth-token', dest='auth_token', help='authenticate to github with a token') auth_type_parser_group.add_argument('--auth-user', dest='auth_user', help='authenticate to github with credentials') parser.add_argument('repo_slug', help='the repository to filter') parser.add_argument('type', choices=('issues', 'pulls'), help='thing to filter') parser.add_argument('rule', help='the rule to apply') parser.epilog = EPILOG arguments = parser.parse_args() # need to define a custom context to use a custom resolver function context = rule_engine.Context(resolver=rule_engine.engine.resolve_attribute) try: rule = rule_engine.Rule(arguments.rule, context=context) except rule_engine.RuleSyntaxError as error: print(error.message) return 0 gh = _get_github(arguments) repo = gh.get_repo(arguments.repo_slug) things = tuple(getattr(repo, 'get_' + arguments.type)(state='all')) for thing in rule.filter(things): print("{0}#{1: <4} - {2}".format(arguments.repo_slug, thing.number, thing.title)) return 0 if __name__ == '__main__': sys.exit(main()) rule-engine-4.1.0/examples/shodan/000077500000000000000000000000001446303237000170225ustar00rootroot00000000000000rule-engine-4.1.0/examples/shodan/query.py000066400000000000000000000054251446303237000205470ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/shodan/query.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import gzip import json import os import shodan DESCRIPTION = 'Query results from Shodan' def main(): parser = argparse.ArgumentParser( conflict_handler='resolve', description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument('--api-key', default=os.getenv('SHODAN_API_KEY'), help='the API key') parser.add_argument('--gzip', action='store_true', default=False, help='compress the file') parser.add_argument('json_file', type=argparse.FileType('wb'), help='the JSON file to write to') parser.add_argument('query', nargs='+', help='the search queries to retrieve') arguments = parser.parse_args() if arguments.api_key is None: print('[-] The --api-key must be specified or the SHODAN_API_KEY environment variable must be defined') return os.EX_CONFIG api = shodan.Shodan(arguments.api_key) all_results = [] for query in arguments.query: print('[*] Querying: ' + query) search_results = api.search(query) all_results.extend(search_results['matches']) output = '\n'.join(json.dumps(result) for result in all_results) output = output.encode('utf-8') if arguments.gzip: output = gzip.compress(output) arguments.json_file.write(output) if __name__ == '__main__': main()rule-engine-4.1.0/examples/shodan/results_filter.py000066400000000000000000000076701446303237000224540ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/shodan/results_filter.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import functools import gzip import json import os import pprint import re import sys get_path = functools.partial(os.path.join, os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))) sys.path.append(get_path('lib')) import rule_engine BLACKLIST = ('_shodan', 'asn', 'hash', 'ip') DESCRIPTION = 'Apply a rule to filter results exported from Shodan.' EPILOG = """\ example rules: * Find all HTTPS servers missing the Strict-Transport-Security header "http and ssl and data !~~ '^Strict-Transport-Security:\s'" * Find OpenSSH servers on non-default ports "product == 'OpenSSH' and port != 22" """ def result_to_url(result): protocol = result['transport'] if 'http' in result: protocol = 'https' if 'ssl' in result else 'http' return "{protocol}://{ip_str}:{port}".format(protocol=protocol, **result) def main(): parser = argparse.ArgumentParser( conflict_handler='resolve', description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument('-d', '--depth', default=2, type=int, help='the depth to pretty print') parser.add_argument('--gzip', action='store_true', default=False, help='decompress the file') parser.add_argument('--regex-case-sensitive', default=False, action='store_true', help='use case-sensitive regular expressions') parser.add_argument('json_file', type=argparse.FileType('rb'), help='the JSON file to filter') parser.add_argument('rule', help='the rule to apply') parser.epilog = EPILOG arguments = parser.parse_args() re_flags = re.MULTILINE if arguments.regex_case_sensitive: re_flags &= re.IGNORECASE context = rule_engine.Context(default_value=None, regex_flags=re_flags) try: rule = rule_engine.Rule(arguments.rule, context=context) except rule_engine.RuleSyntaxError as error: print(error.message) return 0 file_object = arguments.json_file if arguments.gzip: file_object = gzip.GzipFile(fileobj=file_object) total = 0 matches = 0 for line in file_object: result = json.loads(line.decode('utf-8')) total += 1 if not rule.matches(result): continue matches += 1 print(result_to_url(result)) if arguments.depth > 0: for key in BLACKLIST: result.pop(key, None) pprint.pprint(result, depth=arguments.depth) print("rule matched {:,} of {:,} results ({:.2f}%)".format(matches, total, ((matches / total) * 100))) return 0 if __name__ == '__main__': sys.exit(main()) rule-engine-4.1.0/examples/shodan/results_scan.py000066400000000000000000000074051446303237000221070ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # examples/shodan/results_scan.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import functools import gzip import json import os import re import sys get_path = functools.partial(os.path.join, os.path.abspath(os.path.join(os.path.dirname(__file__)))) sys.path.append(get_path()) sys.path.append(get_path('..', '..', 'lib')) import results_filter import rule_engine import yaml DESCRIPTION = 'Scan results exported from Shodan for vulnerabilities.' RULES_FILE = get_path('rules.yml') def _print_references(references): cves = references.get('cves') if cves and len(cves) == 1: print('CVE: CVE-' + cves[0]) elif cves and len(cves) > 1: print('CVEs: ') for cve in cves: print(' * CVE-' + cve) msf_modules = references.get('metasploit-modules') if msf_modules and len(msf_modules) == 1: print('Metasploit Module: ' + msf_modules[0]) elif msf_modules and len(msf_modules) > 1: print('Metasploit Modules:') for msf_module in msf_modules: print(' * ' + msf_module) def main(): parser = argparse.ArgumentParser( conflict_handler='resolve', description=DESCRIPTION, formatter_class=argparse.RawDescriptionHelpFormatter ) parser.add_argument('--gzip', action='store_true', default=False, help='decompress the file') parser.add_argument('json_file', type=argparse.FileType('rb'), help='the JSON file to filter') arguments = parser.parse_args() re_flags = re.IGNORECASE | re.MULTILINE context = rule_engine.Context(default_value=None, regex_flags=re_flags) file_object = arguments.json_file if arguments.gzip: file_object = gzip.GzipFile(fileobj=file_object) results = [json.loads(line.decode('utf-8')) for line in file_object] with open(RULES_FILE, 'r') as file_h: rules = yaml.load(file_h, Loader=yaml.FullLoader) for vulnerability in rules['rules']: try: rule = rule_engine.Rule(vulnerability['rule'], context=context) except rule_engine.RuleSyntaxError as error: print(error.message) return 0 matches = tuple(rule.filter(results)) if not matches: continue print(vulnerability['description']) references = vulnerability.get('references', {}) _print_references(references) print('Hosts:') for match in matches: print(" * {}".format(results_filter.result_to_url(match))) print() return 0 if __name__ == '__main__': sys.exit(main()) rule-engine-4.1.0/examples/shodan/rules.yml000066400000000000000000000026051446303237000207020ustar00rootroot00000000000000rules: - description: Anonymous FTP Access is enabled rule: ftp.anonymous - description: HTTP server prompts for basic authentication without SSL rule: http and not ssl and data =~~ '^WWW-Authenticate:\s+Basic\s+realm=' - description: HTTP server missing the 'X-Frame-Options' header rule: http and data =~~ 'HTTP/\d.\d 2\d\d' and data !~~ '^X-Frame-Options:\s' - description: HTTPS server missing the 'Strict-Transport-Security' header rule: http and ssl and data !~~ '^Strict-Transport-Security:\s' - description: Outdated software - OpenSSH Server < v7.7 rule: product == 'OpenSSH' and (version =~ '[1-6]\.\d+' or version =~ '7\.[0-6]') references: cves: - 2018-15473 metasploit-modules: - auxiliary/scanner/ssh/ssh_enumusers - description: Outdated software - Allegro RomPager < v4.34 rule: product == 'Allegro RomPager' and version =~ '([1-3]\.\d\d|4\.([0-2]\d|3[0-3]))' references: cves: - 2014-9222 metasploit-modules: - auxiliary/admin/http/allegro_rompager_auth_bypass - auxiliary/scanner/http/allegro_rompager_misfortune_cookie - description: SSLv3 is enabled rule: ssl.versions and 'SSLv3' in ssl.versions - description: TLSv1 is enabled rule: ssl.versions and 'TLSv1' in ssl.versions - description: TLSv1.1 is enabled rule: ssl.versions and 'TLSv1.1' in ssl.versions rule-engine-4.1.0/lib/000077500000000000000000000000001446303237000144765ustar00rootroot00000000000000rule-engine-4.1.0/lib/rule_engine/000077500000000000000000000000001446303237000167725ustar00rootroot00000000000000rule-engine-4.1.0/lib/rule_engine/__init__.py000066400000000000000000000037051446303237000211100ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/__init__.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # __version__ = '4.1.0' from .engine import resolve_attribute from .engine import resolve_item from .engine import type_resolver_from_dict from .engine import Context from .engine import Rule from .errors import AttributeResolutionError from .errors import EngineError from .errors import EvaluationError from .errors import RuleSyntaxError from .errors import SymbolResolutionError from .types import DataType rule-engine-4.1.0/lib/rule_engine/_utils.py000066400000000000000000000032161446303237000206450ustar00rootroot00000000000000import ast as pyast import datetime import decimal import re from . import errors import dateutil.parser _sub_regex = r'[0-9]+([,.][0-9]+)?' timedelta_regex = ( r'P(?!\b)' r'(?P' + _sub_regex + r'W)?' r'(?P' + _sub_regex + r'D)?' r'(T' r'(?P' + _sub_regex + r'H)?' r'(?P' + _sub_regex + r'M)?' r'(?P' + _sub_regex + r'S)?' r')?' ) def parse_datetime(string, default_timezone): try: dt = dateutil.parser.isoparse(string) except ValueError: raise errors.DatetimeSyntaxError('invalid datetime', string) from None if dt.tzinfo is None: dt = dt.replace(tzinfo=default_timezone) return dt def parse_float(string): if re.match('^0[0-9]', string): raise errors.FloatSyntaxError('invalid floating point literal (leading zeros in decimal literals are not permitted)', string) try: if re.match('^0[box]', string): val = decimal.Decimal(pyast.literal_eval(string)) else: val = decimal.Decimal(string) except Exception: raise errors.FloatSyntaxError('invalid floating point literal', string) from None return val def parse_timedelta(periodstring): if periodstring == "P": raise errors.TimedeltaSyntaxError('empty timedelta string', periodstring) match = re.match("^" + timedelta_regex + "$", periodstring) if not match: raise errors.TimedeltaSyntaxError('invalid timedelta string', periodstring) groups = match.groupdict() for key, val in groups.items(): if val is None: val = "0n" groups[key] = float(val[:-1].replace(',', '.')) return datetime.timedelta( weeks=groups['weeks'], days=groups['days'], hours=groups['hours'], minutes=groups['minutes'], seconds=groups['seconds'], ) rule-engine-4.1.0/lib/rule_engine/ast.py000066400000000000000000001466241446303237000201500ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/ast.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import collections.abc import datetime import functools import operator import re from . import errors from ._utils import parse_datetime, parse_float, parse_timedelta from .suggestions import suggest_symbol from .types import * def _assert_is_integer_number(*values): if not all(map(is_integer_number, values)): raise errors.EvaluationError('data type mismatch (not an integer number)') def _assert_is_natural_number(*values): if not all(map(is_natural_number, values)): raise errors.EvaluationError('data type mismatch (not a natural number)') def _assert_is_numeric(*values): if not all(map(is_numeric, values)): raise errors.EvaluationError('data type mismatch (not a numeric value)') def _assert_is_string(*values): if not all(map(isinstance, values, [str])): raise errors.EvaluationError('data type mismatch (not a string value)') def _is_reduced(*values): """ Check if the ast expression *value* is a literal expression and if it is a compound datatype, that all of its members are reduced literals. A value that causes this to evaluate to True for is able to be evaluated without a *thing*. """ return all((isinstance(value, LiteralExpressionBase) and value.is_reduced) for value in values) def _iterable_member_value_type(value): value = ( member.result_type if isinstance(member, ExpressionBase) else member for member in value ) return iterable_member_value_type(value) class Assignment(object): """An internal assignment whereby a symbol is populated with a value of the specified type.""" __slots__ = ('name', 'value', 'value_type') def __init__(self, name, *, value=errors.UNDEFINED, value_type=None): """ :param str name: The symbol name that the assignment is defining. :param value: The value of the assignment. :param value_type: The data type of the assignment. :type value_type: :py:class:`~.DataType` """ self.name = name self.value = value if value is not errors.UNDEFINED and value_type is not None: value_type = DataType.from_value(value) self.value_type = value_type def __repr__(self): return "<{} name={!r} value={!r} value_type={!r} >".format(self.__class__.__name__, self.name, self.value, self.value_type) class ASTNodeBase(object): def to_graphviz(self, digraph): digraph.node(str(id(self)), self.__class__.__name__) @classmethod def build(cls, *args, **kwargs): return cls(*args, **kwargs).reduce() def evaluate(self, thing): """ Evaluate this AST node and all applicable children nodes. :param thing: The object to use for symbol resolution. :return: The result of the evaluation as a native Python type. """ raise NotImplementedError() def reduce(self): """ Reduce this expression into a smaller subset of nodes. If the expression can not be reduced, then return an instance of itself, otherwise return a reduced :py:class:`.ExpressionBase` to replace it. :return: Either a reduced version of this node or itself. :rtype: :py:class:`.ExpressionBase` """ return self class Comment(ASTNodeBase): __slots__ = ('value',) def __init__(self, value): self.value = value def __repr__(self): return "<{0} {1!r}>".format(self.__class__.__name__, self.value) def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\n{!r}".format(self.__class__.__name__, self.value)) ################################################################################ # Base Expression Classes ################################################################################ class ExpressionBase(ASTNodeBase): __slots__ = ('context',) result_type = DataType.UNDEFINED """The data type of the result of successful evaluation.""" def __repr__(self): return "<{0} >".format(self.__class__.__name__) def _new_value(self, *args, **kwargs): # perform a context aware load of value value = coerce_value(*args, **kwargs) if isinstance(value, datetime.datetime) and value.tzinfo is None: value = value.replace(tzinfo=self.context.default_timezone) return value class LiteralExpressionBase(ExpressionBase): """A base class for representing literal values from the grammar text.""" __slots__ = ('value',) is_reduced = True def __init__(self, context, value): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param value: The native Python value. """ self.context = context if not isinstance(value, self.result_type.python_type) and self.result_type.is_scalar: raise TypeError("__init__ argument 2 must be {}, not {}".format(self.result_type.python_type.__name__, type(value).__name__)) self.value = value def __repr__(self): return "<{0} value={1!r} >".format(self.__class__.__name__, self.value) @classmethod def from_value(cls, context, value): """ Create a Literal Expression instance to represent the specified *value*. .. versionadded:: 2.0.0 :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param value: The value to represent as a Literal Expression. :return: A subclass of :py:class:`~.LiteralExpressionBase` specific to the type of *value*. """ datatype = DataType.from_value(value) for subclass in cls.__subclasses__(): if DataType.is_compatible(subclass.result_type, datatype): break else: raise errors.EngineError("can not create literal expression from python value: {!r}".format(value)) if datatype.is_compound: if isinstance(datatype, DataType.ARRAY.__class__) or isinstance(datatype, DataType.SET.__class__): value = datatype.python_type(cls.from_value(context, v) for v in value) elif isinstance(datatype, DataType.MAPPING.__class__): value = tuple((cls.from_value(context, k), cls.from_value(context, v)) for k, v in value.items()) else: value = coerce_value(value) return subclass(context, value) def evaluate(self, thing): return self.value def to_graphviz(self, digraph, *args, **kwargs): if self.result_type.is_compound: digraph.node(str(id(self)), self.__class__.__name__) else: digraph.node(str(id(self)), "{}\nvalue={!r}".format(self.__class__.__name__, self.value)) ################################################################################ # Literal Expressions ################################################################################ class _CollectionMixin(object): def evaluate(self, thing): return self.result_type.python_type(member.evaluate(thing) for member in self.value) @property def is_reduced(self): return _is_reduced(*self.value) def to_graphviz(self, digraph, *args, **kwargs): super(_CollectionMixin, self).to_graphviz(digraph, *args, **kwargs) for member in self.value: member.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(member))) class ArrayExpression(_CollectionMixin, LiteralExpressionBase): """Literal array expressions containing 0 or more sub-expressions.""" result_type = DataType.ARRAY def __init__(self, *args, **kwargs): super(ArrayExpression, self).__init__(*args, **kwargs) self.result_type = DataType.ARRAY(value_type=_iterable_member_value_type(self.value)) @classmethod def build(cls, context, value): return cls(context, [member.build() for member in value]) class BooleanExpression(LiteralExpressionBase): """Literal boolean expressions representing True or False.""" result_type = DataType.BOOLEAN class DatetimeExpression(LiteralExpressionBase): """ Literal datetime expressions representing a specific point in time. This expression type always evaluates to true. """ result_type = DataType.DATETIME @classmethod def from_string(cls, context, string): dt = parse_datetime(string, default_timezone=context.default_timezone) return cls(context, dt) class TimedeltaExpression(LiteralExpressionBase): """ Literal timedelta expressions representing an offset from a specific point in time. .. versionadded:: 3.5.0 """ result_type = DataType.TIMEDELTA @classmethod def from_string(cls, context, string): return cls(context, parse_timedelta(string)) class FloatExpression(LiteralExpressionBase): """Literal float expressions representing numerical values.""" result_type = DataType.FLOAT def __init__(self, context, value, **kwargs): value = coerce_value(value) super(FloatExpression, self).__init__(context, value, **kwargs) @classmethod def from_string(cls, context, string): return cls(context, parse_float(string)) class MappingExpression(LiteralExpressionBase): """Literal mapping expression representing a set of associations between keys and values.""" result_type = DataType.MAPPING def __init__(self, context, value, **kwargs): if isinstance(value, dict): value = tuple(value.items()) super(MappingExpression, self).__init__(context, value, **kwargs) self.result_type = DataType.MAPPING( key_type=_iterable_member_value_type(key for key, _ in self.value), value_type=_iterable_member_value_type(value for _, value in self.value) ) @classmethod def build(cls, context, value): value = collections.OrderedDict(value) value = collections.OrderedDict((k.build(), v.build()) for k, v in value.items()) return cls(context, value) def evaluate(self, thing): mapping = collections.OrderedDict() for key, value in self.value: key = key.evaluate(thing) key_type = DataType.from_value(key) if key_type.is_compound and not isinstance(key_type, DataType.ARRAY.__class__): raise errors.EngineError("the {} data type may not be used for mapping keys".format(key_type.name)) mapping[key] = value # defer value evaluation to avoid evaluating values of duplicate keys for key, value in mapping.items(): mapping[key] = value.evaluate(thing) return mapping @property def is_reduced(self): return all(_is_reduced(key, value) for key, value in self.value) class NullExpression(LiteralExpressionBase): """Literal null expressions representing null values. This expression type always evaluates to false.""" result_type = DataType.NULL def __init__(self, context, value=None): # all of the literal expressions take a value if value is not None: raise TypeError('value must be None') super(NullExpression, self).__init__(context, value=None) class SetExpression(_CollectionMixin, LiteralExpressionBase): """Literal set expressions containing 0 or more sub-expressions.""" result_type = DataType.SET def __init__(self, *args, **kwargs): super(SetExpression, self).__init__(*args, **kwargs) self.result_type = DataType.SET(value_type=_iterable_member_value_type(self.value)) @classmethod def build(cls, context, value): value = set(member.build() for member in value) return cls(context, value) class StringExpression(LiteralExpressionBase): """Literal string expressions representing an array of characters.""" result_type = DataType.STRING ################################################################################ # Left-Operator-Right Expressions ################################################################################ class LeftOperatorRightExpressionBase(ExpressionBase): """ A base class for representing complex expressions composed of a left side and a right side, separated by an operator. """ compatible_types = (DataType.ARRAY, DataType.BOOLEAN, DataType.DATETIME, DataType.TIMEDELTA, DataType.FLOAT, DataType.MAPPING, DataType.NULL, DataType.SET, DataType.STRING) """ A tuple containing the compatible data types that the left and right expressions must return. This can for example be used to indicate that arithmetic operations are compatible with :py:attr:`~.DataType.FLOAT` but not :py:attr:`~.DataType.STRING` values. """ result_type = DataType.BOOLEAN def __init__(self, context, type_, left, right): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param str type_: The grammar type of operator at the center of the expression. Subclasses must define operator methods to handle evaluation based on this value. :param left: The expression to the left of the operator. :type left: :py:class:`.ExpressionBase` :param right: The expression to the right of the operator. :type right: :py:class:`.ExpressionBase` """ self.context = context type_ = type_.lower() self.type = type_ self._evaluator = getattr(self, '_op_' + type_, None) if self._evaluator is None: raise errors.EngineError('unsupported operator: ' + type_) self._assert_type_is_compatible(left) self.left = left self._assert_type_is_compatible(right) self.right = right @classmethod def build(cls, context, type_, left, right): return cls(context, type_, left.build(), right.build()).reduce() def _assert_type_is_compatible(self, value): if value.result_type == DataType.UNDEFINED: return if any(DataType.is_compatible(dt, value.result_type) for dt in self.compatible_types): return raise errors.EvaluationError('data type mismatch') def __repr__(self): return "<{} type={!r} >".format(self.__class__.__name__, self.type) def evaluate(self, thing): return self._evaluator(thing) def reduce(self): if not _is_reduced(self.left, self.right): return self return LiteralExpressionBase.from_value(self.context, self.evaluate(None)) def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\ntype={!r}".format(self.__class__.__name__, self.type)) self.left.to_graphviz(digraph, *args, **kwargs) self.right.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.left)), label='left') digraph.edge(str(id(self)), str(id(self.right)), label='right') class AddExpression(LeftOperatorRightExpressionBase): """A class for representing addition expressions from the grammar text.""" compatible_types = (DataType.FLOAT, DataType.STRING, DataType.DATETIME, DataType.TIMEDELTA) result_type = DataType.UNDEFINED def __init__(self, *args, **kwargs): super(AddExpression, self).__init__(*args, **kwargs) if self.left.result_type != DataType.UNDEFINED and self.right.result_type != DataType.UNDEFINED: if self.left.result_type == DataType.DATETIME: if self.right.result_type != DataType.TIMEDELTA: raise errors.EvaluationError('data type mismatch') self.result_type = self.left.result_type elif self.left.result_type == DataType.TIMEDELTA: if self.right.result_type not in (DataType.DATETIME, DataType.TIMEDELTA): raise errors.EvaluationError('data type mismatch') self.result_type = self.right.result_type elif self.left.result_type != self.right.result_type: raise errors.EvaluationError('data type mismatch') else: self.result_type = self.left.result_type def _op_add(self, thing): left_value = self.left.evaluate(thing) right_value = self.right.evaluate(thing) if isinstance(left_value, datetime.datetime): if not isinstance(right_value, datetime.timedelta): raise errors.EvaluationError('data type mismatch (not a timedelta value)') elif isinstance(left_value, datetime.timedelta): if not isinstance(right_value, (datetime.timedelta, datetime.datetime)): raise errors.EvaluationError('data type mismatch (not a datetime or timedelta value)') elif isinstance(left_value, str) or isinstance(right_value, str): _assert_is_string(left_value, right_value) else: _assert_is_numeric(left_value, right_value) return operator.add(left_value, right_value) class SubtractExpression(LeftOperatorRightExpressionBase): """ A class for representing subtraction expressions from the grammar text. .. versionadded:: 3.5.0 """ compatible_types = (DataType.FLOAT, DataType.DATETIME, DataType.TIMEDELTA) result_type = DataType.UNDEFINED def __init__(self, *args, **kwargs): super(SubtractExpression, self).__init__(*args, **kwargs) if self.left.result_type != DataType.UNDEFINED and self.right.result_type != DataType.UNDEFINED: if self.left.result_type == DataType.DATETIME: if self.right.result_type == DataType.DATETIME: self.result_type = DataType.TIMEDELTA elif self.right.result_type == DataType.TIMEDELTA: self.result_type = DataType.DATETIME else: raise errors.EvaluationError('data type mismatch') elif self.left.result_type == DataType.TIMEDELTA: if self.right.result_type != DataType.TIMEDELTA: raise errors.EvaluationError('data type mismatch') self.result_type = self.left.result_type elif self.left.result_type != self.right.result_type: raise errors.EvaluationError('data type mismatch') else: self.result_type = self.left.result_type def _op_sub(self, thing): left_value = self.left.evaluate(thing) right_value = self.right.evaluate(thing) if isinstance(left_value, datetime.datetime): if not isinstance(right_value, (datetime.datetime, datetime.timedelta)): raise errors.EvaluationError('data type mismatch (not a datetime or timedelta value)') elif isinstance(left_value, datetime.timedelta): if not isinstance(right_value, datetime.timedelta): raise errors.EvaluationError('data type mismatch (not a timedelta value)') else: _assert_is_numeric(left_value, right_value) return operator.sub(left_value, right_value) class ArithmeticExpression(LeftOperatorRightExpressionBase): """A class for representing arithmetic expressions from the grammar text such as multiplication and division.""" compatible_types = (DataType.FLOAT,) result_type = DataType.FLOAT def __op_arithmetic(self, op, thing): left_value = self.left.evaluate(thing) _assert_is_numeric(left_value) right_value = self.right.evaluate(thing) _assert_is_numeric(right_value) return op(left_value, right_value) _op_fdiv = functools.partialmethod(__op_arithmetic, operator.floordiv) _op_tdiv = functools.partialmethod(__op_arithmetic, operator.truediv) _op_mod = functools.partialmethod(__op_arithmetic, operator.mod) _op_mul = functools.partialmethod(__op_arithmetic, operator.mul) _op_pow = functools.partialmethod(__op_arithmetic, operator.pow) class BitwiseExpression(LeftOperatorRightExpressionBase): """ A class for representing bitwise arithmetic expressions from the grammar text such as XOR and shifting operations. """ compatible_types = (DataType.FLOAT, DataType.SET) result_type = DataType.UNDEFINED def __init__(self, *args, **kwargs): super(BitwiseExpression, self).__init__(*args, **kwargs) # don't use DataType.is_compatible, because for sets the member type isn't important if self.left.result_type != DataType.UNDEFINED and self.right.result_type != DataType.UNDEFINED: if self.left.result_type.__class__ != self.right.result_type.__class__: raise errors.EvaluationError('data type mismatch') if self.left.result_type == DataType.FLOAT: if _is_reduced(self.left): _assert_is_natural_number(self.left.evaluate(None)) self.result_type = DataType.FLOAT if self.right.result_type == DataType.FLOAT: if _is_reduced(self.right): _assert_is_natural_number(self.right.evaluate(None)) self.result_type = DataType.FLOAT if isinstance(self.left.result_type, DataType.SET.__class__) or isinstance(self.right.result_type, DataType.SET.__class__): self.result_type = DataType.SET # this discards the member type info def _op_bitwise(self, op, thing): left = self.left.evaluate(thing) if DataType.from_value(left) == DataType.FLOAT: return self._op_bitwise_float(op, thing, left) elif isinstance(DataType.from_value(left), DataType.SET.__class__): return self._op_bitwise_set(op, thing, left) raise errors.EvaluationError('data type mismatch') def _op_bitwise_float(self, op, thing, left): _assert_is_natural_number(left) right = self.right.evaluate(thing) _assert_is_natural_number(right) return coerce_value(op(int(left), int(right))) def _op_bitwise_set(self, op, thing, left): right = self.right.evaluate(thing) if not DataType.is_compatible(DataType.from_value(right), DataType.SET): raise errors.EvaluationError('data type mismatch') return op(left, right) _op_bwand = functools.partialmethod(_op_bitwise, operator.and_) _op_bwor = functools.partialmethod(_op_bitwise, operator.or_) _op_bwxor = functools.partialmethod(_op_bitwise, operator.xor) class BitwiseShiftExpression(BitwiseExpression): compatible_types = (DataType.FLOAT,) result_type = DataType.FLOAT def _op_bitwise_shift(self, *args, **kwargs): return self._op_bitwise(*args, **kwargs) _op_bwlsh = functools.partialmethod(_op_bitwise_shift, operator.lshift) _op_bwrsh = functools.partialmethod(_op_bitwise_shift, operator.rshift) class LogicExpression(LeftOperatorRightExpressionBase): """A class for representing logical expressions from the grammar text such as "and" and "or".""" def _op_and(self, thing): return bool(self.left.evaluate(thing) and self.right.evaluate(thing)) def _op_or(self, thing): return bool(self.left.evaluate(thing) or self.right.evaluate(thing)) ################################################################################ # Left-Operator-Right Comparison Expressions ################################################################################ class ComparisonExpression(LeftOperatorRightExpressionBase): """A class for representing comparison expressions from the grammar text such as equality checks.""" def _op_eq(self, thing): left_value = self.left.evaluate(thing) right_value = self.right.evaluate(thing) if type(left_value) is not type(right_value): return False return operator.eq(left_value, right_value) def _op_ne(self, thing): left_value = self.left.evaluate(thing) right_value = self.right.evaluate(thing) if type(left_value) is not type(right_value): return True return operator.ne(left_value, right_value) class ArithmeticComparisonExpression(ComparisonExpression): """ A class for representing arithmetic comparison expressions from the grammar text such as less-than-or-equal-to and greater-than. """ compatible_types = (DataType.ARRAY, DataType.BOOLEAN, DataType.DATETIME, DataType.TIMEDELTA, DataType.FLOAT, DataType.NULL, DataType.STRING) def __init__(self, *args, **kwargs): super(ArithmeticComparisonExpression, self).__init__(*args, **kwargs) if self.left.result_type != DataType.UNDEFINED and self.right.result_type != DataType.UNDEFINED: if self.left.result_type != self.right.result_type: raise errors.EvaluationError('data type mismatch') def __op_arithmetic(self, op, thing): left_value = self.left.evaluate(thing) right_value = self.right.evaluate(thing) return self.__op_arithmetic_values(op, left_value, right_value) def __op_arithmetic_arrays(self, op, left_value, right_value): for subleft_value, subright_value in zip(left_value, right_value): if self.__op_arithmetic_values(operator.ne, subleft_value, subright_value): return self.__op_arithmetic_values(op, subleft_value, subright_value) if len(left_value) != len(right_value): return self.__op_arithmetic_values(op, len(left_value), len(right_value)) return op in (operator.ge, operator.le) def __op_arithmetic_values(self, op, left_value, right_value): if left_value is None and right_value is None: return op in (operator.ge, operator.le) elif isinstance(left_value, tuple) and isinstance(right_value, tuple): return self.__op_arithmetic_arrays(op, left_value, right_value) elif type(left_value) is not type(right_value): raise errors.EvaluationError('data type mismatch') return op(left_value, right_value) _op_ge = functools.partialmethod(__op_arithmetic, operator.ge) _op_gt = functools.partialmethod(__op_arithmetic, operator.gt) _op_le = functools.partialmethod(__op_arithmetic, operator.le) _op_lt = functools.partialmethod(__op_arithmetic, operator.lt) class FuzzyComparisonExpression(ComparisonExpression): """ A class for representing regular expression comparison expressions from the grammar text such as search and does not match. """ compatible_types = (DataType.NULL, DataType.STRING) def __init__(self, *args, **kwargs): super(FuzzyComparisonExpression, self).__init__(*args, **kwargs) if isinstance(self.right, StringExpression): self._right = self._compile_regex(self.right.evaluate(None)) def _compile_regex(self, regex): try: result = re.compile(regex, flags=self.context.regex_flags) except re.error as error: raise errors.RegexSyntaxError('invalid regular expression', error=error, value=regex) from None return result def __op_regex(self, regex_function, modifier, thing): left = self.left.evaluate(thing) if not isinstance(left, str) and left is not None: raise errors.EvaluationError('data type mismatch') if isinstance(self.right, StringExpression): regex = self._right else: regex = self.right.evaluate(thing) if isinstance(regex, str): regex = self._compile_regex(regex) elif regex is not None: raise errors.EvaluationError('data type mismatch') if left is None or regex is None: return not modifier(left, regex) match = getattr(regex, regex_function)(left) if match is not None: self.context._tls.regex_groups = coerce_value(match.groups()) return modifier(match, None) _op_eq_fzm = functools.partialmethod(__op_regex, 'match', operator.is_not) _op_eq_fzs = functools.partialmethod(__op_regex, 'search', operator.is_not) _op_ne_fzm = functools.partialmethod(__op_regex, 'match', operator.is_) _op_ne_fzs = functools.partialmethod(__op_regex, 'search', operator.is_) ################################################################################ # Miscellaneous Expressions ################################################################################ class ComprehensionExpression(ExpressionBase): result_type = DataType.ARRAY def __init__(self, context, result, variable, iterable, condition=None): self.context = context self.result = result self.variable = variable self.iterable = iterable self.condition = condition self.result_type = DataType.ARRAY(self.result.result_type) @classmethod def build(cls, context, result, variable, iterable, condition=None): iterable = iterable.build() if iterable.result_type is not DataType.UNDEFINED and not iterable.result_type.is_iterable: raise errors.EvaluationError('data type mismatch (comprehension requires an iterable)') assignment = Assignment(variable, value_type=getattr(iterable.result_type, 'iterable_type', DataType.UNDEFINED)) with context.assignments(assignment): if condition is not None: condition = condition.build() result = result.build() return cls(context, result, variable, iterable, condition=condition).reduce() def __repr__(self): return "<{0} iterable={1!r} result={2!r} condition={3!r} >".format(self.__class__.__name__, self.iterable, self.result, self.condition) def evaluate(self, thing): output_array = collections.deque() input_iterable = self.iterable.evaluate(thing) if not DataType.from_value(input_iterable).is_iterable: raise errors.EvaluationError('data type mismatch (comprehension requires an iterable)') for value in input_iterable: assignment = Assignment(self.variable, value=value) with self.context.assignments(assignment): if self.condition is None or self.condition.evaluate(thing): output_array.append(self.result.evaluate(thing)) return tuple(output_array) def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\nvariable={!r}".format(self.__class__.__name__, self.variable)) self.result.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.result)), label='result') self.iterable.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.iterable)), label='iterable') if self.condition is not None: self.condition.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.condition)), label='condition') class ContainsExpression(ExpressionBase): """An expression used to test whether an item exists within a container.""" __slots__ = ('container', 'member') result_type = DataType.BOOLEAN def __init__(self, context, container, member): if container.result_type == DataType.STRING: if member.result_type != DataType.UNDEFINED and member.result_type != DataType.STRING: raise errors.EvaluationError('data type mismatch') elif container.result_type != DataType.UNDEFINED and container.result_type.is_scalar: raise errors.EvaluationError('data type mismatch') self.context = context self.member = member self.container = container @classmethod def build(cls, context, container, member): return cls(context, container.build(), member.build()).reduce() def __repr__(self): return "<{0} container={1!r} member={2!r} >".format(self.__class__.__name__, self.container, self.member) def evaluate(self, thing): container_value = self.container.evaluate(thing) member_value = self.member.evaluate(thing) if DataType.from_value(container_value) == DataType.STRING: if DataType.from_value(member_value) != DataType.STRING: raise errors.EvaluationError('data type mismatch') return bool(member_value in container_value) def reduce(self): if not _is_reduced(self.container, self.member): return self return BooleanExpression(self.context, self.evaluate(None)) def to_graphviz(self, digraph, *args, **kwargs): super(ContainsExpression, self).to_graphviz(digraph, *args, **kwargs) self.container.to_graphviz(digraph, *args, **kwargs) self.member.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.container)), label='container') digraph.edge(str(id(self)), str(id(self.member)), label='member') class GetAttributeExpression(ExpressionBase): """A class representing an expression in which *name* is retrieved as an attribute of *object*.""" __slots__ = ('name', 'object', 'safe') def __init__(self, context, object_, name, safe=False): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param object_: The parent object from which to retrieve the attribute. :param str name: The name of the attribute to retrieve. :param bool safe: Whether or not the safe version should be invoked. .. versionchanged:: 2.4.0 Added the *safe* parameter. """ self.context = context self.object = object_ if self.object.result_type != DataType.UNDEFINED: if not (self.object.result_type == DataType.NULL and safe): try: self.result_type = context.resolve_attribute_type(self.object.result_type, name) except errors.AttributeResolutionError as error: # this is necessary because MAPPING objects can have their keys accessed as attributes if not isinstance(self.object.result_type, DataType.MAPPING.__class__): raise error # leave the result type undefined because the name could be a mapping key or attribute self.name = name self.safe = safe @classmethod def build(cls, context, object_, name, safe=False): return cls(context, object_.build(), name, safe=safe).reduce() def __repr__(self): return "<{0} name={1!r} >".format(self.__class__.__name__, self.name) def evaluate(self, thing): resolved_obj = self.object.evaluate(thing) if resolved_obj is None and self.safe: return resolved_obj attribute_error = None try: value = self.context.resolve_attribute(thing, resolved_obj, self.name) except errors.AttributeResolutionError as error: attribute_error = error else: return self._new_value(value, verify_type=False) try: value = self.context.resolve(resolved_obj, self.name) except errors.SymbolResolutionError as symbol_error: default_value = self.context.default_value if default_value is errors.UNDEFINED: suggestion = attribute_error.suggestion or symbol_error.suggestion if attribute_error.suggestion and symbol_error.suggestion: # if there are two suggestions, select the best one suggestion = suggest_symbol(self.name, (attribute_error.suggestion, symbol_error.suggestion)) attribute_error.suggestion = suggestion raise attribute_error from None value = default_value return self._new_value(value, verify_type=False) def reduce(self): if not _is_reduced(self.object): return self return LiteralExpressionBase.from_value(self.context, self.evaluate(None)) def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\nname={!r}".format(self.__class__.__name__, self.name)) self.object.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.object))) class GetItemExpression(ExpressionBase): """A class representing an expression in which an *item* is retrieved from a container *object*.""" __slots__ = ('container', 'item', 'safe') def __init__(self, context, container, item, safe=False): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param container: The container object from which to retrieve the item. :param str item: The item to retrieve from the container. :param bool safe: Whether or not the safe version should be invoked. .. versionchanged:: 2.4.0 Added the *safe* parameter. """ self.context = context self.container = container if container.result_type == DataType.STRING: if not DataType.is_compatible(item.result_type, DataType.FLOAT): raise errors.EvaluationError('data type mismatch (not an integer number)') self.result_type = DataType.STRING # check against __class__ so the parent class is dynamic in case it changes in the future, what we're doing here # is explicitly checking if result_type is an array with out checking the value_type elif isinstance(container.result_type, DataType.ARRAY.__class__): if not DataType.is_compatible(item.result_type, DataType.FLOAT): raise errors.EvaluationError('data type mismatch (not an integer number)') self.result_type = container.result_type.value_type elif isinstance(container.result_type, DataType.MAPPING.__class__): if not (safe or DataType.is_compatible(item.result_type, container.result_type.key_type)): raise errors.LookupError(errors.UNDEFINED, errors.UNDEFINED) self.result_type = container.result_type.value_type elif isinstance(container.result_type, DataType.SET.__class__): raise errors.EvaluationError('data type mismatch (container is a set)') elif container.result_type != DataType.UNDEFINED: if not (container.result_type == DataType.NULL and safe): raise errors.EvaluationError('data type mismatch') self.item = item self.safe = safe @classmethod def build(cls, context, container, item, safe=False): return cls(context, container.build(), item.build(), safe=safe).reduce() def __repr__(self): return "<{0} container={1!r} item={2!r} >".format(self.__class__.__name__, self.container, self.item) def evaluate(self, thing): resolved_obj = self.container.evaluate(thing) if resolved_obj is None: if self.safe: return resolved_obj raise errors.EvaluationError('data type mismatch (container is null)') resolved_item = self.item.evaluate(thing) if isinstance(resolved_obj, (str, tuple)): _assert_is_integer_number(resolved_item) resolved_item = int(resolved_item) try: value = operator.getitem(resolved_obj, resolved_item) except (IndexError, KeyError): if self.safe: return None raise errors.LookupError(resolved_obj, resolved_item) return self._new_value(value, verify_type=False) def reduce(self): if isinstance(self.container.result_type, DataType.MAPPING.__class__): if self.safe and not DataType.is_compatible(self.item.result_type, self.container.result_type.key_type): return NullExpression(self.context) if _is_reduced(self.container, self.item): return LiteralExpressionBase.from_value(self.context, self.evaluate(None)) return self def to_graphviz(self, digraph, *args, **kwargs): super(GetItemExpression, self).to_graphviz(digraph, *args, **kwargs) self.container.to_graphviz(digraph, *args, **kwargs) self.item.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.container)), label='container') digraph.edge(str(id(self)), str(id(self.item)), label='item') class GetSliceExpression(ExpressionBase): """A class representing an expression in which a range of items is retrieved from a container *object*.""" __slots__ = ('container', 'start', 'stop', 'safe') def __init__(self, context, container, start=None, stop=None, safe=False): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param container: The container object from which to retrieve the item. :param start: The expression that represents the starting index of the slice. :param stop: The expression that represents the stopping index of the slice. :param bool safe: Whether or not the safe version should be invoked. .. versionchanged:: 2.4.0 Added the *safe* parameter. """ self.context = context self.container = container if container.result_type == DataType.STRING: self.result_type = DataType.STRING # check against __class__ so the parent class is dynamic in case it changes in the future, what we're doing here # is explicitly checking if result_type is an array with out checking the value_type elif isinstance(container.result_type, DataType.ARRAY.__class__): self.result_type = container.result_type elif isinstance(container.result_type, DataType.SET.__class__): raise errors.EvaluationError('data type mismatch (container is a set)') elif container.result_type != DataType.UNDEFINED: if not (container.result_type == DataType.NULL and safe): raise errors.EvaluationError('data type mismatch') self.start = start or LiteralExpressionBase.from_value(context, 0) self.stop = stop or LiteralExpressionBase.from_value(context, None) self.safe = safe @classmethod def build(cls, context, container, start=None, stop=None, safe=False): if start is not None: start = start.build() if stop is not None: stop = stop.build() return cls(context, container.build(), start=start, stop=stop, safe=safe).reduce() def __repr__(self): return "<{0} container={1!r} start={2!r} stop={3!r} >".format(self.__class__.__name__, self.container, self.start, self.stop) def evaluate(self, thing): resolved_obj = self.container.evaluate(thing) if resolved_obj is None: if self.safe: return resolved_obj raise errors.EvaluationError('data type mismatch') resolved_start = self.start.evaluate(thing) if resolved_start is not None: _assert_is_integer_number(resolved_start) resolved_start = int(resolved_start) resolved_stop = self.stop.evaluate(thing) if resolved_stop is not None: _assert_is_integer_number(resolved_stop) resolved_stop = int(resolved_stop) value = operator.getitem(resolved_obj, slice(resolved_start, resolved_stop)) return coerce_value(value, verify_type=False) def reduce(self): if not _is_reduced(self.container, self.start, self.stop): return self return LiteralExpressionBase.from_value(self.context, self.evaluate(None)) def to_graphviz(self, digraph, *args, **kwargs): super(GetSliceExpression, self).to_graphviz(digraph, *args, **kwargs) self.container.to_graphviz(digraph, *args, **kwargs) self.start.to_graphviz(digraph, *args, **kwargs) self.stop.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.container)), label='container') digraph.edge(str(id(self)), str(id(self.start)), label='start') digraph.edge(str(id(self)), str(id(self.stop)), label='stop') class SymbolExpression(ExpressionBase): """ A class representing a symbol name to be resolved at evaluation time with the help of a :py:class:`~rule_engine.engine.Context` object. """ __slots__ = ('name', 'result_type', 'scope') def __init__(self, context, name, scope=None): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param str name: The name of the symbol. This will be resolved with a given context object on the specified *thing*. :param str scope: The optional scope to use while resolving the symbol. """ context.symbols.add(name) self.context = context self.name = name type_hint = context.resolve_type(name, scope=scope) if type_hint is not None: self.result_type = type_hint self.scope = scope def __repr__(self): return "<{0} name={1!r} >".format(self.__class__.__name__, self.name) def evaluate(self, thing): try: value = self.context.resolve(thing, self.name, scope=self.scope) except errors.SymbolResolutionError: default_value = self.context.default_value if default_value is errors.UNDEFINED: raise value = default_value value = self._new_value(value, verify_type=False) # if the expected result type is undefined, return the value if self.result_type == DataType.UNDEFINED: return value # use DataType.from_value to raise a TypeError if value is not of a # compatible data type value_type = DataType.from_value(value) # if the type is the expected result type, return the value if DataType.is_compatible(value_type, self.result_type): if self.result_type.is_scalar: return value if self.result_type.value_type == DataType.UNDEFINED: return value if self.result_type.value_type != DataType.NULL and not self.result_type.value_type_nullable and any(v is None for v in value): raise errors.SymbolTypeError(self.name, is_value=value, is_type=value_type, expected_type=self.result_type) if self.result_type.value_type == value_type.value_type: return value # if the type is null, return the value (treat null as a special case) if value_type == DataType.NULL: return value raise errors.SymbolTypeError(self.name, is_value=value, is_type=value_type, expected_type=self.result_type) def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\nname={!r}".format(self.__class__.__name__, self.name)) class FunctionCallExpression(ExpressionBase): __slots__ = ('function', 'arguments',) def __init__(self, context, function, arguments): self.context = context self.function = function if self.function.result_type != DataType.UNDEFINED: function_type = self.function.result_type self._validate_function(function_type, arguments) self.result_type = function_type.return_type self.arguments = arguments @classmethod def build(cls, context, function, arguments): return cls(context, function.build(), tuple(argument.build() for argument in arguments)).reduce() # because there is no syntax for defining a function, they can't be reduced until symbols can be reduced def evaluate(self, thing): function = self.function.evaluate(thing) if not callable(function): raise errors.EvaluationError('data type mismatch (not a callable value)') arguments = tuple(argument.evaluate(thing) for argument in self.arguments) function_name = '' if self.function.result_type != DataType.UNDEFINED: function_type = self.function.result_type function_name = function_type.value_name self._validate_function(function_type, arguments) elif hasattr(function, '__name__'): function_name = function.__name__ + '?' try: result = function(*arguments) except errors.FunctionCallError as error: error.function_name = function_name raise error except Exception as error: raise errors.FunctionCallError('function call failed', error=error, function_name=function_name) from None return self._new_value(result) def _validate_function(self, function_type, arguments): if not isinstance(function_type, DataType.FUNCTION.__class__): raise errors.EvaluationError('data type mismatch (not a callable value)') if function_type.minimum_arguments is not DataType.UNDEFINED: if len(arguments) < function_type.minimum_arguments: raise errors.FunctionCallError( "expected at least {} positional arguments".format(function_type.minimum_arguments), function_name=function_type.value_name ) if function_type.argument_types is not DataType.UNDEFINED: if len(arguments) > len(function_type.argument_types): raise errors.FunctionCallError( "expected at most {} positional arguments".format(len(function_type.argument_types)), function_name=function_type.value_name ) for pos, (arg1, arg2_type) in enumerate(zip(arguments, function_type.argument_types), 1): if isinstance(arg1, ExpressionBase): arg1_type = arg1.result_type else: arg1_type = DataType.from_value(arg1) if not DataType.is_compatible(arg1_type, arg2_type): raise errors.FunctionCallError( "data type mismatch (argument #{})".format(pos), function_name=function_type.value_name ) def to_graphviz(self, digraph, *args, **kwargs): super(FunctionCallExpression, self).to_graphviz(digraph, *args, **kwargs) self.function.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.function)), label='function') for idx, argument in enumerate(self.arguments, 1): argument.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(argument)), label="argument #{}".format(idx)) class Statement(ASTNodeBase): """A class representing the top level statement of the grammar text.""" __slots__ = ('context', 'expression', 'comment') def __init__(self, context, expression, comment=None): """ :param context: The context to use for evaluating the statement. :type context: :py:class:`~rule_engine.engine.Context` :param expression: The top level expression of the statement. :type expression: :py:class:`~.ExpressionBase` """ self.context = context self.expression = expression self.comment = comment @classmethod def build(cls, context, expression, **kwargs): return cls(context, expression.build(), **kwargs).reduce() def evaluate(self, thing): return self.expression.evaluate(thing) def to_graphviz(self, digraph, *args, **kwargs): super(Statement, self).to_graphviz(digraph, *args, **kwargs) self.expression.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.expression))) if self.comment: self.comment.to_graphviz(digraph, *args, **kwargs) class TernaryExpression(ExpressionBase): """ A class for representing ternary expressions from the grammar text. These involve evaluating :py:attr:`.condition` before evaluating either :py:attr:`.case_true` or :py:attr:`.case_false` based on the results. """ def __init__(self, context, condition, case_true, case_false): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param condition: The condition expression whose evaluation determines whether the *case_true* or *case_false* expression is evaluated. :param case_true: The expression that's evaluated when *condition* is True. :param case_false:The expression that's evaluated when *condition* is False. """ self.context = context self.condition = condition self.case_true = case_true self.case_false = case_false if self.case_true.result_type == self.case_false.result_type: self.result_type = self.case_true.result_type elif isinstance(self.case_true.result_type, DataType.ARRAY.__class__) and isinstance(self.case_false.result_type, DataType.ARRAY.__class__): self.result_type = DataType.ARRAY # todo: the other compound types should be checked here as well. @classmethod def build(cls, context, condition, case_true, case_false): return cls(context, condition.build(), case_true.build(), case_false.build()).reduce() def evaluate(self, thing): case = (self.case_true if self.condition.evaluate(thing) else self.case_false) return case.evaluate(thing) def reduce(self): if not _is_reduced(self.condition): return self reduced_condition = bool(self.condition.value) return self.case_true.reduce() if reduced_condition else self.case_false.reduce() def to_graphviz(self, digraph, *args, **kwargs): super(TernaryExpression, self).to_graphviz(digraph, *args, **kwargs) self.condition.to_graphviz(digraph, *args, **kwargs) self.case_true.to_graphviz(digraph, *args, **kwargs) self.case_false.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.condition)), label='condition') digraph.edge(str(id(self)), str(id(self.case_true)), label='true case') digraph.edge(str(id(self)), str(id(self.case_false)), label='false case') class UnaryExpression(ExpressionBase): """ A class for representing unary expressions from the grammar text. These involve a single operator on the left side. """ def __init__(self, context, type_, right): """ :param context: The context to use for evaluating the expression. :type context: :py:class:`~rule_engine.engine.Context` :param str type_: The grammar type of operator to the left of the expression. :param right: The expression to the right of the operator. :type right: :py:class:`~.ExpressionBase` """ self.context = context type_ = type_.lower() self.type = type_ if type_ == 'not': self.result_type = DataType.BOOLEAN elif type_ == 'uminus': self.result_type = right.result_type else: raise ValueError('unknown unary expression type') self._evaluator = getattr(self, '_op_' + type_) self.right = right @classmethod def build(cls, context, type_, right): return cls(context, type_, right.build()).reduce() def __repr__(self): return "<{} type={!r} >".format(self.__class__.__name__, self.type) def evaluate(self, thing): return self._evaluator(thing) def __op(self, op, thing): return op(self.right.evaluate(thing)) _op_not = functools.partialmethod(__op, operator.not_) def __op_arithmetic(self, op, thing): right = self.right.evaluate(thing) if not is_numeric(right) and not isinstance(right, datetime.timedelta): raise errors.EvaluationError('data type mismatch (not a numeric or timedelta value)') return op(right) _op_uminus = functools.partialmethod(__op_arithmetic, operator.neg) def reduce(self): type_ = self.type.lower() if not _is_reduced(self.right): return self if type_ == 'not': return BooleanExpression(self.context, self.evaluate(None)) elif type_ == 'uminus': if isinstance(self.right, FloatExpression): return FloatExpression(self.context, self.evaluate(None)) elif isinstance(self.right, TimedeltaExpression): return TimedeltaExpression(self.context, self.evaluate(None)) raise errors.EvaluationError('data type mismatch (not a float or timedelta expression)') def to_graphviz(self, digraph, *args, **kwargs): digraph.node(str(id(self)), "{}\ntype={!r}".format(self.__class__.__name__, self.type.lower())) self.right.to_graphviz(digraph, *args, **kwargs) digraph.edge(str(id(self)), str(id(self.right))) rule-engine-4.1.0/lib/rule_engine/builtins.py000066400000000000000000000204211446303237000211740ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/builtins.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import collections.abc import datetime import decimal import functools import math import random from ._utils import parse_datetime, parse_float, parse_timedelta from . import ast from . import errors from . import types import dateutil.tz def _builtin_filter(function, iterable): return tuple(filter(function, iterable)) def _builtin_map(function, iterable): return tuple(map(function, iterable)) def _builtin_parse_datetime(builtins, string): return parse_datetime(string, builtins.timezone) def _builtin_random(boundary=None): if boundary: if not types.is_natural_number(boundary): raise errors.FunctionCallError('argument #1 (boundary) must be a natural number') return random.randint(0, int(boundary)) return random.random() def _builtins_split(string, sep=None, maxsplit=None): if maxsplit is None: maxsplit = -1 elif types.is_natural_number(maxsplit): maxsplit = int(maxsplit) else: raise errors.FunctionCallError('argument #3 (maxsplit) must be a natural number') return tuple(string.split(sep=sep, maxsplit=maxsplit)) class BuiltinValueGenerator(object): """ A class used as a wrapper for builtin values to differentiate between a value that is a function and a value that should be generated by calling a function. A value that is generated by calling a function is useful for determining the value during evaluation for things like the current time. .. versionadded:: 4.0.0 """ __slots__ = ('callable',) def __init__(self, callable): self.callable = callable def __call__(self, builtins): return self.callable(builtins) class Builtins(collections.abc.Mapping): """ A class to define and provide variables to within the builtin context of rules. These can be accessed by specifying a symbol name with the ``$`` prefix. """ scope_name = 'built-in' """The identity name of the scope for builtin symbols.""" def __init__(self, values, namespace=None, timezone=None, value_types=None): """ :param dict values: A mapping of string keys to be used as symbol names with values of either Python literals or a function which will be called when the symbol is accessed. When using a function, it will be passed a single argument, which is the instance of :py:class:`Builtins`. :param str namespace: The namespace of the variables to resolve. :param timezone: A timezone to use when resolving timestamps. :type timezone: :py:class:`~datetime.tzinfo` :param dict value_types: A mapping of the values to their datatypes. .. versionchanged:: 2.3.0 Added the *value_types* parameter. """ self.__values = values self.__value_types = value_types or {} self.namespace = namespace self.timezone = timezone or dateutil.tz.tzlocal() def resolve_type(self, name): """ The method to use for resolving the data type of a builtin symbol. :param str name: The name of the symbol to retrieve the data type of. :return: The data type of the symbol or :py:attr:`~rule_engine.ast.DataType.UNDEFINED`. """ return self.__value_types.get(name, ast.DataType.UNDEFINED) def __repr__(self): return "<{} namespace={!r} keys={!r} timezone={!r} >".format(self.__class__.__name__, self.namespace, tuple(self.keys()), self.timezone) def __getitem__(self, name): value = self.__values[name] if isinstance(value, collections.abc.Mapping): if self.namespace is None: namespace = name else: namespace = self.namespace + '.' + name return self.__class__(value, namespace=namespace, timezone=self.timezone) elif callable(value) and isinstance(value, BuiltinValueGenerator): value = value(self) return value def __iter__(self): return iter(self.__values) def __len__(self): return len(self.__values) @classmethod def from_defaults(cls, values=None, **kwargs): """Initialize a :py:class:`Builtins` instance with a set of default values.""" now = BuiltinValueGenerator(lambda builtins: datetime.datetime.now(tz=builtins.timezone)) # there may be errors here if the decimal.Context precision exceeds what is provided by the math constants default_values = { # mathematical constants 'e': decimal.Decimal(repr(math.e)), 'pi': decimal.Decimal(repr(math.pi)), # timestamps 'now': now, 'today': BuiltinValueGenerator(lambda builtins: now(builtins).replace(hour=0, minute=0, second=0, microsecond=0)), # functions 'abs': abs, 'any': any, 'all': all, 'sum': sum, 'map': _builtin_map, 'max': max, 'min': min, 'filter': _builtin_filter, 'parse_datetime': BuiltinValueGenerator(lambda builtins: functools.partial(_builtin_parse_datetime, builtins)), 'parse_float': parse_float, 'parse_timedelta': parse_timedelta, 'random': _builtin_random, 'split': _builtins_split } default_values.update(values or {}) default_value_types = { # mathematical constants 'e': ast.DataType.FLOAT, 'pi': ast.DataType.FLOAT, # timestamps 'now': ast.DataType.DATETIME, 'today': ast.DataType.DATETIME, # functions 'abs': ast.DataType.FUNCTION('abs', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.FLOAT,)), 'all': ast.DataType.FUNCTION('all', return_type=ast.DataType.BOOLEAN, argument_types=(ast.DataType.ARRAY,)), 'any': ast.DataType.FUNCTION('any', return_type=ast.DataType.BOOLEAN, argument_types=(ast.DataType.ARRAY,)), 'sum': ast.DataType.FUNCTION('sum', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.ARRAY(ast.DataType.FLOAT),)), 'map': ast.DataType.FUNCTION('map', return_type=ast.DataType.ARRAY, argument_types=(ast.DataType.FUNCTION, ast.DataType.ARRAY)), 'max': ast.DataType.FUNCTION('max', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.ARRAY(ast.DataType.FLOAT),)), 'min': ast.DataType.FUNCTION('min', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.ARRAY(ast.DataType.FLOAT),)), 'filter': ast.DataType.FUNCTION('filter', return_type=ast.DataType.ARRAY, argument_types=(ast.DataType.FUNCTION, ast.DataType.ARRAY)), 'parse_datetime': ast.DataType.FUNCTION('parse_datetime', return_type=ast.DataType.DATETIME, argument_types=(ast.DataType.STRING,)), 'parse_float': ast.DataType.FUNCTION('parse_float', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.STRING,)), 'parse_timedelta': ast.DataType.FUNCTION('parse_timedelta', return_type=ast.DataType.TIMEDELTA, argument_types=(ast.DataType.STRING,)), 'random': ast.DataType.FUNCTION('random', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.FLOAT,), minimum_arguments=0), 'split': ast.DataType.FUNCTION( 'split', return_type=ast.DataType.ARRAY(ast.DataType.STRING), argument_types=(ast.DataType.STRING, ast.DataType.STRING, ast.DataType.FLOAT), minimum_arguments=1 ) } default_value_types.update(kwargs.pop('value_types', {})) return cls(default_values, value_types=default_value_types, **kwargs) rule-engine-4.1.0/lib/rule_engine/debug_ast.py000066400000000000000000000047201446303237000213040ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/debug_ast.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import os from . import __version__ from . import engine def _print_written(file_path): size = os.stat(file_path).st_size print("wrote {:,} bytes to {}".format(size, file_path)) def main(): parser = argparse.ArgumentParser(description='Rule Engine: Debug AST', conflict_handler='resolve') parser.add_argument('output', help='output files') parser.add_argument('-t', '--text', dest='rule_text', help='the rule text to debug') parser.add_argument('-v', '--version', action='version', version=parser.prog + ' Version: ' + __version__) arguments = parser.parse_args() rule_text = arguments.rule_text if not rule_text: rule_text = input('rule > ') rule = engine.Rule(rule_text) digraph = rule.to_graphviz() digraph.save(arguments.output + '.gv') _print_written(arguments.output + '.gv') digraph.render(arguments.output) _print_written(arguments.output + '.pdf') if __name__ == '__main__': main() rule-engine-4.1.0/lib/rule_engine/debug_repl.py000066400000000000000000000111431446303237000214540ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/debug_repl.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import argparse import code import io import os import pprint import re import sys import textwrap import traceback from . import __version__ from . import engine from . import errors def _console_interact(console, *args, **kwargs): # see: https://bugs.python.org/issue34115 stdin = os.dup(0) try: console.interact(*args, **kwargs) except SystemExit: if 'exitmsg' in kwargs: print(kwargs['exitmsg']) sys.stdin = io.TextIOWrapper(io.BufferedReader(io.FileIO(stdin, mode='rb', closefd=False))) def main(): parser = argparse.ArgumentParser(description='Rule Engine: Debug REPL', conflict_handler='resolve') parser.add_argument( '--debug', action='store_true', default=False, help='enable debugging output' ) parser.add_argument( '--edit-console', action='store_true', default=False, help='edit the environment (via an interactive console)' ) parser.add_argument( '--edit-file', metavar='', type=argparse.FileType('r'), help='edit the environment (via a file)' ) parser.add_argument('-v', '--version', action='version', version=parser.prog + ' Version: ' + __version__) arguments = parser.parse_args() context = engine.Context() thing = None if arguments.edit_console or arguments.edit_file: console = code.InteractiveConsole({ 'context': context, 'thing': thing }) if arguments.edit_file: print('executing: ' + arguments.edit_file.name) console.runcode(code.compile_command( arguments.edit_file.read(), filename=arguments.edit_file.name, symbol='exec' )) if arguments.edit_console: _console_interact( console, banner='edit the \'context\' and \'thing\' objects as necessary', exitmsg='exiting the edit console...' ) context = console.locals['context'] thing = console.locals['thing'] debugging = arguments.debug while True: try: rule_text = input('rule > ') except (EOFError, KeyboardInterrupt): break match = re.match(r'\s*#!\s*debug\s*=\s*(\w+)', rule_text) if match: debugging = match.group(1).lower() != 'false' print('# debugging = ' + str(debugging).lower()) continue try: rule = engine.Rule(rule_text, context=context) result = rule.evaluate(thing) except errors.EngineError as error: print("{}: {}".format(error.__class__.__name__, error.message)) if isinstance(error, (errors.AttributeResolutionError, errors.SymbolResolutionError)) and error.suggestion: print("Did you mean '{}'?".format(error.suggestion)) elif isinstance(error, errors.RegexSyntaxError): print(" Regex: {!r}".format(error.error.pattern)) print(" Details: {} at position {}".format(error.error.msg, error.error.pos)) elif isinstance(error, errors.FunctionCallError): if debugging: inner_exception = ''.join(traceback.format_exception( error.error, error.error, error.error.__traceback__ )) print(textwrap.indent(inner_exception, ' ' * 2)) if debugging: traceback.print_exc() except Exception as error: traceback.print_exc() else: print('result: ') pprint.pprint(result, indent=4) if __name__ == '__main__': main() rule-engine-4.1.0/lib/rule_engine/engine.py000066400000000000000000000560441446303237000206220ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/engine.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import collections.abc import contextlib import datetime import decimal import functools import math import re import threading from . import ast from . import builtins from . import errors from . import parser from .suggestions import suggest_symbol import dateutil.tz def _tls_getter(thread_local, key, _builtins): # a function stub to be used with functools.partial for retrieving thread-local values return getattr(thread_local.storage, key) def resolve_attribute(thing, name): """ A replacement resolver function for looking up symbols as members of *thing*. This is effectively the same as ``thing.name``. The *thing* object can be a :py:func:`~collections.namedtuple`, a custom Python class or any other object. Each of the members of *thing* must be of a compatible data type. .. warning:: This effectively exposes all members of *thing*. If any members are sensitive, then a custom resolver should be used that checks *name* against a whitelist of attributes that are allowed to be accessed. :param thing: The object on which the *name* attribute will be accessed. :param str name: The symbol name that is being resolved. :return: The value for the corresponding attribute *name*. """ if not hasattr(thing, name): raise errors.SymbolResolutionError(name, thing=thing, suggestion=suggest_symbol(name, dir(thing))) return getattr(thing, name) def resolve_item(thing, name): """ A resolver function for looking up symbols as items from an object (*thing*) which supports the :py:class:`~collections.abc.Mapping` interface, such as a dictionary. This is effectively the same as ``thing['name']``. Each of the values in *thing* must be of a compatible data type. :param thing: The object from which the *name* item will be accessed. :param str name: The symbol name that is being resolved. :return: The value for the corresponding attribute *name*. """ if not isinstance(thing, collections.abc.Mapping): raise errors.SymbolResolutionError(name, thing=thing) if name not in thing: raise errors.SymbolResolutionError(name, thing=thing, suggestion=suggest_symbol(name, thing.keys())) return thing[name] def _type_resolver(type_map, name): if name not in type_map: raise errors.SymbolResolutionError(name, suggestion=suggest_symbol(name, type_map.keys())) return type_map[name] def _float_op(value, op): if value.is_nan() or value.is_infinite(): return value return op(value) def type_resolver_from_dict(dictionary): """ Return a function suitable for use as the *type_resolver* for a :py:class:`.Context` instance from a dictionary. If any of the values within the dictionary are not of a compatible data type, a :py:exc:`TypeError` will be raised. Additionally, the resulting function will raise a :py:exc:`~rule_engine.errors.SymbolResolutionError` if the symbol name does not exist within the dictionary. :param dict dictionary: A dictionary (or any other object which supports the :py:class:`~collections.abc.Mapping` interface) from which to create the callback function. :return: The callback function. :rtype: function """ type_map = {key: value if ast.DataType.is_definition(value) else ast.DataType.from_value(value) for key, value in dictionary.items()} return functools.partial(_type_resolver, type_map) _AttributeResolverFunction = collections.namedtuple('_AttributeResolverFunction', ('function', 'result_type')) class _AttributeResolver(object): class attribute(object): __slots__ = ('types', 'name', 'result_type') type_map = collections.defaultdict(dict) def __init__(self, name, *data_types, result_type=ast.DataType.UNDEFINED): self.types = data_types self.name = name self.result_type = result_type def __call__(self, function): for type_ in self.types: self.type_map[type_][self.name] = _AttributeResolverFunction(function, self.result_type) return function def __call__(self, thing, object_, name): try: object_type = ast.DataType.from_value(object_) except TypeError: # if the object can't be mapped to a supported type, raise a resolution error raise errors.AttributeResolutionError(name, object_, thing=thing) from None resolver = self._get_resolver(object_type, name, thing=thing) value = resolver.function(self, object_) value = ast.coerce_value(value) if resolver.result_type == ast.DataType.UNDEFINED: return value value_type = ast.DataType.from_value(value) if ast.DataType.is_compatible(resolver.result_type, value_type): return value raise errors.AttributeTypeError(name, object_, is_value=value, is_type=value_type, expected_type=resolver.result_type) def _get_resolver(self, object_type, name, thing=errors.UNDEFINED): for data_type, attribute_resolvers in self.attribute.type_map.items(): if ast.DataType.is_compatible(data_type, object_type): break else: raise errors.AttributeResolutionError(name, object_type, thing=thing) resolver = attribute_resolvers.get(name) if resolver is None: raise errors.AttributeResolutionError(name, object_type, thing=thing, suggestion=suggest_symbol(name, attribute_resolvers.keys())) return resolver def resolve_type(self, object_type, name): """ The method to use for resolving the data type of an attribute. :param object_type: The data type of the object that *name* is an attribute of. :param str name: The name of the attribute to retrieve the data type of. :return: The data type of the specified attribute. """ return self._get_resolver(object_type, name).result_type @attribute('to_epoch', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_to_epoch(self, value): return value.timestamp() @attribute('date', ast.DataType.DATETIME, result_type=ast.DataType.DATETIME) def datetime_date(self, value): return value.replace(hour=0, minute=0, second=0, microsecond=0) @attribute('day', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_day(self, value): return value.day @attribute('hour', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_hour(self, value): return value.hour @attribute('microsecond', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_microsecond(self, value): return value.microsecond @attribute('millisecond', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_millisecond(self, value): return value.microsecond / 1000 @attribute('minute', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_minute(self, value): return value.minute @attribute('month', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_month(self, value): return value.month @attribute('second', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_second(self, value): return value.second @attribute('weekday', ast.DataType.DATETIME, result_type=ast.DataType.STRING) def datetime_weekday(self, value): # use strftime %A so the value is localized return value.strftime('%A') @attribute('year', ast.DataType.DATETIME, result_type=ast.DataType.FLOAT) def datetime_year(self, value): return value.year @attribute('zone_name', ast.DataType.DATETIME, result_type=ast.DataType.STRING) def datetime_zone_name(self, value): return value.tzname() @attribute('days', ast.DataType.TIMEDELTA, result_type=ast.DataType.FLOAT) def timedelta_days(self, value): return value.days @attribute('seconds', ast.DataType.TIMEDELTA, result_type=ast.DataType.FLOAT) def timedelta_seconds(self, value): return value.seconds @attribute('microseconds', ast.DataType.TIMEDELTA, result_type=ast.DataType.FLOAT) def timedelta_microseconds(self, value): return value.microseconds @attribute('total_seconds', ast.DataType.TIMEDELTA, result_type=ast.DataType.FLOAT) def timedelta_total_seconds(self, value): return value.total_seconds() @attribute('ceiling', ast.DataType.FLOAT, result_type=ast.DataType.FLOAT) def float_ceiling(self, value): return _float_op(value, math.ceil) @attribute('floor', ast.DataType.FLOAT, result_type=ast.DataType.FLOAT) def float_floor(self, value): return _float_op(value, math.floor) @attribute('to_str', ast.DataType.FLOAT, result_type=ast.DataType.STRING) def float_to_str(self, value): # keep the string representations consistent for nan, inf, -inf if value.is_nan(): return 'nan' elif value.is_infinite(): if value.is_signed(): return '-inf' else: return 'inf' return str(value) @attribute('keys', ast.DataType.MAPPING, result_type=ast.DataType.ARRAY) def mapping_keys(self, value): return tuple(value.keys()) @attribute('values', ast.DataType.MAPPING, result_type=ast.DataType.ARRAY) def mapping_values(self, value): return tuple(value.values()) @attribute('to_ary', ast.DataType.SET, result_type=ast.DataType.ARRAY) def set_to_ary(self, value): return tuple(value) @attribute('as_lower', ast.DataType.STRING, result_type=ast.DataType.STRING) def string_as_lower(self, value): return value.lower() @attribute('as_upper', ast.DataType.STRING, result_type=ast.DataType.STRING) def string_as_upper(self, value): return value.upper() @attribute('to_ary', ast.DataType.STRING, result_type=ast.DataType.ARRAY(ast.DataType.STRING)) def string_to_ary(self, value): return tuple(value) @attribute('to_flt', ast.DataType.STRING, result_type=ast.DataType.FLOAT) def string_to_flt(self, value): value = value.strip() if re.match(r'-?inf', value): return decimal.Decimal(value) match = re.match(r'^(' + parser.Parser.get_token_regex('FLOAT') + ')$', value) if match is None: return decimal.Decimal('nan') return parser.literal_eval(match.group(0)) @attribute('to_int', ast.DataType.STRING, result_type=ast.DataType.FLOAT) def string_to_int(self, value): value = self.string_to_flt(value) if not ast.is_integer_number(value): raise errors.EvaluationError('data type mismatch (not an integer number)') return value @attribute('is_empty', ast.DataType.ARRAY, ast.DataType.STRING, ast.DataType.MAPPING, ast.DataType.SET, result_type=ast.DataType.BOOLEAN) def value_is_empty(self, value): return len(value) == 0 @attribute('length', ast.DataType.ARRAY, ast.DataType.STRING, ast.DataType.MAPPING, ast.DataType.SET, result_type=ast.DataType.FLOAT) def value_length(self, value): return len(value) @attribute('to_set', ast.DataType.ARRAY, ast.DataType.STRING, result_type=ast.DataType.SET) def value_to_set(self, value): return set(value) class _ThreadLocalStorage(object): """ An object whose attributes are required to be tracked separately among multiple threads. This is to guarantee that if a context is used by one or more rules that are being evaluated simultaneously in multiple threads, that the states are kept isolated. """ __slots__ = ('assignment_scopes', 'regex_groups') def __init__(self): self.assignment_scopes = collections.deque() self.regex_groups = None def reset(self): self.assignment_scopes.clear() self.regex_groups = None class Context(object): """ An object defining the context for a rule's evaluation. This can be used to change the behavior of certain aspects of the rule such as how symbols are resolved and what regex flags should be used. """ def __init__( self, *, regex_flags=0, resolver=None, type_resolver=None, default_timezone='local', default_value=errors.UNDEFINED, decimal_context=None ): """ :param int regex_flags: The flags to provide to functions in the :py:mod:`re` module when calling either the :py:func:`~re.match` or :py:func:`~re.search` functions for comparison expressions. :param resolver: An optional callback function to use in place of :py:meth:`.resolve`. :param type_resolver: An optional callback function to use in place of :py:meth:`.resolve_type`. :type type_resolver: function, dict :param default_timezone: The default timezone to apply to :py:class:`~datetime.datetime` instances which do not have one specified. This is necessary for comparison operations. The value should either be a :py:class:`~datetime.tzinfo` instance, or a string. If *default_timzezone* is a string it must be one of the specially supported (case-insensitive) values of "local" or "utc". :type default_timezone: str, :py:class:`~datetime.tzinfo` :param default_value: The default value to return when resolving either a missing symbol or attribute. :param decimal_context: A specific :py:class:`decimal.Context` object to use for evaluation of ``FLOAT`` values. The default value will be taken from the current thread and will be used by all evaluations using this :py:class:`~rule_engine.engine.Context` regardless of the decimal context of the thread which evaluates the rule. This causes the rule evaluation to be consistent regardless of the calling thread. .. versionchanged:: 2.0.0 Added the *default_value* parameter. .. versionchanged:: 2.1.0 If *type_resolver* is a dictionary, :py:func:`~.type_resolver_from_dict` will be called on it automatically and the result will be used as the callback. .. versionchanged:: 3.0.0 Added the *decimal_context* parameter. """ self.regex_flags = regex_flags """The *regex_flags* parameter from :py:meth:`~__init__`""" self.symbols = set() """ The symbols that are referred to by the rule. Some or all of these will need to be resolved at evaluation time. This attribute can be used after a rule is generated to ensure that all symbols are valid before it is evaluated. """ if isinstance(default_timezone, str): default_timezone = default_timezone.lower() if default_timezone == 'local': default_timezone = dateutil.tz.tzlocal() elif default_timezone == 'utc': default_timezone = dateutil.tz.tzutc() else: raise ValueError('unsupported timezone: ' + default_timezone) elif not isinstance(default_timezone, datetime.tzinfo): raise TypeError('invalid default_timezone type') self._thread_local = threading.local() self.default_timezone = default_timezone """The *default_timezone* parameter from :py:meth:`~__init__`""" self.default_value = default_value """The *default_value* parameter from :py:meth:`~__init__`""" self.builtins = builtins.Builtins.from_defaults( values={'re_groups': builtins.BuiltinValueGenerator(functools.partial(_tls_getter, self._thread_local, 'regex_groups'))}, value_types={'re_groups': ast.DataType.ARRAY(ast.DataType.STRING)}, timezone=default_timezone ) """An instance of :py:class:`~rule_engine.builtins.Builtins` to provided a default set of builtin symbol values.""" self.decimal_context = decimal_context or decimal.getcontext() """The *decimal_context* parameter from :py:meth:`~__init__`""" if isinstance(type_resolver, collections.abc.Mapping): type_resolver = type_resolver_from_dict(type_resolver) self.__type_resolver = type_resolver or (lambda _: ast.DataType.UNDEFINED) self.__resolver = resolver or resolve_item @contextlib.contextmanager def assignments(self, *assignments): """ Add the specified assignments to a thread-specific scope. This is used when an assignment originates from an expression. :param assignments: The one or more assignments to define. :type assignments: :py:class:`~rule_engine.ast.Assignment` """ self._tls.assignment_scopes.append({assign.name: assign for assign in assignments}) try: yield finally: self._tls.assignment_scopes.pop() @property def _tls(self): if not hasattr(self._thread_local, 'storage'): self._thread_local.storage = _ThreadLocalStorage() return self._thread_local.storage def resolve(self, thing, name, scope=None): """ The method to use for resolving symbols names to values. This function must return a compatible value for the specified symbol name. When a *scope* is defined, this function handles the resolution itself, however when the *scope* is ``None`` the resolver specified in :py:meth:`~.Context.__init__` is used which defaults to :py:func:`resolve_item`. If *name* fails to resolve, this method will raise :py:exc:`~rule_engine.errors.SymbolResolutionError`. It is then up to the caller to determine whether or not it is appropriate to use :py:attr:`.default_value`. :param thing: The object from which the *name* item will be accessed. :param str name: The symbol name that is being resolved. :return: The value for the corresponding symbol *name*. """ if scope == builtins.Builtins.scope_name: thing = self.builtins if isinstance(thing, builtins.Builtins): return resolve_item(thing, name) if scope is None: for assignments in self._tls.assignment_scopes: if name in assignments: return assignments[name].value return self.__resolver(thing, name) raise errors.SymbolResolutionError(name, symbol_scope=scope, thing=thing) __resolve_attribute = _AttributeResolver() def resolve_attribute(self, thing, object_, name): """ The method to use for resolving attributes from values. This function must return a compatible value for the specified attribute name. If *name* fails to resolve, this method will raise :py:exc:`~rule_engine.errors.AttributeResolutionError`. It is then up to the caller to determine whether or not it is appropriate to use :py:attr:`.default_value`. :param thing: The object from which the *object_* was retrieved. :param object_: The object from which the *name* attribute will be accessed. :param str name: The attribute name that is being resolved. :return: The value for the corresponding attribute *name*. """ return self.__resolve_attribute(thing, object_, name) resolve_attribute_type = __resolve_attribute.resolve_type def resolve_type(self, name, scope=None): """ A method for providing type hints while the rule is being generated. This can be used to ensure that all symbol names are valid and that the types are appropriate for the operations being performed. It must then return one of the compatible data type constants if the symbol is valid or raise an exception. The default behavior is to return :py:data:`~rule_engine.ast.DataType.UNDEFINED` for all symbols. :param str name: The symbol name to provide a type hint for. :param str scope: An optional scope name that identifies from where to resolve the name. :return: The type of the specified symbol. """ if scope == builtins.Builtins.scope_name: return self.builtins.resolve_type(name) for assignments in self._tls.assignment_scopes: if name in assignments: return assignments[name].value_type return self.__type_resolver(name) class Rule(object): """ A rule which parses a string with a logical expression and can then evaluate an arbitrary object for whether or not it matches based on the constraints of the expression. """ parser = parser.Parser() """ The :py:class:`~rule_engine.parser.Parser` instance that will be used for parsing the rule text into a compatible abstract syntax tree (AST) for evaluation. """ def __init__(self, text, context=None): """ :param str text: The text of the logical expression. :param context: The context to use for evaluating the expression on arbitrary objects. This can be used to change the default behavior. The default context is :py:class:`.Context` but any object providing the same interface (such as a subclass) can be used. :type context: :py:class:`.Context` """ context = context or Context() self.text = text self.context = context self.statement = self.parser.parse(text, context) def __repr__(self): return "<{0} text={1!r} >".format(self.__class__.__name__, self.text) def __str__(self): return self.text def filter(self, things): """ A convenience function for iterating over *things* and yielding each member that :py:meth:`.matches` return True for. :param things: The collection of objects to iterate over. """ yield from (thing for thing in things if self.matches(thing)) @classmethod def is_valid(cls, text, context=None): """ Test whether or not the rule is syntactically correct. This verifies the grammar is well structured and that there are no type compatibility issues regarding literals or symbols with known types (see :py:meth:`~.Context.resolve_type` for specifying symbol type information). :param str text: The text of the logical expression. :param context: The context as would be passed to the :py:meth:`.__init__` method. This can be used for specifying symbol type information. :return: Whether or not the expression is well formed and appears valid. :rtype: bool """ try: cls.parser.parse(text, (context or Context())) except errors.EngineError: return False return True def evaluate(self, thing): """ Evaluate the rule against the specified *thing* and return the value. This can be used to, for example, apply the symbol resolver. :param thing: The object on which to apply the rule. :return: The value the rule evaluates to. Unlike the :py:meth:`.matches` method, this is not necessarily a boolean. """ self.context._tls.reset() with decimal.localcontext(self.context.decimal_context): return self.statement.evaluate(thing) def matches(self, thing): """ Evaluate the rule against the specified *thing*. This will either return whether *thing* matches, or an exception will be raised. :param thing: The object on which to apply the rule. :return: Whether or not the rule matches. :rtype: bool """ return bool(self.evaluate(thing)) def to_graphviz(self): """ Generate a diagram of the parsed rule's AST using GraphViz. :return: The rule diagram. :rtype: :py:class:`graphviz.Digraph` """ import graphviz digraph = graphviz.Digraph(comment=self.text) self.statement.to_graphviz(digraph) return digraph class DebugRule(Rule): parser = None def __init__(self, *args, **kwargs): self.parser = parser.Parser(debug=True) super(DebugRule, self).__init__(*args, **kwargs) rule-engine-4.1.0/lib/rule_engine/errors.py000066400000000000000000000273161446303237000206710ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/errors.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # class _UNDEFINED(object): def __bool__(self): return False __name__ = 'UNDEFINED' __nonzero__ = __bool__ def __repr__(self): return self.__name__ UNDEFINED = _UNDEFINED() """ A sentinel value to specify that something is undefined. When evaluated, the value is falsy. .. versionadded:: 2.0.0 """ class EngineError(Exception): """The base exception class from which other exceptions within this package inherit.""" def __init__(self, message=''): """ :param str message: A text description of what error occurred. """ self.message = message """A text description of what error occurred.""" def __repr__(self): return "<{} message={!r} >".format(self.__class__.__name__, self.message) class EvaluationError(EngineError): """ An error raised for issues which occur while the rule is being evaluated. This can occur at parse time while AST nodes are being evaluated during the reduction phase. """ pass class SyntaxError(EngineError): """A base error for syntax related issues.""" class DatetimeSyntaxError(SyntaxError): """An error raised for issues regarding the use of improperly formatted datetime expressions.""" def __init__(self, message, value): """ :param str message: A text description of what error occurred. :param str value: The datetime value which contains the syntax error which caused this exception to be raised. """ super(DatetimeSyntaxError, self).__init__(message) self.value = value """The datetime value which contains the syntax error which caused this exception to be raised.""" class FloatSyntaxError(SyntaxError): """ An error raised for issues regarding the use of improperly formatted float expressions. .. versionadded:: 4.0.0 """ def __init__(self, message, value): """ :param str message: A text description of what error occurred. :param str value: The float value which contains the syntax error which caused this exception to be raised. """ super(FloatSyntaxError, self).__init__(message) self.value = value """The float value which contains the syntax error which caused this exception to be raised.""" class TimedeltaSyntaxError(SyntaxError): """ An error raised for issues regarding the use of improperly formatted timedelta expressions. .. versionadded:: 3.5.0 """ def __init__(self, message, value): """ :param str message: A text description of what error occurred. :param str value: The timedelta value which contains the syntax error which caused this exception to be raised. """ super(TimedeltaSyntaxError, self).__init__(message) self.value = value """The timedelta value which contains the syntax error which caused this exception to be raised.""" class RegexSyntaxError(SyntaxError): """An error raised for issues regarding the use of improper regular expression syntax.""" def __init__(self, message, error, value): """ :param str message: A text description of what error occurred. :param error: The :py:exc:`re.error` exception from which this error was triggered. :type error: :py:exc:`re.error` :param str value: The regular expression value which contains the syntax error which caused this exception to be raised. """ super(RegexSyntaxError, self).__init__(message) self.error = error """The :py:exc:`re.error` exception from which this error was triggered.""" self.value = value """The regular expression value which contains the syntax error which caused this exception to be raised.""" class RuleSyntaxError(SyntaxError): """An error raised for issues identified while parsing the grammar of the rule text.""" def __init__(self, message, token=None): """ :param str message: A text description of what error occurred. :param token: The PLY token (if available) which is related to the syntax error. """ if token is None: position = 'EOF' else: position = "line {0}:{1}".format(token.lineno, token.lexpos) message = message + ' at: ' + position super(RuleSyntaxError, self).__init__(message) self.token = token """The PLY token (if available) which is related to the syntax error.""" class AttributeResolutionError(EvaluationError): """ An error raised with an attribute can not be resolved to a value. .. versionadded:: 2.0.0 """ def __init__(self, attribute_name, object_, thing=UNDEFINED, suggestion=None): """ :param str attribute_name: The name of the symbol that can not be resolved. :param object_: The value that *attribute_name* was used as an attribute for. :param thing: The root-object that was used to resolve *object*. :param str suggestion: An optional suggestion for a valid attribute name. .. versionchanged:: 3.2.0 Added the *suggestion* parameter. """ self.attribute_name = attribute_name """The name of the symbol that can not be resolved.""" self.object = object_ """The value that *attribute_name* was used as an attribute for.""" self.thing = thing """The root-object that was used to resolve *object*.""" self.suggestion = suggestion """An optional suggestion for a valid attribute name.""" super(AttributeResolutionError, self).__init__("unknown attribute: {0!r}".format(attribute_name)) def __repr__(self): return "<{} message={!r} suggestion={!r} >".format(self.__class__.__name__, self.message, self.suggestion) class AttributeTypeError(EvaluationError): """ An error raised when an attribute with type information is resolved to a Python value that is not of that type. """ def __init__(self, attribute_name, object_type, is_value, is_type, expected_type): """ :param str attribute_name: The name of the symbol that can not be resolved. :param object_type: The value that *attribute_name* was used as an attribute for. :param is_value: The native Python value of the incompatible attribute. :param is_type: The :py:class:`rule-engine type` of the incompatible attribute. :param expected_type: The :py:class:`rule-engine type` that was expected for this attribute. """ self.attribute_name = attribute_name """The name of the attribute that is of an incompatible type.""" self.object_type = object_type """The object on which the attribute was resolved.""" self.is_value = is_value """The native Python value of the incompatible attribute.""" self.is_type = is_type """The :py:class:`rule-engine type` of the incompatible attribute.""" self.expected_type = expected_type """The :py:class:`rule-engine type` that was expected for this attribute.""" message = "attribute {0!r} resolved to incorrect datatype (is: {1}, expected: {2})".format( attribute_name, is_type.name, expected_type.name ) super(AttributeTypeError, self).__init__(message) class LookupError(EvaluationError): """ An error raised when a lookup operation fails to obtain and *item* from a *container*. This is analogous to a combination of Python's builtin :py:exc:`IndexError` and :py:exc:`KeyError` exceptions. .. versionadded:: 2.4.0 """ def __init__(self, container, item): """ :param container: The container object that the lookup was performed on. :param item: The item that was used as either the key or index of *container* for the lookup. """ self.container = container """The container object that the lookup was performed on.""" self.item = item """The item that was used as either the key or index of *container* for the lookup.""" super(LookupError, self).__init__('lookup operation failed') class SymbolResolutionError(EvaluationError): """An error raised when a symbol name is not able to be resolved to a value.""" def __init__(self, symbol_name, symbol_scope=None, thing=UNDEFINED, suggestion=None): """ :param str symbol_name: The name of the symbol that can not be resolved. :param str symbol_scope: The scope of where the symbol should be valid for resolution. :param thing: The root-object that was used to resolve the symbol. :param str suggestion: An optional suggestion for a valid symbol name. .. versionchanged:: 2.0.0 Added the *thing* parameter. .. versionchanged:: 3.2.0 Added the *suggestion* parameter. """ self.symbol_name = symbol_name """The name of the symbol that can not be resolved.""" self.symbol_scope = symbol_scope """The scope of where the symbol should be valid for resolution.""" self.thing = thing """The root-object that was used to resolve the symbol.""" self.suggestion = suggestion """An optional suggestion for a valid symbol name.""" super(SymbolResolutionError, self).__init__("unknown symbol: {0!r}".format(symbol_name)) def __repr__(self): return "<{} message={!r} suggestion={!r} >".format(self.__class__.__name__, self.message, self.suggestion) class SymbolTypeError(EvaluationError): """An error raised when a symbol with type information is resolved to a Python value that is not of that type.""" def __init__(self, symbol_name, is_value, is_type, expected_type): """ :param str symbol_name: The name of the symbol that is of an incompatible type. :param is_value: The native Python value of the incompatible symbol. :param is_type: The :py:class:`rule-engine type` of the incompatible symbol. :param expected_type: The :py:class:`rule-engine type` that was expected for this symbol. """ self.symbol_name = symbol_name """The name of the symbol that is of an incompatible type.""" self.is_value = is_value """The native Python value of the incompatible symbol.""" self.is_type = is_type """The :py:class:`rule-engine type` of the incompatible symbol.""" self.expected_type = expected_type """The :py:class:`rule-engine type` that was expected for this symbol.""" message = "symbol {0!r} resolved to incorrect datatype (is: {1}, expected: {2})".format( symbol_name, is_type.name, expected_type.name ) super(SymbolTypeError, self).__init__(message) class FunctionCallError(EvaluationError): """ An error raised when there is an issue calling a function. .. versionadded:: 4.0.0 """ def __init__(self, message, error=None, function_name=None): super(FunctionCallError, self).__init__(message) self.error = error """The exception from which this error was triggered.""" self.function_name = function_name rule-engine-4.1.0/lib/rule_engine/parser.py000066400000000000000000000442701446303237000206470ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/parser.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import ast as pyast import collections import threading import types as pytypes from . import ast from . import errors from ._utils import timedelta_regex import ply.lex as lex import ply.yacc as yacc literal_eval = pyast.literal_eval class _DeferredAstNode(object): __slots__ = ('cls', 'args', 'kwargs', 'method') def __init__(self, cls, *, args, kwargs=None, method='build'): if not issubclass(cls, ast.ASTNodeBase): raise TypeError('cls is not a subclass of AstNodeBase') self.cls = cls self.args = args self.kwargs = kwargs or {} self.method = method def build(self): constructor = getattr(self.cls, self.method) return constructor(*self.args, **self.kwargs) class ParserBase(object): """ A base class for parser objects to inherit from. This does not provide any grammar related definitions. """ precedence = () """The precedence for operators.""" tokens = () reserved_words = {} """ A mapping of literal words which are reserved to their corresponding grammar names. """ __mutex = threading.Lock() def __init__(self, debug=False): """ :param bool debug: Whether or not to enable debugging features when using the ply API. """ self.debug = debug self.context = None # Build the lexer and parser self._lexer = lex.lex(module=self, debug=self.debug) self._parser = yacc.yacc(module=self, debug=self.debug, write_tables=self.debug) def parse(self, text, context, **kwargs): """ Parse the specified text in an abstract syntax tree of nodes that can later be evaluated. This is done in two phases. First, the syntax is parsed and a tree of deferred / uninitialized AST nodes are constructed. Next each node is built recursively using it's respective :py:meth:`rule_engine.ast.ASTNodeBase.build`. :param str text: The grammar text to parse into an AST. :param context: A context for specifying parsing and evaluation options. :type context: :py:class:`~rule_engine.engine.Context` :return: The parsed AST statement. :rtype: :py:class:`~rule_engine.ast.Statement` """ kwargs['lexer'] = kwargs.pop('lexer', self._lexer) with self.__mutex: self.context = context # phase 1: parse the string into a tree of deferred nodes result = self._parser.parse(text, **kwargs) self.context = None # phase 2: initialize each AST node recursively, providing them with an opportunity to define assignments return result.build() class Parser(ParserBase): """ The parser class for the rule grammar. This class contains many ply specific members to define the various components of the grammar allowing it to be parsed and reduced into an abstract syntax tree (AST). Once the AST has been constructed it can then be evaluated multiple times. To make the evaluation more efficient, nodes within the AST that are able to be reduced are while the parsing is taking place. This reduction phase involves evaluation, causing :py:exc:`~rule_engine.errors.EvaluationError` exceptions to be raised during parsing. """ op_names = { # arithmetic operators '+': 'ADD', '-': 'SUB', '**': 'POW', '*': 'MUL', '/': 'TDIV', '//': 'FDIV', '%': 'MOD', # bitwise operators '&': 'BWAND', '|': 'BWOR', '^': 'BWXOR', '<<': 'BWLSH', '>>': 'BWRSH', # comparison operators '==': 'EQ', '=~': 'EQ_FZM', '=~~': 'EQ_FZS', '!=': 'NE', '!~': 'NE_FZM', '!~~': 'NE_FZS', '>': 'GT', '>=': 'GE', '<': 'LT', '<=': 'LE', # logical operators 'and': 'AND', 'or': 'OR', 'not': 'NOT', 'for': 'FOR', 'if': 'IF', # other operators '.': 'ATTR', '&.': 'ATTR_SAFE', 'in': 'IN', } reserved_words = { # booleans 'true': 'TRUE', 'false': 'FALSE', # float constants 'inf': 'FLOAT_INF', 'nan': 'FLOAT_NAN', # null 'null': 'NULL', # operators 'and': 'AND', 'in': 'IN', 'or': 'OR', 'not': 'NOT', 'for': 'FOR', 'if': 'IF' } tokens = ( 'DATETIME', 'TIMEDELTA', 'FLOAT', 'STRING', 'SYMBOL', 'LPAREN', 'RPAREN', 'QMARK', 'COLON', 'COMMA', 'LBRACKET', 'RBRACKET', 'LBRACE', 'RBRACE', 'COMMENT' ) + tuple(set(list(reserved_words.values()) + list(op_names.values()))) t_ignore = ' \t' # Tokens t_BWAND = r'\&' t_BWOR = r'\|' t_BWXOR = r'\^' t_LPAREN = r'\(' t_RPAREN = r'\)' t_EQ = r'==' t_NE = r'!=' t_QMARK = r'\?' t_COLON = r'\:' t_ADD = r'\+' t_SUB = r'\-' t_MOD = r'\%' t_COMMA = r'\,' t_LBRACKET = r'((?<=\S)&)?\[' t_RBRACKET = r'\]' t_LBRACE = r'\{' t_RBRACE = r'\}' t_FLOAT = r'0(b[01]+|o[0-7]+|x[0-9a-fA-F]+)|[0-9]+(\.[0-9]*)?([eE][+-]?[0-9]+)?|\.[0-9]+([eE][+-]?[0-9]+)?' # attributes must be valid symbol names so the right side is more specific t_ATTR = r'(?<=\S)\.(?=[a-zA-Z_][a-zA-Z0-9_]*)' t_ATTR_SAFE = r'(?<=\S)&\.(?=[a-zA-Z_][a-zA-Z0-9_]*)' # Tokens are listed from highest to lowest precedence, ones that appear # later are effectively evaluated last # see: # * https://en.wikipedia.org/wiki/Order_of_operations#Programming_languages # * https://docs.python.org/3/reference/expressions.html precedence = tuple( # reverse the order to lowest to highest for ply reversed(( ('nonassoc', 'LPAREN', 'RPAREN'), ('left', 'ATTR', 'ATTR_SAFE'), ('right', 'UMINUS'), ('left', 'POW'), ('left', 'MUL', 'TDIV', 'FDIV', 'MOD'), ('left', 'BWLSH', 'BWRSH'), ('left', 'ADD', 'SUB'), ('nonassoc', 'EQ', 'NE', 'EQ_FZM', 'EQ_FZS', 'NE_FZM', 'NE_FZS', 'GE', 'GT', 'LE', 'LT', 'IN'), # Nonassociative operators ('right', 'QMARK', 'COLON'), ('left', 'BWAND'), ('left', 'BWXOR'), ('left', 'BWOR'), ('right', 'NOT'), ('left', 'AND'), ('left', 'OR'), ) )) @classmethod def get_token_regex(cls, token_name): """ Return the regex that is used by the specified token. :param str token_name: The token for which to return the regex. :rtype: str """ obj = getattr(cls, 't_' + token_name, None) if isinstance(obj, str): return obj elif isinstance(obj, pytypes.FunctionType): return obj.__doc__ raise ValueError('unknown token: ' + token_name) def t_POW(self, t): r'\*\*?' if t.value == '*': t.type = 'MUL' return t def t_FDIV(self, t): r'\/\/?' if t.value == '/': t.type = 'TDIV' return t def t_LT(self, t): r'<([=<])?' t.type = {'<': 'LT', '<=': 'LE', '<<': 'BWLSH'}[t.value] return t def t_GT(self, t): r'>([=>])?' t.type = {'>': 'GT', '>=': 'GE', '>>': 'BWRSH'}[t.value] return t def t_EQ_FZS(self, t): r'=~~?' if t.value == '=~': t.type = 'EQ_FZM' return t def t_NE_FZS(self, t): r'!~~?' if t.value == '!~': t.type = 'NE_FZM' return t def t_DATETIME(self, t): r'd(?P["\'])([^\\\n]|(\\.))*?(?P=quote)' t.value = t.value[1:] return t def t_TIMEDELTA(self, t): t.value = t.value[2:-1] return t t_TIMEDELTA.__doc__ = r't(?P["\'])' + timedelta_regex + r'(?P=quote)' def t_STRING(self, t): r's?(?P["\'])([^\\\n]|(\\.))*?(?P=quote)' if t.value[0] == 's': t.value = t.value[1:] return t def t_SYMBOL(self, t): r'\$?[a-zA-Z_][a-zA-Z0-9_]*' if t.value in ('elif', 'else', 'while'): raise errors.RuleSyntaxError("syntax error (the {} keyword is reserved for future use)".format(t.value)) t.type = self.reserved_words.get(t.value, 'SYMBOL') return t def t_COMMENT(self, t): r'\#.*$' return t def t_newline(self, t): r'\n+' t.lexer.lineno += t.value.count("\n") def t_error(self, t): raise errors.RuleSyntaxError("syntax error (illegal character {0!r})".format(t.value[0]), t) # Parsing Rules def p_error(self, token): raise errors.RuleSyntaxError('syntax error', token) def p_statement_expr(self, p): """ statement : expression | expression COMMENT """ kwargs = {} if len(p) == 3: kwargs['comment'] = ast.Comment(p[2][1:].strip()) p[0] = _DeferredAstNode(ast.Statement, args=(self.context, p[1]), kwargs=kwargs) def p_expression_getattr(self, p): """ object : object ATTR SYMBOL | object ATTR_SAFE SYMBOL """ op_name = self.op_names.get(p[2]) p[0] = _DeferredAstNode(ast.GetAttributeExpression, args=(self.context, p[1], p[3]), kwargs={'safe': op_name == 'ATTR_SAFE'}) def p_expression_object(self, p): """ expression : object """ p[0] = p[1] def p_expression_ternary(self, p): """ expression : expression QMARK expression COLON expression """ condition, _, case_true, _, case_false = p[1:6] p[0] = _DeferredAstNode(ast.TernaryExpression, args=(self.context, condition, case_true, case_false)) def p_expression_arithmetic(self, p): """ expression : expression MOD expression | expression MUL expression | expression FDIV expression | expression TDIV expression | expression POW expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.ArithmeticExpression, args=(self.context, op_name, left, right)) def p_expression_add(self, p): """ expression : expression ADD expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.AddExpression, args=(self.context, op_name, left, right)) def p_expression_sub(self, p): """ expression : expression SUB expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.SubtractExpression, args=(self.context, op_name, left, right)) def p_expression_bitwise(self, p): """ expression : expression BWAND expression | expression BWOR expression | expression BWXOR expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.BitwiseExpression, args=(self.context, op_name, left, right)) def p_expression_bitwise_shift(self, p): """ expression : expression BWLSH expression | expression BWRSH expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.BitwiseShiftExpression, args=(self.context, op_name, left, right)) def p_expression_contains(self, p): """ expression : expression IN expression | expression NOT IN expression """ if len(p) == 4: member, _, container = p[1:4] p[0] = _DeferredAstNode(ast.ContainsExpression, args=(self.context, container, member)) else: member, _, _, container = p[1:5] p[0] = _DeferredAstNode(ast.ContainsExpression, args=(self.context, container, member)) p[0] = _DeferredAstNode(ast.UnaryExpression, args=(self.context, 'NOT', p[0])) def p_expression_comparison(self, p): """ expression : expression EQ expression | expression NE expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.ComparisonExpression, args=(self.context, op_name, left, right)) def p_expression_arithmetic_comparison(self, p): """ expression : expression GT expression | expression GE expression | expression LT expression | expression LE expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.ArithmeticComparisonExpression, args=(self.context, op_name, left, right)) def p_expression_fuzzy_comparison(self, p): """ expression : expression EQ_FZM expression | expression EQ_FZS expression | expression NE_FZM expression | expression NE_FZS expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.FuzzyComparisonExpression, args=(self.context, op_name, left, right)) def p_expression_logic(self, p): """ expression : expression AND expression | expression OR expression """ left, op, right = p[1:4] op_name = self.op_names[op] p[0] = _DeferredAstNode(ast.LogicExpression, args=(self.context, op_name, left, right)) def p_expression_group(self, p): 'object : LPAREN expression RPAREN' p[0] = p[2] def p_expression_negate(self, p): 'expression : NOT expression' p[0] = _DeferredAstNode(ast.UnaryExpression, args=(self.context, 'NOT', p[2])) def p_expression_symbol(self, p): 'object : SYMBOL' name = p[1] scope = None if name[0] == '$': scope = 'built-in' name = name[1:] p[0] = _DeferredAstNode(ast.SymbolExpression, args=(self.context, name), kwargs={'scope': scope}) def p_expression_uminus(self, p): 'expression : SUB expression %prec UMINUS' names = {'-': 'UMINUS'} p[0] = _DeferredAstNode(ast.UnaryExpression, args=(self.context, names[p[1]], p[2])) # Literal expressions def p_expression_boolean(self, p): """ expression : TRUE | FALSE """ p[0] = _DeferredAstNode(ast.BooleanExpression, args=(self.context, p[1] == 'true')) def p_expression_datetime(self, p): 'object : DATETIME' p[0] = _DeferredAstNode(ast.DatetimeExpression, args=(self.context, literal_eval(p[1])), method='from_string') def p_expression_timedelta(self, p): 'object : TIMEDELTA' p[0] = _DeferredAstNode(ast.TimedeltaExpression, args=(self.context, p[1]), method='from_string') def p_expression_float(self, p): """ expression : FLOAT | FLOAT_NAN | FLOAT_INF """ str_val = p[1] p[0] = _DeferredAstNode(ast.FloatExpression, args=(self.context, str_val), method='from_string') def p_expression_null(self, p): 'object : NULL' # null is an object because of the safe operator p[0] = _DeferredAstNode(ast.NullExpression, args=(self.context,)) def p_expression_set(self, p): """ object : LBRACE ary_members RBRACE | LBRACE ary_members COMMA RBRACE """ p[0] = _DeferredAstNode(ast.SetExpression, args=(self.context, tuple(p[2]))) def p_expression_string(self, p): 'object : STRING' p[0] = _DeferredAstNode(ast.StringExpression, args=(self.context, literal_eval(p[1]))) def p_expression_array(self, p): """ object : LBRACKET RBRACKET | LBRACKET ary_members RBRACKET | LBRACKET ary_members COMMA RBRACKET """ if len(p) < 4: p[0] = _DeferredAstNode(ast.ArrayExpression, args=(self.context, tuple())) else: p[0] = _DeferredAstNode(ast.ArrayExpression, args=(self.context, tuple(p[2]))) def p_expression_array_comprehension(self, p): """ object : LBRACKET expression FOR SYMBOL IN expression RBRACKET | LBRACKET expression FOR SYMBOL IN expression IF expression RBRACKET """ condition = None if len(p) == 10: condition = p[8] p[0] = _DeferredAstNode(ast.ComprehensionExpression, args=(self.context, p[2], p[4], p[6]), kwargs={'condition': condition}) def p_expression_array_members(self, p): """ ary_members : expression | ary_members COMMA expression """ if len(p) == 2: deque = collections.deque() deque.append(p[1]) else: deque = p[1] deque.append(p[3]) p[0] = deque def p_expression_mapping(self, p): """ object : LBRACE RBRACE | LBRACE map_members RBRACE | LBRACE map_members COMMA RBRACE """ if len(p) < 4: p[0] = _DeferredAstNode(ast.MappingExpression, args=(self.context, tuple())) else: p[0] = _DeferredAstNode(ast.MappingExpression, args=(self.context, tuple(p[2]))) def p_expression_mapping_member(self, p): """ map_member : expression COLON expression """ p[0] = (p[1], p[3]) def p_expression_mapping_members(self, p): """ map_members : map_member | map_members COMMA map_member """ return self.p_expression_array_members(p) def p_expression_getitem(self, p): """ object : object LBRACKET expression RBRACKET """ container, lbracket, item = p[1:4] p[0] = _DeferredAstNode(ast.GetItemExpression, args=(self.context, container, item), kwargs={'safe': lbracket == '&['}) def p_expression_getslice(self, p): """ object : object LBRACKET COLON RBRACKET | object LBRACKET COLON expression RBRACKET | object LBRACKET expression COLON RBRACKET | object LBRACKET expression COLON expression RBRACKET """ container = p[1] safe = p[2] == '&[' colon_index = p[1:].index(':') if colon_index == 2 and len(p) == 5: start, stop = None, None elif colon_index == 2 and len(p) == 6: start, stop = None, p[4] elif colon_index == 3 and len(p) == 6: start, stop = p[3], None elif colon_index == 3 and len(p) == 7: start, _, stop = p[3:6] else: raise errors.RuleSyntaxError('invalid get slice expression') p[0] = _DeferredAstNode(ast.GetSliceExpression, args=(self.context, container, start, stop), kwargs={'safe': safe}) def p_expression_function_call(self, p): """ object : expression LPAREN RPAREN | expression LPAREN ary_members RPAREN """ function = p[1] if len(p) == 4: arguments = collections.deque() elif len(p) == 5: arguments = p[3] else: raise errors.RuleSyntaxError('invalid function call expression') p[0] = _DeferredAstNode(ast.FunctionCallExpression, args=(self.context, function, arguments)) rule-engine-4.1.0/lib/rule_engine/suggestions.py000066400000000000000000000071061446303237000217220ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/suggestions.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import functools import re def jaro_distance(str1, str2): if str1 == str2: return 1.0 str1_len = len(str1) str2_len = len(str2) max_len = max(str1_len, str2_len) match_distance = (max_len // 2) - 1 str1_matches = [False] * max_len str2_matches = [False] * max_len matches = 0.0 for i in range(str1_len): start = max(0, i - match_distance) end = min(i + match_distance, str2_len - 1) + 1 for j in range(start, end): if not str2_matches[j] and str1[i] == str2[j]: str1_matches[i] = True str2_matches[j] = True matches += 1 break if matches == 0.0: return 0.0 k = 0 transpositions = 0.0 for i in range(str1_len): if not str1_matches[i]: continue while not str2_matches[k]: k += 1 if str1[i] != str2[k]: transpositions += 1.0 k += 1 return ((matches / str1_len) + (matches / str2_len) + ((matches - transpositions / 2.0) / matches)) / 3.0 def jaro_winkler_distance(str1, str2, scale=0.1): jaro_dist = jaro_distance(str1, str2) if jaro_dist > 0.7: prefix = 0 while prefix < min(len(str1), len(str2), 5) and str1[prefix] == str2[prefix]: prefix += 1 jaro_dist += scale * prefix * (1 - jaro_dist) return jaro_dist def jaro_winkler_similarity(*args, **kwargs): return 1 - jaro_winkler_distance(*args, **kwargs) def _suggest(word, options): if not len(options): return None return sorted(options, key=functools.partial(jaro_winkler_similarity, word))[0] def suggest_symbol(word, options): """ Select the best match for *word* from a list of value *options*. Values that are not suitable symbol names will be filtered out of *options*. If no match is found, this function will return None. :param str word: The original word to suggest an alternative for. :param tuple options: A list of strings to select the best match from. :return: The best replacement for *word*. :rtype: str """ from .parser import Parser # avoid circular imports symbol_regex = '^' + Parser.get_token_regex('SYMBOL') + '$' return _suggest(word, [option for option in options if re.match(symbol_regex, option)]) rule-engine-4.1.0/lib/rule_engine/types.py000066400000000000000000000540541446303237000205200ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # rule_engine/types.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import collections.abc import datetime import decimal import math from . import errors __all__ = ( 'DataType', 'NoneType', 'coerce_value', 'is_integer_number', 'is_natural_number', 'is_numeric', 'is_real_number', 'iterable_member_value_type' ) _PYTHON_FUNCTION_TYPE = type(lambda: None) NoneType = type(None) def _to_decimal(value): if isinstance(value, decimal.Decimal): return value return decimal.Decimal(repr(value)) def coerce_value(value, verify_type=True): """ Take a native Python *value* and convert it to a value of a data type which can be represented by a Rule Engine :py:class:`~.DataType`. This function is useful for converting native Python values at the engine boundaries such as when resolving a symbol from an object external to the engine. .. versionadded:: 2.0.0 :param value: The value to convert. :param bool verify_type: Whether or not to verify the converted value's type. :return: The converted value. """ # ARRAY if isinstance(value, (list, range, tuple)): value = tuple(coerce_value(v, verify_type=verify_type) for v in value) # DATETIME elif isinstance(value, datetime.date) and not isinstance(value, datetime.datetime): value = datetime.datetime(value.year, value.month, value.day) # FLOAT elif isinstance(value, (float, int)) and not isinstance(value, bool): value = _to_decimal(value) # MAPPING elif isinstance(value, (dict, collections.OrderedDict)): value = collections.OrderedDict( (coerce_value(k, verify_type=verify_type), coerce_value(v, verify_type=verify_type)) for k, v in value.items() ) if verify_type: DataType.from_value(value) # use this to raise a TypeError, if the type is incompatible return value def is_integer_number(value): """ Check whether *value* is an integer number (i.e. a whole, number). This can, for example, be used to check if a floating point number such as ``3.0`` can safely be converted to an integer without loss of information. .. versionadded:: 2.1.0 :param value: The value to check. This value is a native Python type. :return: Whether or not the value is an integer number. :rtype: bool """ if not is_real_number(value): return False if math.floor(value) != value: return False return True def is_natural_number(value): """ Check whether *value* is a natural number (i.e. a whole, non-negative number). This can, for example, be used to check if a floating point number such as ``3.0`` can safely be converted to an integer without loss of information. :param value: The value to check. This value is a native Python type. :return: Whether or not the value is a natural number. :rtype: bool """ if not is_integer_number(value): return False if value < 0: return False return True def is_real_number(value): """ Check whether *value* is a real number (i.e. capable of being represented as a floating point value without loss of information as well as being finite). Despite being able to be represented as a float, ``NaN`` is not considered a real number for the purposes of this function. :param value: The value to check. This value is a native Python type. :return: Whether or not the value is a natural number. :rtype: bool """ if not is_numeric(value): return False if not math.isfinite(value): return False return True def is_numeric(value): """ Check whether *value* is a numeric value (i.e. capable of being represented as a floating point value without loss of information). :param value: The value to check. This value is a native Python type. :return: Whether or not the value is numeric. :rtype: bool """ if not isinstance(value, (decimal.Decimal, float, int)): return False if isinstance(value, bool): return False return True def iterable_member_value_type(python_value): """ Take a native *python_value* and return the corresponding data type of each of its members if the types are either the same or NULL. NULL is considered a special case to allow nullable-values. This by extension means that an iterable may not be defined as only capable of containing NULL values. :return: The data type of the sequence members. This will never be NULL, because that is considered a special case. It will either be UNSPECIFIED or one of the other types. """ subvalue_types = set() for subvalue in python_value: if DataType.is_definition(subvalue): subvalue_type = subvalue else: subvalue_type = DataType.from_value(subvalue) subvalue_types.add(subvalue_type) if DataType.NULL in subvalue_types: # treat NULL as a special case, allowing typed arrays to be a specified type *or* NULL # this however makes it impossible to define an array with a type of NULL subvalue_types.remove(DataType.NULL) if len(subvalue_types) == 1: subvalue_type = subvalue_types.pop() else: subvalue_type = DataType.UNDEFINED return subvalue_type class _DataTypeDef(object): __slots__ = ('name', 'python_type', 'is_scalar', 'iterable_type') def __init__(self, name, python_type): self.name = name self.python_type = python_type self.is_scalar = True if '__call__' in dir(self) and self.__call__.__doc__: # patch the call docs into the top-level class for Sphinx self.__class__.__doc__ = self.__call__.__doc__ @property def is_iterable(self): return getattr(self, 'iterable_type', None) is not None def __eq__(self, other): if not isinstance(other, self.__class__): return False return self.name == other.name def __hash__(self): return hash((self.python_type, self.is_scalar)) def __repr__(self): return "<{} name={} python_type={} >".format(self.__class__.__name__, self.name, self.python_type.__name__) @property def is_compound(self): return not self.is_scalar class _UndefinedDataTypeDef(_DataTypeDef): def __repr__(self): return 'UNDEFINED' _DATA_TYPE_UNDEFINED = _UndefinedDataTypeDef('UNDEFINED', errors.UNDEFINED) class _CollectionDataTypeDef(_DataTypeDef): __slots__ = ('value_type', 'value_type_nullable') def __init__(self, name, python_type, value_type=_DATA_TYPE_UNDEFINED, value_type_nullable=True): # check these three classes individually instead of using Collection which isn't available before Python v3.6 if not issubclass(python_type, collections.abc.Container): raise TypeError('the specified python_type is not a container') if not issubclass(python_type, collections.abc.Iterable): raise TypeError('the specified python_type is not an iterable') if not issubclass(python_type, collections.abc.Sized): raise TypeError('the specified python_type is not a sized') super(_CollectionDataTypeDef, self).__init__(name, python_type) self.is_scalar = False self.value_type = value_type self.value_type_nullable = value_type_nullable @property def iterable_type(self): return self.value_type def __call__(self, value_type, value_type_nullable=True): """ :param value_type: The type of the members. :param bool value_type_nullable: Whether or not members are allowed to be :py:attr:`.NULL`. """ return self.__class__( self.name, self.python_type, value_type=value_type, value_type_nullable=value_type_nullable ) def __repr__(self): return "<{} name={} python_type={} value_type={} >".format( self.__class__.__name__, self.name, self.python_type.__name__, self.value_type.name ) def __eq__(self, other): if not super().__eq__(other): return False return all(( self.value_type == other.value_type, self.value_type_nullable == other.value_type_nullable )) def __hash__(self): return hash((self.python_type, self.is_scalar, hash((self.value_type, self.value_type_nullable)))) class _ArrayDataTypeDef(_CollectionDataTypeDef): pass class _SetDataTypeDef(_CollectionDataTypeDef): pass class _MappingDataTypeDef(_DataTypeDef): __slots__ = ('key_type', 'value_type', 'value_type_nullable') def __init__(self, name, python_type, key_type=_DATA_TYPE_UNDEFINED, value_type=_DATA_TYPE_UNDEFINED, value_type_nullable=True): if not issubclass(python_type, collections.abc.Mapping): raise TypeError('the specified python_type is not a mapping') super(_MappingDataTypeDef, self).__init__(name, python_type) self.is_scalar = False # ARRAY is the only compound data type that can be used as a mapping key, this is because ARRAY's are backed by # Python tuple's while SET and MAPPING objects are set and dict instances, respectively which are not hashable. if key_type.is_compound and not isinstance(key_type, DataType.ARRAY.__class__): raise errors.EngineError("the {} data type may not be used for mapping keys".format(key_type.name)) self.key_type = key_type self.value_type = value_type self.value_type_nullable = value_type_nullable @property def iterable_type(self): return self.key_type def __call__(self, key_type, value_type=_DATA_TYPE_UNDEFINED, value_type_nullable=True): """ :param key_type: The type of the mapping keys. :param value_type: The type of the mapping values. :param bool value_type_nullable: Whether or not mapping values are allowed to be :py:attr:`.NULL`. """ return self.__class__( self.name, self.python_type, key_type=key_type, value_type=value_type, value_type_nullable=value_type_nullable ) def __repr__(self): return "<{} name={} python_type={} key_type={} value_type={} >".format( self.__class__.__name__, self.name, self.python_type.__name__, self.key_type.name, self.value_type.name ) def __eq__(self, other): if not super().__eq__(other): return False return all(( self.key_type == other.key_type, self.value_type == other.value_type, self.value_type_nullable == other.value_type_nullable )) def __hash__(self): return hash((self.python_type, self.is_scalar, hash((self.key_type, self.value_type, self.value_type_nullable)))) class _FunctionDataTypeDef(_DataTypeDef): __slots__ = ('value_name', 'return_type', 'argument_types', 'minimum_arguments') def __init__(self, name, python_type, value_name=None, return_type=_DATA_TYPE_UNDEFINED, argument_types=_DATA_TYPE_UNDEFINED, minimum_arguments=None): super(_FunctionDataTypeDef, self).__init__(name, python_type) self.value_name = value_name self.return_type = return_type if argument_types is _DATA_TYPE_UNDEFINED: if minimum_arguments is None: minimum_arguments = _DATA_TYPE_UNDEFINED else: if not isinstance(argument_types, collections.abc.Sequence): raise TypeError('argument_types must be a sequence (list or tuple)') if minimum_arguments is None: # if arguments are specified, assume that they're all required by default minimum_arguments = len(argument_types) if len(argument_types) < minimum_arguments: raise ValueError('minimum_arguments can not be greater than the length of argument_types') self.argument_types = argument_types self.minimum_arguments = minimum_arguments def __call__(self, name, return_type=_DATA_TYPE_UNDEFINED, argument_types=_DATA_TYPE_UNDEFINED, minimum_arguments=None): """ .. versionadded:: 4.0.0 :param str name: The name of the function, e.g. "split". :param return_type: The data type of the functions return value. :param tuple argument_types: The data types of the functions arguments. :param int minimum_arguments: The minimum number of arguments the function requires. If *argument_types* is specified and *minimum_arguments* is not, then *minimum_arguments* will default to the length of *argument_types* effectively meaning that every defined argument is required. If """ return self.__class__( self.name, self.python_type, value_name=name, return_type=return_type, argument_types=argument_types, minimum_arguments=minimum_arguments ) def __repr__(self): return "<{} name={} python_type={} return_type={} >".format( self.__class__.__name__, self.name, self.python_type.__name__, self.return_type.name ) def __eq__(self, other): if not super().__eq__(other): return False return all(( self.return_type == other.return_type, self.argument_types == other.argument_types, self.minimum_arguments == other.minimum_arguments )) def __hash__(self): return hash((self.python_type, self.is_scalar, hash((self.return_type, self.argument_types, self.minimum_arguments)))) class DataTypeMeta(type): def __new__(metacls, cls, bases, classdict): data_type = super().__new__(metacls, cls, bases, classdict) data_type._member_map_ = collections.OrderedDict() for key, value in classdict.items(): if not isinstance(value, _DataTypeDef): continue data_type._member_map_[key] = value return data_type def __contains__(self, item): return item in self._member_map_ def __getitem__(cls, item): return cls._member_map_[item] def __iter__(cls): yield from cls._member_map_ def __len__(cls): return len(cls._member_map_) class DataType(metaclass=DataTypeMeta): """ A collection of constants representing the different supported data types. There are three ways to compare data types. All three are effectively the same when dealing with scalars. Equality checking .. code-block:: dt == DataType.TYPE This is the most explicit form of testing and when dealing with compound data types, it recursively checks that all of the member types are also equal. Class checking .. code-block:: isinstance(dt, DataType.TYPE.__class__) This checks that the data types are the same but when dealing with compound data types, the member types are ignored. Compatibility checking .. code-block:: DataType.is_compatible(dt, DataType.TYPE) This checks that the types are compatible without any kind of conversion. When dealing with compound data types, this ensures that the member types are either the same or :py:attr:`~.UNDEFINED`. """ ARRAY = staticmethod(_ArrayDataTypeDef('ARRAY', tuple)) BOOLEAN = _DataTypeDef('BOOLEAN', bool) DATETIME = _DataTypeDef('DATETIME', datetime.datetime) FLOAT = _DataTypeDef('FLOAT', decimal.Decimal) FUNCTION = staticmethod(_FunctionDataTypeDef('FUNCTION', _PYTHON_FUNCTION_TYPE)) MAPPING = staticmethod(_MappingDataTypeDef('MAPPING', dict)) NULL = _DataTypeDef('NULL', NoneType) SET = staticmethod(_SetDataTypeDef('SET', set)) STRING = _DataTypeDef('STRING', str) TIMEDELTA = _DataTypeDef('TIMEDELTA', datetime.timedelta) UNDEFINED = _DATA_TYPE_UNDEFINED """ Undefined values. This constant can be used to indicate that a particular symbol is valid, but it's data type is currently unknown. """ @classmethod def from_name(cls, name): """ Get the data type from its name. .. versionadded:: 2.0.0 :param str name: The name of the data type to retrieve. :return: One of the constants. """ if not isinstance(name, str): raise TypeError('from_name argument 1 must be str, not ' + type(name).__name__) dt = getattr(cls, name, None) if not isinstance(dt, _DataTypeDef): raise ValueError("can not map name {0!r} to a compatible data type".format(name)) return dt @classmethod def from_type(cls, python_type): """ Get the supported data type constant for the specified Python type/type hint. If the type or typehint can not be mapped to a supported data type, then a :py:exc:`ValueError` exception will be raised. This function will not return :py:attr:`.UNDEFINED`. :param type python_type: The native Python type or type hint to retrieve the corresponding type constant for. :return: One of the constants. .. versionchanged:: 4.1.0 Added support for typehints. """ if not (isinstance(python_type, type) or hasattr(python_type, '__origin__')): raise TypeError('from_type argument 1 must be a type or a type hint, not ' + type(python_type).__name__) if python_type in (list, range, tuple): return cls.ARRAY elif python_type is bool: return cls.BOOLEAN elif python_type is datetime.date or python_type is datetime.datetime: return cls.DATETIME elif python_type is datetime.timedelta: return cls.TIMEDELTA elif python_type in (decimal.Decimal, float, int): return cls.FLOAT elif python_type is dict: return cls.MAPPING elif python_type is NoneType: return cls.NULL elif python_type is set: return cls.SET elif python_type is str: return cls.STRING elif python_type is _PYTHON_FUNCTION_TYPE: return cls.FUNCTION elif hasattr(python_type, "__origin__"): origin_python_type = python_type.__origin__ maintype = cls.from_type(origin_python_type) if origin_python_type in (list, tuple, set): if hasattr(python_type, "__args__") and origin_python_type is not tuple: valuetype = cls.from_type(python_type.__args__[0]) return maintype(valuetype) if origin_python_type is dict: if hasattr(python_type, "__args__"): key_type = cls.from_type(python_type.__args__[0]) value_type = cls.from_type(python_type.__args__[1]) return maintype(key_type, value_type) return maintype raise ValueError("can not map python type {0!r} to a compatible data type".format(python_type.__name__)) @classmethod def from_value(cls, python_value): """ Get the supported data type constant for the specified Python value. If the value can not be mapped to a supported data type, then a :py:exc:`TypeError` exception will be raised. This function will not return :py:attr:`.UNDEFINED`. :param python_value: The native Python value to retrieve the corresponding data type constant for. :return: One of the constants. """ if isinstance(python_value, bool): return cls.BOOLEAN elif isinstance(python_value, (datetime.date, datetime.datetime)): return cls.DATETIME elif isinstance(python_value, datetime.timedelta): return cls.TIMEDELTA elif isinstance(python_value, (decimal.Decimal, float, int)): return cls.FLOAT elif python_value is None: return cls.NULL elif isinstance(python_value, (set,)): return cls.SET(value_type=iterable_member_value_type(python_value)) elif isinstance(python_value, (str,)): return cls.STRING elif isinstance(python_value, collections.abc.Mapping): return cls.MAPPING( key_type=iterable_member_value_type(python_value.keys()), value_type=iterable_member_value_type(python_value.values()) ) elif isinstance(python_value, collections.abc.Sequence): return cls.ARRAY(value_type=iterable_member_value_type(python_value)) elif callable(python_value): return cls.FUNCTION raise TypeError("can not map python type {0!r} to a compatible data type".format(type(python_value).__name__)) @classmethod def is_compatible(cls, dt1, dt2): """ Check if two data type definitions are compatible without any kind of conversion. This evaluates to ``True`` when one or both are :py:attr:`.UNDEFINED` or both types are the same. In the case of compound data types (such as :py:attr:`.ARRAY`) the member types are checked recursively in the same manner. .. versionadded:: 2.1.0 :param dt1: The first data type to compare. :param dt2: The second data type to compare. :return: Whether or not the two types are compatible. :rtype: bool """ if not (cls.is_definition(dt1) and cls.is_definition(dt2)): raise TypeError('argument is not a data type definition') if dt1 is _DATA_TYPE_UNDEFINED or dt2 is _DATA_TYPE_UNDEFINED: return True if dt1.is_scalar and dt2.is_scalar: if isinstance(dt1, DataType.FUNCTION.__class__) and isinstance(dt2, DataType.FUNCTION.__class__): if not cls.is_compatible(dt1.return_type, dt2.return_type): return False if dt1.argument_types != _DATA_TYPE_UNDEFINED and dt2.argument_types != _DATA_TYPE_UNDEFINED: if len(dt1.argument_types) != len(dt2.argument_types): return False if not all(cls.is_compatible(arg1_dt, arg2_dt) for (arg1_dt, arg2_dt) in zip(dt1.argument_types, dt2.argument_types)): return False if dt1.minimum_arguments != _DATA_TYPE_UNDEFINED and dt2.minimum_arguments != _DATA_TYPE_UNDEFINED: if dt1.minimum_arguments != dt2.minimum_arguments: return False return True return dt1 == dt2 elif dt1.is_compound and dt2.is_compound: if isinstance(dt1, DataType.ARRAY.__class__) and isinstance(dt2, DataType.ARRAY.__class__): return cls.is_compatible(dt1.value_type, dt2.value_type) elif isinstance(dt1, DataType.MAPPING.__class__) and isinstance(dt2, DataType.MAPPING.__class__): if not cls.is_compatible(dt1.key_type, dt2.key_type): return False if not cls.is_compatible(dt1.value_type, dt2.value_type): return False return True elif isinstance(dt1, DataType.SET.__class__) and isinstance(dt2, DataType.SET.__class__): return cls.is_compatible(dt1.value_type, dt2.value_type) return False @classmethod def is_definition(cls, value): """ Check if *value* is a data type definition. .. versionadded:: 2.1.0 :param value: The value to check. :return: ``True`` if *value* is a data type definition. :rtype: bool """ return isinstance(value, _DataTypeDef) rule-engine-4.1.0/setup.py000077500000000000000000000073021446303237000154470ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # setup.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import os import re import sys base_directory = os.path.dirname(__file__) try: from setuptools import setup, find_packages except ImportError: print('This project needs setuptools in order to build. Install it using your package') print('manager (usually python-setuptools) or via pip (pip install setuptools).') sys.exit(1) try: with open(os.path.join(base_directory, 'README.rst')) as file_h: long_description = file_h.read() except OSError: sys.stderr.write('README.rst is unavailable, can not generate the long description\n') long_description = None with open(os.path.join(base_directory, 'lib', 'rule_engine', '__init__.py')) as file_h: match = re.search(r'^__version__\s*=\s*([\'"])(?P\d+(\.\d+)*)\1$', file_h.read(), flags=re.MULTILINE) if match is None: raise RuntimeError('Unable to find the version information') version = match.group('version') DESCRIPTION = """\ A lightweight, optionally typed expression language with a custom grammar for matching arbitrary Python objects.\ """ setup( name='rule-engine', version=version, author='Spencer McIntyre', author_email='zeroSteiner@gmail.com', maintainer='Spencer McIntyre', maintainer_email='zeroSteiner@gmail.com', description=DESCRIPTION, long_description=long_description, long_description_content_type='text/x-rst', url='https://github.com/zeroSteiner/rule-engine', license='BSD', # these are duplicated in requirements.txt install_requires=[ 'ply>=3.9', 'python-dateutil~=2.7' ], package_dir={'': 'lib'}, packages=find_packages('lib'), classifiers=[ 'Development Status :: 5 - Production/Stable', 'Environment :: Console', 'Intended Audience :: Developers', 'License :: OSI Approved :: BSD License', 'Operating System :: OS Independent', #'Programming Language :: Python :: 3.4', # dropped in v4.0 #'Programming Language :: Python :: 3.5', # dropped in v4.0 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', 'Programming Language :: Python :: 3.10', 'Programming Language :: Python :: 3.11', 'Topic :: Software Development :: Libraries :: Python Modules' ] ) rule-engine-4.1.0/tests/000077500000000000000000000000001446303237000150725ustar00rootroot00000000000000rule-engine-4.1.0/tests/__init__.py000066400000000000000000000034111446303237000172020ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/__init__.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # from ._utils import * from .ast import * from .builtins import * from .engine import * from .errors import * from .issues import * from .parser import * from .suggestions import * from .thread_safety import * from .types import * rule-engine-4.1.0/tests/_utils.py000066400000000000000000000023541446303237000167470ustar00rootroot00000000000000import datetime import unittest import rule_engine._utils as utils import rule_engine.errors as errors class UtilityTests(unittest.TestCase): def test_parse_timedelta(self): self.assertEqual(utils.parse_timedelta('PT'), datetime.timedelta()) self.assertEqual(utils.parse_timedelta('P1W'), datetime.timedelta(weeks=1)) self.assertEqual(utils.parse_timedelta('P1D'), datetime.timedelta(days=1)) self.assertEqual(utils.parse_timedelta('PT1H'), datetime.timedelta(hours=1)) self.assertEqual(utils.parse_timedelta('PT1M'), datetime.timedelta(minutes=1)) self.assertEqual(utils.parse_timedelta('PT1S'), datetime.timedelta(seconds=1)) def test_parse_timedelta_error(self): with self.assertRaisesRegex(errors.TimedeltaSyntaxError, 'empty timedelta string'): utils.parse_timedelta('P') with self.assertRaisesRegex(errors.TimedeltaSyntaxError, 'invalid timedelta string'): utils.parse_timedelta('1W') with self.assertRaisesRegex(errors.TimedeltaSyntaxError, 'invalid timedelta string'): utils.parse_timedelta('p1w') with self.assertRaisesRegex(errors.TimedeltaSyntaxError, 'invalid timedelta string'): utils.parse_timedelta('PZ') rule-engine-4.1.0/tests/ast/000077500000000000000000000000001446303237000156615ustar00rootroot00000000000000rule-engine-4.1.0/tests/ast/__init__.py000066400000000000000000000322241446303237000177750ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/__init__.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import unittest from .expression import * import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors import rule_engine.parser as parser inf = float('inf') nan = float('nan') class AstTests(unittest.TestCase): context = engine.Context() thing = {'age': 21.0, 'name': 'Alice'} def test_ast_evaluates_arithmetic_comparisons(self): parser_ = parser.Parser() statement = parser_.parse('age >= 21', self.context) self.assertTrue(statement.evaluate(self.thing)) statement = parser_.parse('age > 100', self.context) self.assertFalse(statement.evaluate(self.thing)) def test_ast_evaluates_logic(self): parser_ = parser.Parser() self.assertTrue(parser_.parse('true and true', self.context).evaluate(None)) self.assertFalse(parser_.parse('true and false', self.context).evaluate(None)) self.assertTrue(parser_.parse('true or false', self.context).evaluate(None)) self.assertFalse(parser_.parse('false or false', self.context).evaluate(None)) def test_ast_evaluates_fuzzy_comparisons(self): parser_ = parser.Parser() statement = parser_.parse('name =~ ".lic."', self.context) self.assertTrue(statement.evaluate(self.thing)) statement = parser_.parse('name =~~ "lic"', self.context) self.assertTrue(statement.evaluate(self.thing)) def test_ast_evaluates_string_comparisons(self): parser_ = parser.Parser() statement = parser_.parse('name == "Alice"', self.context) self.assertTrue(statement.evaluate(self.thing)) statement = parser_.parse('name == "calie"', self.context) self.assertFalse(statement.evaluate(self.thing)) def test_ast_evaluates_unary_not(self): parser_ = parser.Parser() statement = parser_.parse('not false', self.context) self.assertTrue(statement.evaluate(None)) statement = parser_.parse('not true', self.context) self.assertFalse(statement.evaluate(None)) statement = parser_.parse('true and not false', self.context) self.assertTrue(statement.evaluate(None)) statement = parser_.parse('false and not true', self.context) self.assertFalse(statement.evaluate(None)) def test_ast_evaluates_unary_uminus_float(self): parser_ = parser.Parser() statement = parser_.parse('-(2 * 5)', self.context) self.assertEqual(statement.evaluate(None), -10) def test_ast_evaluates_unary_uminus_timedelta(self): parser_ = parser.Parser() statement = parser_.parse('-(t"PT1H" + t"PT6M")', self.context) self.assertEqual(statement.evaluate(None), datetime.timedelta(days=-1, seconds=82440)) def test_ast_raises_type_mismatch_arithmetic_comparisons(self): parser_ = parser.Parser() statement = parser_.parse('symbol < 1', self.context) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': 'string'}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': True}) self.assertTrue(statement.evaluate({'symbol': 0.0})) def test_ast_raises_type_mismatch_bitwise(self): parser_ = parser.Parser() statement = parser_.parse('symbol << 1', self.context) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': 1.1}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': 'string'}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': True}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': inf}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': nan}) self.assertEqual(statement.evaluate({'symbol': 1}), 2) with self.assertRaises(errors.EvaluationError): parser_.parse('symbol << 1.1', self.context) with self.assertRaises(errors.EvaluationError): parser_.parse('symbol << "string"', self.context) with self.assertRaises(errors.EvaluationError): parser_.parse('symbol << true', self.context) with self.assertRaises(errors.EvaluationError): parser_.parse('inf << 1', self.context) with self.assertRaises(errors.EvaluationError): parser_.parse('nan << 1', self.context) def test_ast_raises_type_mismatch_fuzzy_comparisons(self): parser_ = parser.Parser() statement = parser_.parse('symbol =~ "string"', self.context) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': 1.1}) with self.assertRaises(errors.EvaluationError): statement.evaluate({'symbol': True}) self.assertTrue(statement.evaluate({'symbol': 'string'})) with self.assertRaises(errors.EvaluationError): parser_.parse('"string" =~ 1', self.context) with self.assertRaises(errors.EvaluationError): parser_.parse('"string" =~ true', self.context) def test_ast_reduces_add_float(self): thing = {'one': 1, 'two': 2} parser_ = parser.Parser() statement = parser_.parse('1 + 2', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 3) statement = parser_.parse('one + 2', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), 3) statement = parser_.parse('1 + two', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), 3) def test_ast_reduces_add_string(self): thing = {'first': 'Luke', 'last': 'Skywalker'} parser_ = parser.Parser() statement = parser_.parse('"Luke" + "Skywalker"', self.context) self.assertIsInstance(statement.expression, ast.StringExpression) self.assertEqual(statement.evaluate(None), 'LukeSkywalker') statement = parser_.parse('first + "Skywalker"', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), 'LukeSkywalker') statement = parser_.parse('"Luke" + last', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), 'LukeSkywalker') def test_ast_reduces_add_timedelta(self): thing = {'first': datetime.timedelta(seconds=5), 'last': datetime.timedelta(minutes=1)} parser_ = parser.Parser() statement = parser_.parse('t"PT5S" + t"PT1M"', self.context) self.assertIsInstance(statement.expression, ast.TimedeltaExpression) self.assertEqual(statement.evaluate(None), datetime.timedelta(minutes=1, seconds=5)) statement = parser_.parse('first + t"PT1M"', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), datetime.timedelta(minutes=1, seconds=5)) statement = parser_.parse('t"PT5S" + last', self.context) self.assertIsInstance(statement.expression, ast.AddExpression) self.assertEqual(statement.evaluate(thing), datetime.timedelta(minutes=1, seconds=5)) def test_ast_reduces_subtract_float(self): thing = {'one': 1, 'two': 2} parser_ = parser.Parser() statement = parser_.parse('2 - 1', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 1) statement = parser_.parse('two - 1', self.context) self.assertIsInstance(statement.expression, ast.SubtractExpression) self.assertEqual(statement.evaluate(thing), 1) statement = parser_.parse('1 - two', self.context) self.assertIsInstance(statement.expression, ast.SubtractExpression) self.assertEqual(statement.evaluate(thing), -1) def test_ast_reduces_subtract_timedelta(self): thing = {'first': datetime.timedelta(seconds=5), 'last': datetime.timedelta(minutes=1)} parser_ = parser.Parser() statement = parser_.parse('t"PT1M" - t"PT5S"', self.context) self.assertIsInstance(statement.expression, ast.TimedeltaExpression) self.assertEqual(statement.evaluate(None), datetime.timedelta(seconds=55)) statement = parser_.parse('first - t"PT1M"', self.context) self.assertIsInstance(statement.expression, ast.SubtractExpression) self.assertEqual(statement.evaluate(thing), -datetime.timedelta(seconds=55)) statement = parser_.parse('t"PT5S" - last', self.context) self.assertIsInstance(statement.expression, ast.SubtractExpression) self.assertEqual(statement.evaluate(thing), -datetime.timedelta(seconds=55)) def test_ast_reduces_arithmetic(self): thing = {'two': 2, 'four': 4} parser_ = parser.Parser() statement = parser_.parse('2 * 4', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 8) statement = parser_.parse('two * 4', self.context) self.assertIsInstance(statement.expression, ast.ArithmeticExpression) self.assertEqual(statement.evaluate(thing), 8) statement = parser_.parse('2 * four', self.context) self.assertIsInstance(statement.expression, ast.ArithmeticExpression) self.assertEqual(statement.evaluate(thing), 8) def test_ast_reduces_array_literals(self): parser_ = parser.Parser() statement = parser_.parse('[1, 2, 1 + 2]', self.context) self.assertIsInstance(statement.expression, ast.ArrayExpression) self.assertTrue(statement.expression.is_reduced) self.assertEqual(statement.evaluate(None), (1, 2, 3)) statement = parser_.parse('[foobar]', self.context) self.assertIsInstance(statement.expression, ast.ArrayExpression) self.assertFalse(statement.expression.is_reduced) def test_ast_reduces_attributes(self): parser_ = parser.Parser() statement = parser_.parse('"foobar".length', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 6) def test_ast_reduces_bitwise(self): parser_ = parser.Parser() statement = parser_.parse('1 << 2', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 4) def test_ast_reduces_ternary(self): parser_ = parser.Parser() statement = parser_.parse('true ? 1 : 0', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), 1) def test_ast_reduces_unary_uminus_float(self): parser_ = parser.Parser() statement = parser_.parse('-1.0', self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), -1) statement = parser_.parse('-one', self.context) self.assertIsInstance(statement.expression, ast.UnaryExpression) self.assertEqual(statement.evaluate({'one': 1}), -1) def test_ast_reduces_unary_uminus_timedelta(self): parser_ = parser.Parser() statement = parser_.parse('-t"P1D"', self.context) self.assertIsInstance(statement.expression, ast.TimedeltaExpression) self.assertEqual(statement.evaluate(None), datetime.timedelta(days=-1)) statement = parser_.parse('-day', self.context) self.assertIsInstance(statement.expression, ast.UnaryExpression) self.assertEqual(statement.evaluate({'day': datetime.timedelta(days=1)}), datetime.timedelta(days=-1)) def test_ast_type_hints(self): parser_ = parser.Parser() cases = ( # type, type_is, type_is_not ('symbol << 1', ast.DataType.FLOAT, ast.DataType.STRING), ('symbol + 1', ast.DataType.FLOAT, ast.DataType.STRING), ('symbol - 1', ast.DataType.FLOAT, ast.DataType.STRING), ('symbol[1]', ast.DataType.STRING, ast.DataType.FLOAT), ('symbol[1]', ast.DataType.ARRAY, ast.DataType.FLOAT), ('symbol =~ "foo"', ast.DataType.STRING, ast.DataType.FLOAT), ) for case, type_is, type_is_not in cases: parser_.parse(case, self.context) context = engine.Context(type_resolver=engine.type_resolver_from_dict({'symbol': type_is})) parser_.parse(case, context) context = engine.Context(type_resolver=engine.type_resolver_from_dict({'symbol': type_is_not})) with self.assertRaises(errors.EvaluationError, msg='case: ' + case): parser_.parse(case, context) if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/ast/expression/000077500000000000000000000000001446303237000200605ustar00rootroot00000000000000rule-engine-4.1.0/tests/ast/expression/__init__.py000066400000000000000000000033751446303237000222010ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/__init__.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import unittest from .attribute import * from .function_call import * from .left_operator_right import * from .literal import * from .miscellaneous import * if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/ast/expression/attribute.py000066400000000000000000000223251446303237000224410ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/attribute.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import decimal import math import unittest from .literal import context import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors import dateutil.tz __all__ = ('GetAttributeExpressionTests',) class BadAttributeResolver(engine._AttributeResolver): @engine._AttributeResolver.attribute('undefined', ast.DataType.STRING) @engine._AttributeResolver.attribute('unsupported', ast.DataType.STRING, result_type=ast.DataType.BOOLEAN) def string_attribute(self, value): return None class GetAttributeExpressionTests(unittest.TestCase): def test_ast_expression_attribute_error(self): symbol = ast.SymbolExpression(context, 'foo') expression = ast.GetAttributeExpression(context, symbol, 'bar') with self.assertRaises(errors.AttributeResolutionError): expression.evaluate({'foo': 1}) with self.assertRaises(errors.AttributeResolutionError): expression.evaluate({'foo': 'baz'}) def test_ast_expression_attribute_type_error(self): symbol = ast.StringExpression(context, 'foo') expression = ast.GetAttributeExpression(context, symbol, 'undefined') self.assertIsNone(expression.evaluate(None)) expression = ast.GetAttributeExpression(context, symbol, 'unsupported') with self.assertRaises(errors.AttributeTypeError): expression.evaluate(None) def test_ast_expression_attribute_safe(self): symbol = ast.StringExpression(context, 'foo') expression = ast.GetAttributeExpression(context, symbol, 'undefined', safe=True) expression.evaluate(None) expression = ast.GetAttributeExpression(context, ast.NullExpression(context), 'undefined', safe=True) self.assertIsNone(expression.evaluate(None)) def test_ast_expression_array_attributes(self): ary = [1, 2, 3] symbol = ast.SymbolExpression(context, 'ary') attributes = { 'length': len(ary), 'to_set': set(ary) } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate({'ary': ary}), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_datetime_attributes(self): timestamp = datetime.datetime(2019, 9, 11, 20, 46, 57, 506406, tzinfo=dateutil.tz.UTC) symbol = ast.DatetimeExpression(context, timestamp) attributes = { 'to_epoch': decimal.Decimal(str(timestamp.timestamp())), 'day': 11, 'hour': 20, 'microsecond': 506406, 'millisecond': decimal.Decimal('506.406'), 'minute': 46, 'month': 9, 'second': 57, 'weekday': timestamp.strftime('%A'), 'year': 2019, 'zone_name': 'UTC', } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate(None), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_timedelta_attributes(self): timedelta = datetime.timedelta(weeks=7, days=6, hours=5, minutes=4, seconds=3, milliseconds=2, microseconds=1) symbol = ast.TimedeltaExpression(context, timedelta) attributes = { 'days': 55, 'seconds': 18243, 'microseconds': 2001, 'total_seconds': decimal.Decimal('4770243.002001'), } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate(None), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_float_attributes(self): flt = decimal.Decimal('3.14159') symbol = ast.SymbolExpression(context, 'flt') attributes = { 'ceiling': decimal.Decimal('4'), 'floor': decimal.Decimal('3'), 'to_str': '3.14159' } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate({'flt': flt}), value, "attribute {} failed".format(attribute_name)) # check special values too expression = ast.GetAttributeExpression(context, symbol, 'to_str') for value in ('nan', 'inf', '-inf'): flt = decimal.Decimal(value) self.assertEqual(expression.evaluate({'flt': flt}), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_mapping_attributes(self): mapping = dict(one=1, two=2, three=3) symbol = ast.SymbolExpression(context, 'map') attributes = { 'keys': tuple(mapping.keys()), 'is_empty': len(mapping) == 0, 'length': len(mapping), 'values': tuple(mapping.values()), } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate({'map': mapping}), value, "attribute {} failed".format(attribute_name)) # verify that accessing mapping keys as attributes maintains the preference of attributes over keys expression = ast.GetAttributeExpression(context, symbol, 'length') self.assertEqual(expression.evaluate({'map': {'length': -1}}), 1) def test_ast_expression_set_attributes(self): set_ = {1, 2, 3} symbol = ast.SymbolExpression(context, 'set') attributes = { 'length': len(set_), 'to_ary': tuple(set_) } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate({'set': set_}), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_string_attributes(self): string = 'Rule Engine' symbol = ast.StringExpression(context, string) attributes = { 'as_lower': string.lower(), 'as_upper': string.upper(), 'to_ary': tuple(string), 'to_set': set(string), 'length': len(string), } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate(None), value, "attribute {} failed".format(attribute_name)) def test_ast_expression_string_attributes_flt(self): combos = ( ('3.14159', decimal.Decimal('3.14159')), ('0xdead', 0xdead), ('3.14e5', decimal.Decimal('3.14e5')) ) for str_value, flt_value in combos: symbol = ast.StringExpression(context, str_value) expression = ast.GetAttributeExpression(context, symbol, 'to_flt') self.assertEqual(expression.evaluate(None), flt_value, "attribute {} failed".format(str_value)) def test_ast_expression_string_attributes_int(self): tens = ('0b1010', '0o12', '10', '0xa', '1e1') for ten in tens: symbol = ast.StringExpression(context, ten) expression = ast.GetAttributeExpression(context, symbol, 'to_int') self.assertEqual(expression.evaluate(None), 10, "attribute {} failed".format(ten)) symbol = ast.StringExpression(context, '3.14159') expression = ast.GetAttributeExpression(context, symbol, 'to_int') with self.assertRaises(errors.EvaluationError): expression.evaluate(None) def test_ast_expression_string_attributes_numeric(self): symbol = ast.StringExpression(context, '123') attributes = { 'to_int': 123.0, 'to_flt': 123.0, } for attribute_name, value in attributes.items(): expression = ast.GetAttributeExpression(context, symbol, attribute_name) self.assertEqual(expression.evaluate(None), value, "attribute {} failed".format(attribute_name)) expression = ast.GetAttributeExpression(context, ast.StringExpression(context, 'Foobar'), 'to_flt') self.assertTrue(math.isnan(expression.evaluate(None))) with self.assertRaises(errors.EvaluationError): expression = ast.GetAttributeExpression(context, ast.StringExpression(context, 'Foobar'), 'to_int') self.assertEqual(expression.evaluate(None), float('nan')) expression = ast.GetAttributeExpression(context, ast.StringExpression(context, 'inf'), 'to_flt') self.assertEqual(expression.evaluate(None), float('inf')) if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/ast/expression/function_call.py000066400000000000000000000115541446303237000232600ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/function_call.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import unittest from .literal import context import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors __all__ = ( 'FunctionCallExpressionTests', ) class FunctionCallExpressionTests(unittest.TestCase): def test_ast_expression_function_call(self): def _function(): return True symbol = ast.SymbolExpression(context, 'function') function_call = ast.FunctionCallExpression(context, symbol, []) self.assertTrue(function_call.evaluate({'function': _function})) def test_ast_expression_function_call_error_on_function_type_mismatch(self): # function type mismatch with self.assertRaises(errors.EvaluationError): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'function': ast.DataType.NULL }) ) ast.FunctionCallExpression( context, ast.SymbolExpression(context, 'function'), [] ) def test_ast_expression_function_call_error_on_function_argument_type_mismatch(self): # function argument type mismatch with self.assertRaises(errors.EvaluationError): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'function': ast.DataType.FUNCTION( 'function', argument_types=(ast.DataType.FLOAT,) ) }) ) ast.FunctionCallExpression( context, ast.SymbolExpression(context, 'function'), [ast.StringExpression(context, '1')] ) def test_ast_expression_function_call_error_on_uncallable_value(self): context = engine.Context() symbol = ast.SymbolExpression(context, 'function') function_call = ast.FunctionCallExpression(context, symbol, [ast.FloatExpression(context, 1)]) # function is not callable with self.assertRaises(errors.EvaluationError): self.assertTrue(function_call.evaluate({'function': True})) def test_ast_expression_function_call_error_on_to_few_arguments(self): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'function': ast.DataType.FUNCTION( 'function', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.FLOAT, ast.DataType.FLOAT,), minimum_arguments=1 ) }) ) symbol = ast.SymbolExpression(context, 'function') # function is missing arguments with self.assertRaises(errors.FunctionCallError): ast.FunctionCallExpression(context, symbol, []) def test_ast_expression_function_call_error_on_to_many_arguments(self): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'function': ast.DataType.FUNCTION( 'function', return_type=ast.DataType.FLOAT, argument_types=(ast.DataType.FLOAT,), minimum_arguments=1 ) }) ) symbol = ast.SymbolExpression(context, 'function') # function is missing arguments with self.assertRaises(errors.FunctionCallError): ast.FunctionCallExpression(context, symbol, [ ast.FloatExpression(context, 1), ast.FloatExpression(context, 1) ]) def test_ast_expression_function_call_error_on_exception(self): symbol = ast.SymbolExpression(context, 'function') function_call = ast.FunctionCallExpression(context, symbol, [ast.FloatExpression(context, 1)]) # function raises an exception class SomeException(Exception): pass def _function(): raise SomeException() with self.assertRaises(errors.EvaluationError): function_call.evaluate({'function': _function}) rule-engine-4.1.0/tests/ast/expression/left_operator_right.py000066400000000000000000000726341446303237000245100ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/left_operator_right.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import functools import itertools import unittest from .literal import context, trueish, falseish import rule_engine.ast as ast import rule_engine.errors as errors __all__ = ( 'ArithmeticExpressionTests', 'AddExpressionTests', 'AddDatetimeExpressionTests', 'SubtractExpressionTests', 'BitwiseExpressionTests', 'BitwiseExpressionSetTests', 'BitwiseShiftExpressionTests', 'LogicExpressionTests', # comparison expressions 'ComparisonExpressionTests', 'ArithmeticComparisonExpressionTests', 'FuzzyComparisonExpressionTests' ) class LeftOperatorRightExpresisonTestsBase(unittest.TestCase): ExpressionClass = None false_value = False thing = {} def assertExpressionTests(self, operation, left_value=None, right_value=None, equals_value=None): left_value = left_value or self.left_value right_value = right_value or self.right_value equals_value = self.false_value if equals_value is None else equals_value expression = self.ExpressionClass(context, operation, left_value, right_value) self.assertIsInstance(expression, ast.LeftOperatorRightExpressionBase) message = "{0}({1!r} {2} {3!r})".format(self.ExpressionClass.__name__, left_value, operation, right_value) self.assertEqual(expression.evaluate(self.thing), equals_value, msg=message) def test_ast_expression_left_operator_right_operation_error(self): if self.ExpressionClass is None: return unittest.skip('skipped') with self.assertRaisesRegex(errors.EngineError, r'unsupported operator: fake'): self.ExpressionClass(context, 'fake', None, None) ################################################################################ # Left-Operator-Right Expressions ################################################################################ class ArithmeticExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.ArithmeticExpression false_value = 0.0 left_value = two = ast.FloatExpression(context, 2.0) right_value = four = ast.FloatExpression(context, 4.0) def test_ast_expression_left_operator_right_arithmetic(self): self.assertExpressionTests('fdiv', equals_value=0.0) self.assertExpressionTests('tdiv', equals_value=0.5) self.assertExpressionTests('mod', equals_value=2.0) self.assertExpressionTests('mul', equals_value=8.0) self.assertExpressionTests('pow', equals_value=16.0) def test_ast_expression_left_operator_right_arithmetic_type_errors(self): for operation in ('fdiv', 'tdiv', 'mod', 'mul', 'pow'): with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 2.0), ast.StringExpression(context, '4.0')) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.StringExpression(context, '2.0'), ast.FloatExpression(context, 4.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 2.0), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.BooleanExpression(context, True), ast.FloatExpression(context, 4.0)) class AddExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.AddExpression false_value = 0.0 left_value = two = ast.FloatExpression(context, 2.0) right_value = four = ast.FloatExpression(context, 4.0) def test_ast_expression_left_operator_right_add(self): self.assertExpressionTests('add', equals_value=6.0) self.assertExpressionTests('add', left_value=ast.StringExpression(context,'a'), right_value=ast.StringExpression(context,'b'), equals_value='ab') def test_ast_expression_left_operator_right_add_type_errors(self): with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.FloatExpression(context, 2.0), ast.StringExpression(context, '4.0')) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.StringExpression(context, '2.0'), ast.FloatExpression(context, 4.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.FloatExpression(context, 2.0), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.BooleanExpression(context, True), ast.FloatExpression(context, 4.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.BooleanExpression(context, True), ast.StringExpression(context, 'b')) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.StringExpression(context, 'b'), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.DatetimeExpression(context, datetime.datetime.now()), ast.StringExpression(context, 'abc')) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.DatetimeExpression(context, datetime.datetime.now()), ast.FloatExpression(context, 6.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.DatetimeExpression(context, datetime.datetime.now()), ast.BooleanExpression(context, False)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.DatetimeExpression(context, datetime.datetime.now()), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.StringExpression(context, 'abc'), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.FloatExpression(context, 6.0), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.BooleanExpression(context, False), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.TimedeltaExpression(context, datetime.timedelta()), ast.StringExpression(context, 'abc')) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.TimedeltaExpression(context, datetime.timedelta()), ast.FloatExpression(context, 6.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.TimedeltaExpression(context, datetime.timedelta()), ast.BooleanExpression(context, False)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.StringExpression(context, 'abc'), ast.TimedeltaExpression(context, datetime.timedelta())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.FloatExpression(context, 6.0), ast.TimedeltaExpression(context, datetime.timedelta())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('add', ast.BooleanExpression(context, False), ast.TimedeltaExpression(context, datetime.timedelta())) class AddDatetimeExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.AddExpression def test_add_datetime_to_timedelta(self): start_datetime = datetime.datetime(year=2022, month=6, day=28, hour=1, minute=2, second=3) start_datetime_expr = ast.DatetimeExpression(context, start_datetime) assert_func = functools.partial(self.assertExpressionTests, 'add') td_expr_func = functools.partial(ast.TimedeltaExpression, context) assert_func( left_value=start_datetime_expr, right_value=td_expr_func(datetime.timedelta(hours=3, minutes=2, seconds=1)), equals_value=start_datetime.replace(hour=4, minute=4, second=4), ) assert_func( left_value=td_expr_func(datetime.timedelta(days=1, minutes=30, seconds=5)), right_value=start_datetime_expr, equals_value=start_datetime.replace(day=29, minute=32, second=8), ) assert_func( left_value=start_datetime_expr, right_value=ast.TimedeltaExpression(context, datetime.timedelta()), equals_value=start_datetime, ) def test_add_timedeltas(self): assert_func = functools.partial(self.assertExpressionTests, 'add') td_expr_func = functools.partial(ast.TimedeltaExpression, context) assert_func( left_value=td_expr_func(datetime.timedelta(weeks=6, days=5, hours=4, minutes=3, seconds=2)), right_value=td_expr_func(datetime.timedelta(seconds=4)), equals_value=datetime.timedelta(weeks=6, days=5, hours=4, minutes=3, seconds=6), ) assert_func( left_value=td_expr_func(datetime.timedelta()), right_value=td_expr_func(datetime.timedelta(days=6, minutes=25, seconds=42)), equals_value=datetime.timedelta(days=6, minutes=25, seconds=42), ) assert_func( left_value=td_expr_func(datetime.timedelta(hours=4)), right_value=td_expr_func(datetime.timedelta(days=1, seconds=54)), equals_value=datetime.timedelta(days=1, hours=4, seconds=54), ) class SubtractExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.SubtractExpression false_value = 0.0 left_value = ten = ast.FloatExpression(context, 10.0) right_value = five = ast.FloatExpression(context, 5.0) def test_ast_expression_left_operator_right_subtract(self): self.assertExpressionTests('sub', equals_value=5.0) self.assertExpressionTests('sub', left_value=self.right_value, right_value=self.left_value, equals_value=-5.0) def test_ast_expression_left_operator_right_subtract_type_errors(self): with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.FloatExpression(context, 12.0), ast.StringExpression(context, "abc")) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.StringExpression(context, "def"), ast.FloatExpression(context, 4.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.FloatExpression(context, 14.5), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.BooleanExpression(context, False), ast.FloatExpression(context, 9.9)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.DatetimeExpression(context, datetime.datetime.now()), ast.StringExpression(context, "ghi")) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.DatetimeExpression(context, datetime.datetime.now()), ast.FloatExpression(context, 8.4)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.DatetimeExpression(context, datetime.datetime.now()), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.StringExpression(context, "jkl"), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.FloatExpression(context, 7.7), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.BooleanExpression(context, False), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.TimedeltaExpression(context, datetime.timedelta()), ast.DatetimeExpression(context, datetime.datetime.now())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.TimedeltaExpression(context, datetime.timedelta()), ast.StringExpression(context, "ghi")) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.TimedeltaExpression(context, datetime.timedelta()), ast.FloatExpression(context, 8.4)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.TimedeltaExpression(context, datetime.timedelta()), ast.BooleanExpression(context, True)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.StringExpression(context, "jkl"), ast.TimedeltaExpression(context, datetime.timedelta())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.FloatExpression(context, 7.7), ast.TimedeltaExpression(context, datetime.timedelta())) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests('sub', ast.BooleanExpression(context, False), ast.TimedeltaExpression(context, datetime.timedelta())) class SubtractDatetimeExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.SubtractExpression def test_subtract_datetime_from_datetime(self): dt_expr_func = functools.partial(ast.DatetimeExpression, context) start_datetime_expr = dt_expr_func(datetime.datetime(year=2022, month=3, day=15, hour=13, minute=6, second=12)) assert_func = functools.partial(self.assertExpressionTests, 'sub') assert_func( left_value=start_datetime_expr, right_value=dt_expr_func(datetime.datetime(year=2022, month=3, day=12, hour=9, minute=34, second=11)), equals_value=datetime.timedelta(days=3, seconds=12721), ) assert_func( left_value=start_datetime_expr, right_value=dt_expr_func(datetime.datetime(year=2022, month=4, day=2, hour=3, minute=56, second=22)), equals_value=datetime.timedelta(days=-18, seconds=32990), ) def test_subtract_timedelta_from_datetime(self): start_datetime = datetime.datetime(year=2022, month=1, day=24, hour=16, minute=19, second=44) start_datetime_expr = ast.DatetimeExpression(context, start_datetime) assert_func = functools.partial(self.assertExpressionTests, 'sub') td_expr_func = functools.partial(ast.TimedeltaExpression, context) assert_func( left_value=start_datetime_expr, right_value=td_expr_func(datetime.timedelta(days=21, hours=2)), equals_value=start_datetime.replace(day=3, hour=14), ) assert_func( left_value=start_datetime_expr, right_value=td_expr_func(-datetime.timedelta(hours=10, minutes=39, seconds=20)), equals_value=start_datetime.replace(day=25, hour=2, minute=59, second=4), ) def test_subtract_timedelta_from_timedelta(self): assert_func = functools.partial(self.assertExpressionTests, 'sub') td_expr_func = functools.partial(ast.TimedeltaExpression, context) assert_func( left_value=td_expr_func(datetime.timedelta(days=8, minutes=44, seconds=12)), right_value=td_expr_func(datetime.timedelta(seconds=23)), equals_value=datetime.timedelta(days=8, seconds=2629), ) assert_func( left_value=td_expr_func(datetime.timedelta(hours=15, minutes=35)), right_value=td_expr_func(datetime.timedelta(minutes=41, seconds=45)), equals_value=datetime.timedelta(seconds=53595), ) class BitwiseExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.BitwiseExpression false_value = 0.0 left_value = three = ast.FloatExpression(context, 3.0) right_value = five = ast.FloatExpression(context, 5.0) def test_ast_expression_left_operator_right_bitwise(self): self.assertExpressionTests('bwand', equals_value=1.0) self.assertExpressionTests('bwor', equals_value=7.0) self.assertExpressionTests('bwxor', equals_value=6.0) def test_ast_expression_left_operator_right_bitwise_type_errors(self): for operation in ('bwand', 'bwor', 'bwxor'): with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.1), ast.FloatExpression(context, 5.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.0), ast.FloatExpression(context, 5.1)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, -3.0), ast.FloatExpression(context, 5.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.0), ast.FloatExpression(context, -5.0)) for left, right in itertools.product(trueish, falseish): if isinstance(left, ast.FloatExpression) and isinstance(right, ast.FloatExpression): continue with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, left, right) class BitwiseExpressionSetTests(BitwiseExpressionTests): false_value = set() left_value = ast.LiteralExpressionBase.from_value(context, set([1, 2, 3])) right_value = ast.LiteralExpressionBase.from_value(context, set([3, 4, 5])) def test_ast_expression_left_operator_right_bitwise(self): self.assertExpressionTests('bwand', equals_value=set([3])) self.assertExpressionTests('bwor', equals_value=set([1, 2, 3, 4, 5])) self.assertExpressionTests('bwxor', equals_value=set([1, 2, 4, 5])) class BitwiseShiftExpressionTests(BitwiseExpressionTests): ExpressionClass = ast.BitwiseShiftExpression def test_ast_expression_left_operator_right_bitwise(self): self.assertExpressionTests('bwlsh', equals_value=96.0) self.assertExpressionTests('bwrsh', equals_value=0.0) def test_ast_expression_left_operator_right_bitwise_type_errors(self): for operation in ('bwlsh', 'bwrsh'): with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.1), ast.FloatExpression(context, 5.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.0), ast.FloatExpression(context, 5.1)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, -3.0), ast.FloatExpression(context, 5.0)) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, ast.FloatExpression(context, 3.0), ast.FloatExpression(context, -5.0)) for left, right in itertools.product(trueish, falseish): if isinstance(left, ast.FloatExpression) and isinstance(right, ast.FloatExpression): continue with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, left, right) class LogicExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.LogicExpression def test_ast_expression_left_operator_right_logical(self): for operator, left, right in itertools.product(('and', 'or'), trueish, falseish): self.assertExpressionTests(operator, left, right, operator == 'or') for operator, left, right in itertools.product(('and', 'or'), trueish, trueish): self.assertExpressionTests(operator, left, right, True) for operator, left, right in itertools.product(('and', 'or'), falseish, falseish): self.assertExpressionTests(operator, left, right, False) ################################################################################ # Left-Operator-Right Comparison Expressions ################################################################################ class ComparisonExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.ComparisonExpression thing = {'pi': 3.14159} def test_ast_expression_left_operator_right_comparison(self): chain = tuple(itertools.chain( (ast.SymbolExpression(context, 'pi'),), trueish, falseish )) for left, right in itertools.product(chain, chain): self.assertExpressionTests('eq', left, right, left is right) for left, right in itertools.product(chain, chain): self.assertExpressionTests('ne', left, right, left is not right) def test_ast_expression_left_operator_right_comparison_compound(self): names1 = ast.LiteralExpressionBase.from_value(context, ('Alice', 'Bob')) names2 = ast.LiteralExpressionBase.from_value(context, ('Alice', 'Bob', 'Charlie')) self.assertExpressionTests('eq', names1, names1, True) self.assertExpressionTests('eq', names1, names2, False) self.assertExpressionTests('ne', names1, names1, False) self.assertExpressionTests('ne', names1, names2, True) class ArithmeticComparisonExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.ArithmeticComparisonExpression def test_ast_expression_left_operator_right_arithmeticcomparison_array(self): left_expr = ast.LiteralExpressionBase.from_value(context, ((1, 2, 3),)) right_expr = ast.LiteralExpressionBase.from_value(context, ((1, 2, 3),)) self.assertExpressionTests('ge', left_expr, right_expr, True) self.assertExpressionTests('gt', left_expr, right_expr, False) self.assertExpressionTests('le', left_expr, right_expr, True) self.assertExpressionTests('lt', left_expr, right_expr, False) right_expr = ast.LiteralExpressionBase.from_value(context, ((1, 2, 3, 4),)) self.assertExpressionTests('ge', left_expr, right_expr, False) self.assertExpressionTests('gt', left_expr, right_expr, False) self.assertExpressionTests('le', left_expr, right_expr, True) self.assertExpressionTests('lt', left_expr, right_expr, True) def test_ast_expression_left_operator_right_arithmeticcomparison_boolean(self): for left, right in itertools.product([True, False], repeat=2): left_expr = ast.BooleanExpression(context, left) right_expr = ast.BooleanExpression(context, right) self.assertExpressionTests('ge', left_expr, right_expr, left >= right) self.assertExpressionTests('gt', left_expr, right_expr, left > right) self.assertExpressionTests('le', left_expr, right_expr, left <= right) self.assertExpressionTests('lt', left_expr, right_expr, left < right) def test_ast_expression_left_operator_right_arithmeticcomparison_datetime(self): past_date = ast.DatetimeExpression(context, datetime.datetime(2016, 10, 15)) now = ast.DatetimeExpression(context, datetime.datetime.now()) self.assertExpressionTests('ge', past_date, now, False) self.assertExpressionTests('gt', past_date, now, False) self.assertExpressionTests('le', past_date, now, True) self.assertExpressionTests('lt', past_date, now, True) def test_ast_expression_left_operator_right_arithmeticcomparison_timedelta(self): smaller_period = ast.TimedeltaExpression(context, datetime.timedelta(seconds=1)) larger_period = ast.TimedeltaExpression(context, datetime.timedelta(minutes=1)) self.assertExpressionTests('ge', smaller_period, larger_period, False) self.assertExpressionTests('gt', smaller_period, larger_period, False) self.assertExpressionTests('le', smaller_period, larger_period, True) self.assertExpressionTests('lt', smaller_period, larger_period, True) def test_ast_expression_left_operator_right_arithmeticcomparison_float(self): neg_one = ast.FloatExpression(context, -1.0) zero = ast.FloatExpression(context, 0.0) one = ast.FloatExpression(context, 1.0) values = (neg_one, zero, one) for number in values: self.assertExpressionTests('ge', number, zero, number is zero or number is one) self.assertExpressionTests('gt', number, zero, number is one) self.assertExpressionTests('le', number, zero, number is zero or number is neg_one) self.assertExpressionTests('lt', number, zero, number is neg_one) def test_ast_expression_left_operator_right_arithmeticcomparison_null(self): left_expr = ast.NullExpression(context) right_expr = ast.NullExpression(context) self.assertExpressionTests('ge', left_expr, right_expr, True) self.assertExpressionTests('gt', left_expr, right_expr, False) self.assertExpressionTests('le', left_expr, right_expr, True) self.assertExpressionTests('lt', left_expr, right_expr, False) def test_ast_expression_left_operator_right_arithmeticcomparison_string(self): string1 = ast.StringExpression(context, 'abcd') string2 = ast.StringExpression(context, 'ABCD') self.assertExpressionTests('ge', string1, string2, True) self.assertExpressionTests('gt', string1, string2, True) self.assertExpressionTests('le', string1, string2, False) self.assertExpressionTests('lt', string1, string2, False) def test_ast_expression_left_operator_right_arithmeticcomparison_type_errors(self): for operation, left, right in itertools.product(('ge', 'gt', 'le', 'lt'), trueish, falseish): if type(left) is type(right): continue with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, left, right) class FuzzyComparisonExpressionTests(LeftOperatorRightExpresisonTestsBase): ExpressionClass = ast.FuzzyComparisonExpression left_value = luke = ast.StringExpression(context, 'Luke Skywalker') thing = {'darth': 'Vader', 'luke': 'Skywalker', 'zero': 0.0} def test_ast_expression_left_operator_right_fuzzycomparison_literal(self): fuzzy = functools.partial(ast.StringExpression, context) darth = ast.StringExpression(context, 'Darth Vader') self.assertExpressionTests('eq_fzm', right_value=self.luke, equals_value=True) self.assertExpressionTests('eq_fzm', right_value=fuzzy('Skywalker'), equals_value=False) self.assertExpressionTests('eq_fzm', right_value=darth, equals_value=False) self.assertExpressionTests('eq_fzs', right_value=self.luke, equals_value=True) self.assertExpressionTests('eq_fzs', right_value=fuzzy('Skywalker'), equals_value=True) self.assertExpressionTests('eq_fzs', right_value=darth, equals_value=False) self.assertExpressionTests('ne_fzm', right_value=self.luke, equals_value=False) self.assertExpressionTests('ne_fzm', right_value=fuzzy('Skywalker'), equals_value=True) self.assertExpressionTests('ne_fzm', right_value=darth, equals_value=True) self.assertExpressionTests('ne_fzs', right_value=self.luke, equals_value=False) self.assertExpressionTests('ne_fzs', right_value=fuzzy('Skywalker'), equals_value=False) self.assertExpressionTests('ne_fzs', right_value=darth, equals_value=True) def test_ast_expression_left_operator_right_fuzzycomparison_nulls(self): darth = ast.StringExpression(context, 'Darth Vader') null = ast.NullExpression(context) for operation, left, right in itertools.product(('eq_fzm', 'eq_fzs'), (darth, null), (darth, null)): self.assertExpressionTests(operation, left_value=left, right_value=right, equals_value=left is right) for operation, left, right in itertools.product(('ne_fzm', 'ne_fzs'), (darth, null), (darth, null)): self.assertExpressionTests(operation, left_value=left, right_value=right, equals_value=left is not right) def test_ast_expression_left_operator_right_fuzzycomparison_symbolic(self): fuzzy = functools.partial(ast.SymbolExpression, context) darth = ast.SymbolExpression(context, 'darth') self.assertExpressionTests('eq_fzm', right_value=self.luke, equals_value=True) self.assertExpressionTests('eq_fzm', right_value=fuzzy('luke'), equals_value=False) self.assertExpressionTests('eq_fzm', right_value=darth, equals_value=False) self.assertExpressionTests('eq_fzs', right_value=self.luke, equals_value=True) self.assertExpressionTests('eq_fzs', right_value=fuzzy('luke'), equals_value=True) self.assertExpressionTests('eq_fzs', right_value=darth, equals_value=False) self.assertExpressionTests('ne_fzm', right_value=self.luke, equals_value=False) self.assertExpressionTests('ne_fzm', right_value=fuzzy('luke'), equals_value=True) self.assertExpressionTests('ne_fzm', right_value=darth, equals_value=True) self.assertExpressionTests('ne_fzs', right_value=self.luke, equals_value=False) self.assertExpressionTests('ne_fzs', right_value=fuzzy('luke'), equals_value=False) self.assertExpressionTests('ne_fzs', right_value=darth, equals_value=True) def test_ast_expression_left_operator_right_fuzzycomparison_type_errors(self): operations = ('eq_fzm', 'eq_fzs', 'ne_fzm', 'ne_fzs') for operation, left, right in itertools.product(operations, trueish, falseish): if isinstance(left, (ast.NullExpression, ast.StringExpression)) and isinstance(right, (ast.NullExpression, ast.StringExpression)): continue with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, left, right) string = ast.StringExpression(context, 'string') symbol = ast.SymbolExpression(context, 'zero') for operation in operations: with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, string, symbol) with self.assertRaises(errors.EvaluationError): self.assertExpressionTests(operation, symbol, string) def test_ast_expression_left_operator_right_fuzzycomparison_syntax_errors(self): for operation in ('eq_fzm', 'eq_fzs', 'ne_fzm', 'ne_fzs'): try: self.assertExpressionTests(operation, right_value=ast.StringExpression(context, '*')) except errors.RegexSyntaxError as error: self.assertEqual(error.value, '*') else: self.fail('fuzzySyntaxError was not raised') rule-engine-4.1.0/tests/ast/expression/literal.py000066400000000000000000000132661446303237000220760ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/literal.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import decimal import unittest import rule_engine.ast as ast import rule_engine.builtins as builtins import rule_engine.engine as engine import rule_engine.errors as errors __all__ = ('LiteralExpressionTests',) context = engine.Context() context.builtins = builtins.Builtins.from_defaults( {'test': {'one': 1.0, 'two': 2.0}} ) # literal expressions which should evaluate to false falseish = ( ast.ArrayExpression(context, tuple()), ast.BooleanExpression(context, False), ast.TimedeltaExpression(context, datetime.timedelta()), ast.FloatExpression(context, 0.0), ast.NullExpression(context), ast.StringExpression(context, '') ) # literal expressions which should evaluate to true trueish = ( ast.ArrayExpression(context, tuple((ast.NullExpression(context),))), ast.ArrayExpression(context, tuple((ast.FloatExpression(context, 1.0),))), ast.BooleanExpression(context, True), ast.DatetimeExpression(context, datetime.datetime.now()), ast.TimedeltaExpression(context, datetime.timedelta(seconds=1)), ast.FloatExpression(context, float('-inf')), ast.FloatExpression(context, -1.0), ast.FloatExpression(context, 1.0), ast.FloatExpression(context, float('inf')), ast.StringExpression(context, 'non-empty') ) class UnknownType(object): pass class LiteralExpressionTests(unittest.TestCase): context = engine.Context() def assertLiteralTests(self, ExpressionClass, false_value, *true_values): with self.assertRaises(TypeError): ast.StringExpression(self.context, UnknownType()) expression = ExpressionClass(self.context, false_value) self.assertIsInstance(expression, ast.LiteralExpressionBase) self.assertFalse(expression.evaluate(None)) for true_value in true_values: expression = ExpressionClass(self.context, true_value) self.assertTrue(expression.evaluate(None)) def test_ast_expression_literal(self): expressions = ( (ast.ArrayExpression, ()), (ast.BooleanExpression, False), (ast.DatetimeExpression, datetime.datetime(2020, 1, 1)), (ast.TimedeltaExpression, datetime.timedelta(seconds=42)), (ast.FloatExpression, 0), (ast.MappingExpression, {}), (ast.SetExpression, set()), (ast.StringExpression, ''), ) for expression_class, value in expressions: expression = ast.LiteralExpressionBase.from_value(context, value) self.assertIsInstance(expression, expression_class) with self.assertRaises(TypeError): ast.LiteralExpressionBase.from_value(context, object()) def test_ast_expression_literal_array(self): self.assertLiteralTests(ast.ArrayExpression, tuple(), tuple((ast.NullExpression(self.context),))) def test_ast_expression_literal_boolean(self): self.assertLiteralTests(ast.BooleanExpression, False, True) def test_ast_expression_literal_float(self): trueish_floats = (expression.value for expression in trueish if isinstance(expression, ast.FloatExpression)) self.assertLiteralTests(ast.FloatExpression, 0.0, float('nan'), *trueish_floats) # converts ints to floats automatically int_float = ast.FloatExpression(context, 1) self.assertIsInstance(int_float.value, decimal.Decimal) self.assertEqual(int_float.value, 1.0) def test_ast_expression_literal_mapping(self): self.assertLiteralTests(ast.MappingExpression, {}, {ast.StringExpression(context, 'one'): ast.FloatExpression(context, 1)}) with self.assertRaises(errors.EngineError): expression = ast.MappingExpression(context, {ast.MappingExpression(context, {}): ast.NullExpression(context)}) expression = ast.MappingExpression(context, {ast.SymbolExpression(context, 'map'): ast.NullExpression(context)}) with self.assertRaises(errors.EngineError): expression.evaluate({'map': {}}) def test_ast_expression_literal_null(self): expression = ast.NullExpression(self.context) self.assertIsNone(expression.evaluate(None)) with self.assertRaises(TypeError): ast.NullExpression(self.context, False) def test_ast_expression_literal_string(self): self.assertLiteralTests(ast.StringExpression, '', 'non-empty') def test_ast_expression_literal_timedelta(self): with self.assertRaises(errors.TimedeltaSyntaxError): ast.TimedeltaExpression.from_string(self.context, 'INVALID') if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/ast/expression/miscellaneous.py000066400000000000000000000416471446303237000233110ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/ast/expression/miscellaneous.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import decimal import itertools import random import string import unittest from .literal import context, trueish, falseish import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors import rule_engine.types as types import dateutil.tz __all__ = ( 'CommentExpressionTests', 'ComprehensionExpressionTests', 'ContainsExpressionTests', 'GetItemExpressionTests', 'GetSliceExpressionTests', 'SymbolExpressionTests', 'SymbolExpressionConversionTests', 'TernaryExpressionTests', 'UnaryExpressionTests' ) class CommentExpressionTests(unittest.TestCase): def test_ast_expression_comment(self): value = ''.join(random.choice(string.ascii_letters) for _ in range(10)) comment = ast.Comment(value) self.assertIn(value, repr(comment)) class ComprehensionExpressionTests(unittest.TestCase): def test_ast_conditional_comprehension(self): iterable = (None,) iterable_expression = ast.LiteralExpressionBase.from_value(context, iterable) comprehension = ast.ComprehensionExpression( context, ast.NullExpression(context), 'test', iterable_expression, condition=ast.SymbolExpression(context, 'test') ) self.assertEqual(comprehension.evaluate(None), ()) def test_ast_conditional_comprehension_error(self): iterable_expression = ast.SymbolExpression(context, 'iterable') comprehension = ast.ComprehensionExpression( context, ast.NullExpression(context), 'member', iterable_expression ) with self.assertRaises(errors.EvaluationError): comprehension.evaluate({'iterable': None}) def test_ast_unconditional_comprehension(self): iterable = (None,) iterable_expression = ast.LiteralExpressionBase.from_value(context, iterable) comprehension = ast.ComprehensionExpression(context, ast.NullExpression(context), 'test', iterable_expression) self.assertEqual(comprehension.evaluate(None), iterable) def test_ast_comprehension_result_type(self): iterable = (None,) iterable_expression = ast.LiteralExpressionBase.from_value(context, iterable) comprehension = ast.ComprehensionExpression(context, ast.NullExpression(context), 'test', iterable_expression) self.assertEqual(comprehension.result_type, types.DataType.ARRAY(types.DataType.NULL)) comprehension = ast.ComprehensionExpression(context, ast.FloatExpression(context, 1), 'test', iterable_expression) self.assertEqual(comprehension.result_type, types.DataType.ARRAY(types.DataType.FLOAT)) class ContainsExpressionTests(unittest.TestCase): def test_ast_expression_contains(self): container = ast.LiteralExpressionBase.from_value(context, range(3)) member = ast.FloatExpression(context, 1.0) contains = ast.ContainsExpression(context, container, member) self.assertTrue(contains.evaluate(None)) self.assertIsInstance(contains.reduce(), ast.BooleanExpression) member = ast.FloatExpression(context, -1.0) contains = ast.ContainsExpression(context, container, member) self.assertFalse(contains.evaluate(None)) self.assertIsInstance(contains.reduce(), ast.BooleanExpression) container = ast.StringExpression(context, 'Rule Engine') member = ast.StringExpression(context, ' ') self.assertTrue(ast.ContainsExpression(context, container, member).evaluate(None)) member = ast.StringExpression(context, 'x') self.assertFalse(ast.ContainsExpression(context, container, member).evaluate(None)) def test_ast_expression_contains_error(self): container = ast.StringExpression(context, 'Rule Engine') member = ast.FloatExpression(context, 1.0) with self.assertRaises(errors.EvaluationError): ast.ContainsExpression(context, container, member).evaluate(None) container = ast.FloatExpression(context, 1.0) with self.assertRaises(errors.EvaluationError): ast.ContainsExpression(context, container, member).evaluate(None) class GetItemExpressionTests(unittest.TestCase): containers = { types.DataType.ARRAY: ast.LiteralExpressionBase.from_value(context, ['one', 'two']), # ARRAY types.DataType.MAPPING: ast.LiteralExpressionBase.from_value(context, {'foo': 'bar'}), # MAPPING types.DataType.STRING: ast.LiteralExpressionBase.from_value(context, 'Rule Engine!') # STRING } def test_ast_expression_getitem(self): container = self.containers[types.DataType.ARRAY] item_0 = ast.FloatExpression(context, 0.0) get_item = ast.GetItemExpression(context, container, item_0) self.assertEqual(get_item.evaluate(None), 'one') self.assertIsInstance(get_item.reduce(), ast.StringExpression) item_n1 = ast.FloatExpression(context, -1.0) get_item = ast.GetItemExpression(context, container, item_n1) self.assertEqual(get_item.evaluate(None), 'two') self.assertIsInstance(get_item.reduce(), ast.StringExpression) container = self.containers[types.DataType.STRING] get_item = ast.GetItemExpression(context, container, item_0) self.assertEqual(get_item.evaluate(None), 'R') self.assertIsInstance(get_item.reduce(), ast.StringExpression) get_item = ast.GetItemExpression(context, container, item_n1) self.assertEqual(get_item.evaluate(None), '!') self.assertIsInstance(get_item.reduce(), ast.StringExpression) def test_ast_expression_getitem_mapping(self): container = self.containers[types.DataType.MAPPING] item = ast.StringExpression(context, 'foo') get_item = ast.GetItemExpression(context, container, item) self.assertEqual(get_item.evaluate(None), 'bar') self.assertIsInstance(get_item.reduce(), ast.StringExpression) def test_ast_expression_getitem_error(self): for container in self.containers.values(): member = ast.FloatExpression(context, 100.0) with self.assertRaises(errors.LookupError): ast.GetItemExpression(context, container, member).evaluate(None) member = ast.FloatExpression(context, 1.1) with self.assertRaises(errors.EvaluationError): ast.GetItemExpression(context, container, member).evaluate(None) member = ast.NullExpression(context) with self.assertRaises(errors.EvaluationError): ast.GetItemExpression(context, container, member) def test_ast_expression_getitem_safe(self): sym_name = ''.join(random.choice(string.ascii_letters) for _ in range(10)) container = ast.SymbolExpression(context, sym_name) member = ast.FloatExpression(context, 0) get_item = ast.GetItemExpression(context, container, member) with self.assertRaises(errors.EvaluationError): get_item.evaluate({sym_name: None}) get_item = ast.GetItemExpression(context, container, member, safe=True) self.assertIsNone(get_item.evaluate({sym_name: None})) get_item = ast.GetItemExpression(context, container, member, safe=True) self.assertIsNone(get_item.evaluate({sym_name: ''})) def test_ast_expression_getitem_reduces(self): container = ast.MappingExpression(context, (('one', 1), ('two', 2))) member = ast.FloatExpression(context, 0) with self.assertRaises(errors.LookupError): get_item = ast.GetItemExpression(context, container, member) get_item = ast.GetItemExpression(context, container, member, safe=True) self.assertIsInstance(get_item.reduce(), ast.NullExpression) class GetSliceExpressionTests(unittest.TestCase): def test_ast_expression_getslice(self): ary_value = tuple(random.choice(string.ascii_letters) for _ in range(12)) str_value = ''.join(ary_value) cases = ( (ary_value, str_value), (None, 0, 2), (None, -1, -3), ) for container, start, end in itertools.product(*cases): get_slice = ast.GetSliceExpression( context, ast.LiteralExpressionBase.from_value(context, container), start=(None if start is None else ast.LiteralExpressionBase.from_value(context, start)), stop=(None if end is None else ast.LiteralExpressionBase.from_value(context, end)) ) self.assertEqual(get_slice.evaluate({}), container[start:end]) def test_ast_expression_getslice_error(self): with self.assertRaises(errors.EvaluationError): ast.GetSliceExpression(context, ast.LiteralExpressionBase.from_value(context, 1.0)) with self.assertRaises(errors.EvaluationError): ast.GetSliceExpression(context, ast.LiteralExpressionBase.from_value(context, None)) with self.assertRaises(errors.EvaluationError): ast.GetSliceExpression(context, ast.LiteralExpressionBase.from_value(context, True)) def test_ast_expression_getslice_safe(self): sym_name = ''.join(random.choice(string.ascii_letters) for _ in range(10)) container = ast.SymbolExpression(context, sym_name) start = ast.FloatExpression(context, 0) stop = ast.FloatExpression(context, -1) get_slice = ast.GetSliceExpression(context, container, start, stop) with self.assertRaises(errors.EvaluationError): get_slice.evaluate({sym_name: None}) get_slice = ast.GetSliceExpression(context, container, start, stop, safe=True) self.assertIsNone(get_slice.evaluate({sym_name: None})) class SymbolExpressionTests(unittest.TestCase): def setUp(self): self.sym_aryname = ''.join(random.choice(string.ascii_letters) for _ in range(12)) self.sym_aryvalue = [1.0, 2.0] self.sym_aryname_nontyped = ''.join(random.choice(string.ascii_letters) for _ in range(12)) self.sym_aryvalue_nontyped = self.sym_aryvalue self.sym_aryname_nullable = ''.join(random.choice(string.ascii_letters) for _ in range(12)) self.sym_aryvalue_nullable = [1.0, 2.0, None] self.sym_strname = ''.join(random.choice(string.ascii_letters) for _ in range(10)) self.sym_strvalue = ''.join(random.choice(string.ascii_letters) for _ in range(10)) def _type_resolver(self, name): if name == self.sym_aryname: return types.DataType.ARRAY(types.DataType.FLOAT, value_type_nullable=False) elif name == self.sym_aryname_nontyped: return types.DataType.ARRAY elif name == self.sym_aryname_nullable: return types.DataType.ARRAY(types.DataType.FLOAT, value_type_nullable=True) elif name == self.sym_strname: return types.DataType.STRING return types.DataType.UNDEFINED def test_ast_expression_symbol(self): symbol = ast.SymbolExpression(engine.Context(), self.sym_strname) self.assertIs(symbol.result_type, types.DataType.UNDEFINED) self.assertEqual(symbol.name, self.sym_strname) self.assertEqual(symbol.evaluate({self.sym_strname: self.sym_strvalue}), self.sym_strvalue) def test_ast_expression_symbol_scope(self): symbol = ast.SymbolExpression(context, 'test', scope='built-in') expression = ast.GetAttributeExpression(context, symbol, 'one') value = expression.evaluate(None) self.assertIsInstance(value, decimal.Decimal) self.assertEqual(value, 1.0) def test_ast_expression_symbol_scope_error(self): symbol = ast.SymbolExpression(context, 'fake-name', scope='fake-scope') try: symbol.evaluate(None) except errors.SymbolResolutionError as error: self.assertEqual(error.symbol_name, 'fake-name') self.assertEqual(error.symbol_scope, 'fake-scope') else: self.fail('SymbolResolutionError was not raised') def test_ast_expression_symbol_type(self): context = engine.Context(type_resolver=self._type_resolver) symbol = ast.SymbolExpression(context, self.sym_strname) self.assertIs(symbol.result_type, types.DataType.STRING) self.assertEqual(symbol.name, self.sym_strname) self.assertEqual(symbol.evaluate({self.sym_strname: self.sym_strvalue}), self.sym_strvalue) def test_ast_expression_symbol_type_errors(self): context = engine.Context(type_resolver=self._type_resolver) symbol = ast.SymbolExpression(context, self.sym_strname) self.assertIs(symbol.result_type, types.DataType.STRING) self.assertEqual(symbol.name, self.sym_strname) with self.assertRaises(errors.SymbolTypeError): self.assertEqual(symbol.evaluate({self.sym_strname: not self.sym_strvalue}), self.sym_strvalue) self.assertIsNone(symbol.evaluate({self.sym_strname: None})) symbol = ast.SymbolExpression(context, self.sym_aryname) with self.assertRaises(errors.SymbolTypeError): symbol.evaluate({self.sym_aryname: self.sym_aryvalue_nullable}) try: symbol.evaluate({self.sym_aryname: self.sym_aryvalue}) except errors.SymbolTypeError: self.fail('raises SymbolTypeError when it should not') symbol = ast.SymbolExpression(context, self.sym_aryname_nontyped) try: symbol.evaluate({self.sym_aryname_nontyped: self.sym_aryvalue}) symbol.evaluate({self.sym_aryname_nontyped: self.sym_aryvalue_nontyped}) symbol.evaluate({self.sym_aryname_nontyped: self.sym_aryvalue_nullable}) except errors.SymbolTypeError: self.fail('raises SymbolTypeError when it should not') symbol = ast.SymbolExpression(context, self.sym_aryname_nullable) try: symbol.evaluate({self.sym_aryname_nullable: self.sym_aryvalue}) symbol.evaluate({self.sym_aryname_nullable: self.sym_aryvalue_nullable}) except errors.SymbolTypeError: self.fail('raises SymbolTypeError when it should not') class SymbolExpressionConversionTests(unittest.TestCase): def setUp(self): self.sym_name = ''.join(random.choice(string.ascii_letters) for _ in range(10)) self.symbol = ast.SymbolExpression(context, self.sym_name) self.assertEqual(self.symbol.name, self.sym_name) def test_ast_expression_symbol_type_converts_date(self): result = self.symbol.evaluate({self.sym_name: datetime.date(2016, 10, 15)}) self.assertIsInstance(result, datetime.datetime) self.assertEqual(result, datetime.datetime(2016, 10, 15, tzinfo=dateutil.tz.tzlocal())) def test_ast_expression_symbol_type_converts_int(self): result = self.symbol.evaluate({self.sym_name: 1}) self.assertIsInstance(result, decimal.Decimal) self.assertEqual(result, 1.0) def test_ast_expression_symbol_type_converts_range(self): result = self.symbol.evaluate({self.sym_name: range(3)}) self.assertIsInstance(result, tuple) self.assertEqual(result, (0, 1, 2)) class TernaryExpressionTests(unittest.TestCase): left_value = ast.StringExpression(context, 'left') right_value = ast.StringExpression(context, 'right') def test_ast_expression_ternary(self): for value in trueish: ternary = ast.TernaryExpression(context, value, case_true=self.left_value, case_false=self.right_value) self.assertEqual(ternary.evaluate(None), self.left_value.value) for value in falseish: ternary = ast.TernaryExpression(context, value, case_true=self.left_value, case_false=self.right_value) self.assertEqual(ternary.evaluate(None), self.right_value.value) class UnaryExpressionTests(unittest.TestCase): def test_ast_expression_unary(self): with self.assertRaises(ValueError): ast.UnaryExpression(context, 'type', ast.NullExpression(context)) def test_ast_expression_unary_not(self): for value in trueish: unary = ast.UnaryExpression(context, 'not', value) self.assertFalse(unary.evaluate(None)) for value in falseish: unary = ast.UnaryExpression(context, 'not', value) self.assertTrue(unary.evaluate(None)) def test_ast_expression_unary_uminus(self): for value in trueish: if not isinstance(value, (ast.FloatExpression, ast.TimedeltaExpression)): continue unary = ast.UnaryExpression(context, 'uminus', value) result = unary.evaluate(None) self.assertTrue(result) self.assertNotEqual(result, value.value) for value in falseish: if not isinstance(value, (ast.FloatExpression, ast.TimedeltaExpression)): continue unary = ast.UnaryExpression(context, 'uminus', value) result = unary.evaluate(None) self.assertFalse(result) self.assertEqual(result, value.value) def test_ast_expresison_unary_minus_type_errors(self): for value in trueish + falseish: if isinstance(value, (ast.FloatExpression, ast.TimedeltaExpression)): continue unary = ast.UnaryExpression(context, 'uminus', value) with self.assertRaises(errors.EvaluationError): unary.evaluate(None) if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/builtins.py000066400000000000000000000203001446303237000172700ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/builtins.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import contextlib import datetime import decimal import random import string import unittest import rule_engine.ast as ast import rule_engine.builtins as builtins import rule_engine.engine as engine import rule_engine.errors as errors import dateutil.tz try: import graphviz except ImportError: has_graphviz = False else: has_graphviz = True @contextlib.contextmanager def disable_random(): now = datetime.datetime.now() state = random.getstate() random.seed(now.timestamp()) try: yield random.getstate() finally: random.setstate(state) class BuiltinsTests(unittest.TestCase): def assertBuiltinFunction(self, name, expected_result, *arguments): blts = builtins.Builtins.from_defaults() function = blts[name] function_type = blts.resolve_type(name) self.assertIsNot( function_type.minimum_arguments, ast.DataType.UNDEFINED, msg='builtin function should have a defined minimum number of arguments' ) self.assertTrue(callable(function), msg='builtin functions should be callable') result = function(*arguments) self.assertEqual(result, expected_result, msg='builtin functions should return the expected result') result_type = ast.DataType.from_value(result) self.assertTrue(ast.DataType.is_compatible(result_type, function_type.return_type)) return result def test_engine_builtin_functions(self): blts = builtins.Builtins.from_defaults() for name in blts: data_type = blts.resolve_type(name) if not isinstance(data_type, ast.DataType.FUNCTION.__class__): continue self.assertEqual(name, data_type.value_name) def test_engine_builtins(self): blts = builtins.Builtins.from_defaults({'test': {'one': 1.0, 'two': 2.0}}) self.assertIsInstance(blts, builtins.Builtins) self.assertIsNone(blts.namespace) self.assertRegex(repr(blts), r' baz) : (bar < -baz)] # comment') digraph = rule.to_graphviz() self.assertIsInstance(digraph, graphviz.Digraph) @unittest.skipUnless(has_graphviz, 'graphviz is unavailable') def test_engine_rule_to_graphviz_3(self): rule = engine.Rule('[member for member in iterable if member]') digraph = rule.to_graphviz() self.assertIsInstance(digraph, graphviz.Digraph) def test_engine_rule_to_strings(self): rule = engine.Rule(self.rule_text) self.assertEqual(str(rule), self.rule_text) self.assertRegex(repr(rule), "".format(re.escape(self.rule_text))) def test_engine_rule_matches(self, rule=None): rule = rule or engine.Rule(self.rule_text) result = rule.matches(self.true_item) self.assertIsInstance(result, bool) self.assertTrue(result) result = rule.matches(self.false_item) self.assertIsInstance(result, bool) self.assertFalse(result) def test_engine_rule_filter(self, rule=None): rule = rule or engine.Rule(self.rule_text) result = rule.filter([self.true_item, self.false_item]) self.assertIsInstance(result, types.GeneratorType) result = tuple(result) self.assertIn(self.true_item, result) self.assertNotIn(self.false_item, result) def test_engine_rule_evaluate(self): rule = engine.Rule('"string"') self.assertEqual(rule.evaluate(None), 'string') def test_engine_rule_evaluate_attributes(self): # ensure that multiple levels can be evaluated as attributes rule = engine.Rule('a.b.c') self.assertTrue(rule.evaluate({'a': {'b': {'c': True}}})) value = rule.evaluate({'a': {'b': {'c': 1}}}) self.assertIsInstance(value, decimal.Decimal) self.assertEqual(value, 1.0) value = rule.evaluate({'a': {'b': {'c': {'d': None}}}}) self.assertIsInstance(value, dict) self.assertIn('d', value) with self.assertRaises(errors.AttributeResolutionError): rule.evaluate({'a': {}}) def test_engine_rule_debug_parser(self): with open(os.devnull, 'w') as file_h: original_stderr = sys.stderr sys.stderr = file_h debug_rule = engine.DebugRule(self.rule_text) sys.stderr = original_stderr self.test_engine_rule_matches(rule=debug_rule) self.test_engine_rule_filter(rule=debug_rule) class EngineDatetimeRuleTests(unittest.TestCase): def test_add_timedeltas(self): rule = engine.Rule("t'P4DT2H31S' + t'P1WT45M17S' == t'P1W4DT2H45M48S'") self.assertTrue(rule.evaluate({})) def test_add_empty_timedelta(self): rule = engine.Rule("t'P1DT3S' + t'PT' == t'P1DT3S'") self.assertTrue(rule.evaluate({})) def test_add_to_today(self): rule = engine.Rule("$today + t'PT' == $today") self.assertTrue(rule.evaluate({})) def test_add_datetime_to_timedelta(self): rule = engine.Rule("d'2022-05-23 08:23' + t'PT4H3M2S' == d'2022-05-23 12:26:02'") self.assertTrue(rule.evaluate({})) rule = engine.Rule("start + t'PT1H' == end") self.assertTrue(rule.evaluate({ "start": datetime.datetime(year=2022, month=2, day=28, hour=23, minute=32, second=56), "end": datetime.datetime(year=2022, month=3, day=1, hour=0, minute=32, second=56), })) def test_subtract_timedeltas(self): rule = engine.Rule("t'P4DT2H31S' - t'P1DT45S' == t'P3DT1H59M46S'") self.assertTrue(rule.evaluate({})) rule = engine.Rule("t'P4DT2H31S' - t'P1WT45M17S' == -t'P2DT22H44M46S'") self.assertTrue(rule.evaluate({})) def test_subtract_empty_timedelta(self): rule = engine.Rule("t'P1DT3S' - t'PT' == t'P1DT3S'") self.assertTrue(rule.evaluate({})) def test_subtract_from_today(self): rule = engine.Rule("$today - t'PT' == $today") self.assertTrue(rule.evaluate({})) def test_subtract_datetime_from_datetime(self): rule = engine.Rule("d'2022-05-23 14:12' - d'2022-05-23 12:15' == t'PT1H57M'") self.assertTrue(rule.evaluate({})) rule = engine.Rule("end - t'PT1H' == start") self.assertTrue(rule.evaluate({ "start": datetime.datetime(year=2022, month=2, day=28, hour=23, minute=32, second=56), "end": datetime.datetime(year=2022, month=3, day=1, hour=0, minute=32, second=56), })) def test_subtract_timedelta_from_datetime(self): rule = engine.Rule("d'2022-06-12' - t'P1D' == d'2022-06-11'") self.assertTrue(rule.evaluate({})) if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/errors.py000066400000000000000000000056101446303237000167620ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/errors.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import random import string import unittest import rule_engine.errors as errors class ResolutionErrorTests(unittest.TestCase): def test_attribute_error_repr(self): attribute_error = errors.AttributeResolutionError('doesnotexist', None) self.assertIn('suggestion', repr(attribute_error)) suggestion = ''.join(random.choice(string.ascii_letters) for _ in range(10)) attribute_error = errors.AttributeResolutionError('doesnotexist', None, suggestion=suggestion) self.assertIn('suggestion', repr(attribute_error)) self.assertIn(suggestion, repr(attribute_error)) def test_symbol_error_repr(self): symbol_error = errors.SymbolResolutionError('doesnotexist') self.assertIn('suggestion', repr(symbol_error)) suggestion = ''.join(random.choice(string.ascii_letters) for _ in range(10)) symbol_error = errors.SymbolResolutionError('doesnotexist', suggestion=suggestion) self.assertIn('suggestion', repr(symbol_error)) self.assertIn(suggestion, repr(symbol_error)) class UndefinedSentinelTests(unittest.TestCase): def test_undefined_has_a_repr(self): self.assertEqual(repr(errors.UNDEFINED), 'UNDEFINED') def test_undefined_is_a_sentinel(self): self.assertIsNotNone(errors.UNDEFINED) self.assertIs(errors.UNDEFINED, errors.UNDEFINED) def test_undefined_is_falsy(self): self.assertFalse(errors.UNDEFINED) if __name__ == '__main__': unittest.main()rule-engine-4.1.0/tests/issues.py000066400000000000000000000074261446303237000167700ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/issues.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import random import unittest import rule_engine.engine as engine import rule_engine.errors as errors import rule_engine.types as types import dateutil.tz class GitHubIssueTests(unittest.TestCase): def test_number_10(self): value = random.randint(1, 10000) thing = { 'c': { 'c1': value, } } rule_text = 'c.c1 == ' + str(value) rule1 = engine.Rule(rule_text, context=engine.Context()) rule2 = engine.Rule(rule_text, context=engine.Context(default_value=None)) self.assertEqual(rule1.evaluate(thing), rule2.evaluate(thing)) def test_number_14(self): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'TEST_FLOAT': types.DataType.FLOAT, }) ) rule = engine.Rule( '(TEST_FLOAT == null ? 0 : TEST_FLOAT) < 42', context=context ) rule.matches({'TEST_FLOAT': None}) def test_number_19(self): context = engine.Context( type_resolver=engine.type_resolver_from_dict({ 'facts': types.DataType.MAPPING( key_type=types.DataType.STRING, value_type=types.DataType.STRING ) }) ) rule = engine.Rule('facts.abc == "def"', context=context) self.assertTrue(rule.matches({'facts': {'abc': 'def'}})) def test_number_20(self): rule = engine.Rule('a / b ** 2') self.assertEqual(rule.evaluate({'a': 8, 'b': 4}), 0.5) def test_number_22(self): rules = ('object["timestamp"] > $now', 'object.timestamp > $now') for rule in rules: rule = engine.Rule(rule) self.assertFalse(rule.evaluate({ 'object': {'timestamp': datetime.datetime(2021, 8, 19)} })) def test_number_54(self): rules = ( 'count == 01', "test=='NOTTEST' and count==01 and other=='other'" ) for rule in rules: with self.assertRaises(errors.FloatSyntaxError): engine.Rule(rule) def test_number_66(self): rule = engine.Rule('$parse_datetime("2020-01-01")') try: result = rule.evaluate({}) except Exception: self.fail('evaluation raised an exception') self.assertEqual(result, datetime.datetime(2020, 1, 1, tzinfo=dateutil.tz.tzlocal())) def test_number_68(self): rule = engine.Rule('$min(items)') try: result = rule.evaluate({'items': [1, 2, 3, 4, 5, 6, 7, 8, 9]}) except Exception: self.fail('evaluation raised an exception') self.assertEqual(result, 1) rule-engine-4.1.0/tests/parser.py000066400000000000000000000502531446303237000167450ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/parser.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import datetime import decimal import itertools import math import random import string import unittest import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors import rule_engine.parser as parser import rule_engine.types as types import dateutil.tz class ParserTestsBase(unittest.TestCase): _parser = parser.Parser() context = engine.Context() def _parse(self, string, context): return self._parser.parse(string, context) def assertStatementType(self, string, ast_expression): statement = self._parse(string, self.context) self.assertIsInstance(statement, ast.Statement, msg='the parser did not return a statement') expression = statement.expression self.assertIsInstance(expression, ast_expression, msg='the statement expression is not the correct expression type') return statement class ParserTests(ParserTestsBase): def test_parser_comment_expressions(self): expression = self.assertStatementType('null', ast.NullExpression) self.assertIsNone(expression.comment) comment = ''.join(random.choice(string.ascii_letters) for _ in range(10)) expression = self.assertStatementType('null # ' + comment, ast.NullExpression) self.assertIsInstance(expression.comment, ast.Comment) self.assertEqual(expression.comment.value, comment) def test_parser_comprehension_expressions(self): expressions = [] # conditional expression = self.assertStatementType( '[member for member in iterable if member]', ast.ComprehensionExpression ).expression self.assertIsNotNone(expression.condition) expressions.append(expression) # unconditional expression = self.assertStatementType( '[member for member in iterable]', ast.ComprehensionExpression ).expression self.assertIsNone(expression.condition) expressions.append(expression) for expression in expressions: self.assertIsInstance(expression.iterable, ast.SymbolExpression) self.assertEqual(expression.iterable.name, 'iterable') self.assertIsInstance(expression.result, ast.SymbolExpression) self.assertEqual(expression.result.name, 'member') def test_parser_comprehension_expressions_errors(self): # test non-iterables raise an exception with self.assertRaises(errors.EvaluationError): self._parse('[null for something in null]', self.context) # test invalid assignments raise an exception with self.assertRaises(errors.SyntaxError): self._parse('[null for null in something]', self.context) # test that data types are propagated... typed_context = engine.Context(type_resolver=engine.type_resolver_from_dict({ 'words': types.DataType.ARRAY(types.DataType.STRING) })) # ... the result expression self._parse('[word =~ ".*" for word in words]', typed_context) with self.assertRaises(errors.EvaluationError): self._parse('[word % 2 for word in words]', typed_context) # ... and the condition expression self._parse('[null for word in words if word =~ ".*"]', typed_context) with self.assertRaises(errors.EvaluationError): self._parse('[null for word in words if word % 2]', typed_context) def test_parser_contains_expressions(self): expressions = [] expression = self.assertStatementType('member in container', ast.ContainsExpression).expression expressions.append(expression) expression = self.assertStatementType('member not in container', ast.UnaryExpression).expression self.assertIsInstance(expression.right, ast.ContainsExpression) expressions.append(expression.right) for expression in expressions: self.assertIsInstance(expression.member, ast.SymbolExpression) self.assertEqual(expression.member.name, 'member') self.assertIsInstance(expression.container, ast.SymbolExpression) self.assertEqual(expression.container.name, 'container') def test_parser_function_call_expressions(self): expression = self.assertStatementType( 'function()', ast.FunctionCallExpression ).expression self.assertIsInstance(expression.function, ast.SymbolExpression) self.assertEqual(expression.function.name, 'function') self.assertEqual(len(expression.arguments), 0) expression = self.assertStatementType( 'function(arg1)', ast.FunctionCallExpression ).expression self.assertEqual(len(expression.arguments), 1) self.assertIsInstance(expression.arguments[0], ast.SymbolExpression) self.assertEqual(expression.arguments[0].name, 'arg1') def test_parser_order_of_operations(self): cases = ( '100 * ( 2 + 12 ) / 14', '50 + 50 * 2 - 50', '19 + 9 ** 2', '(4 * 5) ** 2 / 4' ) for case in cases: statement = self._parse(case, self.context) self.assertIsInstance(statement.expression, ast.FloatExpression) self.assertEqual(statement.evaluate(None), decimal.Decimal('100')) def test_parser_raises_syntax_error(self): with self.assertRaises(errors.RuleSyntaxError): self._parse('test[', self.context) def test_parser_reserved_keywords(self): keywords = ('elif', 'else', 'while') for keyword in keywords: with self.assertRaises(errors.RuleSyntaxError): self.assertStatementType(keyword, ast.SymbolExpression) def test_parser_returns_statement(self): expression = self._parse('true', self.context) self.assertIsInstance(expression, ast.Statement) def test_parser_symbol_expressions(self): symbols = ('a', 'b') for text in symbols: expression = self.assertStatementType(text, ast.SymbolExpression).expression self.assertEqual(expression.name, text) self.assertIsNone(expression.scope) expression = self.assertStatementType('$' + text, ast.SymbolExpression).expression self.assertEqual(expression.name, text) self.assertEqual(expression.scope, 'built-in') def test_parser_ternary_expressions(self): statement = self.assertStatementType('condition ? case_true : case_false', ast.TernaryExpression) self.assertIsInstance(statement.expression.condition, ast.SymbolExpression) self.assertEqual(statement.expression.condition.name, 'condition') self.assertIsInstance(statement.expression.case_true, ast.SymbolExpression) self.assertEqual(statement.expression.case_true.name, 'case_true') self.assertIsInstance(statement.expression.case_false, ast.SymbolExpression) self.assertEqual(statement.expression.case_false.name, 'case_false') def test_parser_unary_expressions(self): expressions = ('-right', 'not right') for expression in expressions: statement = self.assertStatementType(expression, ast.UnaryExpression) self.assertIsInstance(statement.expression.right, ast.SymbolExpression) self.assertEqual(statement.expression.right.name, 'right') class ParserLeftOperatorRightTests(ParserTestsBase): def assertStatementType(self, string, ast_expression): statement = super(ParserLeftOperatorRightTests, self).assertStatementType(string, ast_expression) expression = statement.expression self.assertIsInstance(expression.left, ast.SymbolExpression) self.assertEqual(expression.left.name, 'left') self.assertIsInstance(expression.right, ast.SymbolExpression) self.assertEqual(expression.right.name, 'right') return statement def test_parser_arithmetic_expressions(self): expressions = ( 'left / right', 'left // right', 'left % right', 'left * right', 'left ** right' ) for expression in expressions: self.assertStatementType(expression, ast.ArithmeticExpression) def test_parser_add_expressions(self): expressions = ( 'left + right', ) for expression in expressions: self.assertStatementType(expression, ast.AddExpression) def test_parser_subtract_expressions(self): expressions = ( 'left - right', ) for expression in expressions: self.assertStatementType(expression, ast.SubtractExpression) def test_parser_bitwise_expressions(self): expressions = ( 'left & right', 'left | right', 'left ^ right', 'left << right', 'left >> right' ) for expression in expressions: self.assertStatementType(expression, ast.BitwiseExpression) def test_parser_logical_expressions(self): expressions = ('left and right', 'left or right') for expression in expressions: self.assertStatementType(expression, ast.LogicExpression) def test_parser_comparison_expressions(self): expressions = ('left == right', 'left != right') for expression in expressions: self.assertStatementType(expression, ast.ComparisonExpression) def test_parser_comparison_arithmetic_expressions(self): expressions = ( 'left > right', 'left >= right', 'left < right', 'left <= right' ) for expression in expressions: self.assertStatementType(expression, ast.ComparisonExpression) def test_parser_comparison_fuzzy_expressions(self): expressions = ('left =~ right', 'left =~~ right', 'left !~ right', 'left !~~ right') for expression in expressions: self.assertStatementType(expression, ast.FuzzyComparisonExpression) class ParserLiteralTests(ParserTestsBase): def assertLiteralStatementEvalEqual(self, string, python_value, msg=None): statement = self._parse(string, self.context) self.assertIsInstance(statement, ast.Statement, msg='the parser did not return a statement') self.assertIsInstance(statement.expression, ast.LiteralExpressionBase, msg='the statement expression is not the correct type') self.assertTrue(statement.expression.is_reduced) value = statement.evaluate(None) self.assertEqual(value, python_value, msg=msg or "{0!r} does not evaluate to {1!r}".format(string, python_value)) def assertLiteralStatementEqual(self, string, ast_expression, python_value, msg=None): statement = self._parse(string, self.context) self.assertIsInstance(statement, ast.Statement, msg='the parser did not return a statement') self.assertIsInstance(statement.expression, ast_expression, msg='the statement expression is not the correct literal type') self.assertEqual(statement.expression.value, python_value, msg=msg or "{0!r} does not evaluate to {1!r}".format(string, python_value)) def test_parse_array(self): self.assertLiteralStatementEvalEqual('[ ]', tuple()) self.assertLiteralStatementEvalEqual('[1, 2]', tuple((decimal.Decimal('1.0'), decimal.Decimal('2.0')))) self.assertLiteralStatementEvalEqual('[1, 2,]', tuple((decimal.Decimal('1.0'), decimal.Decimal('2.0')))) def test_parse_array_getitem(self): cases = ( ('["t", "e", "s", "t", "i", "n", "g"]', '"testing"'), (('[0]', 't'), ('[1]', 'e'), ('[-1]', 'g')) ) for (container, (getitem, answer)) in itertools.product(*cases): self.assertLiteralStatementEvalEqual(container + getitem, answer) def test_parse_array_getslice(self): self.assertLiteralStatementEvalEqual('"testing"[:]', 'testing') self.assertLiteralStatementEvalEqual('"testing"[4:]', 'ing') self.assertLiteralStatementEvalEqual('"testing"[:4]', 'test') self.assertLiteralStatementEvalEqual('"testing"[1:-1]', 'estin') self.assertLiteralStatementEvalEqual('"testing"[1:6]', 'estin') self.assertLiteralStatementEvalEqual('["t", "e", "s", "t", "i", "n", "g"][:]', tuple('testing')) self.assertLiteralStatementEvalEqual('["t", "e", "s", "t", "i", "n", "g"][1:-1]', tuple('estin')) self.assertLiteralStatementEvalEqual('["t", "e", "s", "t", "i", "n", "g"][1:6]', tuple('estin')) def test_parse_boolean(self): self.assertLiteralStatementEqual('true', ast.BooleanExpression, True) self.assertLiteralStatementEqual('false', ast.BooleanExpression, False) def test_parse_datetime(self): self.assertLiteralStatementEqual('d"2016-10-15"', ast.DatetimeExpression, datetime.datetime(2016, 10, 15, tzinfo=dateutil.tz.tzlocal())) self.assertLiteralStatementEqual('d"2016-10-15 12:30"', ast.DatetimeExpression, datetime.datetime(2016, 10, 15, 12, 30, tzinfo=dateutil.tz.tzlocal())) def test_parse_datetime_attributes(self): self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".date', datetime.datetime(2019, 9, 11, tzinfo=dateutil.tz.UTC)) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".day', decimal.Decimal('11')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".hour', decimal.Decimal('20')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".microsecond', decimal.Decimal('506406')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".millisecond', decimal.Decimal('506.406')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".minute', decimal.Decimal('46')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".month', decimal.Decimal('9')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".second', decimal.Decimal('57')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".weekday', 'Wednesday') self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".year', decimal.Decimal('2019')) self.assertLiteralStatementEvalEqual('d"2019-09-11T20:46:57.506406+00:00".zone_name', 'UTC') def test_parse_datetime_syntax_errors(self): try: self._parse('d"this is wrong"', self.context) except errors.DatetimeSyntaxError as error: self.assertEqual(error.value, 'this is wrong') else: self.fail('DatetimeSyntaxError was not raised') def test_parse_timedelta(self): self.assertLiteralStatementEqual('t"P1W"', ast.TimedeltaExpression, datetime.timedelta(weeks=1)) self.assertLiteralStatementEqual('t"P7W6DT5H4M3S"', ast.TimedeltaExpression, datetime.timedelta(weeks=7, days=6, hours=5, minutes=4, seconds=3)) self.assertLiteralStatementEqual('t"PT3H2S"', ast.TimedeltaExpression, datetime.timedelta(hours=3, seconds=2)) self.assertLiteralStatementEqual('t"PT"', ast.TimedeltaExpression, datetime.timedelta()) def test_parse_timedelta_attributes(self): self.assertLiteralStatementEvalEqual('t"P7W6DT5H4M3S".days', decimal.Decimal('55')) self.assertLiteralStatementEvalEqual('t"P7W6DT5H4M3S".seconds', decimal.Decimal('18243')) self.assertLiteralStatementEvalEqual('t"P7W6DT5H4M3S".microseconds', decimal.Decimal('0')) self.assertLiteralStatementEvalEqual('t"P7W6DT5H4M3S".total_seconds', decimal.Decimal('4770243')) def test_parse_float(self): self.assertLiteralStatementEqual('3.14', ast.FloatExpression, decimal.Decimal('3.14')) self.assertLiteralStatementEqual('3.140', ast.FloatExpression, decimal.Decimal('3.140')) self.assertLiteralStatementEqual('.314', ast.FloatExpression, decimal.Decimal('0.314')) self.assertLiteralStatementEqual('0.314', ast.FloatExpression, decimal.Decimal('0.314')) def test_parse_float_exponent(self): self.assertLiteralStatementEqual('3.14e5', ast.FloatExpression, decimal.Decimal('314000.0')) self.assertLiteralStatementEqual('3.14e+3', ast.FloatExpression, decimal.Decimal('3140.0')) self.assertLiteralStatementEqual('3.14e-3', ast.FloatExpression, decimal.Decimal('0.00314')) self.assertLiteralStatementEqual('3.14E5', ast.FloatExpression, decimal.Decimal('314000.0')) self.assertLiteralStatementEqual('3.14E+3', ast.FloatExpression, decimal.Decimal('3140.0')) self.assertLiteralStatementEqual('3.14E-3', ast.FloatExpression, decimal.Decimal('0.00314')) def test_parse_float_base_2(self): self.assertLiteralStatementEqual('0b00', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('0b11', ast.FloatExpression, decimal.Decimal('3')) def test_parse_float_base_8(self): self.assertLiteralStatementEqual('0o00', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('0o77', ast.FloatExpression, decimal.Decimal('63')) def test_parse_float_base_10(self): self.assertLiteralStatementEqual('0', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('99', ast.FloatExpression, decimal.Decimal('99')) with self.assertRaises(errors.FloatSyntaxError): self._parse('00', self.context) def test_parse_float_base_16(self): self.assertLiteralStatementEqual('0x00', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('0xdeadbeef', ast.FloatExpression, decimal.Decimal('3735928559')) self.assertLiteralStatementEqual('0xdeADbeEF', ast.FloatExpression, decimal.Decimal('3735928559')) def test_parse_float_inf(self): self.assertLiteralStatementEqual('inf', ast.FloatExpression, decimal.Decimal('inf')) def test_parse_float_nan(self): statement = self._parse('nan', self.context) self.assertIsInstance(statement, ast.Statement, msg='the parser did not return a statement') self.assertIsInstance(statement.expression, ast.FloatExpression, msg='the statement expression is not the correct literal type') self.assertTrue(math.isnan(statement.expression.value), msg='the statement expression is not nan') def test_parse_mapping(self): self.assertLiteralStatementEvalEqual('{}', {}) self.assertLiteralStatementEvalEqual('{"one": 1}', {'one': decimal.Decimal('1')}) self.assertLiteralStatementEvalEqual('{"one": 1,}', {'one': decimal.Decimal('1')}) self.assertLiteralStatementEvalEqual('{"one": 1, "two": 2, "one": 1.11}', {'two': decimal.Decimal('2'), 'one': decimal.Decimal('1.11')}) with self.assertRaises(errors.EngineError): self._parse('{ {1: asdfsadfasd}: "compound key" }', self.context) def test_parse_null(self): self.assertLiteralStatementEqual('null', ast.NullExpression, None) def test_parse_set(self): self.assertLiteralStatementEvalEqual("{1}", set([decimal.Decimal('1')])) self.assertLiteralStatementEvalEqual("{'Alice', 'Bob'}", set(['Alice', 'Bob'])) def test_parse_string(self): self.assertLiteralStatementEqual("'Alice'", ast.StringExpression, 'Alice') self.assertLiteralStatementEqual('"Alice"', ast.StringExpression, 'Alice') self.assertLiteralStatementEqual("s'Alice'", ast.StringExpression, 'Alice') self.assertLiteralStatementEqual('s"Alice"', ast.StringExpression, 'Alice') def test_parse_string_attributes(self): self.assertLiteralStatementEvalEqual('s"".is_empty', True) self.assertLiteralStatementEvalEqual('s"Alice".length', decimal.Decimal('5')) def test_parse_string_escapes(self): self.assertLiteralStatementEqual("'Alice\\\'s'", ast.StringExpression, 'Alice\'s') self.assertLiteralStatementEqual('"Alice\'s"', ast.StringExpression, 'Alice\'s') def test_parse_xxx_edge_cases(self): # test the safe getattr parsing for weird edge cases self.assertLiteralStatementEqual('null&.doesnotexist', ast.NullExpression, None) self.assertLiteralStatementEqual('2&.0', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('1 & .0', ast.FloatExpression, decimal.Decimal('0')) self.assertLiteralStatementEqual('"test"&.length', ast.FloatExpression, decimal.Decimal('4')) self.assertLiteralStatementEqual('("test").length', ast.FloatExpression, decimal.Decimal('4')) with self.assertRaises(errors.RuleSyntaxError): self.assertLiteralStatementEqual('"test"(.length)', ast.FloatExpression, decimal.Decimal('4')) with self.assertRaises(errors.RuleSyntaxError): self.assertLiteralStatementEqual('"test".(length)', ast.FloatExpression, decimal.Decimal('4')) if __name__ == '__main__': unittest.main() rule-engine-4.1.0/tests/suggestions.py000066400000000000000000000061051446303237000200200ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/suggestions.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import random import string import unittest import rule_engine.suggestions as suggestions # JARO_WINKLER_TEST_CASES taken from the original whitepaper: see page 13, table 4 # https://www.census.gov/srd/papers/pdf/rr91-9.pdf # not all JARO_WINKLER_TEST_CASES are a perfect match, so the table is a selection of those that are JARO_WINKLER_TEST_CASES = ( ('shackleford', 'shackelford', 0.9848), ('cunningham', 'cunnigham', 0.9833), ('galloway', 'calloway', 0.9167), ('lampley', 'campley', 0.9048), ('michele', 'michelle', 0.9792), ('jonathon', 'jonathan', 0.9583), ) class JaroWinklerTests(unittest.TestCase): def test_jaro_winkler_distance(self): for str1, str2, distance in JARO_WINKLER_TEST_CASES: self.assertEqual( round(suggestions.jaro_winkler_distance(str1, str2), 4), distance, msg="({}, {}) != {}".format(str1, str2, distance) ) def test_jaro_winkler_distance_match(self): strx = ''.join(random.choice(string.ascii_letters) for _ in range(10)) self.assertEqual( suggestions.jaro_winkler_distance(strx, strx), 1.0 ) def test_jaro_winkler_similarity(self): for str1, str2, distance in JARO_WINKLER_TEST_CASES: similarity = round(1 - distance, 4) self.assertEqual( round(suggestions.jaro_winkler_similarity(str1, str2), 4), similarity, msg="({}, {}) != {}".format(str1, str2, similarity) ) def test_jaro_winkler_similarity_match(self): strx = ''.join(random.choice(string.ascii_letters) for _ in range(10)) self.assertEqual( suggestions.jaro_winkler_similarity(strx, strx), 0.0 ) rule-engine-4.1.0/tests/thread_safety.py000066400000000000000000000067721446303237000203020ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/thread_safety.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import functools import queue import random import threading import unittest import rule_engine.ast as ast import rule_engine.engine as engine import rule_engine.errors as errors __all__ = ('ThreadSafetyTests',) def testing_resolver(lock, thing, name): if name == 'lock': lock.acquire() return True return engine.resolve_item(thing, name) class RuleThread(threading.Thread): def __init__(self, rule, thing): self.rule = rule self.thing = thing self.queue = queue.Queue() super(RuleThread, self).__init__() self.start() def run(self): self.queue.put(self.rule.evaluate(self.thing)) def join(self, *args, **kwargs): super(RuleThread, self).join(*args, **kwargs) return self.queue.get() class ThreadSafetyTests(unittest.TestCase): def test_tls_for_comprehension(self): context = engine.Context() rule = engine.Rule('[word for word in words][0]', context=context) rule.evaluate({'words': ('MainThread', 'Test')}) # this isn't exactly a thread test since the assignment scope should be cleared after the comprehension is # complete self.assertEqual(len(context._tls.assignment_scopes), 0) def test_tls_for_regex1(self): context = engine.Context() rule = engine.Rule('words =~ "(\w+) \w+"', context=context) rule.evaluate({'words': 'MainThread Test'}) self.assertEqual(context._tls.regex_groups, ('MainThread',)) RuleThread(rule, {'words': 'AlternateThread Test'}).join() self.assertEqual(context._tls.regex_groups, ('MainThread',)) def test_tls_for_regex2(self): lock = threading.RLock() context = engine.Context(resolver=functools.partial(testing_resolver, lock)) rule = engine.Rule('words =~ "(\w+) \w+" and lock and $re_groups[0] == "MainThread"', context=context) self.assertTrue(rule.evaluate({'words': 'MainThread Test'})) lock.release() with lock: thread = RuleThread(rule, {'words': 'AlternateThread Test'}) self.assertTrue(rule.evaluate({'words': 'MainThread Test'})) lock.release() self.assertFalse(thread.join())rule-engine-4.1.0/tests/types.py000066400000000000000000000356121446303237000166170ustar00rootroot00000000000000#!/usr/bin/env python3 # -*- coding: utf-8 -*- # # tests/types.py # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are # met: # # * Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above # copyright notice, this list of conditions and the following disclaimer # in the documentation and/or other materials provided with the # distribution. # * Neither the name of the project nor the names of its # contributors may be used to endorse or promote products derived from # this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # import collections import datetime import sys import typing import unittest import rule_engine.types as types __all__ = ('DataTypeTests', 'MetaDataTypeTests', 'ValueIsTests') DataType = types.DataType class DataTypeTests(unittest.TestCase): class _UnsupportedType(object): pass def test_data_type_collections(self): with self.assertRaises(TypeError): types._CollectionDataTypeDef('TEST', float) def test_data_type_equality_array(self): dt1 = DataType.ARRAY(DataType.STRING) self.assertIs(dt1.value_type, DataType.STRING) self.assertEqual(dt1, DataType.ARRAY(DataType.STRING)) self.assertNotEqual(dt1, DataType.ARRAY) self.assertNotEqual(dt1, DataType.ARRAY(DataType.STRING, value_type_nullable=False)) def test_data_type_equality_function(self): dt1 = DataType.FUNCTION('test', return_type=DataType.FLOAT, argument_types=(), minimum_arguments=0) self.assertEqual(dt1.value_name, 'test') self.assertEqual(dt1, DataType.FUNCTION('otherTest', return_type=DataType.FLOAT, argument_types=(), minimum_arguments=0)) self.assertNotEqual(dt1, DataType.NULL) self.assertNotEqual(dt1, DataType.FUNCTION('test', return_type=DataType.NULL, argument_types=(), minimum_arguments=0)) self.assertNotEqual(dt1, DataType.FUNCTION('test', return_type=DataType.FLOAT, argument_types=(DataType.FLOAT,), minimum_arguments=0)) self.assertNotEqual(dt1, DataType.FUNCTION('otherTest', return_type=DataType.FLOAT, minimum_arguments=1)) def test_data_type_equality_mapping(self): dt1 = DataType.MAPPING(DataType.STRING) self.assertIs(dt1.key_type, DataType.STRING) self.assertEqual(dt1, DataType.MAPPING(DataType.STRING)) self.assertNotEqual(dt1, DataType.MAPPING) self.assertNotEqual(dt1, DataType.MAPPING(DataType.STRING, value_type=DataType.STRING)) self.assertNotEqual(dt1, DataType.MAPPING(DataType.STRING, value_type_nullable=False)) def test_data_type_equality_set(self): dt1 = DataType.SET(DataType.STRING) self.assertIs(dt1.value_type, DataType.STRING) self.assertEqual(dt1, DataType.SET(DataType.STRING)) self.assertNotEqual(dt1, DataType.SET) self.assertNotEqual(dt1, DataType.SET(DataType.STRING, value_type_nullable=False)) def test_data_type_from_name(self): self.assertIs(DataType.from_name('ARRAY'), DataType.ARRAY) self.assertIs(DataType.from_name('BOOLEAN'), DataType.BOOLEAN) self.assertIs(DataType.from_name('DATETIME'), DataType.DATETIME) self.assertIs(DataType.from_name('TIMEDELTA'), DataType.TIMEDELTA) self.assertIs(DataType.from_name('FLOAT'), DataType.FLOAT) self.assertIs(DataType.from_name('MAPPING'), DataType.MAPPING) self.assertIs(DataType.from_name('NULL'), DataType.NULL) self.assertIs(DataType.from_name('SET'), DataType.SET) self.assertIs(DataType.from_name('STRING'), DataType.STRING) self.assertIs(DataType.from_name('FUNCTION'), DataType.FUNCTION) def test_data_type_from_name_error(self): with self.assertRaises(TypeError): DataType.from_name(1) with self.assertRaises(ValueError): DataType.from_name('FOOBAR') def test_data_type_from_type(self): self.assertIs(DataType.from_type(list), DataType.ARRAY) self.assertIs(DataType.from_type(tuple), DataType.ARRAY) self.assertIs(DataType.from_type(bool), DataType.BOOLEAN) self.assertIs(DataType.from_type(datetime.date), DataType.DATETIME) self.assertIs(DataType.from_type(datetime.datetime), DataType.DATETIME) self.assertIs(DataType.from_type(datetime.timedelta), DataType.TIMEDELTA) self.assertIs(DataType.from_type(float), DataType.FLOAT) self.assertIs(DataType.from_type(int), DataType.FLOAT) self.assertIs(DataType.from_type(dict), DataType.MAPPING) self.assertIs(DataType.from_type(type(None)), DataType.NULL) self.assertIs(DataType.from_type(set), DataType.SET) self.assertIs(DataType.from_type(str), DataType.STRING) self.assertIs(DataType.from_type(type(lambda: None)), DataType.FUNCTION) def test_data_type_from_type_hint(self): # simple compound tests self.assertEqual(DataType.from_type(typing.List[str]), DataType.ARRAY(DataType.STRING)) self.assertEqual(DataType.from_type(typing.Tuple[str]), DataType.ARRAY(DataType.UNDEFINED)) self.assertEqual(DataType.from_type(typing.Set[int]), DataType.SET(DataType.FLOAT)) self.assertEqual(DataType.from_type(typing.Dict[str, str]), DataType.MAPPING(DataType.STRING, DataType.STRING)) # complex compound tests self.assertEqual(DataType.from_type(typing.List[list]), DataType.ARRAY(DataType.ARRAY)) self.assertEqual(DataType.from_type( typing.Dict[str, typing.Dict[str, datetime.datetime]]), DataType.MAPPING(DataType.STRING, DataType.MAPPING(DataType.STRING, DataType.DATETIME) )) if sys.version_info >= (3, 9): self.assertEqual(DataType.from_type(list[str]), DataType.ARRAY(DataType.STRING)) self.assertEqual(DataType.from_type(tuple[str]), DataType.ARRAY(DataType.UNDEFINED)) self.assertEqual(DataType.from_type(set[int]), DataType.SET(DataType.FLOAT)) self.assertEqual(DataType.from_type(dict[str, str]), DataType.MAPPING(DataType.STRING, DataType.STRING)) self.assertEqual(DataType.from_type(list[list]), DataType.ARRAY(DataType.ARRAY)) self.assertEqual(DataType.from_type( dict[str, dict[str, datetime.datetime]]), DataType.MAPPING(DataType.STRING, DataType.MAPPING(DataType.STRING, DataType.DATETIME) )) def test_data_type_from_type_error(self): with self.assertRaisesRegex(TypeError, r'^from_type argument 1 must be a type or a type hint, not _UnsupportedType$'): DataType.from_type(self._UnsupportedType()) with self.assertRaisesRegex(ValueError, r'^can not map python type \'_UnsupportedType\' to a compatible data type$'): DataType.from_type(self._UnsupportedType) def test_data_type_from_value_compound_array(self): for value in [list(), range(0), tuple()]: value = DataType.from_value(value) self.assertEqual(value, DataType.ARRAY) self.assertIs(value.value_type, DataType.UNDEFINED) self.assertIs(value.iterable_type, DataType.UNDEFINED) value = DataType.from_value(['test']) self.assertEqual(value, DataType.ARRAY(DataType.STRING)) self.assertIs(value.value_type, DataType.STRING) self.assertIs(value.iterable_type, DataType.STRING) def test_data_type_from_value_compound_mapping(self): value = DataType.from_value({}) self.assertEqual(value, DataType.MAPPING) self.assertIs(value.key_type, DataType.UNDEFINED) self.assertIs(value.value_type, DataType.UNDEFINED) self.assertIs(value.iterable_type, DataType.UNDEFINED) value = DataType.from_value({'one': 1}) self.assertEqual(value, DataType.MAPPING(DataType.STRING, DataType.FLOAT)) self.assertIs(value.key_type, DataType.STRING) self.assertIs(value.value_type, DataType.FLOAT) self.assertIs(value.iterable_type, DataType.STRING) def test_data_type_from_value_compound_set(self): value = DataType.from_value(set()) self.assertEqual(value, DataType.SET) self.assertIs(value.value_type, DataType.UNDEFINED) self.assertIs(value.iterable_type, DataType.UNDEFINED) value = DataType.from_value({'test'}) self.assertEqual(value, DataType.SET(DataType.STRING)) self.assertIs(value.value_type, DataType.STRING) self.assertIs(value.iterable_type, DataType.STRING) def test_data_type_from_value_scalar(self): self.assertIs(DataType.from_value(False), DataType.BOOLEAN) self.assertIs(DataType.from_value(datetime.date.today()), DataType.DATETIME) self.assertIs(DataType.from_value(datetime.datetime.now()), DataType.DATETIME) self.assertIs(DataType.from_value(datetime.timedelta()), DataType.TIMEDELTA) self.assertIs(DataType.from_value(0), DataType.FLOAT) self.assertIs(DataType.from_value(0.0), DataType.FLOAT) self.assertIs(DataType.from_value(None), DataType.NULL) self.assertIs(DataType.from_value(''), DataType.STRING) self.assertIs(DataType.from_value(lambda: None), DataType.FUNCTION) self.assertIs(DataType.from_value(print), DataType.FUNCTION) def test_data_type_from_value_error(self): with self.assertRaisesRegex(TypeError, r'^can not map python type \'_UnsupportedType\' to a compatible data type$'): DataType.from_value(self._UnsupportedType()) def test_data_type_function(self): with self.assertRaises(TypeError, msg='argument_types should be a sequence'): DataType.FUNCTION('test', argument_types=DataType.NULL) with self.assertRaises(ValueError, msg='minimum_arguments should be less than or equal to the length of argument_types'): DataType.FUNCTION('test', argument_types=(), minimum_arguments=1) def test_data_type_definitions_describe_themselves(self): for name in DataType: if name == 'UNDEFINED': continue data_type = getattr(DataType, name) self.assertRegex(repr(data_type), 'name=' + name) class MetaDataTypeTests(unittest.TestCase): def test_data_type_is_iterable(self): self.assertGreater(len(DataType), 0) for name in DataType: self.assertIsInstance(name, str) self.assertRegex(name, r'^[A-Z]+$') def test_data_type_is_compatible(self): def _is_compat(*args): return self.assertTrue(DataType.is_compatible(*args)) def _is_not_compat(*args): return self.assertFalse(DataType.is_compatible(*args)) _is_compat(DataType.STRING, DataType.STRING) _is_compat(DataType.STRING, DataType.UNDEFINED) _is_compat(DataType.UNDEFINED, DataType.STRING) _is_compat(DataType.UNDEFINED, DataType.ARRAY) _is_compat(DataType.ARRAY, DataType.ARRAY(DataType.STRING)) _is_not_compat(DataType.STRING, DataType.ARRAY) _is_not_compat(DataType.STRING, DataType.NULL) _is_not_compat(DataType.ARRAY(DataType.STRING), DataType.ARRAY(DataType.FLOAT)) _is_compat(DataType.MAPPING, DataType.MAPPING) _is_compat( DataType.MAPPING(DataType.STRING), DataType.MAPPING(DataType.STRING, value_type=DataType.ARRAY) ) _is_compat( DataType.MAPPING(DataType.STRING, value_type=DataType.ARRAY), DataType.MAPPING(DataType.STRING, value_type=DataType.ARRAY(DataType.STRING)) ) _is_not_compat( DataType.MAPPING(DataType.STRING), DataType.MAPPING(DataType.FLOAT) ) _is_not_compat( DataType.MAPPING(DataType.STRING, value_type=DataType.STRING), DataType.MAPPING(DataType.STRING, value_type=DataType.FLOAT) ) with self.assertRaises(TypeError): DataType.is_compatible(DataType.STRING, None) def test_data_type_is_compatible_function(self): def _is_compat(*args): return self.assertTrue(DataType.is_compatible(*args)) def _is_not_compat(*args): return self.assertFalse(DataType.is_compatible(*args)) # the function name doesn't matter, it's only for reporting _is_compat( DataType.FUNCTION('functionA'), DataType.FUNCTION('functionB') ) # return type is UNDEFINED by default which should be compatible _is_compat( DataType.FUNCTION('test', return_type=DataType.FLOAT), DataType.FUNCTION('test') ) # argument types are UNDEFINED by default which should be compatible _is_compat( DataType.FUNCTION('test', argument_types=(DataType.STRING,), minimum_arguments=1), DataType.FUNCTION('test', minimum_arguments=1) ) # minimum arguments defaults to the number of arguments _is_compat( DataType.FUNCTION('test', argument_types=(DataType.STRING,), minimum_arguments=1), DataType.FUNCTION('test', argument_types=(DataType.STRING,)) ) _is_not_compat( DataType.FUNCTION('test', return_type=DataType.FLOAT), DataType.FUNCTION('test', return_type=DataType.STRING) ) _is_not_compat( DataType.FUNCTION('test', argument_types=(DataType.STRING,)), DataType.FUNCTION('test', argument_types=()) ) _is_not_compat( DataType.FUNCTION('test', argument_types=(DataType.FLOAT,)), DataType.FUNCTION('test', argument_types=(DataType.STRING,)) ) _is_not_compat( DataType.FUNCTION('test', minimum_arguments=0), DataType.FUNCTION('test', minimum_arguments=1) ) def test_data_type_is_definition(self): self.assertTrue(DataType.is_definition(DataType.ARRAY)) self.assertFalse(DataType.is_definition(1)) self.assertFalse(DataType.is_definition(None)) def test_data_type_supports_contains(self): self.assertIn('STRING', DataType) def test_data_type_supports_getitem(self): dt = DataType['STRING'] self.assertEqual(dt, DataType.STRING) inf = float('inf') nan = float('nan') class ValueIsTests(unittest.TestCase): _Case = collections.namedtuple('_Case', ('value', 'numeric', 'real', 'integer', 'natural')) cases = ( # value numeric real integer natural _Case(-inf, True, False, False, False), _Case(-1.5, True, True, False, False), _Case(-1.0, True, True, True, False), _Case(-1, True, True, True, False), _Case(0, True, True, True, True ), _Case(1, True, True, True, True ), _Case(1.0, True, True, True, True ), _Case(1.5, True, True, False, False), _Case(inf, True, False, False, False), _Case(nan, True, False, False, False), _Case(True, False, False, False, False), _Case(False, False, False, False, False), _Case('', False, False, False, False), _Case(None, False, False, False, False), ) def test_value_is_integer_number(self): for case in self.cases: self.assertEqual(types.is_integer_number(case.value), case.integer) def test_value_is_natural_number(self): for case in self.cases: self.assertEqual(types.is_natural_number(case.value), case.natural) def test_value_is_numeric(self): for case in self.cases: self.assertEqual(types.is_numeric(case.value), case.numeric) def test_value_is_real_number(self): for case in self.cases: self.assertEqual(types.is_real_number(case.value), case.real) if __name__ == '__main__': unittest.main()