{ "info": { "author": "Venmo", "author_email": "open-source@venmo.com", "bugtrack_url": null, "classifiers": [], "description": "business-rules\n==============\n\n[![Build Status](https://travis-ci.org/venmo/business-rules.svg?branch=master)](https://travis-ci.org/venmo/business-rules)\n\nAs a software system grows in complexity and usage, it can become burdensome if\nevery change to the logic/behavior of the system also requires you to write and\ndeploy new code. The goal of this business rules engine is to provide a simple\ninterface allowing anyone to capture new rules and logic defining the behavior\nof a system, and a way to then process those rules on the backend.\n\nYou might, for example, find this is a useful way for analysts to define\nmarketing logic around when certain customers or items are eligible for a\ndiscount or to automate emails after users enter a certain state or go through\na particular sequence of events.\n\n

\n \n

\n\n## Usage\n\n### 1. Define Your set of variables\n\nVariables represent values in your system, usually the value of some particular object. You create rules by setting threshold conditions such that when a variable is computed that triggers the condition some action is taken.\n\nYou define all the available variables for a certain kind of object in your code, and then later dynamically set the conditions and thresholds for those.\n\nFor example:\n\n```python\nclass ProductVariables(BaseVariables):\n\n def __init__(self, product):\n self.product = product\n\n @numeric_rule_variable\n def current_inventory(self):\n return self.product.current_inventory\n\n @numeric_rule_variable(label='Days until expiration')\n def expiration_days(self)\n last_order = self.product.orders[-1]\n return (last_order.expiration_date - datetime.date.today()).days\n\n @string_rule_variable()\n def current_month(self):\n return datetime.datetime.now().strftime(\"%B\")\n\n @select_rule_variable(options=Products.top_holiday_items())\n def goes_well_with(self):\n return products.related_products\n```\n\n### 2. Define your set of actions\n\nThese are the actions that are available to be taken when a condition is triggered.\n\nFor example:\n\n```python\nclass ProductActions(BaseActions):\n\n def __init__(self, product):\n self.product = product\n\n @rule_action(params={\"sale_percentage\": FIELD_NUMERIC})\n def put_on_sale(self, sale_percentage):\n self.product.price = (1.0 - sale_percentage) * self.product.price\n self.product.save()\n\n @rule_action(params={\"number_to_order\": FIELD_NUMERIC})\n def order_more(self, number_to_order):\n ProductOrder.objects.create(product_id=self.product.id,\n quantity=number_to_order)\n```\n\nIf you need a select field for an action parameter, another -more verbose- syntax is available:\n\n```python\nclass ProductActions(BaseActions):\n\n def __init__(self, product):\n self.product = product\n\n @rule_action(params=[{'fieldType': FIELD_SELECT,\n 'name': 'stock_state',\n 'label': 'Stock state',\n 'options': [\n {'label': 'Available', 'name': 'available'},\n {'label': 'Last items', 'name': 'last_items'},\n {'label': 'Out of stock', 'name': 'out_of_stock'}\n ]}])\n def change_stock_state(self, stock_state):\n self.product.stock_state = stock_state\n self.product.save()\n```\n\n### 3. Build the rules\n\nA rule is just a JSON object that gets interpreted by the business-rules engine.\n\nNote that the JSON is expected to be auto-generated by a UI, which makes it simple for anyone to set and tweak business rules without knowing anything about the code. The javascript library used for generating these on the web can be found [here](https://github.com/venmo/business-rules-ui).\n\nAn example of the resulting python lists/dicts is:\n\n```python\nrules = [\n# expiration_days < 5 AND current_inventory > 20\n{ \"conditions\": { \"all\": [\n { \"name\": \"expiration_days\",\n \"operator\": \"less_than\",\n \"value\": 5,\n },\n { \"name\": \"current_inventory\",\n \"operator\": \"greater_than\",\n \"value\": 20,\n },\n ]},\n \"actions\": [\n { \"name\": \"put_on_sale\",\n \"params\": {\"sale_percentage\": 0.25},\n },\n ],\n},\n\n# current_inventory < 5 OR (current_month = \"December\" AND current_inventory < 20)\n{ \"conditions\": { \"any\": [\n { \"name\": \"current_inventory\",\n \"operator\": \"less_than\",\n \"value\": 5,\n },\n ]},\n { \"all\": [\n { \"name\": \"current_month\",\n \"operator\": \"equal_to\",\n \"value\": \"December\",\n },\n { \"name\": \"current_inventory\",\n \"operator\": \"less_than\",\n \"value\": 20,\n }\n ]},\n },\n \"actions\": [\n { \"name\": \"order_more\",\n \"params\":{\"number_to_order\": 40},\n },\n ],\n}]\n```\n\n### Export the available variables, operators and actions\n\nTo e.g. send to your client so it knows how to build rules\n\n```python\nfrom business_rules import export_rule_data\nexport_rule_data(ProductVariables, ProductActions)\n```\n\nthat returns\n\n```python\n{\"variables\": [\n { \"name\": \"expiration_days\",\n \"label\": \"Days until expiration\",\n \"field_type\": \"numeric\",\n \"options\": []},\n { \"name\": \"current_month\",\n \"label\": \"Current Month\",\n \"field_type\": \"string\",\n \"options\": []},\n { \"name\": \"goes_well_with\",\n \"label\": \"Goes Well With\",\n \"field_type\": \"select\",\n \"options\": [\"Eggnog\", \"Cookies\", \"Beef Jerkey\"]}\n ],\n \"actions\": [\n { \"name\": \"put_on_sale\",\n \"label\": \"Put On Sale\",\n \"params\": {\"sale_percentage\": \"numeric\"}},\n { \"name\": \"order_more\",\n \"label\": \"Order More\",\n \"params\": {\"number_to_order\": \"numeric\"}}\n ],\n \"variable_type_operators\": {\n \"numeric\": [ {\"name\": \"equal_to\",\n \"label\": \"Equal To\",\n \"input_type\": \"numeric\"},\n {\"name\": \"less_than\",\n \"label\": \"Less Than\",\n \"input_type\": \"numeric\"},\n {\"name\": \"greater_than\",\n \"label\": \"Greater Than\",\n \"input_type\": \"numeric\"}],\n \"string\": [ { \"name\": \"equal_to\",\n \"label\": \"Equal To\",\n \"input_type\": \"text\"},\n { \"name\": \"non_empty\",\n \"label\": \"Non Empty\",\n \"input_type\": \"none\"}]\n }\n}\n```\n\n### Run your rules\n\n```python\nfrom business_rules import run_all\n\nrules = _some_function_to_receive_from_client()\n\nfor product in Products.objects.all():\n run_all(rule_list=rules,\n defined_variables=ProductVariables(product),\n defined_actions=ProductActions(product),\n stop_on_first_trigger=True\n )\n```\n\n## API\n\n#### Variable Types and Decorators:\n\nThe type represents the type of the value that will be returned for the variable and is necessary since there are different available comparison operators for different types, and the front-end that's generating the rules needs to know which operators are available.\n\nAll decorators can optionally take a label:\n- `label` - A human-readable label to show on the frontend. By default we just split the variable name on underscores and capitalize the words.\n\nThe available types and decorators are:\n\n**numeric** - an integer, float, or python Decimal.\n\n`@numeric_rule_variable` operators:\n\n* `equal_to`\n* `greater_than`\n* `less_than`\n* `greater_than_or_equal_to`\n* `less_than_or_equal_to`\n\nNote: to compare floating point equality we just check that the difference is less than some small epsilon\n\n**string** - a python bytestring or unicode string.\n\n`@string_rule_variable` operators:\n\n* `equal_to`\n* `starts_with`\n* `ends_with`\n* `contains`\n* `matches_regex`\n* `non_empty`\n\n**boolean** - a True or False value.\n\n`@boolean_rule_variable` operators:\n\n* `is_true`\n* `is_false`\n\n**select** - a set of values, where the threshold will be a single item.\n\n`@select_rule_variable` operators:\n\n* `contains`\n* `does_not_contain`\n\n**select_multiple** - a set of values, where the threshold will be a set of items.\n\n`@select_multiple_rule_variable` operators:\n\n* `contains_all`\n* `is_contained_by`\n* `shares_at_least_one_element_with`\n* `shares_exactly_one_element_with`\n* `shares_no_elements_with`\n\n### Returning data to your client\n\n\n\n## Contributing\n\nOpen up a pull request, making sure to add tests for any new functionality. To set up the dev environment (assuming you're using [virtualenvwrapper](http://docs.python-guide.org/en/latest/dev/virtualenvs/#virtualenvwrapper)):\n\n```bash\n$ mkvirtualenv business-rules\n$ pip install -r dev-requirements.txt\n$ nosetests\n```\n", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/venmo/business-rules", "keywords": null, "license": "MIT", "maintainer": null, "maintainer_email": null, "name": "business-rules", "package_url": "https://pypi.org/project/business-rules/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/business-rules/", "project_urls": { "Download": "UNKNOWN", "Homepage": "https://github.com/venmo/business-rules" }, "release_url": "https://pypi.org/project/business-rules/1.0.1/", "requires_dist": null, "requires_python": null, "summary": "Python DSL for setting up business intelligence rules that can be configured without code\n\nHistory\n-------\n\n1.0.1\n+++++\nreleased 2016-3-16\n\n- Fixes a packaging bug preventing 1.0.0 from being installed on some platforms.\n\n1.0.0\n+++++\nreleased 2016-3-16\n\n- Removes caching layer on rule decorator", "version": "1.0.1" }, "last_serial": 2010874, "releases": { "0.1": [ { "comment_text": "", "digests": { "md5": "686025c99c7d529d905d3a541ceb9b43", "sha256": "3c042c42cc397a706c610551214ceb76145ee6f528113c07f727c3dc5d0f8431" }, "downloads": -1, "filename": "business-rules-0.1.tar.gz", "has_sig": false, "md5_digest": "686025c99c7d529d905d3a541ceb9b43", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9682, "upload_time": "2014-05-19T20:21:53", "url": "https://files.pythonhosted.org/packages/7e/72/56da16618a246acf2a4a5daa16bba5176bd26ba641b19bcc7ddee49556c9/business-rules-0.1.tar.gz" } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "c98e8bcb44d98542a912a46c2ead8451", "sha256": "b09074bb7ef455f8c9624d810e5240d6fc06d63d30a4936bef8fa7bc6409b024" }, "downloads": -1, "filename": "business-rules-0.1.1.tar.gz", "has_sig": false, "md5_digest": "c98e8bcb44d98542a912a46c2ead8451", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9699, "upload_time": "2014-05-30T21:48:00", "url": "https://files.pythonhosted.org/packages/9d/e7/7756a44ca17ecbd6a1e0987bf4854d91328ca5ab1d66abb2cbb6e7611ce2/business-rules-0.1.1.tar.gz" } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "67494e5ab90cbf11392f47a2d7919d1b", "sha256": "f36f33ef300adc739ba84ba75daf738aff20051c0c47b867e28d7eacedd9f747" }, "downloads": -1, "filename": "business-rules-0.1.2.tar.gz", "has_sig": false, "md5_digest": "67494e5ab90cbf11392f47a2d7919d1b", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 9728, "upload_time": "2014-06-11T18:43:40", "url": "https://files.pythonhosted.org/packages/d8/28/b3f4a5b086a3bc378764580d16d2cc48caa83d4ab97e5e97226f837b0667/business-rules-0.1.2.tar.gz" } ], "0.1.3": [ { "comment_text": "", "digests": { "md5": "8cce4076f62d6561407532c24dc3c7a4", "sha256": "e29b0c861349340acdaf7dd74127fa0032447a307c3a05d7b3fa90ef932f7dcd" }, "downloads": -1, "filename": "business-rules-0.1.3.tar.gz", "has_sig": false, "md5_digest": "8cce4076f62d6561407532c24dc3c7a4", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10132, "upload_time": "2014-06-16T16:20:13", "url": "https://files.pythonhosted.org/packages/5e/d7/09134aa1f863a420872900b5fc85dfdb408844df1b818dcd983c229a8851/business-rules-0.1.3.tar.gz" } ], "0.2.0": [ { "comment_text": "", "digests": { "md5": "1da52fd7672b7e4ef7c7983de5c3d6df", "sha256": "7e912650ec775648a2e8231756a30133d8c3c7cae82e3c8cca92047066d1e55d" }, "downloads": -1, "filename": "business-rules-0.2.0.tar.gz", "has_sig": false, "md5_digest": "1da52fd7672b7e4ef7c7983de5c3d6df", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 10319, "upload_time": "2015-06-16T02:13:19", "url": "https://files.pythonhosted.org/packages/9b/86/26653b41d03f5810b9eea46c6b5d95452e7ac88c6fb5d27eaaa4359ad228/business-rules-0.2.0.tar.gz" } ], "1.0.1": [ { "comment_text": "", "digests": { "md5": "00c92215ef3aeccea5f0adb7778aa264", "sha256": "e0f58104df937378856e8199a49af4f5b4dbe5ac21b863a080810dedc3326d1d" }, "downloads": -1, "filename": "business-rules-1.0.1.tar.gz", "has_sig": false, "md5_digest": "00c92215ef3aeccea5f0adb7778aa264", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13862, "upload_time": "2016-03-16T19:02:28", "url": "https://files.pythonhosted.org/packages/44/b1/5aa6d81111e701e83917ee4b16ac8882c2c4dfde57af4013f1f97a2175ac/business-rules-1.0.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "00c92215ef3aeccea5f0adb7778aa264", "sha256": "e0f58104df937378856e8199a49af4f5b4dbe5ac21b863a080810dedc3326d1d" }, "downloads": -1, "filename": "business-rules-1.0.1.tar.gz", "has_sig": false, "md5_digest": "00c92215ef3aeccea5f0adb7778aa264", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 13862, "upload_time": "2016-03-16T19:02:28", "url": "https://files.pythonhosted.org/packages/44/b1/5aa6d81111e701e83917ee4b16ac8882c2c4dfde57af4013f1f97a2175ac/business-rules-1.0.1.tar.gz" } ] }