{"id":20957222,"url":"https://github.com/axiros/pycond","last_synced_at":"2025-05-14T05:32:48.128Z","repository":{"id":62579442,"uuid":"95900143","full_name":"axiros/pycond","owner":"axiros","description":"Lightweight condition parsing and building of evaluation expressions","archived":false,"fork":false,"pushed_at":"2023-02-11T23:50:57.000Z","size":242,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-09T00:48:50.010Z","etag":null,"topics":["boolean-function","conditions","evaluation","filter","parsing-expression-grammar","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/axiros.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-06-30T15:14:59.000Z","updated_at":"2024-04-25T13:27:16.000Z","dependencies_parsed_at":"2022-11-03T20:47:23.900Z","dependency_job_id":null,"html_url":"https://github.com/axiros/pycond","commit_stats":{"total_commits":155,"total_committers":3,"mean_commits":"51.666666666666664","dds":"0.40645161290322585","last_synced_commit":"0e3fabb9decbee241f5afbac30ada8de7bbbe17b"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fpycond","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fpycond/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fpycond/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/axiros%2Fpycond/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/axiros","download_url":"https://codeload.github.com/axiros/pycond/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225277872,"owners_count":17448762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boolean-function","conditions","evaluation","filter","parsing-expression-grammar","python"],"created_at":"2024-11-19T01:30:13.162Z","updated_at":"2024-11-19T01:30:13.909Z","avatar_url":"https://github.com/axiros.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"---\n\nauthor: gk\nversion: 20230212\n\n---\n\n\n# pycond: Lightweight Declarative Condition Expressions\n\n[![Build Status](https://travis-ci.org/axiros/pycond.svg?branch=master)](https://travis-ci.org/axiros/pycond) [![codecov](https://codecov.io/gh/axiros/pycond/branch/master/graph/badge.svg)](https://codecov.io/gh/axiros/pycond)[![PyPI    version][pypisvg]][pypi] [![][blacksvg]][black]\n\n[blacksvg]: https://img.shields.io/badge/code%20style-black-000000.svg\n[black]: https://github.com/ambv/black\n[pypisvg]: https://img.shields.io/pypi/v/pycond.svg\n[pypi]: https://badge.fury.io/py/pycond\n\n\u003c!-- badges: http://thomas-cokelaer.info/blog/2014/08/1013/ --\u003e\n\n\n\u003c!-- TOC --\u003e\n\n# Table Of Contents\n\n- \u003ca name=\"toc1\"\u003e\u003c/a\u003e[What](#what)\n- \u003ca name=\"toc2\"\u003e\u003c/a\u003e[Why](#why)\n    - \u003ca name=\"toc3\"\u003e\u003c/a\u003e[Alternatives](#alternatives)\n- \u003ca name=\"toc4\"\u003e\u003c/a\u003e[Mechanics](#mechanics)\n    - \u003ca name=\"toc5\"\u003e\u003c/a\u003e[Parsing](#parsing)\n    - \u003ca name=\"toc6\"\u003e\u003c/a\u003e[Building](#building)\n    - \u003ca name=\"toc7\"\u003e\u003c/a\u003e[Structured Conditions](#structured-conditions)\n    - \u003ca name=\"toc8\"\u003e\u003c/a\u003e[Evaluation](#evaluation)\n    - \u003ca name=\"toc9\"\u003e\u003c/a\u003e[Default Lookup](#default-lookup)\n    - \u003ca name=\"toc10\"\u003e\u003c/a\u003e[Passing State](#passing-state)\n    - \u003ca name=\"toc11\"\u003e\u003c/a\u003e[Deep Lookup / Nested State / Lists](#deep-lookup-nested-state-lists)\n        - \u003ca name=\"toc12\"\u003e\u003c/a\u003e[Lookup Performance: Prebuilt Deep Getters](#lookup-performance-prebuilt-deep-getters)\n        - \u003ca name=\"toc13\"\u003e\u003c/a\u003e[Best Practices](#best-practices)\n    - \u003ca name=\"toc14\"\u003e\u003c/a\u003e[Prefixed Data](#prefixed-data)\n    - \u003ca name=\"toc15\"\u003e\u003c/a\u003e[Attributes Access](#attributes-access)\n    - \u003ca name=\"toc16\"\u003e\u003c/a\u003e[Custom Lookup And Value Passing](#custom-lookup-and-value-passing)\n    - \u003ca name=\"toc17\"\u003e\u003c/a\u003e[Lazy Evaluation](#lazy-evaluation)\n    - \u003ca name=\"toc18\"\u003e\u003c/a\u003e[Condition Operators (Comparators)](#condition-operators-comparators)\n        - \u003ca name=\"toc19\"\u003e\u003c/a\u003e[Using Symbolic Operators](#using-symbolic-operators)\n        - \u003ca name=\"toc20\"\u003e\u003c/a\u003e[Extending Condition Operators](#extending-condition-operators)\n        - \u003ca name=\"toc21\"\u003e\u003c/a\u003e[Negation `not`](#negation-not)\n        - \u003ca name=\"toc22\"\u003e\u003c/a\u003e[Reversal `rev`](#reversal-rev)\n        - \u003ca name=\"toc23\"\u003e\u003c/a\u003e[Wrapping Condition Operators](#wrapping-condition-operators)\n            - \u003ca name=\"toc24\"\u003e\u003c/a\u003e[Global Wrapping](#global-wrapping)\n        - \u003ca name=\"toc25\"\u003e\u003c/a\u003e[Condition Local Wrapping](#condition-local-wrapping)\n        - \u003ca name=\"toc26\"\u003e\u003c/a\u003e[Combining Operations](#combining-operations)\n    - \u003ca name=\"toc27\"\u003e\u003c/a\u003e[Details](#details)\n        - \u003ca name=\"toc28\"\u003e\u003c/a\u003e[Debugging Lookups](#debugging-lookups)\n        - \u003ca name=\"toc29\"\u003e\u003c/a\u003e[Enabling/Disabling of Branches](#enabling-disabling-of-branches)\n        - \u003ca name=\"toc30\"\u003e\u003c/a\u003e[Building Conditions From Text](#building-conditions-from-text)\n            - \u003ca name=\"toc31\"\u003e\u003c/a\u003e[Grammar](#grammar)\n            - \u003ca name=\"toc32\"\u003e\u003c/a\u003e[Atomic Conditions](#atomic-conditions)\n            - \u003ca name=\"toc33\"\u003e\u003c/a\u003e[Nesting](#nesting)\n        - \u003ca name=\"toc34\"\u003e\u003c/a\u003e[Tokenizing Details](#tokenizing-details)\n            - \u003ca name=\"toc35\"\u003e\u003c/a\u003e[Functioning](#functioning)\n            - \u003ca name=\"toc36\"\u003e\u003c/a\u003e[Separator `sep`](#separator-sep)\n            - \u003ca name=\"toc37\"\u003e\u003c/a\u003e[Apostrophes](#apostrophes)\n            - \u003ca name=\"toc38\"\u003e\u003c/a\u003e[Escaping](#escaping)\n        - \u003ca name=\"toc39\"\u003e\u003c/a\u003e[Building](#building)\n            - \u003ca name=\"toc40\"\u003e\u003c/a\u003e[Autoconv: Casting of values into python simple types](#autoconv-casting-of-values-into-python-simple-types)\n    - \u003ca name=\"toc41\"\u003e\u003c/a\u003e[Context On Demand](#context-on-demand)\n    - \u003ca name=\"toc42\"\u003e\u003c/a\u003e[Lookup Providers](#lookup-providers)\n        - \u003ca name=\"toc43\"\u003e\u003c/a\u003e[Accepted Signatures](#accepted-signatures)\n        - \u003ca name=\"toc44\"\u003e\u003c/a\u003e[Parametrized Lookup Functions](#parametrized-lookup-functions)\n        - \u003ca name=\"toc45\"\u003e\u003c/a\u003e[Namespace](#namespace)\n    - \u003ca name=\"toc46\"\u003e\u003c/a\u003e[Caching](#caching)\n    - \u003ca name=\"toc47\"\u003e\u003c/a\u003e[Extensions](#extensions)\n    - \u003ca name=\"toc48\"\u003e\u003c/a\u003e[Named Conditions: Qualification](#named-conditions-qualification)\n    - \u003ca name=\"toc49\"\u003e\u003c/a\u003e[Options](#options)\n    - \u003ca name=\"toc50\"\u003e\u003c/a\u003e[Partial Evaluation](#partial-evaluation)\n    - \u003ca name=\"toc51\"\u003e\u003c/a\u003e[Streaming Data](#streaming-data)\n        - \u003ca name=\"toc52\"\u003e\u003c/a\u003e[Filtering](#filtering)\n        - \u003ca name=\"toc53\"\u003e\u003c/a\u003e[Streaming Classification](#streaming-classification)\n            - \u003ca name=\"toc54\"\u003e\u003c/a\u003e[Selective Classification](#selective-classification)\n                - \u003ca name=\"toc55\"\u003e\u003c/a\u003e[Treating of Booleans (Conditions, Not Names)](#treating-of-booleans-conditions-not-names)\n        - \u003ca name=\"toc56\"\u003e\u003c/a\u003e[Asyncronous Operations](#asyncronous-operations)\n            - \u003ca name=\"toc57\"\u003e\u003c/a\u003e[Asyncronous Filter](#asyncronous-filter)\n\n\u003c!-- TOC --\u003e\n\n\n# \u003ca href=\"#toc1\"\u003eWhat\u003c/a\u003e\n\nYou have a bunch of data, possibly streaming...\n\n```csv\nid,first_name,last_name,email,gender,ip_address\n1,Rufe,Morstatt,rmorstatt0@newsvine.de,Male,216.70.69.120\n2,Kaela,Scott,scott@opera.com,Female,73.248.145.44,2\n(...)\n```\n\n... and you need to filter. For now lets say we have them already as list of dicts.\n\nYou can do it imperatively:\n\n```python\nfoo_users = [\n    u\n    for u in users\n    if (u['gender'] == 'Male' or u['last_name'] == 'Scott') and '@' in u['email']\n]\n```\n\nor you have this module assemble a condition function from a declaration like:\n\n```python\nfrom pycond import make_filter\ncond = 'email contains .de and gender eq Male or last_name eq Scott'\nis_foo = make_filter(cond) # the built filter function is first\n```\n\nand then apply as often as you need, against varying state / facts / models (...):\n\n```\nfoo_users = filter(is_foo, users)\n```\n\nwith roughly the same performance (factor 2-3) than the handcrafted python.\n\n\u003e In real life performance is often **better** then using imperative code, due to\n`pycond's` [lazy evaluation](#context-on-demand-and-lazy-evaluation) feature. \n\n# \u003ca href=\"#toc2\"\u003eWhy\u003c/a\u003e\n\nWhen the developer can decide upon the filters to apply on data he'll certainly\nuse Python's excellent expressive possibilities directly, e.g. as shown above\nthrough list comprehensions.   \nBut what if the filtering conditions are based on decisions outside of the program's\ncontrol? I.e. from an end user, hitting the program via the network, in a somehow serialized form, which is rarely directly evaluatable Python.\n\nThis is the main use case for this module.  \n\n## \u003ca href=\"#toc3\"\u003eAlternatives\u003c/a\u003e\n\nBut why yet another tool for such a standard job?  \n\nThere is a list of great tools and frameworks where condition parsing is a (small) part of them, e.g. [pyke](http://pyke.sourceforge.net/) or [durable](https://pypi.python.org/pypi/durable_rules) and many in the django world or from SQL statement parsers.\n\n\n`1.` I just needed a very **slim** tool for only the parsing into functions - but this pretty transparent and customizable\n\npycond allows to customize\n- the list of condition operators\n- the list of combination operators\n- the general behavior of condition operators via global or condition local wrappers\n- their names\n- the tokenizer\n- the value lookup function\n\nand ships as zero dependency single module.\n\nAll evaluation is done via [partials](https://stackoverflow.com/a/3252425/4583360) and not lambdas, i.e. operations can be introspected and debugged very simply, through breakpoints or custom logging operator or lookup wrappers.\n\n`2.` Simplicity of the grammar: Easy to type directly, readable by non\nprogrammers but also synthesisable from structured data, e.g. from a web framework.\n\n\n`3.` Performance: Good enough to have \"pyconditions\" used within [stream filters](https://github.com/ReactiveX/RxPY).\nWith the current feature set we are sometimes a factor 2-3 worse but (due to lazy eval) often better,\ncompared with handcrafted list comprehensions.\n\n\n# \u003ca href=\"#toc4\"\u003eMechanics\u003c/a\u003e\n\n\u003c!-- md_links_for: github --\u003e\n\u003c!-- autogen tutorial --\u003e\n\n## \u003ca href=\"#toc5\"\u003eParsing\u003c/a\u003e\n\npycond parses the condition expressions according to a set of constraints given to the parser in the `tokenizer` function.\n\nThe result of the tokenizer is given to the builder.\n  \n\n\n```python\nimport pycond as pc\n\nexpr = '[a eq b and [c lt 42 or foo eq bar]]'\ncond = pc.to_struct(pc.tokenize(expr, sep=' ', brkts='[]'))\nprint('filter:', cond)\n# test:\ndata = [\n    {'a': 'b', 'c': 1, 'foo': 42},\n    {'a': 'not b', 'c': 1},\n]\nfiltered = list(filter(pc.make_filter(expr), data))\nprint('matching:', filtered)\nreturn cond, len(filtered)\n```\nOutput:\n\n```\nfilter: [['a', 'eq', 'b', 'and', ['c', 'lt', '42', 'or', 'foo', 'eq', 'bar']]]\nmatching: [{'a': 'b', 'c': 1, 'foo': 42}]\n```\n\n\n## \u003ca href=\"#toc6\"\u003eBuilding\u003c/a\u003e\n\nAfter parsing, the builder is assembling a nested set of operator functions,\ncombined via combining operators. The functions are partials, i.e. not yet\nevaluated - but information about the necessary keys is already available:\n  \n\n\n```python\nf, meta = pc.parse_cond('foo eq bar')\nassert meta['keys'] == ['foo']\nassert f(state={'foo': 'bar'}) == True\n```\n\n\n\nNote: The `make_filter` function is actually a convencience function for\n`parse_cond`, ignoring that meta information and calling with\n`state=\u003cfilter val\u003e`\n\n\n## \u003ca href=\"#toc7\"\u003eStructured Conditions\u003c/a\u003e\n\nOther processes may deliver condition structures via serializable formats (e.g.\njson). If you pass such already tokenized constructs to the `pycond` function,\nthen the tokenizer is bypassed:\n  \n\n\n```python\ncond = [['a', 'eq', 'b'], 'or', ['c', 'in', ['foo', 'bar']]]\nassert pc.pycond(cond)(state={'a': 'b'}) == True\n# json support is built in:\ncond_as_json = json.dumps(cond)\nassert pc.pycond(cond_as_json)(state={'a': 'b'}) == True\n```\n\n\n\n## \u003ca href=\"#toc8\"\u003eEvaluation\u003c/a\u003e\n\nThe result of the builder is a 'pycondition', i.e. a function which can be run many times against varying state of the system.\nHow state is evaluated is customizable at build and run time.\n\n## \u003ca href=\"#toc9\"\u003eDefault Lookup\u003c/a\u003e\n\n\"Lookup\" denotes the process of deriving the actual values to evaluate, from a given state. Can be simple gets, getattrs, walks into the structure - or arbitrary, via custom lookup functions.\n\nThe default is to *get* lookup keys within expressions from an initially empty `State` dict within the module. This is *not* thread safe, i.e. not to be used in async or non cooperative multitasking environments.\n  \n\n\n```python\nf = pc.pycond('foo eq bar')\nassert f() == False\npc.State['foo'] = 'bar'  # not thread safe!\nassert f() == True\n```\n\n\n(`pycond` is a shortcut for `parse_cond`, when meta infos are not required).\n\n## \u003ca href=\"#toc10\"\u003ePassing State\u003c/a\u003e\n\nUsing a state argument at evaluation *is* thread safe:  \n\n\n```python\nassert pc.pycond('a gt 2')(state={'a': 42}) == True\nassert pc.pycond('a gt 2')(state={'a': -2}) == False\n```\n\n## \u003ca href=\"#toc11\"\u003eDeep Lookup / Nested State / Lists\u003c/a\u003e\n\nYou may supply a path seperator for diving into nested structures like so:  \n\n\n```python\nm = {'a': {'b': [{'c': 1}]}}\nassert pc.pycond('a.b.0.c', deep='.')(state=m) == True\nassert pc.pycond('a.b.1.c', deep='.')(state=m) == False\nassert pc.pycond('a.b.0.c eq 1', deep='.')(state=m) == True\n# convencience argument for string conditions:\nassert pc.pycond('deep: a.b.0.c')(state=m) == True\n\n# This is how you express deep access via structured conditions:\nassert pc.pycond([('a', 'b', 0, 'c'), 'eq', 1])(state=m) == True\n\n# Since tuples are not transferrable in json, we also allow deep paths as list:\n# We apply heuristics to exclude expressions or conditions:\nc = [[['a', 'b', 0, 'c'], 'eq', 1], 'and', 'a']\nf, nfos = pc.parse_cond(c)\n# sorting order for keys: tuples at end, sorted by len, rest default py sorted:\nassert f(state=m) == True and nfos['keys'] == ['a', ('a', 'b', 0, 'c')]\n```\n\n\n- The structure may also contain objects, then we use getattribute to get to the next value.\n\n- `deep=\".\"` is actually just convience notation for supplying the following \"lookup function\" (see below):\n  \n\n\n```python\nm = {'a': {'b': [{'c': 1}]}}\nassert pc.pycond('a.b.0.c', lookup=pc.state_get_deep)(state=m) == True\n```\n\n\n### \u003ca href=\"#toc12\"\u003eLookup Performance: Prebuilt Deep Getters\u003c/a\u003e\n\nThe value lookup within nested structures can be stored into item and attribute getters (or , alternatively, an evaluated synthesized lookup function), built, when the first item has a matching structure.\n\n- Upside: [Performance](./test/test_getter_perf.py) is a few times better compared to when the structure of items is explored each time, as with the 'deep' parameter.\n- Downside: The lookup remains as built for the first structurely matching item. Schematic changes like from a key within a dict to an attribute will not except but deliver always False for the\n  actual condition value matching.\n\n- `pycond.Getters.state_get_deep2`: A list of item and attribute getters is built at first successfull lookup evaluation.\n- `pycond.Getters.state_get_evl`: An expression like \"lambda state=state['a'].b[0]['c']\" is built and evaluated, then applied to the items. \n   - Fastest way to get to the values at evaluation time.   \n   - Security: Round brackets within key names are forbidden and deliver always false - but an eval is an eval i.e. potentially evil.\n\nThese two additional \"deep\" lookup functions are conveniently made accessible by supplying a `deep2` or `deep3` argument:\n  \n\n\n```python\nm = {'a': {'b': [{'c': 1}]}}\n# 3 times faster than deep. Safe.\nassert pc.pycond('a.b.0.c', deep2='.')(state=m) == True\n# 4 times faster than deep. Eval involved.\nassert pc.pycond('a.b.0.c', deep3='.')(state=m) == True\n```\n\nThe evaluation results for the keys are cached. The cache is cleared after 1Mio entries but can be cleared manually via `pc.clear_caches()` any time before that.\n\n### \u003ca href=\"#toc13\"\u003eBest Practices\u003c/a\u003e\n\n- Lookup keys change all the time, not many items checked for specific key: Use `deep`\n- Many items to be checked with same keys, input from untrusted users: Use `deep2`\n- Many items to be checked with same keys, input from trusted users: Use `deep3`\n\n\n\n## \u003ca href=\"#toc14\"\u003ePrefixed Data\u003c/a\u003e\n\nWhen data is passed through processing pipelines, it often is passed with headers. So it may be useful to pass a global prefix to access the payload like so:\n  \n\n\n```python\nm = {'payload': {'b': [{'c': 1}], 'id': 123}}\nassert pc.pycond('b.0.c', deep='.', prefix='payload')(state=m) == True\n```\n\n## \u003ca href=\"#toc15\"\u003eAttributes Access\u003c/a\u003e\n\nSince version 20210221 we try attributes when objects are not dicts:\n  \n\n\n```python\nclass MyObj:\n    val = {'a': 'b'}\n\nm = {'payload': {'obj': MyObj()}}\ncond = [['obj.val.a', 'eq', 'b']]\nassert pc.pycond(cond, deep='.', prefix='payload')(state=m) == True\n```\n\n\n## \u003ca href=\"#toc16\"\u003eCustom Lookup And Value Passing\u003c/a\u003e\n\nYou can supply your own function for value acquisition.\n\n- Signature: See example.\n- Returns: The value for the key from the current state plus the\n  compare value for the operator function.  \n\n\n```python\n# must return a (key, value) tuple:\nmodel = {'eve': {'last_host': 'somehost'}}\n\ndef my_lu(k, v, req, user, model=model):\n    print('user check. locals:', dict(locals()))\n    return (model.get(user) or {}).get(k), req[v]\n\nf = pc.pycond('last_host eq host', lookup=my_lu)\n\nreq = {'host': 'somehost'}\nassert f(req=req, user='joe') == False\nassert f(req=req, user='eve') == True\n```\nOutput:\n\n```\nuser check. locals: {'k': 'last_host', 'v': 'host', 'req': {'host': 'somehost'}, 'user': 'joe', 'model': {'eve': {'last_host': 'somehost'}}}\nuser check. locals: {'k': 'last_host', 'v': 'host', 'req': {'host': 'somehost'}, 'user': 'eve', 'model': {'eve': {'last_host': 'somehost'}}}\n```\n\n\u003e as you can see in the example, the state parameter is just a convention\nfor `pyconds'` [title: default lookup function, fmatch:pycond.py, lmatch:def state_get] \u003c SRC \u003e .\n\n## \u003ca href=\"#toc17\"\u003eLazy Evaluation\u003c/a\u003e\n\nThis is avoiding unnecessary calculations in many cases:\n\nWhen an evaluation branch contains an \"and\" or \"and_not\" combinator, then\nat runtime we evaluate the first expression - and stop if it is already\nFalse.\nSame when first expression is True, followed by \"or\" or \"or_not\".\n\nThat way expensive deep branch evaluations are omitted or, when\nthe lookup is done lazy, the values won't be even fetched:\n  \n\n\n```python\nevaluated = []\n\ndef myget(key, val, cfg, state=None, **kw):\n    evaluated.append(key)\n    return pc.state_get(key, val, cfg, state, **kw)\n\nf = pc.pycond('[a eq b] or foo eq bar and baz eq bar', lookup=myget)\nassert f(state={'foo': 42}) == False\n# the value for \"baz\" is not even fetched and the whole (possibly\n# deep) branch after the last and is ignored:\nassert evaluated == ['a', 'foo']\nprint(evaluated)\nevaluated.clear()\n\nf = pc.pycond('[[a eq b] or foo eq bar] and baz eq bar', lookup=myget)\nassert f(state={'a': 'b', 'baz': 'bar'}) == True\n# the value for \"baz\" is not even fetched and the whole (possibly\n# deep) branch after the last and is ignored:\nassert evaluated == ['a', 'baz']\nprint(evaluated)\n```\nOutput:\n\n```\n['a', 'foo']\n['a', 'baz']\n```\n\nRemember that all keys occurring in a condition(which may be provided by the user at runtime) are returned by the condition parser. Means that building of evaluation contexts[can be done](  # context-on-demand-and-lazy-evaluation), based on the data actually needed and not more.\n\n## \u003ca href=\"#toc18\"\u003eCondition Operators (Comparators)\u003c/a\u003e\n\nAll boolean[standardlib operators](https://docs.python.org/2/library/operator.html)\nare available by default:\n  \n\n\n```python\nfrom pytest2md import html_table as tbl  # just a table gen.\nfrom pycond import get_ops\n\nfor k in 'nr', 'str':\n    s = 'Default supported ' + k + ' operators...(click to extend)'\n    print(tbl(get_ops()[k], [k + ' operator', 'alias'], summary=s))\n```\n\n\n\u003cdetails\u003e\u003csummary\u003eDefault supported nr operators...(click to extend)\u003c/summary\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003enr operator\u003c/td\u003e\u003ctd\u003ealias\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eadd\u003c/td\u003e\u003ctd\u003e+\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eand_\u003c/td\u003e\u003ctd\u003e\u0026\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eeq\u003c/td\u003e\u003ctd\u003e==\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003efloordiv\u003c/td\u003e\u003ctd\u003e//\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003ege\u003c/td\u003e\u003ctd\u003e\u003e=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003egt\u003c/td\u003e\u003ctd\u003e\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eiadd\u003c/td\u003e\u003ctd\u003e+=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eiand\u003c/td\u003e\u003ctd\u003e\u0026=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eifloordiv\u003c/td\u003e\u003ctd\u003e//=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eilshift\u003c/td\u003e\u003ctd\u003e\u003c\u003c=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eimod\u003c/td\u003e\u003ctd\u003e%=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eimul\u003c/td\u003e\u003ctd\u003e*=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eior\u003c/td\u003e\u003ctd\u003e|=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eipow\u003c/td\u003e\u003ctd\u003e**=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eirshift\u003c/td\u003e\u003ctd\u003e\u003e\u003e=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eis_\u003c/td\u003e\u003ctd\u003eis\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eis_not\u003c/td\u003e\u003ctd\u003eis\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eisub\u003c/td\u003e\u003ctd\u003e-=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eitruediv\u003c/td\u003e\u003ctd\u003e/=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eixor\u003c/td\u003e\u003ctd\u003e^=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003ele\u003c/td\u003e\u003ctd\u003e\u003c=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003elshift\u003c/td\u003e\u003ctd\u003e\u003c\u003c\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003elt\u003c/td\u003e\u003ctd\u003e\u003c\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003emod\u003c/td\u003e\u003ctd\u003e%\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003emul\u003c/td\u003e\u003ctd\u003e*\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003ene\u003c/td\u003e\u003ctd\u003e!=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eor_\u003c/td\u003e\u003ctd\u003e|\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003epow\u003c/td\u003e\u003ctd\u003e**\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003ershift\u003c/td\u003e\u003ctd\u003e\u003e\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003esub\u003c/td\u003e\u003ctd\u003e-\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003etruediv\u003c/td\u003e\u003ctd\u003e/\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003exor\u003c/td\u003e\u003ctd\u003e^\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eitemgetter\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003elength_hint\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\n\n\n\u003cdetails\u003e\u003csummary\u003eDefault supported str operators...(click to extend)\u003c/summary\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003estr operator\u003c/td\u003e\u003ctd\u003ealias\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eattrgetter\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003econcat\u003c/td\u003e\u003ctd\u003e+\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003econtains\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003ecountOf\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eiconcat\u003c/td\u003e\u003ctd\u003e+=\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003eindexOf\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003emethodcaller\u003c/td\u003e\u003ctd\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\u003c/details\u003e\n\n\n\n\n### \u003ca href=\"#toc19\"\u003eUsing Symbolic Operators\u003c/a\u003e\n\nBy default pycond uses text style operators.\n\n- `ops_use_symbolic` switches processwide to symbolic style only.\n- `ops_use_symbolic_and_txt` switches processwide to both notations allowed.\n  \n\n\n```python\npc.ops_use_symbolic()\npc.State['foo'] = 'bar'\nassert pc.pycond('foo == bar')() == True\ntry:\n    # this raises now, text ops not known anymore:\n    pc.pycond('foo eq bar')\nexcept:\n    pc.ops_use_symbolic_and_txt(allow_single_eq=True)\n    assert pc.pycond('foo = bar')() == True\n    assert pc.pycond('foo == bar')() == True\n    assert pc.pycond('foo eq bar')() == True\n    assert pc.pycond('foo != baz')() == True\n```\n\n\n\u003e Operator namespace(s) should be assigned at process start, they are global.\n\n### \u003ca href=\"#toc20\"\u003eExtending Condition Operators\u003c/a\u003e\n  \n\n\n```python\npc.OPS['maybe'] = lambda a, b: int(time.time()) % 2\n# valid expression now:\nassert pc.pycond('a maybe b')() in (True, False)\n```\n\n\n### \u003ca href=\"#toc21\"\u003eNegation `not`\u003c/a\u003e\n\nNegates the result of the condition operator:\n  \n\n\n```python\npc.State['foo'] = 'abc'\nassert pc.pycond('foo eq abc')() == True\nassert pc.pycond('foo not eq abc')() == False\n```\n\n\n### \u003ca href=\"#toc22\"\u003eReversal `rev`\u003c/a\u003e\n\nReverses the arguments before calling the operator  \n\n\n```python\npc.State['foo'] = 'abc'\nassert pc.pycond('foo contains a')() == True\nassert pc.pycond('foo rev contains abc')() == True\n```\n\n\n\u003e `rev` and `not` can be combined in any order.\n\n### \u003ca href=\"#toc23\"\u003eWrapping Condition Operators\u003c/a\u003e\n\n#### \u003ca href=\"#toc24\"\u003eGlobal Wrapping\u003c/a\u003e\n\nYou may globally wrap all evaluation time condition operations through a custom function:\n  \n\n\n```python\nl = []\n\ndef hk(f_op, a, b, l=l):\n    l.append((getattr(f_op, '__name__', ''), a, b))\n    return f_op(a, b)\n\npc.run_all_ops_thru(hk)  # globally wrap the operators\n\npc.State.update({'a': 1, 'b': 2, 'c': 3})\nf = pc.pycond('a gt 0 and b lt 3 and not c gt 4')\nassert l == []\nf()\nexpected_log = [('gt', 1, 0.0), ('lt', 2, 3.0), ('gt', 3, 4.0)]\nassert l == expected_log\npc.ops_use_symbolic_and_txt()\n```\n\n\nYou may compose such wrappers via repeated application of the `run_all_ops_thru` API function.\n\n### \u003ca href=\"#toc25\"\u003eCondition Local Wrapping\u003c/a\u003e\n\nThis is done through the `ops_thru` parameter as shown:\n  \n\n\n```python\ndef myhk(f_op, a, b):\n    return True\n\npc.State['a'] = 1\nf = pc.pycond('a eq 2')\nassert f() == False\nf = pc.pycond('a eq 2', ops_thru=myhk)\nassert f() == True\n```\n\n\n\u003e Using `ops_thru` is a good way to debug unexpected results, since you\n\u003e can add breakpoints or loggers there.\n\n### \u003ca href=\"#toc26\"\u003eCombining Operations\u003c/a\u003e\n\nYou can combine single conditions with\n\n- `and`\n- `and not`\n- `or`\n- `or not`\n- `xor` by default.\n\nThe combining functions are stored in `pycond.COMB_OPS` dict and may be extended.\n\n\u003e Do not use spaces for the names of combining operators. The user may use them but they are replaced at before tokenizing time, like `and not` -\u003e `and_not`.\n\n## \u003ca href=\"#toc27\"\u003eDetails\u003c/a\u003e\n\n### \u003ca href=\"#toc28\"\u003eDebugging Lookups\u003c/a\u003e\n\npycond provides a key getter which prints out every lookup.  \n\n\n```python\nf = pc.pycond('[[a eq b] or foo eq bar] or [baz eq bar]', lookup=pc.dbg_get)\nassert f(state={'foo': 'bar'}) == True\n```\nOutput:\n\n```\nLookup: a b -\u003e None\nLookup: foo bar -\u003e bar\n```\n\n### \u003ca href=\"#toc29\"\u003eEnabling/Disabling of Branches\u003c/a\u003e\n\nInsert booleans like shown:  \n\n\n```python\nf = pc.pycond(['foo', 'and', ['bar', 'eq', 1]])\nassert f(state={'foo': 1}) == False\nf = pc.pycond(['foo', 'and', [True, 'or', ['bar', 'eq', 1]]])\nassert f(state={'foo': 1}) == True\n```\n\n### \u003ca href=\"#toc30\"\u003eBuilding Conditions From Text\u003c/a\u003e\n\nCondition functions are created internally from structured expressions -\nbut those are[hard to type](  # lazy-dynamic-context-assembly),\ninvolving many apostropies.\n\nThe text based condition syntax is intended for situations when end users\ntype them into text boxes directly.\n\n#### \u003ca href=\"#toc31\"\u003eGrammar\u003c/a\u003e\n\nCombine atomic conditions with boolean operators and nesting brackets like:\n\n```\n[\u003c atom1 \u003e \u003c and | or | and not|... \u003e \u003catom2 \u003e ] \u003c and|or... \u003e [ [ \u003c atom3 \u003e ....\n```\n\n#### \u003ca href=\"#toc32\"\u003eAtomic Conditions\u003c/a\u003e\n\n```\n[not] \u003c lookup_key \u003e [[rev] [not] \u003c condition operator (co) \u003e \u003cvalue \u003e ]\n```\n- When just `lookup_key` is given, then `co` is set to the `truthy` function:\n```python\ndef truthy(key, val=None):\n    return operatur.truth(k)\n```\n\nso such an expression is valid and True:\n  \n\n\n```python\npc.State.update({'foo': 1, 'bar': 'a', 'baz': []})\nassert pc.pycond('[ foo and bar and not baz]')() == True\n```\n\n- When `not lookup_key` is given, then `co` is set to the `falsy`\n  function:\n  \n\n\n```python\nm = {'x': 'y', 'falsy_val': {}}\n# normal way\nassert pc.pycond(['foo', 'eq', None])(state=m) == True\n# using \"not\" as prefix:\nassert pc.pycond('not foo')(state=m) == True\nassert pc.pycond(['not', 'foo'])(state=m) == True\nassert pc.pycond('not falsy_val')(state=m) == True\nassert pc.pycond('x and not foo')(state=m) == True\nassert pc.pycond('y and not falsy_val')(state=m) == False\n```\n\n\n#### \u003ca href=\"#toc33\"\u003eNesting\u003c/a\u003e\n\nCombined conditions may be arbitrarily nested using brackets \"[\" and \"]\".\n\n\u003e Via the `brkts` config parameter you may change those to other separators at build time.\n\n### \u003ca href=\"#toc34\"\u003eTokenizing Details\u003c/a\u003e\n\n\u003e Brackets as strings in this flat list form, e.g. `['[', 'a', 'and' 'b', ']'...]`\n\n#### \u003ca href=\"#toc35\"\u003eFunctioning\u003c/a\u003e\n\nThe tokenizers job is to take apart expression strings for the builder.\n\n#### \u003ca href=\"#toc36\"\u003eSeparator `sep`\u003c/a\u003e\n\nSeparates the different parts of an expression. Default is ' '.\n  \n\n\n```python\npc.State['a'] = 42\nassert pc.pycond('a.eq.42', sep='.')() == True\n```\n\n\u003e sep can be a any single character including binary.\n\nBracket characters do not need to be separated, the tokenizer will do:\n  \n\n\n```python\n# equal:\nassert (\n    pc.pycond('[[a eq 42] and b]')() == pc.pycond('[ [ a eq 42 ] and b ]')()\n)\n```\n\n\u003e The condition functions themselves do not evaluate equal - those\n\u003e had been assembled two times.\n\n#### \u003ca href=\"#toc37\"\u003eApostrophes\u003c/a\u003e\n\nBy putting strings into Apostrophes you can tell the tokenizer to not further inspect them, e.g. for the seperator:\n  \n\n\n```python\npc.State['a'] = 'Hello World'\nassert pc.pycond('a eq \"Hello World\"')() == True\n```\n\n\n#### \u003ca href=\"#toc38\"\u003eEscaping\u003c/a\u003e\n\nTell the tokenizer to not interpret the next character:\n  \n\n\n```python\npc.State['b'] = 'Hello World'\nassert pc.pycond('b eq Hello\\ World')() == True\n```\n\n\n### \u003ca href=\"#toc39\"\u003eBuilding\u003c/a\u003e\n\n#### \u003ca href=\"#toc40\"\u003eAutoconv: Casting of values into python simple types\u003c/a\u003e\n\nExpression string values are automatically cast into bools and numbers via the public `pycond.py_type` function.\n\nThis can be prevented by setting the `autoconv` parameter to `False` or by using Apostrophes:\n  \n\n\n```python\npc.State['a'] = '42'\nassert pc.pycond('a eq 42')() == False\n# compared as string now\nassert pc.pycond('a eq \"42\"')() == True\n# compared as string now\nassert pc.pycond('a eq 42', autoconv=False)() == True\n```\n\n\nIf you do not want to provide a custom lookup function(where you can do what you want)\nbut want to have looked up keys autoconverted then use:\n  \n\n\n```python\nfor id in '1', 1:\n    pc.State['id'] = id\n    assert pc.pycond('id lt 42', autoconv_lookups=True)\n```\n\n\n## \u003ca href=\"#toc41\"\u003eContext On Demand\u003c/a\u003e\n\nOften the conditions are in user space, applied on data streams under\nthe developer's control only at development time.\n\nThe end user might pick only a few keys from many offered within an API.\n\npycond's `ctx_builder` allows to only calculate those keys at runtime,\nthe user decided to base conditions upon:\nAt condition build time hand over a namespace for *all * functions which\nare available to build the ctx.\n\n`pycon` will return a context builder function for you, calling only those functions\nwhich the condition actually requires.\n  \n\n\n```python\npc.ops_use_symbolic_and_txt(allow_single_eq=True)\n\n# Condition the end user configured, e.g. at program run time:\ncond = [\n    ['group_type', 'in', ['lab', 'first1k', 'friendly', 'auto']],\n    'and',\n    [\n        [\n            [\n                [\n                    ['cur_q', '\u003c', 0.5],\n                    'and',\n                    ['delta_q', '\u003e=', 0.15],\n                ],\n                'and',\n                ['dt_last_enforce', '\u003e', 28800],\n            ],\n            'and',\n            ['cur_hour', 'in', [3, 4, 5]],\n        ],\n        'or',\n        [\n            [\n                [\n                    ['cur_q', '\u003c', 0.5],\n                    'and',\n                    ['delta_q', '\u003e=', 0.15],\n                ],\n                'and',\n                ['dt_last_enforce', '\u003e', 28800],\n            ],\n            'and',\n            ['clients', '=', 0],\n        ],\n    ],\n]\n\n# Getters for API keys offered to the user, involving potentially\n# expensive to fetch context delivery functions:\n# Signature must provide minimum a positional for the current\n# state:\nclass ApiCtxFuncs:\n    def expensive_but_not_needed_here(ctx):\n        raise Exception(\"Won't run with cond. from above\")\n\n    def cur_q(ctx):\n        print('Calculating cur_q')\n        return 0.1\n\n    def cur_hour(ctx):\n        print('Calculating cur_hour')\n        return 4\n\n    def dt_last_enforce(ctx):\n        print('Calculating dt_last_enforce')\n        return 10000000\n\n    def delta_q(ctx):\n        print('Calculating (expensive) delta_q')\n        time.sleep(0.1)\n        return 1\n\n    def clients(ctx):\n        print('Calculating clients')\n        return 0\n\nif sys.version_info[0] \u003c 3:\n    # we don't think it is a good idea to make the getter API stateful ;-)\n    p2m.convert_to_staticmethods(ApiCtxFuncs)\n\nf, nfos = pc.parse_cond(cond, ctx_provider=ApiCtxFuncs)\n\n# now we create (incomplete) data..\ndata1 = {'group_type': 'xxx'}, False\ndata2 = {'group_type': 'lab'}, True\n\n# this key stores a context builder function, calculating the complete data:\nmake_ctx = nfos['complete_ctx']\n\nt0 = time.time()\nfor event, expected in data1, data2:\n    assert f(state=make_ctx(event)) == expected\n\nprint('Calc.Time (delta_q was called twice):', round(time.time() - t0, 4)),\nreturn cond, ApiCtxFuncs\n```\nOutput:\n\n```\nCalculating clients\nCalculating cur_hour\nCalculating cur_q\nCalculating (expensive) delta_q\nCalculating dt_last_enforce\nCalculating clients\nCalculating cur_hour\nCalculating cur_q\nCalculating (expensive) delta_q\nCalculating dt_last_enforce\nCalc.Time (delta_q was called twice): 0.2006\n```\n\n\n## \u003ca href=\"#toc42\"\u003eLookup Providers\u003c/a\u003e\n\nContextBuilders are interesting but we can do better.\n\nWe still calculated values for keys which might(dependent on the data) be not needed in dead ends of a lazily evaluated condition.\n\nLets avoid calculating these values, remembering the [custom lookup function](#custom-lookup-and-value-passing) feature.\n\nThis is where lookup providers come in, providing namespaces for functions to be called conditionally.\n\nPycond [treats the condition keys as function names][pycond.py#614] within that namespace and calls them, when needed.\n\n### \u003ca href=\"#toc43\"\u003eAccepted Signatures\u003c/a\u003e\n\nLookup provider functions may have the following signatures:\n  \n\n\n```python\nclass F:\n    # simple data passing\n    def f1(data):\n        \"\"\"simple return a value being compared, getting passed the state/data\"\"\"\n        return data['a']\n\n    # simple, with ctx\n    def f2(data, **kw):\n        \"\"\"\n        simple return a value being compared, getting passed the state/data\n        All context information within kw, compare value not modifiable\n        \"\"\"\n        return data['b']\n\n    # full pycond compliant signature,\n    def f3(key, val, cfg, data, **kw):\n        \"\"\"\n        full pycond signature.\n        val is the value as defined by the condition, and which you could return modified\n        kw holds the cache, cfg holds the setup\n        v has to be returned:\n        \"\"\"\n        return data['c'], 100  # not 45!\n\n    # applied al\n    def f4(*a, **kw):\n        \"\"\"\n        Full variant(always when varargs are involved)\n        \"\"\"\n        return a[3]['d'], 'foo'\n\n_ = 'and'\nf = pc.pycond(\n    [\n        [':f1', 'eq', 42],\n        _,\n        [':f2', 'eq', 43, _, ':f3', 'eq', 45],\n        _,\n        [':f4', 'eq', 'foo'],\n    ],\n    lookup_provider=F,\n)\nassert f(state={'a': 42, 'b': 43, 'c': 100, 'd': 'foo'}) == True\n```\n\n### \u003ca href=\"#toc44\"\u003eParametrized Lookup Functions\u003c/a\u003e\n\nVia the 'params' parameter you may supply keyword args to lookup functions:  \n\n\n```python\nclass F:\n    def hello(k, v, cfg, data, count, **kw):\n        return data['foo'] == count, 0\n\nm = pc.pycond([':hello'], lookup_provider=F, params={'hello': {'count': 2}})(\n    state={'foo': 2}\n)\nassert m == True\n```\n\n\n### \u003ca href=\"#toc45\"\u003eNamespace\u003c/a\u003e\n\n- Lookup functions can be found in nested class hirarchies or dicts. Separator is colon(':')\n- As shown above, if they are flat within a toplevel class or dict you should still prefix with ':', to get build time exception(MissingLookupFunction) when not present\n- You can switch that behaviour off per condition build as config arg, as shown below\n- You can switch that behaviour off globally via `pc.prefixed_lookup_funcs=False`\n\nWarning: This is a breaking API change with pre-20200610 versions, where the prefix was not required to find functions in, back then, only flat namespaces. Use the global switch after import to get the old behaviour.\n  \n\n\n```python\nclass F:\n    def a(data):\n        return data['foo']\n\n    class inner:\n        def b(data):\n            return data['bar']\n\nm = {'c': {'d': {'func': lambda data: data['baz']}}}\n\n# for the inner lookup the first prefix may be omitted:\n_ = 'and'\ncond = [\n    [':a', 'eq', 'foo1'],\n    _,\n    ['inner:b', 'eq', 'bar1'],\n    _,\n    [\n        'c:d',\n        'eq',\n        'baz1',\n    ],\n]\nc = pc.pycond(cond, lookup_provider=F, lookup_provider_dict=m)\nassert c(state={'foo': 'foo1', 'bar': 'bar1', 'baz': 'baz1'}) == True\n\n# Prefix checking on / off:\ntry:\n    pc.pycond([':xx', 'and', cond])\n    i = 9 / 0  # above will raise this:\nexcept pc.MissingLookupFunction:\n    pass\ntry:\n    pc.pycond([':xx', 'and', cond], prefixed_lookup_funcs=False)\n    i = 9 / 0  # above will raise this:\nexcept pc.MissingLookupFunction:\n    pass\ncond[0] = 'a'  # remove prefix, will still be found\nc = pc.pycond(\n    ['xx', 'or', cond],\n    lookup_provider=F,\n    lookup_provider_dict=m,\n    prefixed_lookup_funcs=False,\n)\nassert c(state={'foo': 'foo1', 'bar': 'bar1', 'baz': 'baz1'}) == True\n```\n\nYou can switch that prefix needs off - and pycond will then check the state for key presence:\n  \n\n\n```python\n# we let pycond generate the lookup function (we use the simple signature type):\nf = pc.pycond(cond, lookup_provider=ApiCtxFuncs, prefixed_lookup_funcs=False)\n# Same events as above:\ndata1 = {'group_type': 'xxx'}, False\ndata2 = {'group_type': 'lab'}, True\n\nt0 = time.time()\nfor event, expected in data1, data2:\n    # we will lookup only once:\n    assert f(state=event) == expected\n\nprint(\n    'Calc.Time (delta_q was called just once):',\n    round(time.time() - t0, 4),\n)\n\n# The deep switch keeps working:\ncond2 = [cond, 'or', ['a-0-b', 'eq', 42]]\nf = pc.pycond(\n    cond2,\n    lookup_provider=ApiCtxFuncs,\n    deep='-',\n    prefixed_lookup_funcs=False,\n)\ndata2[0]['a'] = [{'b': 42}]\nprint('sample:', data2[0])\nassert f(state=data2[0]) == True\n```\nOutput:\n\n```\nCalculating cur_q\nCalculating (expensive) delta_q\nCalculating dt_last_enforce\nCalculating cur_hour\nCalc.Time (delta_q was called just once): 0.1007\nsample: {'group_type': 'lab', 'a': [{'b': 42}]}\nCalculating cur_q\nCalculating (expensive) delta_q\nCalculating dt_last_enforce\nCalculating cur_hour\n```\n\n\nThe output demonstrates that we did not even call the value provider functions for the dead branches of the condition.\n\nNOTE: Instead of providing a class tree you may also provide a dict of functions as `lookup_provider_dict` argument, see `qualify` examples below.\n\n## \u003ca href=\"#toc46\"\u003eCaching\u003c/a\u003e\n\nNote: Currently you cannot override these defaults. Drop an issue if you need to.\n\n- Builtin state lookups: Not cached\n- Custom `lookup` functions: Not cached(you can implement caching within those functions)\n- Lookup provider return values: Cached, i.e. called only once, per data set\n- Named condition sets(see below): Cached\n\n## \u003ca href=\"#toc47\"\u003eExtensions\u003c/a\u003e\n\nWe deliver a few lookup function [extensions][pycond.py#711]\n\n- for time checks\n- for os.environ checks(re-evaluated at runtime)\n  \n\n\n```python\nfrom datetime import datetime as dt\nfrom os import environ as env\n\nthis_sec = dt.now().second\nthis_utc_hour = dt.utcnow().hour\nf = pc.pycond(\n    [\n        ['env:foo', 'eq', 'bar'],\n        'and',\n        # not breaking the build when the sec just jumps:\n        ['dt:second', 'in', [this_sec, this_sec + 1, 0]],\n        'and',\n        ['utc:hour', 'eq', this_utc_hour],\n    ]\n)\nenv['foo'] = 'bar'\nassert f(state={'a': 1}) == True\n```\n\n\n\n## \u003ca href=\"#toc48\"\u003eNamed Conditions: Qualification\u003c/a\u003e\n\nInstead of just delivering booleans, pycond can be used to determine a whole set of\ninformation about data declaratively, like so:  \n\n\n```python\n# We accept different forms of delivery.\n# The first full text is restricted to simple flat dicts only:\nfor c in [\n    'one: a gt 10, two: a gt 10 or foo eq bar',\n    {'one': 'a gt 10', 'two': 'a gt 10 or foo eq bar'},\n    {\n        'one': ['a', 'gt', 10],\n        'two': ['a', 'gt', 10, 'or', 'foo', 'eq', 'bar'],\n    },\n]:\n    f = pc.qualify(c)\n    r = f({'foo': 'bar', 'a': 0})\n    assert r == {'one': False, 'two': True}\n```\n\n\nWe may refer to results of other named conditions and also can pass named condition sets as lists instead of dicts:  \n\n\n```python\ndef run(q):\n    print('Running', q)\n\n    class F:\n        def custom(data):\n            return data.get('a')\n\n    f = pc.qualify(q, lookup_provider=F)\n\n    assert f({'a': 'b'}) == {\n        'first': True,\n        'listed': [False, False],\n        'thrd': True,\n        'zero': True,\n        'last': True,\n    }\n    res = f({'c': 'foo', 'x': 1})\n    assert res == {\n        'first': False,\n        'listed': [False, True],\n        'thrd': False,\n        'zero': True,\n        'last': True,\n    }\n\nq = {\n    'thrd': ['k', 'or', ':first'],\n    'listed': [['foo'], ['c', 'eq', 'foo']],\n    'zero': [['x', 'eq', 1], 'or', ':thrd'],\n    'first': [':custom', 'eq', 'b'],\n    'last': True,  # you might want to do this to always get at least one matcher, e.g. for data streaming\n}\n# as list of conditions:\nrun(q)\n\n# as dict:\nq = dict([[k, v] for k, v in q.items()])\nrun(q)\n```\nOutput:\n\n```\nRunning {'thrd': ['k', 'or', ':first'], 'listed': [['foo'], ['c', 'eq', 'foo']], 'zero': [['x', 'eq', 1], 'or', ':thrd'], 'first': [':custom', 'eq', 'b'], 'last': True}\nRunning {'thrd': ['k', 'or', ':first'], 'listed': [['foo'], ['c', 'eq', 'foo']], 'zero': [['x', 'eq', 1], 'or', ':thrd'], 'first': [':custom', 'eq', 'b'], 'last': True}\n```\n\nWARNING: For performance reasons there is no built in circular reference check. You'll run into python's built in recursion checker!\n\n## \u003ca href=\"#toc49\"\u003eOptions\u003c/a\u003e\n\n- into: Put the matched named conditions into the original data\n- prefix: Work from a prefix nested in the root\n- add_cached: Return also the data from function result cache\n\nHere a few variants to parametrize behaviour, by example:  \n\n\n```python\nconds = {\n    0: ['foo'],\n    1: ['bar'],\n    2: ['func'],\n    3: ['n'],\n    'n': ['bar'],\n}\n\nclass F:\n    def func(*a, **kw):\n        return True, 0\n\nq = lambda d, **kw: pc.qualify(\n    conds, lookup_provider=F, prefixed_lookup_funcs=False, **kw\n)(d)\n\nm = q({'bar': 1})\nassert m == {0: False, 1: True, 2: True, 3: True, 'n': True}\n\n# return data, with matched conds in:\nm = q({'bar': 1}, into='conds')\nassert m == {\n    'bar': 1,\n    'conds': {0: False, 1: True, 2: True, 3: True, 'n': True},\n}\n\ndef msg():\n    return {'bar': 1, 'pl': {'a': 1}}\n\n# add_cached == True -\u003e it's put into the cond results:\nm = q(msg(), into='conds', add_cached=True)\nassert m == {\n    'bar': 1,\n    'conds': {0: False, 1: True, 2: True, 3: True, 'n': True, 'func': True},\n    'pl': {'a': 1},\n}\n\nm = q(msg(), into='conds', add_cached='pl')\nassert m == {\n    'bar': 1,\n    'conds': {0: False, 1: True, 2: True, 3: True, 'n': True},\n    # n had been put into the cache, was not evaled twice:\n    'pl': {'a': 1, 'func': True, 'n': True},\n}\n\nm = q({'bar': 1}, add_cached='pl')\nassert m == {0: False, 1: True, 2: True, 3: True, 'n': True, 'func': True}\n\n# prefix -\u003e Nr 1, bar,  should NOT be True, since not in pl now:\nm = q(\n    msg(),\n    prefix='pl',\n    into='conds',\n    add_cached='pl',\n)\nassert m == {\n    'bar': 1,\n    'conds': {0: False, 1: False, 2: True, 3: False, 'n': False},\n    'pl': {'a': 1, 'func': True, 'n': False},\n}\n```\n\n\n\n## \u003ca href=\"#toc50\"\u003ePartial Evaluation\u003c/a\u003e\n\nIf you either supply a key called 'root' OR supply it as argument to `qualify`, pycond will only evaluate named conditions required to calculate the root key:\n  \n\n\n```python\ncalled = []\n\ndef expensive_func(k, v, cfg, data, **kw):\n    called.append(data)\n    return 1, v\n\ndef xx(k, v, cfg, data, **kw):\n    called.append(data)\n    return data.get('a'), v\n\nfuncs = {'exp': {'func': expensive_func}, 'xx': {'func': xx}}\nq = {\n    'root': ['foo', 'and', ':bar'],\n    'bar': [\n        ['somecond'],\n        'or',\n        [[':exp', 'eq', 1], 'and', ':baz'],\n    ],\n    'x': [':xx'],\n    'baz': [':exp', 'lt', 10],\n}\nqualifier = pc.qualify(q, lookup_provider_dict=funcs, add_cached=True)\n\nd = {'foo': 1}\nr = qualifier(d)\n\n# root, bar, baz had been calculated, not x\nassert r == {'root': True, 'bar': True, 'baz': True, 'exp': 1}\n# expensive_func result, which was cached, is also returned.\n# expensive_func only called once allthough result evaluated for bar and baz:\nassert len(called) == 1\n\ncalled.clear()\nf = pc.qualify(q, lookup_provider_dict=funcs, root='x', add_cached=True)\nassert f({'a': 1}) == {'x': True, 'xx': 1}\nassert f({'b': 1}) == {'x': False, 'xx': None}\nassert called == [{'a': 1}, {'b': 1}]\n```\n\nThis means pycond can be used as a lightweight declarative function dispatching framework.\n  \n\n## \u003ca href=\"#toc51\"\u003eStreaming Data\u003c/a\u003e\n\nSince version 20200601 and Python 3.x versions, pycond can deliver[ReactiveX](https://github.com/ReactiveX/RxPY) compliant stream operators.\n\nLets first set up a test data stream, by defining a function `rx_setup` like so:\n  \n\n\n```python\n# simply `import rx as Rx and rx = rx.operators`:\n# import pycond as pc, like always:\nRx, rx, GS = pc.import_rx('GS')\n\ndef push_through(*test_pipe, items=4):\n    \"\"\"\n    Function which takes a set of operators and runs an 'rx.interval' stream, until count items are through\n    \"\"\"\n\n    # stream sink result holder plus a stream completer:\n    l, compl = [], rx.take(items)\n    l.clear()  # clear any previous results\n\n    def next_(x):\n        # simply remember what went through in a list:\n        l.append(x)\n\n    def err(*a):\n        # should never happen:\n        print('exception', a)\n\n    stream = Rx.interval(0.01)  # numbers, each on its own thread\n\n    # turns the ints into dicts: {'i': 1}, then {'i': 2} and so on:\n    # (we start from 1, the first 0 we filter out)\n    stream = stream.pipe(\n        rx.filter(lambda i: i \u003e 0), rx.map(lambda i: {'i': i})\n    )\n\n    # defines the stream through the tested operators:\n    test_pipe = test_pipe + (compl,)\n    s = stream.pipe(*test_pipe)\n\n    # runs the stream:\n    d = s.subscribe(\n        on_error=err,\n        on_next=next_,\n        on_completed=lambda: l.append('completed'),\n    )\n\n    # blocks until completed:\n    while not (l and l[-1] == 'completed'):\n        time.sleep(0.001)\n    l.pop()  # removes completed indicator\n\n    return l  # returns all processed messages\n\nreturn Rx, rx, push_through\n```\n\nLets test the setup by having some messages streamed through:\n  \n\n\n```python\nRx, rx, push_through = rx_setup()\n# test test setup:\nr = push_through(items=3)\nassert r == [{'i': 1}, {'i': 2}, {'i': 3}]\n```\n\n-\u003e test setup works.\n\n### \u003ca href=\"#toc52\"\u003eFiltering\u003c/a\u003e\n\nThis is the most simple operation: A simple stream filter.\n  \n\n\n```python\nRx, rx, push_through = rx_setup()\n\n# ask pycond for a stream filter based on a condition:\npcfilter = partial(pc.rxop, ['i', 'mod', 2])\n\nr = push_through(pcfilter())\nodds = [{'i': 1}, {'i': 3}, {'i': 5}, {'i': 7}]\nassert r == odds\n\n# try the stream filter with message headered data:\npl = 'payload'\nr = push_through(rx.map(lambda i: {pl: i}), pcfilter(prefix=pl))\nprint('Full messages passed:', r)\nr = [m[pl] for m in r]\nassert len(r) == 4\nassert r == odds\n```\nOutput:\n\n```\nFull messages passed: [{'payload': {'i': 1}}, {'payload': {'i': 3}}, {'payload': {'i': 5}}, {'payload': {'i': 7}}]\n```\n\n### \u003ca href=\"#toc53\"\u003eStreaming Classification\u003c/a\u003e\n\nUsing named condition dicts we can classify data, i.e. tag it, in order to process subsequently:\n  \n\n\n```python\nRx, rx, push_through = rx_setup()\n\n# generate a set of classifiers:\nconds = [['i', 'mod', i] for i in range(2, 4)]\n\ndef run(offs=0):\n\n    # and get a classifying operator from pycond, adding the results in place, at key 'mod':\n    r = push_through(pc.rxop(conds, into='mod'))\n    i, j = 0 + offs, 1 + offs\n    assert r == [\n        {'i': 1, 'mod': {i: 1, j: 1}},\n        {'i': 2, 'mod': {i: 0, j: 2}},\n        {'i': 3, 'mod': {i: 1, j: 0}},\n        {'i': 4, 'mod': {i: 0, j: 1}},\n    ]\n\n# this will automatically number the classifiers, from 0:\nrun()\n\n# we can also provide the names of the classifiers by passing a dict:\n# here we pass 2 and 3 as those names:\nconds = dict([(i, ['i', 'mod', i]) for i in range(2, 4)])\nrun(2)\n```\n\nNormally the data has headers, so thats a good place to keep the classification tags.\n\n#### \u003ca href=\"#toc54\"\u003eSelective Classification\u003c/a\u003e\n\nWe fall back to an alternative condition evaluation(which could be a function call) * only * when a previous condition evaluation returns something falsy - by providing a * root condition*.\nWhen it evaluated, possibly requiring evaluation of other conditions, we return:  \n\n\n```python\nRx, rx, push_through = rx_setup()\n\n# using the list style:\nconds = [[i, [['i', 'mod', i], 'or', ':alt']] for i in range(2, 4)]\nconds.append(['alt', ['i', 'gt', 1]])\n\n# provide the root condition. Only when it evals falsy, the named \"alt\" condiction will be evaluated:\nr = push_through(pc.rxop(conds, into='mod', root=2, add_cached=True))\n\nassert r == [\n    # evaluation of alt was not required:\n    {'i': 1, 'mod': {2: True}},\n    # evaluation of alt was required:\n    {'i': 2, 'mod': {2: True, 'alt': True}},\n    {'i': 3, 'mod': {2: True}},\n    {'i': 4, 'mod': {2: True, 'alt': True}},\n]\n```\n\n##### \u003ca href=\"#toc55\"\u003eTreating of Booleans (Conditions, Not Names)\u003c/a\u003e\n\nFor the special case of booleans in a condition list we do not treat them as names.  \n\n\n```python\n# 2 unnamed conditions -\u003e keys will be positional\nqs = pc.qualify([True, False])\nres = qs({'a': 1})\nassert res == {0: True, 1: False}  # and not {True: False}\n# 2 named conds\nqs = pc.qualify([[1, ['a', 'eq', 1]], [2, ['b', 'eq', 42]]])\nres = qs({'a': 1})\nassert res == {1: True, 2: False}\n```\n\n### \u003ca href=\"#toc56\"\u003eAsyncronous Operations\u003c/a\u003e\n\nWARNING: Early Version. Only for the gevent platform.\n\nSelective classification allows to call condition functions only when other criteria are met.\nThat makes it possible to read e.g. from a database only when data is really required - and not always, \"just in case\".\n\npycond allows to define, that blocking operations should be run * async* within the stream, possibly giving up order.\n\n#### \u003ca href=\"#toc57\"\u003eAsyncronous Filter\u003c/a\u003e\n\nFirst a simple filter, which gives up order but does not block:\n  \n\n\n```python\nRx, rx, push_through = rx_setup()\n\nclass F:\n    def check(k, v, cfg, data, t0=[], **kw):\n        # will be on different thread:\n        i, pointer = data['i'], ''\n        if not t0:\n            t0.append(now())\n        if i == 1:\n            # ints are fired at 0.01, i.e. the 1 will land 4 after 1:\n            time.sleep(0.048)\n            pointer = '   \u003c----- not in order, blocked'\n        # demonstrate that item 1 is not blocking anything - just order is disturbed:\n        print('item %s: %.3fs %s' % (i, now() - t0[0], pointer))\n        return i % 2, v\n\n# have the operator built for us - with a single condition filter:\nrxop = pc.rxop(\n    [':check'],\n    into='mod',\n    lookup_provider=F,\n    asyn=['check'],\n)\nr = push_through(rxop, items=5)\nassert [m['i'] for m in r] == [3, 5, 1, 7, 9]\n```\nOutput:\n\n```\nitem 2: 0.011s \nitem 3: 0.023s \nitem 4: 0.034s \nitem 5: 0.046s \nitem 1: 0.049s    \u003c----- not in order, blocked\nitem 6: 0.057s \nitem 7: 0.068s \nitem 8: 0.079s \nitem 9: 0.090s\n```\n\nFinally asyncronous classification, i.e. evaluation of multiple conditions:\n  \n\n\n```python\ndef _thn(msg, data):\n    return print('thread:', cur_thread().name, msg, data)\n\n# push_through just runs a stream of {'i': \u003cnr\u003e} through a given operator:\nRx, rx, push_through = rx_setup()\n\n# Defining a simple 'set' of classifiers, here as list, with one single key: 42:\nconds = [\n    [\n        42,\n        [\n            ['i', 'lt', 100],\n            'and',\n            [[':odd', 'eq', 1], 'or', ['i', 'eq', 2]],\n            'and_not',\n            [':blocking', 'eq', 3],\n        ],\n    ]\n]\n\nclass F:\n    \"\"\"\n    Namespace for condition lookup functions.\n    You may also pass a dict(lookup_provider_dict)\n\n    We provide the functions for 'odd' and 'blocking'.\n    \"\"\"\n\n    def odd(k, v, cfg, data, **kw):\n        # just print the threadname.\n        # will go up, interval stream has each nr on its own thread:\n        _thn('odd', data)\n        # fullfill condition only for odd numbers\n        # -\u003e even nrs won't even run func 'blocking':\n        return data['i'] % 2, v\n\n    def blocking(k, v, cfg, data, **kw):\n        i = data['i']\n        # will be on different thread:\n        _thn('blocking', data)\n        if i == 1:\n            # two others will \"overtake the i=1 item,\n            # since the interval stream is firing every 0.01 secs:\n            time.sleep(0.028)\n        elif i == 2:\n            # Exceptions, incl. timeouts, will simply be forwarded to cfg['err_handler']\n            # i.e. also timeout mgmt have to be done here, in the custom functions themselves.\n\n            # Rationale for not providing a timeout monitoring within pycond itself:\n            # Async ops are done with libs, which ship with their own timeout params.\n            # No need to re-invent / overlay with our own monitoring of that.\n\n            # In the err handler, then further arrangements can be done.\n            raise TimeoutError('ups')\n        elif i == 5:\n            1 / 0\n        return data['i'], v\n\nerrors = []\n\ndef handle_err(item, cfg, ctx, exc, t=errors, **kw):\n    # args are: [item, cfg]\n    if 'ups' in str(exc):\n        assert item['i'] == 2\n        assert exc.__class__ == TimeoutError\n        t.append(item)\n    else:\n        assert item['i'] == 5\n        assert exc.__class__ == ZeroDivisionError\n        t.append(item)\n\n# have the operator built for us:\nrxop = pc.rxop(\n    conds,\n    into='mod',\n    lookup_provider=F,\n    err_handler=handle_err,\n    asyn=['blocking'],\n)\nr = push_through(rxop, items=5)\nassert [m['i'] for m in r] == [3, 1, 4, 6, 7]\nassert [m['mod'][42] for m in r] == [False, True, False, False, True]\n# item 2 caused a timeout:\nassert [t['i'] for t in errors] == [2, 5]\n```\nOutput:\n\n```\nthread: Thread-54 odd {'i': 1}\nthread: Dummy-56 blocking {'i': 1}\nthread: Thread-55 odd {'i': 2}\nthread: Dummy-58 blocking {'i': 2}\nthread: Thread-57 odd {'i': 3}\nthread: Dummy-60 blocking {'i': 3}\nthread: Thread-59 odd {'i': 4}\nthread: Thread-61 odd {'i': 5}\nthread: Dummy-63 blocking {'i': 5}\nthread: Thread-62 odd {'i': 6}\nthread: Thread-64 odd {'i': 7}\nthread: Dummy-66 blocking {'i': 7}\n```\n\n\n*Auto generated by [pytest2md](https://github.com/axiros/pytest2md), running [./tests/test_tutorial.py](./tests/test_tutorial.py)\n\n\u003c!-- autogen tutorial --\u003e\n\n\n\u003c!-- autogenlinks --\u003e\n[pycond.py#614]: https://github.com/axiros/pycond/blob/1ecb45a67eaec9bf1278a0f2b50f376deb9abcfb/pycond.py#L614\n[pycond.py#711]: https://github.com/axiros/pycond/blob/1ecb45a67eaec9bf1278a0f2b50f376deb9abcfb/pycond.py#L711","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiros%2Fpycond","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faxiros%2Fpycond","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faxiros%2Fpycond/lists"}