<!--
SPDX-FileCopyrightText: 2020-2024 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences
SPDX-FileCopyrightText: 2021-2024 Helmholtz-Zentrum hereon GmbH
SPDX-License-Identifier: CC-BY-4.0
-->
## Progress API for the Data Analytics Software Framework (DASF)
[](https://codebase.helmholtz.cloud/dasf/dasf-progress-api/-/pipelines?page=1&scope=all&ref=master)
[](https://codebase.helmholtz.cloud/dasf/dasf-progress-api)
[](https://pypi.python.org/pypi/deprogressapi/)
[](https://github.com/psf/black)
[](https://pycqa.github.io/isort/)
[](https://www.python.org/dev/peps/pep-0008/)
[](http://mypy-lang.org/)
[](https://api.reuse.software/info/codebase.helmholtz.cloud/dasf/dasf-progress-api)
`DASF: Progress API` is part of the Data Analytics Software Framework (DASF, https://codebase.helmholtz.cloud/dasf),
developed at the GFZ German Research Centre for Geosciences (https://www.gfz-potsdam.de).
It is funded by the Initiative and Networking Fund of the Helmholtz Association through the Digital Earth project
(https://www.digitalearth-hgf.de/).
`DASF: Progress API` provides a light-weight tree-based structure to be sent via the DASF RCP messaging protocol.
It's generic design supports deterministic as well as non-deterministic progress reports.
While `DASF: Messaging Python` provides the necessary implementation to distribute
the progress reports from the reporting backend modules,
`DASF: Web` includes ready to use components to visualize the reported progress.
## Installation
Install this package in a dedicated python environment via
```bash
python -m venv venv
source venv/bin/activate
pip install deprogessapi
```
To use this in a development setup, clone the [source code][source code] from
gitlab, start the development server and make your changes::
```bash
git clone https://codebase.helmholtz.cloud/dasf/dasf-progress-api
cd dasf-progress-api
python -m venv venv
source venv/bin/activate
make dev-install
```
More detailed installation instructions my be found in the [docs][docs].
[source code]: https://codebase.helmholtz.cloud/dasf/dasf-progress-api
[docs]: https://digital-earth.pages.geomar.de/dasf/dasf-messaging-python/installation.html
## Service Desk
For everyone without a Geomar Gitlab account, we setup the Service Desk feature for this repository.
It lets you communicate with the developers via a repository specific eMail address. Each request will be tracked via the Gitlab issuse tracker.
eMail: [gitlab+digital-earth-dasf-dasf-progress-api-2274-issue-@git-issues.geomar.de](mailto:gitlab+digital-earth-dasf-dasf-progress-api-2274-issue-@git-issues.geomar.de)
## Usage
A progress report is stored in a tree structure. So there will be one 'root' report instance containing multiple 'sub-reports'.
In order to report the progress simply add a reporter argument with type `ProgressReport` to the exposed method, e.g.
```python
from deprogressapi import ProgressReport
def some_exposed_method(reporter: Optional[ProgressReport] = ProgressReport(
step_message="some progress message")) -> str:
# ...
```
For a report instance new subreports can be created via the `create_subreport` method.
Each created report is published (sent to the requesting client) automatically upon creation and on completion.
```python
# create a subreport
sub_report = root_report.create_subreport(step_message="Calculating something")
# execute some logic
# ...
# mark the sub-report as compelte
sub_report.complete()
```
All sub-reports are again instances of `ProgressReport`, so you can create more sub-reports for each.
### error handling
In order to report an error, you provide an error status argument to the `complete` method. The corresponding error message can be set via the reports `step_message` field.
```python
from deprogressapi.base import Status
# ...
# some code that raises an exception
# ...
except Exception as e:
error = str(e)
progress_report.step_message = "error '{msg}': {err}".format(msg=progress_report.step_message, err=error)
progress_report.complete(Status.ERROR)
```
## Recommended Software Citation
`Eggert, Daniel; Dransch, Doris (2021): DASF: Progress API: A progress reporting structure for the data analytics software framework. V. v0.1.4. GFZ Data Services. https://doi.org/10.5880/GFZ.1.4.2021.007`
## Technical note
This package has been generated from the template
https://codebase.helmholtz.cloud/hcdc/software-templates/python-package-template.git.
See the template repository for instructions on how to update the skeleton for
this package.
## License information
Copyright © 2020-2024 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences
Code files in this repository are licensed under the
Apache-2.0, if not stated otherwise in the file.
Documentation files in this repository are licensed under CC-BY-4.0, if not stated otherwise in the file.
Supplementary and configuration files in this repository are licensed
under CC0-1.0, if not stated otherwise
in the file.
Please check the header of the individual files for more detailed
information.
### License management
License management is handled with [``reuse``](https://reuse.readthedocs.io/).
If you have any questions on this, please have a look into the
[contributing guide][contributing] or contact the maintainers of
`dasf-progress-api`.
[contributing]: https://digital-earth.pages.geomar.de/dasf/dasf-messaging-python/contributing.html
Raw data
{
"_id": null,
"home_page": null,
"name": "deprogressapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "\"Philipp S. Sommer\" <philipp.sommer@hereon.de>",
"keywords": "digital-earth, dasf, pulsar, gfz, hzg, hereon, hgf, helmholtz, remote procedure call, rpc, django, python, websocket, progress reporting",
"author": null,
"author_email": "Daniel Eggert <daniel.eggert@gfz-potsdam.de>, Adam Sasin <sasin@hu-potsdam.de>, \"Philipp S. Sommer\" <philipp.sommer@hereon.de>",
"download_url": "https://files.pythonhosted.org/packages/2d/b2/f4588963d3bdf7343feca80326dfbdc63ff22f2de8908d9b5a892a8c49a2/deprogressapi-0.4.2.tar.gz",
"platform": null,
"description": "<!--\nSPDX-FileCopyrightText: 2020-2024 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences\nSPDX-FileCopyrightText: 2021-2024 Helmholtz-Zentrum hereon GmbH\n\nSPDX-License-Identifier: CC-BY-4.0\n-->\n\n\n\n## Progress API for the Data Analytics Software Framework (DASF)\n\n[](https://codebase.helmholtz.cloud/dasf/dasf-progress-api/-/pipelines?page=1&scope=all&ref=master)\n[](https://codebase.helmholtz.cloud/dasf/dasf-progress-api)\n[](https://pypi.python.org/pypi/deprogressapi/)\n[](https://github.com/psf/black)\n[](https://pycqa.github.io/isort/)\n[](https://www.python.org/dev/peps/pep-0008/)\n[](http://mypy-lang.org/)\n[](https://api.reuse.software/info/codebase.helmholtz.cloud/dasf/dasf-progress-api)\n\n`DASF: Progress API` is part of the Data Analytics Software Framework (DASF, https://codebase.helmholtz.cloud/dasf),\ndeveloped at the GFZ German Research Centre for Geosciences (https://www.gfz-potsdam.de).\nIt is funded by the Initiative and Networking Fund of the Helmholtz Association through the Digital Earth project\n(https://www.digitalearth-hgf.de/).\n\n`DASF: Progress API` provides a light-weight tree-based structure to be sent via the DASF RCP messaging protocol.\nIt's generic design supports deterministic as well as non-deterministic progress reports.\nWhile `DASF: Messaging Python` provides the necessary implementation to distribute\nthe progress reports from the reporting backend modules,\n`DASF: Web` includes ready to use components to visualize the reported progress.\n\n## Installation\n\nInstall this package in a dedicated python environment via\n\n```bash\npython -m venv venv\nsource venv/bin/activate\npip install deprogessapi\n```\n\nTo use this in a development setup, clone the [source code][source code] from\ngitlab, start the development server and make your changes::\n\n```bash\ngit clone https://codebase.helmholtz.cloud/dasf/dasf-progress-api\ncd dasf-progress-api\npython -m venv venv\nsource venv/bin/activate\nmake dev-install\n```\n\nMore detailed installation instructions my be found in the [docs][docs].\n\n\n[source code]: https://codebase.helmholtz.cloud/dasf/dasf-progress-api\n[docs]: https://digital-earth.pages.geomar.de/dasf/dasf-messaging-python/installation.html\n\n\n## Service Desk\n\nFor everyone without a Geomar Gitlab account, we setup the Service Desk feature for this repository.\nIt lets you communicate with the developers via a repository specific eMail address. Each request will be tracked via the Gitlab issuse tracker.\n\neMail: [gitlab+digital-earth-dasf-dasf-progress-api-2274-issue-@git-issues.geomar.de](mailto:gitlab+digital-earth-dasf-dasf-progress-api-2274-issue-@git-issues.geomar.de)\n\n\n## Usage\n\nA progress report is stored in a tree structure. So there will be one 'root' report instance containing multiple 'sub-reports'.\n\nIn order to report the progress simply add a reporter argument with type `ProgressReport` to the exposed method, e.g.\n\n```python\nfrom deprogressapi import ProgressReport\n\ndef some_exposed_method(reporter: Optional[ProgressReport] = ProgressReport(\n step_message=\"some progress message\")) -> str:\n\n # ...\n```\n\nFor a report instance new subreports can be created via the `create_subreport` method.\nEach created report is published (sent to the requesting client) automatically upon creation and on completion.\n\n```python\n# create a subreport\nsub_report = root_report.create_subreport(step_message=\"Calculating something\")\n\n# execute some logic\n# ...\n\n# mark the sub-report as compelte\nsub_report.complete()\n```\n\nAll sub-reports are again instances of `ProgressReport`, so you can create more sub-reports for each.\n\n### error handling\nIn order to report an error, you provide an error status argument to the `complete` method. The corresponding error message can be set via the reports `step_message` field.\n\n```python\nfrom deprogressapi.base import Status\n\n# ...\n# some code that raises an exception\n# ...\nexcept Exception as e:\n error = str(e)\n progress_report.step_message = \"error '{msg}': {err}\".format(msg=progress_report.step_message, err=error)\n progress_report.complete(Status.ERROR)\n```\n\n## Recommended Software Citation\n\n`Eggert, Daniel; Dransch, Doris (2021): DASF: Progress API: A progress reporting structure for the data analytics software framework. V. v0.1.4. GFZ Data Services. https://doi.org/10.5880/GFZ.1.4.2021.007`\n\n\n## Technical note\n\nThis package has been generated from the template\nhttps://codebase.helmholtz.cloud/hcdc/software-templates/python-package-template.git.\n\nSee the template repository for instructions on how to update the skeleton for\nthis package.\n\n\n## License information\n\nCopyright \u00a9 2020-2024 Helmholtz Centre Potsdam GFZ German Research Centre for Geosciences\n\n\n\nCode files in this repository are licensed under the\nApache-2.0, if not stated otherwise in the file.\n\nDocumentation files in this repository are licensed under CC-BY-4.0, if not stated otherwise in the file.\n\nSupplementary and configuration files in this repository are licensed\nunder CC0-1.0, if not stated otherwise\nin the file.\n\nPlease check the header of the individual files for more detailed\ninformation.\n\n\n\n### License management\n\nLicense management is handled with [``reuse``](https://reuse.readthedocs.io/).\nIf you have any questions on this, please have a look into the\n[contributing guide][contributing] or contact the maintainers of\n`dasf-progress-api`.\n\n[contributing]: https://digital-earth.pages.geomar.de/dasf/dasf-messaging-python/contributing.html\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "basic back-end progress api for the data analytics software framework dasf",
"version": "0.4.2",
"project_urls": {
"Documentation": "https://digital-earth.pages.geomar.de/dasf/dasf-messaging-python/",
"Homepage": "https://codebase.helmholtz.cloud/dasf/dasf-progress-api",
"Source": "https://codebase.helmholtz.cloud/dasf/dasf-progress-api",
"Tracker": "https://codebase.helmholtz.cloud/dasf/dasf-progress-api/issues/"
},
"split_keywords": [
"digital-earth",
" dasf",
" pulsar",
" gfz",
" hzg",
" hereon",
" hgf",
" helmholtz",
" remote procedure call",
" rpc",
" django",
" python",
" websocket",
" progress reporting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "85f2f189782b493acfcfebb14556a457ca48ea6cf6bb2a320f09bc86a865aaed",
"md5": "30fe84a3cd63aa076830da33829c4bbc",
"sha256": "7fa56f33950d011fe1095d71a08663f4f941154c24c8c3693c22f1c4d5b23db7"
},
"downloads": -1,
"filename": "deprogressapi-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30fe84a3cd63aa076830da33829c4bbc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23998,
"upload_time": "2024-05-06T13:18:33",
"upload_time_iso_8601": "2024-05-06T13:18:33.296790Z",
"url": "https://files.pythonhosted.org/packages/85/f2/f189782b493acfcfebb14556a457ca48ea6cf6bb2a320f09bc86a865aaed/deprogressapi-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2db2f4588963d3bdf7343feca80326dfbdc63ff22f2de8908d9b5a892a8c49a2",
"md5": "46e3f529be98ac27aa64e6cdcd944ac5",
"sha256": "63631432d1a8b15f2a27966fa7e6ae7cfa370f680eecd6126d65800b4897212d"
},
"downloads": -1,
"filename": "deprogressapi-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "46e3f529be98ac27aa64e6cdcd944ac5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 23501,
"upload_time": "2024-05-06T13:18:34",
"upload_time_iso_8601": "2024-05-06T13:18:34.902313Z",
"url": "https://files.pythonhosted.org/packages/2d/b2/f4588963d3bdf7343feca80326dfbdc63ff22f2de8908d9b5a892a8c49a2/deprogressapi-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 13:18:34",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "deprogressapi"
}
JSON