| Name | zensols.util JSON |
| Version |
1.14.3
JSON |
| download |
| home_page | https://github.com/plandes/util |
| Summary | Command line, configuration and persistence utilites generally used for any more than basic application. |
| upload_time | 2024-04-14 19:14:49 |
| maintainer | None |
| docs_url | None |
| author | Paul Landes |
| requires_python | None |
| license | None |
| keywords |
tooling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Zensols Utilities
[![PyPI][pypi-badge]][pypi-link]
[![Python 3.10][python310-badge]][python310-link]
[![Python 3.11][python311-badge]][python311-link]
[![Build Status][build-badge]][build-link]
Command line, configuration and persistence utilities generally used for any
more than basic application. This general purpose library is small, has few
dependencies, and helpful across many applications.
* See the [full documentation].
* Paper on [arXiv](http://arxiv.org/abs/2109.03383).
Some features include:
* A [Hydra] or [Java Spring] like application level support for [configuration]
than [configparser].
* Construct objects using configuration files (both INI and YAML).
* Parse primitives, dictionaries, file system objects, instances of classes.
* A [command action library] using an action mnemonic to invocation of a
handler that is integrated with a the configuration API. This supports long
and short GNU style options as provided by [optparse].
* Streamline in memory and on disk [persistence](doc/persist.md).
* Multi-processing work with a [persistence layer](doc/persist.md).
A secondary goal of the API is to make prototyping Python code quick and easy
using the REPL. Examples include reloading modules in the [configuration
factory](doc/config.md).
## Documentation
* [Full documentation](https://plandes.github.io/util/)
* [Configuration](https://plandes.github.io/util/doc/config.html): powerful but
simple configuration system much like [Hydra] or [Java Spring]
* [Command line](https://plandes.github.io/util/doc/command-line.html):
automagically creates a fully functional command with help from a Python
[dataclass](https://docs.python.org/3/library/dataclasses.html)
* [Persistence](https://plandes.github.io/util/doc/persist.html): cache
intermediate data(structures) to the file system
* [API reference](https://plandes.github.io/install/api.html)
## Obtaining
The easiest way to install the command line program is via the `pip` installer:
```bash
pip3 install zensols.util
```
## Command Line Usage
This library contains a full persistence layer and other utilities. However, a
quick and dirty example that uses the configuration and command line
functionality is given below. See the other [examples] to learn how else to
use it.
```python
from dataclasses import dataclass
from enum import Enum, auto
import os
from io import StringIO
from zensols.cli import CliHarness
CONFIG = """
# configure the command line
[cli]
apps = list: app
# define the application, whose code is given below
[app]
class_name = fsinfo.Application
"""
class Format(Enum):
short = auto()
long = auto()
@dataclass
class Application(object):
"""Toy application example that provides file system information.
"""
def ls(self, format: Format = Format.short):
"""List the contents of the directory.
:param format: the output format
"""
cmd = ['ls']
if format == Format.long:
cmd.append('-l')
os.system(' '.join(cmd))
if (__name__ == '__main__'):
harnes = CliHarness(app_config_resource=StringIO(CONFIG))
harnes.run()
```
The framework automatically links each command line action mnemonic (i.e. `ls`)
to the data class `Application` method `ls` and command line help. For
example:
```shell
$ python ./fsinfo.py -h
Usage: fsinfo.py [options]:
List the contents of the directory.
Options:
-h, --help show this help message and exit
--version show the program version and exit
-f, --format <long|short> short the output format
$ python ./fsinfo.py -f short
__pycache__ fsinfo.py
```
See the [full example] that demonstrates more complex command line handling,
documentation and explanation.
## Template
The easiest to get started is to [template] out this project is to create your
own boilerplate project with the `mkproj` utility. This requires a [Java
installation], and easy to create a Python boilerplate with the following
commands:
```bash
# clone the boilerplate repo
git clone https://github.com/plandes/template
# download the boilerplate tool
wget https://github.com/plandes/clj-mkproj/releases/download/v0.0.7/mkproj.jar
# create a python template and build it out
java -jar mkproj.jar config -s template/python
java -jar mkproj.jar
```
This creates a project customized with your organization's name, author, and
other details about the project. In addition, it also creates a sample
configuration file and command line that is ready to be invoked by either a
Python REPL or from the command line via [GNU make].
If you don't want to bother installing this program, the following sections
have generated code as examples from which you can copy/paste.
## Citation
If you use this project in your research please use the following BibTeX entry:
```bibtex
@inproceedings{landes-etal-2023-deepzensols,
title = "{D}eep{Z}ensols: A Deep Learning Natural Language Processing Framework for Experimentation and Reproducibility",
author = "Landes, Paul and
Di Eugenio, Barbara and
Caragea, Cornelia",
editor = "Tan, Liling and
Milajevs, Dmitrijs and
Chauhan, Geeticka and
Gwinnup, Jeremy and
Rippeth, Elijah",
booktitle = "Proceedings of the 3rd Workshop for Natural Language Processing Open Source Software (NLP-OSS 2023)",
month = dec,
year = "2023",
address = "Singapore, Singapore",
publisher = "Empirical Methods in Natural Language Processing",
url = "https://aclanthology.org/2023.nlposs-1.16",
pages = "141--146"
}
```
## Changelog
An extensive changelog is available [here](CHANGELOG.md).
## License
[MIT License](LICENSE.md)
Copyright (c) 2020 - 2023 Paul Landes
<!-- links -->
[pypi]: https://pypi.org/project/zensols.util/
[pypi-link]: https://pypi.python.org/pypi/zensols.util
[pypi-badge]: https://img.shields.io/pypi/v/zensols.util.svg
[python310-badge]: https://img.shields.io/badge/python-3.10-blue.svg
[python310-link]: https://www.python.org/downloads/release/python-3100
[python311-badge]: https://img.shields.io/badge/python-3.11-blue.svg
[python311-link]: https://www.python.org/downloads/release/python-3110
[build-badge]: https://github.com/plandes/util/workflows/CI/badge.svg
[build-link]: https://github.com/plandes/util/actions
[Java Spring]: https://spring.io
[Hydra]: https://github.com/facebookresearch/hydra
[Java installation]: https://java.com/en/download/
[full documentation]: https://plandes.github.io/util/
[template]: https://github.com/plandes/template
[GNU make]: https://www.gnu.org/software/make/
[configparser]: https://docs.python.org/3/library/configparser.html
[optparse]: https://docs.python.org/3/library/optparse.html
[command action library]: doc/command-line.md
[configuration]: doc/config.md
[full example]: https://github.com/plandes/util/blob/master/example/app/fsinfo.py
[examples]: https://github.com/plandes/util/blob/master/example
Raw data
{
"_id": null,
"home_page": "https://github.com/plandes/util",
"name": "zensols.util",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "tooling",
"author": "Paul Landes",
"author_email": "landes@mailc.net",
"download_url": "https://github.com/plandes/util/releases/download/v1.14.3/zensols.util-1.14.3-py3-none-any.whl",
"platform": null,
"description": "# Zensols Utilities\n\n[![PyPI][pypi-badge]][pypi-link]\n[![Python 3.10][python310-badge]][python310-link]\n[![Python 3.11][python311-badge]][python311-link]\n[![Build Status][build-badge]][build-link]\n\nCommand line, configuration and persistence utilities generally used for any\nmore than basic application. This general purpose library is small, has few\ndependencies, and helpful across many applications.\n\n* See the [full documentation].\n* Paper on [arXiv](http://arxiv.org/abs/2109.03383).\n\nSome features include:\n\n* A [Hydra] or [Java Spring] like application level support for [configuration]\n than [configparser].\n * Construct objects using configuration files (both INI and YAML).\n * Parse primitives, dictionaries, file system objects, instances of classes.\n* A [command action library] using an action mnemonic to invocation of a\n handler that is integrated with a the configuration API. This supports long\n and short GNU style options as provided by [optparse].\n* Streamline in memory and on disk [persistence](doc/persist.md).\n* Multi-processing work with a [persistence layer](doc/persist.md).\n\nA secondary goal of the API is to make prototyping Python code quick and easy\nusing the REPL. Examples include reloading modules in the [configuration\nfactory](doc/config.md).\n\n\n## Documentation\n\n* [Full documentation](https://plandes.github.io/util/)\n* [Configuration](https://plandes.github.io/util/doc/config.html): powerful but\n simple configuration system much like [Hydra] or [Java Spring]\n* [Command line](https://plandes.github.io/util/doc/command-line.html):\n automagically creates a fully functional command with help from a Python\n [dataclass](https://docs.python.org/3/library/dataclasses.html)\n* [Persistence](https://plandes.github.io/util/doc/persist.html): cache\n intermediate data(structures) to the file system\n* [API reference](https://plandes.github.io/install/api.html)\n\n\n## Obtaining\n\nThe easiest way to install the command line program is via the `pip` installer:\n```bash\npip3 install zensols.util\n```\n\n\n## Command Line Usage\n\nThis library contains a full persistence layer and other utilities. However, a\nquick and dirty example that uses the configuration and command line\nfunctionality is given below. See the other [examples] to learn how else to\nuse it.\n\n```python\nfrom dataclasses import dataclass\nfrom enum import Enum, auto\nimport os\nfrom io import StringIO\nfrom zensols.cli import CliHarness\n\nCONFIG = \"\"\"\n# configure the command line\n[cli]\napps = list: app\n\n# define the application, whose code is given below\n[app]\nclass_name = fsinfo.Application\n\"\"\"\n\nclass Format(Enum):\n short = auto()\n long = auto()\n\n@dataclass\nclass Application(object):\n \"\"\"Toy application example that provides file system information.\n\n \"\"\"\n def ls(self, format: Format = Format.short):\n \"\"\"List the contents of the directory.\n\n :param format: the output format\n\n \"\"\"\n cmd = ['ls']\n if format == Format.long:\n cmd.append('-l')\n os.system(' '.join(cmd))\n\n\nif (__name__ == '__main__'):\n harnes = CliHarness(app_config_resource=StringIO(CONFIG))\n harnes.run()\n```\n\nThe framework automatically links each command line action mnemonic (i.e. `ls`)\nto the data class `Application` method `ls` and command line help. For\nexample:\n```shell\n$ python ./fsinfo.py -h\nUsage: fsinfo.py [options]:\n\nList the contents of the directory.\n\nOptions:\n -h, --help show this help message and exit\n --version show the program version and exit\n -f, --format <long|short> short the output format\n\n$ python ./fsinfo.py -f short\n__pycache__ fsinfo.py\n```\n\nSee the [full example] that demonstrates more complex command line handling,\ndocumentation and explanation.\n\n\n## Template\n\nThe easiest to get started is to [template] out this project is to create your\nown boilerplate project with the `mkproj` utility. This requires a [Java\ninstallation], and easy to create a Python boilerplate with the following\ncommands:\n\n```bash\n# clone the boilerplate repo\ngit clone https://github.com/plandes/template\n# download the boilerplate tool\nwget https://github.com/plandes/clj-mkproj/releases/download/v0.0.7/mkproj.jar\n# create a python template and build it out\njava -jar mkproj.jar config -s template/python\njava -jar mkproj.jar\n```\n\nThis creates a project customized with your organization's name, author, and\nother details about the project. In addition, it also creates a sample\nconfiguration file and command line that is ready to be invoked by either a\nPython REPL or from the command line via [GNU make].\n\nIf you don't want to bother installing this program, the following sections\nhave generated code as examples from which you can copy/paste.\n\n\n## Citation\n\nIf you use this project in your research please use the following BibTeX entry:\n\n```bibtex\n@inproceedings{landes-etal-2023-deepzensols,\n title = \"{D}eep{Z}ensols: A Deep Learning Natural Language Processing Framework for Experimentation and Reproducibility\",\n author = \"Landes, Paul and\n Di Eugenio, Barbara and\n Caragea, Cornelia\",\n editor = \"Tan, Liling and\n Milajevs, Dmitrijs and\n Chauhan, Geeticka and\n Gwinnup, Jeremy and\n Rippeth, Elijah\",\n booktitle = \"Proceedings of the 3rd Workshop for Natural Language Processing Open Source Software (NLP-OSS 2023)\",\n month = dec,\n year = \"2023\",\n address = \"Singapore, Singapore\",\n publisher = \"Empirical Methods in Natural Language Processing\",\n url = \"https://aclanthology.org/2023.nlposs-1.16\",\n pages = \"141--146\"\n}\n```\n\n\n## Changelog\n\nAn extensive changelog is available [here](CHANGELOG.md).\n\n\n## License\n\n[MIT License](LICENSE.md)\n\nCopyright (c) 2020 - 2023 Paul Landes\n\n\n<!-- links -->\n[pypi]: https://pypi.org/project/zensols.util/\n[pypi-link]: https://pypi.python.org/pypi/zensols.util\n[pypi-badge]: https://img.shields.io/pypi/v/zensols.util.svg\n[python310-badge]: https://img.shields.io/badge/python-3.10-blue.svg\n[python310-link]: https://www.python.org/downloads/release/python-3100\n[python311-badge]: https://img.shields.io/badge/python-3.11-blue.svg\n[python311-link]: https://www.python.org/downloads/release/python-3110\n[build-badge]: https://github.com/plandes/util/workflows/CI/badge.svg\n[build-link]: https://github.com/plandes/util/actions\n\n[Java Spring]: https://spring.io\n[Hydra]: https://github.com/facebookresearch/hydra\n[Java installation]: https://java.com/en/download/\n\n[full documentation]: https://plandes.github.io/util/\n[template]: https://github.com/plandes/template\n[GNU make]: https://www.gnu.org/software/make/\n[configparser]: https://docs.python.org/3/library/configparser.html\n[optparse]: https://docs.python.org/3/library/optparse.html\n\n[command action library]: doc/command-line.md\n[configuration]: doc/config.md\n\n[full example]: https://github.com/plandes/util/blob/master/example/app/fsinfo.py\n[examples]: https://github.com/plandes/util/blob/master/example\n",
"bugtrack_url": null,
"license": null,
"summary": "Command line, configuration and persistence utilites generally used for any more than basic application.",
"version": "1.14.3",
"project_urls": {
"Download": "https://github.com/plandes/util/releases/download/v1.14.3/zensols.util-1.14.3-py3-none-any.whl",
"Homepage": "https://github.com/plandes/util"
},
"split_keywords": [
"tooling"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "402ec36a8316117bccae08ee4a874acd68c6d4c8289f7c1212f977435bab752a",
"md5": "24508382f477262a6e0ccd09b3eb7444",
"sha256": "762f44c2726b680a051bd2069589e893be2782201f4b47a12fc9601629cdc717"
},
"downloads": -1,
"filename": "zensols.util-1.14.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "24508382f477262a6e0ccd09b3eb7444",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 172760,
"upload_time": "2024-04-14T19:14:49",
"upload_time_iso_8601": "2024-04-14T19:14:49.733499Z",
"url": "https://files.pythonhosted.org/packages/40/2e/c36a8316117bccae08ee4a874acd68c6d4c8289f7c1212f977435bab752a/zensols.util-1.14.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 19:14:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plandes",
"github_project": "util",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "zensols.util"
}
