| Name | dash-query-builder JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Component for Dash based on react-awesome-query-builder |
| upload_time | 2024-04-23 18:47:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
dash
dash-query-builder
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Dash Query Builder
Component for Dash based on [react-awesome-query-builder](https://github.com/ukrbublik/react-awesome-query-builder).
The component is a way to graphically generate WHERE clauses for SQL queries.
## Install
```shell
pip install dash_query_builder
```
## Usage
To use Dash Query Builder (DQB), you need to have a Dash app and a dictionary of fields.
The fields property is a dictionary of fields and their properties, following the
[config.fields docs](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc#configfields).
The only caveat is that JavaScript cannot be used as in the example.
For instance the following dictionary is valid:
```python
fields = {
"qty": {
"label": "Qty",
"type": "number",
"fieldSettings": {"min": 0},
"valueSources": ["value"],
"preferWidgets": ["number"],
},
"price": {
"label": "Price",
"type": "number",
"valueSources": ["value"],
"fieldSettings": {"min": 10, "max": 100},
"preferWidgets": ["slider", "rangeslider"],
"operators": ["equal", "between"],
},
"color": {
"label": "Color",
"type": "select",
"valueSources": ["value"],
"fieldSettings": {
"listValues": [
{"value": "yellow", "title": "Yellow"},
{"value": "green", "title": "Green"},
{"value": "orange", "title": "Orange"},
]
},
},
"is_promotion": {
"label": "Promo?",
"type": "boolean",
"operators": ["equal", "is_empty"],
"valueSources": ["value"],
},
}
```
The basic component can be created via:
```python
from dash import Dash, html
import dash_query_builder as dqb
fields =...
app=Dash(__name__)
app.layout=html.Div([dqb.DashQueryBuilder(fields=fields)])
app.run_server()
```
This will run the app similar to this:
https://github.com/TillerBurr/dash-query-builder/assets/49296311/1fdc9663-fde7-4c26-a706-00b5edc9f902
There are other properties available as well, with defaults in parentheses.
- config({}): see [CONFIG.adoc](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc) for full options
- theme("basic"): one of "antd", "mui", "fluent", "bootstrap", "basic"
- loadFormat("tree"): one of "tree", "spelFormat", "jsonLogicFormat"
- alwaysShowActionButtons(True): A boolean whether to always show action buttons, e.g. "Add Rule", "Add Group", etc.
With the above parameters, a query builder will be created with an empty tree. To pre-populate the query builder,
there are several ways to do so:
1. `loadFormat=="tree"`: Set `tree` to a valid tree object.
1. `loadFormat=="spelFormat"`: Set `spelFormat` to a valid SpEL string.
1. `loadFormat=="jsonLogicFormat"`: Set `jsonLogicFormat` to a valid jsonLogic object.
Once `loadFormat` is set, the tree/query builder will update when the query is changed or when the corresponding property is changed.
The `loadFormat` can be changed via a callback, while keeping the same tree.
Here's an example using `usage.py`:
https://github.com/TillerBurr/dash-query-builder/assets/49296311/1191a643-27c0-4a4f-8032-2eb5d4b1d88e
## Where Parser
DQB has a built-in parser for SQL queries. The parser is relatively simple as far as parsers go, but it does what I need it to.
It will parse the query and return a template string and a parameter dictionary. The template string will be in `pyformat` style, as
specified in [PEP 249](https://peps.python.org/pep-0249/#paramstyle).
### Example
```python
from dash_query_builder.where_parser import WhereParser
where_parser = WhereParser()
template, params = where_parser.get_template("qty > 15 and price between 10 and 20")
print(template) # (qty > %(YSaAddDFs27s)s AND price BETWEEN %(W5PRwTGpFqqF)s AND %(N2nGExcGaUSt)s)
print(params) # {'YSaAddDFs27s': 15, 'W5PRwTGpFqqF': 10, 'N2nGExcGaUSt': 20}
```
Currently, only `pyformat` is supported. PRs are welcome!
## Tools Used
- [uv](https://github.com/astral-sh/uv) for Python virtual environment and dependencies.
- [just](https://github.com/casey/just) for common commands
- [mise-en-place](https://mise.jdx.dev) to manage the toolchain.
## Development
### Getting Started
1. Create a Python environment from previous step 1 and install:
```shell
just sync
```
1. Update the requirements and dev requirements
```shell
just compile
```
1. Build
```shell
just build
```
1. Publish
```shell
just publish
```
1. See all commands with `just -l`
Raw data
{
"_id": null,
"home_page": null,
"name": "dash-query-builder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "dash, dash-query-builder",
"author": null,
"author_email": "Tyler Baur <baur.tyler@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d9/20/6466daa55ea880a26725157010fd23deed9f3a26c63cff9e09e62de29771/dash_query_builder-1.0.0.tar.gz",
"platform": null,
"description": "# Dash Query Builder\n\nComponent for Dash based on [react-awesome-query-builder](https://github.com/ukrbublik/react-awesome-query-builder).\nThe component is a way to graphically generate WHERE clauses for SQL queries.\n\n## Install\n\n```shell\npip install dash_query_builder\n```\n\n## Usage\n\nTo use Dash Query Builder (DQB), you need to have a Dash app and a dictionary of fields.\nThe fields property is a dictionary of fields and their properties, following the\n[config.fields docs](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc#configfields).\nThe only caveat is that JavaScript cannot be used as in the example.\n\nFor instance the following dictionary is valid:\n\n```python\nfields = {\n \"qty\": {\n \"label\": \"Qty\",\n \"type\": \"number\",\n \"fieldSettings\": {\"min\": 0},\n \"valueSources\": [\"value\"],\n \"preferWidgets\": [\"number\"],\n },\n \"price\": {\n \"label\": \"Price\",\n \"type\": \"number\",\n \"valueSources\": [\"value\"],\n \"fieldSettings\": {\"min\": 10, \"max\": 100},\n \"preferWidgets\": [\"slider\", \"rangeslider\"],\n \"operators\": [\"equal\", \"between\"],\n },\n \"color\": {\n \"label\": \"Color\",\n \"type\": \"select\",\n \"valueSources\": [\"value\"],\n \"fieldSettings\": {\n \"listValues\": [\n {\"value\": \"yellow\", \"title\": \"Yellow\"},\n {\"value\": \"green\", \"title\": \"Green\"},\n {\"value\": \"orange\", \"title\": \"Orange\"},\n ]\n },\n },\n \"is_promotion\": {\n \"label\": \"Promo?\",\n \"type\": \"boolean\",\n \"operators\": [\"equal\", \"is_empty\"],\n \"valueSources\": [\"value\"],\n },\n}\n```\n\nThe basic component can be created via:\n\n```python\nfrom dash import Dash, html\nimport dash_query_builder as dqb\nfields =...\napp=Dash(__name__)\napp.layout=html.Div([dqb.DashQueryBuilder(fields=fields)])\napp.run_server()\n```\n\nThis will run the app similar to this:\n\nhttps://github.com/TillerBurr/dash-query-builder/assets/49296311/1fdc9663-fde7-4c26-a706-00b5edc9f902\n\nThere are other properties available as well, with defaults in parentheses.\n\n- config({}): see [CONFIG.adoc](https://github.com/ukrbublik/react-awesome-query-builder/blob/master/CONFIG.adoc) for full options\n- theme(\"basic\"): one of \"antd\", \"mui\", \"fluent\", \"bootstrap\", \"basic\"\n- loadFormat(\"tree\"): one of \"tree\", \"spelFormat\", \"jsonLogicFormat\"\n- alwaysShowActionButtons(True): A boolean whether to always show action buttons, e.g. \"Add Rule\", \"Add Group\", etc.\n\nWith the above parameters, a query builder will be created with an empty tree. To pre-populate the query builder,\nthere are several ways to do so:\n\n1. `loadFormat==\"tree\"`: Set `tree` to a valid tree object.\n1. `loadFormat==\"spelFormat\"`: Set `spelFormat` to a valid SpEL string.\n1. `loadFormat==\"jsonLogicFormat\"`: Set `jsonLogicFormat` to a valid jsonLogic object.\n\nOnce `loadFormat` is set, the tree/query builder will update when the query is changed or when the corresponding property is changed.\nThe `loadFormat` can be changed via a callback, while keeping the same tree.\n\nHere's an example using `usage.py`:\n\nhttps://github.com/TillerBurr/dash-query-builder/assets/49296311/1191a643-27c0-4a4f-8032-2eb5d4b1d88e\n\n## Where Parser\n\nDQB has a built-in parser for SQL queries. The parser is relatively simple as far as parsers go, but it does what I need it to.\nIt will parse the query and return a template string and a parameter dictionary. The template string will be in `pyformat` style, as\nspecified in [PEP 249](https://peps.python.org/pep-0249/#paramstyle).\n\n### Example\n\n```python\nfrom dash_query_builder.where_parser import WhereParser\nwhere_parser = WhereParser()\ntemplate, params = where_parser.get_template(\"qty > 15 and price between 10 and 20\")\nprint(template) # (qty > %(YSaAddDFs27s)s AND price BETWEEN %(W5PRwTGpFqqF)s AND %(N2nGExcGaUSt)s)\nprint(params) # {'YSaAddDFs27s': 15, 'W5PRwTGpFqqF': 10, 'N2nGExcGaUSt': 20}\n```\n\nCurrently, only `pyformat` is supported. PRs are welcome!\n\n## Tools Used\n\n- [uv](https://github.com/astral-sh/uv) for Python virtual environment and dependencies.\n- [just](https://github.com/casey/just) for common commands\n- [mise-en-place](https://mise.jdx.dev) to manage the toolchain.\n\n## Development\n\n### Getting Started\n\n1. Create a Python environment from previous step 1 and install:\n ```shell\n just sync\n ```\n1. Update the requirements and dev requirements\n ```shell\n just compile\n ```\n1. Build\n ```shell\n just build\n ```\n1. Publish\n ```shell\n just publish\n ```\n1. See all commands with `just -l`\n",
"bugtrack_url": null,
"license": null,
"summary": "Component for Dash based on react-awesome-query-builder",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/tillerburr/dash-query-builder",
"Issues": "https://github.com/tillerburr/dash-query-builder/issues",
"Repository": "https://github.com/tillerburr/dash-query-builder"
},
"split_keywords": [
"dash",
" dash-query-builder"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "42705fbd828506477326202f62e9ffd3af56e323d7b6df28165aa9e2adb5d4ca",
"md5": "ca1b265be36880c1c8862ec99dfaab9a",
"sha256": "1a590818d6c904dd2b310608a421102589447995baa14969690a5f0cdf5f8fdb"
},
"downloads": -1,
"filename": "dash_query_builder-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca1b265be36880c1c8862ec99dfaab9a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 869765,
"upload_time": "2024-04-23T18:47:27",
"upload_time_iso_8601": "2024-04-23T18:47:27.568716Z",
"url": "https://files.pythonhosted.org/packages/42/70/5fbd828506477326202f62e9ffd3af56e323d7b6df28165aa9e2adb5d4ca/dash_query_builder-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d9206466daa55ea880a26725157010fd23deed9f3a26c63cff9e09e62de29771",
"md5": "245dabbaf535b895ac6470ef162eb1a8",
"sha256": "ca2f802451c3f38bcef0423556ad7c570ca9fb93febfe7dcc8c92f364d355a02"
},
"downloads": -1,
"filename": "dash_query_builder-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "245dabbaf535b895ac6470ef162eb1a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 845587,
"upload_time": "2024-04-23T18:47:30",
"upload_time_iso_8601": "2024-04-23T18:47:30.048753Z",
"url": "https://files.pythonhosted.org/packages/d9/20/6466daa55ea880a26725157010fd23deed9f3a26c63cff9e09e62de29771/dash_query_builder-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-23 18:47:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tillerburr",
"github_project": "dash-query-builder",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "dash-query-builder"
}
