| Name | darq-ui JSON |
| Version |
0.0.4
JSON |
| download |
| home_page | None |
| Summary | A UI for darq |
| upload_time | 2024-10-17 12:13:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | BSD-3-Clause |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
UI for darq async task manager - <https://github.com/seedofjoy/darq>
# <img src="./docs/darq_ui.png" alt="Darq UI" width="800"/>
## Installation
[PyPI package](https://pypi.org/project/darq-ui/)
```bash
pip install darq-ui
```
Or with extra dependencies:
```bash
pip install darq-ui[aiohttp]
# or
pip install darq-ui[fastapi]
```
## Integration
Use `setup` function like this `from darq_ui.integration.<framework> import setup` to integrate darq-ui with your application.
For example, to integrate with FastAPI:
```python
from fastapi import FastAPI
from darq.app import Darq
from darq_ui.integration.fastapi import setup
app = FastAPI()
darq = Darq()
setup(app, darq)
```
### Web UI
Once you have your server running, you can access the web UI at `http://host:port/darq`.
You can pass the `base_path` parameter to the `setup` function in order to change the base path of the UI.
```python
setup(app, darq, base_path="/my-path")
```
You can disable the web UI by passing `web_ui=False` to the `setup` function (it can be usefull if you want to embed darq_ui and use it only that way).
### Embedding
If you already have a UI (admin UI for example) and you can embed darq-ui into it using `<iframe />`.
```python
setup(app, darq, base_path="/admin/darq", embed=True)
```
`embed=True` will enable special endpoint `/admin/darq/embed` (if you set `base_path="/admin/darq"`).
Then you can use it in an iframe:
```jsx
export const Tasks = () => {
const url = "http://localhost:3000/admin/darq/embed";
return <iframe title='Darq UI' style={{ border: '0px' }} src={url} height='100%' width='100%' />;
}
```
### Logging link
If you have a logging system (kibana for example), you can pass `logs_url` to `setup` function. One requirement is that the url should have the `${taskName}` placeholder which will be replaced with the task name.
```python
setup(app, darq, logs_url="https://mylogserver.com/taskname=${taskName}")
```
#### Kibana url example
If you have kibana, you can use the following url:
```
https://kibana.corp/app/discover#/?_g=(time:(from:now-15m,to:now))&_a=(filters:!((('$state':(store:appState),meta:(key:task_name,params:(query:'%22${taskName}%22')),query:(match_phrase:(task_name:’${taskName}')))))
```
In this url, `task_name` is a field name and `${taskName}` will be replaced with the task name value. (This is just an example. You
may need to adjust it according to your kibana configuration.)
## Securing the UI
Since darq-ui is a part of your application, and can run any task, you should consider protecting it with authorization middleware or firewall.
## Dropping tasks
Darq UI allows you to drop running tasks. You can only drop a task that is written to work in batches and calls itself at the end.
> For now we can not drop currently running task, only the next one.
```python
BATCH_SIZE = 10
@darq.task
async def notify_users(last_id: int = 0) -> None:
users = await session.scalars(select(User).where(User.id > last_id).limit(BATCH_SIZE))
for user in users:
notify_user(user)
if len(users) == BATCH_SIZE:
await notify_users(users[-1].id)
else:
log.info("All users notified")
```
In this example, after you `drop` the task, on the next run worker won't run it again by raising an exception.
In order to enable **task dropping**, you need to call special function from `darq_ui` lib in `on_job_prerun` darq callback.
```python
from darq.app import Darq
from darq_ui.darq import maybe_drop_task
darq = Darq(... on_job_prerun=on_job_prerun)
async def on_job_prerun(
ctx: dict[str, Any],
arq_function: Any,
args: Sequence[Any],
kwargs: Mapping[str, Any],
) -> None:
# your code here
await maybe_drop_task(darq, arq_function.name)
```
In the example above, `maybe_drop_task` will check if the task is in the drop list and if so, it will raise `DarqTaskDroppedError` exception.
When you are ready, remove task from droplist in the UI and run task again.
## Examples
In order to run examples you need to install the dependencies:
```bash
cd examples
pdm install
```
And then run the server from the repo root:
```bash
lets run-fastapi
# or
lets run-aiohttp
```
* [FastAPI example](examples/fastapi_server.py)
* [Aiohttp example](examples/aiohttp_server.py)
## Development
* pdm package manager - <https://pdm.fming.dev/>
* lets task runner - <https://lets-cli.org>
### Run client build
In root directory run:
`build-ui` will build production version of assets and copy them to `src/darq_ui/static` directory.
```bash
lets build-ui
```
`build-ui-dev` will build and watch development version of assets and copy them to `src/darq_ui/static` directory.
```bash
lets build-ui-dev
```
Now you can run the server and it will serve the UI from the `src/darq_ui/static` directory.
```bash
lets run-fastapi
```
### Run linters, formatters and other checks
```bash
pdm run ruff
pdm run ruff-fmt
pdm run mypy
```
### Changelog
When developing, add notes to `CHANGELOG.md` to `Unreleased` section.
After we decided to release new version, we must rename `Unreleased` to new tag version and add new `Unreleased` section.
## Publishing
`darq-ui` supports semver versioning.
* Update the version number in the `src/darq_ui/__init__.py` file.
* Update the changelog in the `CHANGELOG.md` file.
* Merge changes into master.
* Create a tag `git tag -a v0.0.X -m 'your tag message'`.
* Push the tag `git push origin --tags`.
All of the above steps can be done with the following command:
```bash
lets release <version> -m 'your release message'
```
When new tag pushed, new release action on GitHub will publish new package to pypi.
Raw data
{
"_id": null,
"home_page": null,
"name": "darq-ui",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "\"m.kindritskiy\" <kindritskiy.m@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/c2/93935ae60efba19bff45718700359f8e884bc93d50e4aa8759b664a42d8a/darq_ui-0.0.4.tar.gz",
"platform": null,
"description": "UI for darq async task manager - <https://github.com/seedofjoy/darq>\n\n# <img src=\"./docs/darq_ui.png\" alt=\"Darq UI\" width=\"800\"/>\n\n## Installation\n\n[PyPI package](https://pypi.org/project/darq-ui/)\n\n```bash\npip install darq-ui\n```\n\nOr with extra dependencies:\n\n```bash\npip install darq-ui[aiohttp]\n# or\npip install darq-ui[fastapi]\n```\n\n## Integration\n\nUse `setup` function like this `from darq_ui.integration.<framework> import setup` to integrate darq-ui with your application.\n\nFor example, to integrate with FastAPI:\n\n```python\nfrom fastapi import FastAPI\nfrom darq.app import Darq\nfrom darq_ui.integration.fastapi import setup\n\napp = FastAPI()\ndarq = Darq()\n\nsetup(app, darq)\n```\n\n### Web UI\n\nOnce you have your server running, you can access the web UI at `http://host:port/darq`.\n\nYou can pass the `base_path` parameter to the `setup` function in order to change the base path of the UI.\n\n```python\nsetup(app, darq, base_path=\"/my-path\")\n```\n\nYou can disable the web UI by passing `web_ui=False` to the `setup` function (it can be usefull if you want to embed darq_ui and use it only that way).\n\n### Embedding\n\nIf you already have a UI (admin UI for example) and you can embed darq-ui into it using `<iframe />`.\n\n```python\nsetup(app, darq, base_path=\"/admin/darq\", embed=True)\n```\n\n`embed=True` will enable special endpoint `/admin/darq/embed` (if you set `base_path=\"/admin/darq\"`).\n\nThen you can use it in an iframe:\n\n```jsx\nexport const Tasks = () => {\n const url = \"http://localhost:3000/admin/darq/embed\";\n return <iframe title='Darq UI' style={{ border: '0px' }} src={url} height='100%' width='100%' />;\n}\n```\n\n### Logging link\n\nIf you have a logging system (kibana for example), you can pass `logs_url` to `setup` function. One requirement is that the url should have the `${taskName}` placeholder which will be replaced with the task name.\n\n```python\nsetup(app, darq, logs_url=\"https://mylogserver.com/taskname=${taskName}\")\n```\n\n#### Kibana url example\n\nIf you have kibana, you can use the following url:\n\n```\nhttps://kibana.corp/app/discover#/?_g=(time:(from:now-15m,to:now))&_a=(filters:!((('$state':(store:appState),meta:(key:task_name,params:(query:'%22${taskName}%22')),query:(match_phrase:(task_name:\u2019${taskName}')))))\n```\n\nIn this url, `task_name` is a field name and `${taskName}` will be replaced with the task name value. (This is just an example. You\nmay need to adjust it according to your kibana configuration.)\n\n## Securing the UI\n\nSince darq-ui is a part of your application, and can run any task, you should consider protecting it with authorization middleware or firewall.\n\n## Dropping tasks\n\nDarq UI allows you to drop running tasks. You can only drop a task that is written to work in batches and calls itself at the end.\n\n> For now we can not drop currently running task, only the next one.\n\n```python\nBATCH_SIZE = 10\n\n@darq.task\nasync def notify_users(last_id: int = 0) -> None:\n users = await session.scalars(select(User).where(User.id > last_id).limit(BATCH_SIZE))\n for user in users:\n notify_user(user)\n\n if len(users) == BATCH_SIZE:\n await notify_users(users[-1].id)\n else:\n log.info(\"All users notified\")\n```\n\nIn this example, after you `drop` the task, on the next run worker won't run it again by raising an exception.\n\nIn order to enable **task dropping**, you need to call special function from `darq_ui` lib in `on_job_prerun` darq callback.\n\n```python\nfrom darq.app import Darq\nfrom darq_ui.darq import maybe_drop_task\n\ndarq = Darq(... on_job_prerun=on_job_prerun)\n\nasync def on_job_prerun(\n ctx: dict[str, Any],\n arq_function: Any,\n args: Sequence[Any],\n kwargs: Mapping[str, Any],\n) -> None:\n # your code here\n await maybe_drop_task(darq, arq_function.name)\n```\n\nIn the example above, `maybe_drop_task` will check if the task is in the drop list and if so, it will raise `DarqTaskDroppedError` exception.\n\nWhen you are ready, remove task from droplist in the UI and run task again.\n\n## Examples\n\nIn order to run examples you need to install the dependencies:\n\n```bash\ncd examples\npdm install\n```\n\nAnd then run the server from the repo root:\n\n```bash\nlets run-fastapi \n# or \nlets run-aiohttp\n```\n\n* [FastAPI example](examples/fastapi_server.py)\n* [Aiohttp example](examples/aiohttp_server.py)\n\n## Development\n\n* pdm package manager - <https://pdm.fming.dev/>\n* lets task runner - <https://lets-cli.org>\n\n### Run client build\n\nIn root directory run:\n\n`build-ui` will build production version of assets and copy them to `src/darq_ui/static` directory.\n\n```bash\nlets build-ui\n```\n\n`build-ui-dev` will build and watch development version of assets and copy them to `src/darq_ui/static` directory.\n\n```bash\nlets build-ui-dev\n```\n\nNow you can run the server and it will serve the UI from the `src/darq_ui/static` directory.\n\n```bash\nlets run-fastapi\n```\n\n### Run linters, formatters and other checks\n\n```bash\npdm run ruff\npdm run ruff-fmt\npdm run mypy\n```\n\n### Changelog\n\nWhen developing, add notes to `CHANGELOG.md` to `Unreleased` section.\n\nAfter we decided to release new version, we must rename `Unreleased` to new tag version and add new `Unreleased` section.\n\n## Publishing\n\n`darq-ui` supports semver versioning.\n\n* Update the version number in the `src/darq_ui/__init__.py` file.\n* Update the changelog in the `CHANGELOG.md` file.\n* Merge changes into master.\n* Create a tag `git tag -a v0.0.X -m 'your tag message'`.\n* Push the tag `git push origin --tags`.\n\nAll of the above steps can be done with the following command:\n\n```bash\nlets release <version> -m 'your release message'\n```\n\nWhen new tag pushed, new release action on GitHub will publish new package to pypi.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A UI for darq",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/evo-company/darq_ui",
"Repository": "https://github.com/evo-company/darq_ui"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "21cf54493fa802fce11f9630a417cb069eaef703fc02d21b6b46fb12b608b6f1",
"md5": "c28a561f88f8aefa707e6af70769add4",
"sha256": "56fddf43cc87d91fbcb4492b460458c819e26b837d287e3bcb3c06fbecc25a1c"
},
"downloads": -1,
"filename": "darq_ui-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c28a561f88f8aefa707e6af70769add4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 328347,
"upload_time": "2024-10-17T12:13:26",
"upload_time_iso_8601": "2024-10-17T12:13:26.106345Z",
"url": "https://files.pythonhosted.org/packages/21/cf/54493fa802fce11f9630a417cb069eaef703fc02d21b6b46fb12b608b6f1/darq_ui-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c2c293935ae60efba19bff45718700359f8e884bc93d50e4aa8759b664a42d8a",
"md5": "f6c8d57c589fdecb9c0e3d16d6a5730d",
"sha256": "1f08a458e13283459a0b1bb3412eaf7a738c6fb424ba243963c9dc12d3a1f2db"
},
"downloads": -1,
"filename": "darq_ui-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "f6c8d57c589fdecb9c0e3d16d6a5730d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 327559,
"upload_time": "2024-10-17T12:13:28",
"upload_time_iso_8601": "2024-10-17T12:13:28.246308Z",
"url": "https://files.pythonhosted.org/packages/c2/c2/93935ae60efba19bff45718700359f8e884bc93d50e4aa8759b664a42d8a/darq_ui-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 12:13:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "evo-company",
"github_project": "darq_ui",
"github_not_found": true,
"lcname": "darq-ui"
}
