| Name | cement JSON |
| Version |
3.0.12
JSON |
| download |
| home_page | None |
| Summary | Application Framework for Python |
| upload_time | 2024-11-10 07:29:17 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Copyright (c) 2009 Data Folk Labs, LLC All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Data Folk Labs, LLC. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
python
module
cli framework
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
# Cement Framework
[](https://builtoncement.com)
[](https://pypistats.org/packages/cement)
[](https://app.travis-ci.com/github/datafolklabs/cement/)
Cement is an advanced Application Framework for Python, with a primary focus on Command Line Interfaces (CLI). Its goal is to introduce a standard, and feature-full platform for both simple and complex command line applications as well as support rapid development needs without sacrificing quality. Cement is flexible, and it's use cases span from the simplicity of a micro-framework to the complexity of a mega-framework. Whether it's a single file script, or a multi-tier application, Cement is the foundation you've been looking for.
The first commit to Git was on Dec 4, 2009. Since then, the framework has seen several iterations in design, and has continued to grow and improve since it's inception. Cement is the most stable, and complete framework for command line and backend application development.
## Installation
```
pip install cement
```
Optional CLI Extras (for development):
```
pip install cement[cli]
```
## Core Features
Cement core features include (but are not limited to):
- Core pieces of the framework are customizable via handlers/interfaces
- Handler system connects implementation classes with Interfaces
- Extension handler interface to easily extend framework functionality
- Config handler supports parsing multiple config files into one config
- Argument handler parses command line arguments and merges with config
- Log handler supports console and file logging
- Plugin handler provides an interface to easily extend your application
- Output handler interface renders return dictionaries to console
- Cache handler interface adds caching support for improved performance
- Controller handler supports sub-commands, and nested controllers
- Hook support adds a bit of magic to apps and also ties into framework
- Zero external dependencies* (not including optional extensions)
- 100% test coverage (`pytest`, `coverage`)
- 100% PEP8 compliance (`ruff`)
- Type annotation compliance (`mypy`)
- Extensive API Reference (`sphinx`)
- Tested on Python 3.8+
## Optional Extensions
Some extensions that are shipped with the mainline Cement source do require external dependencies. It is the responsibility of the application developer to include these dependencies along with their application, as Cement explicitly does not include them. Dependencies can be installed via each extensions optional package (ex: `cement[colorlog]`, `cement[redis]`, etc).
See: [https://docs.builtoncement.com/extensions](https://docs.builtoncement.com/extensions)
## More Information
- [Official Website / Developer Documentation](http://builtoncement.com/)
- [PyPi Packages](http://pypi.python.org/pypi/cement/)
- [Github Source Code / Issue Tracking](http://github.com/datafolklabs/cement/)
- [Travis CI](https://travis-ci.org/datafolklabs/cement/)
- [Slack Channel](https://join.slack.com/t/cementframework/shared_invite/enQtMzU0OTc5MDQ4NDA0LWMwMzZiOTczZjM4ZjFiZDE3MDk4MzA5ZmYxNmZjNTk4NzUwMzcyN2VlMDc5NzIxYjQ1NzlmNzgyNDFjMWJmMWY)
## License
The Cement CLI Application Framework is Open Source and is distributed under the BSD License (three clause). Please see the LICENSE file included with this software.
## Development
### Docker
This project includes a Docker Compose configuration that sets up all required services, and dependencies for development and testing. This is the recommended path for local development, and is the only fully supported option.
The following creates all required docker containers, and launches an BASH shell within the `cement` dev container for development.
```
$ make dev
|> cement <| src #
```
The above is the equivalent of running:
```
$ docker compose up -d
$ docker compose exec cement /bin/bash
```
All execution is done *inside the docker containers*.
**Testing Alternative Versions of Python**
The latest stable version of Python 3 is the default, and target version accessible as the `cement` container within Docker Compose. For testing against alternative versions of python, additional containers are created (ex: `cement-py38`, `cement-py39`, etc). You can access these containers via:
```
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------------
cement_cement-py38_1 /bin/bash Up
cement_cement-py39_1 /bin/bash Up
cement_cement-py310_1 /bin/bash Up
cement_cement-py311_1 /bin/bash Up
cement_cement-py312_1 /bin/bash Up
cement_cement_1 /bin/bash Up
cement_memcached_1 docker-entrypoint.sh memcached Up 11211/tcp
cement_redis_1 docker-entrypoint.sh redis ... Up 6379/tcp
$ docker-compose exec cement-py39 /bin/bash
|> cement-py39 <| src #
```
### Windows Targeted Development
*Windows development and support is not 100% complete. Applications Built on Cement is known to run and work on Windows well, however it is not a primary target for development and as such the setup is not as streamlined and currently has several known issues.*
If you are developing on Windows, the recommended path is still Docker. However if you are specifically targeting development *for* Windows you will want to run Python/Cement natively which will require setting up a development environment on the Windows host.
This is very rough (future doc coming), however the following will be required:
- Python 3.x (latest stable preferred)
- pip
- pipx
- pdm
- Visual C++ 14.0 or Greater Build Tools
- Including: CMake
Assuming Python/PIP are installed, the following will install PDM:
```
pip install pipx
pipx install pdm
```
C++ Build Tools are install, the following will create a development virtual env:
```
pdm venv create
pdm install --without memcached
```
You can then run the core tests:
```
pdm run pytest --cov=cement.core tests/core
```
*Note that only the core library is fully tested on Windows.*
Please explore the Makefile for helpers that may or may not work. Example, the following will run the same as the above `pdm run pytest` command:
```
make test-core
```
And, you can run Cement CLI via:
```
pdm run cement --help
```
### macOS Targeted Development
Similar to the above... if you are developing on macOS, the recommended path is still Docker. However if you are specifically targeting development *for* macOS you will want to run Python/Cement natively which will require setting up a development environment on the macOS host.
This is less nuanced than Windows, however still required some dependencies that will not be fully covered here (example: memcached). The following will get you setup to run the core library tests.
```
pip install pipx
pipx install pdm
pdm venv create
pdm install --without memcached
make test-core
```
And, you can run Cement CLI via:
```
pdm run cement --help
```
### Running Tests and Compliance
Cement has a strict policy that all code and tests meet PEP8 guidelines, therefore `ruff` is called before any unit tests run. All code submissions require 100% test coverage and PEP8 compliance:
Execute the following to run all compliance and unit tests:
```
$ make test
```
A coverage report is printed to console, as well as the HTML version created in `coverage-report`:
```
$ open coverage-report/index.html
```
See `Makefile` for all other common development actions.
Raw data
{
"_id": null,
"home_page": null,
"name": "cement",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "python, module, cli framework",
"author": null,
"author_email": "\"Data Folk Labs, LLC\" <derks@datafolklabs.com>",
"download_url": "https://files.pythonhosted.org/packages/60/a9/c8e506f325a472377c265e086c88a6f6f521d9473bb044c8fdd2fe7d1114/cement-3.0.12.tar.gz",
"platform": null,
"description": "# Cement Framework\n\n[](https://builtoncement.com)\n[](https://pypistats.org/packages/cement)\n[](https://app.travis-ci.com/github/datafolklabs/cement/)\n\n\nCement is an advanced Application Framework for Python, with a primary focus on Command Line Interfaces (CLI). Its goal is to introduce a standard, and feature-full platform for both simple and complex command line applications as well as support rapid development needs without sacrificing quality. Cement is flexible, and it's use cases span from the simplicity of a micro-framework to the complexity of a mega-framework. Whether it's a single file script, or a multi-tier application, Cement is the foundation you've been looking for.\n\nThe first commit to Git was on Dec 4, 2009. Since then, the framework has seen several iterations in design, and has continued to grow and improve since it's inception. Cement is the most stable, and complete framework for command line and backend application development.\n\n## Installation\n\n```\npip install cement\n```\n\nOptional CLI Extras (for development):\n\n```\npip install cement[cli]\n```\n\n\n## Core Features\n\nCement core features include (but are not limited to):\n\n- Core pieces of the framework are customizable via handlers/interfaces\n- Handler system connects implementation classes with Interfaces\n- Extension handler interface to easily extend framework functionality\n- Config handler supports parsing multiple config files into one config\n- Argument handler parses command line arguments and merges with config\n- Log handler supports console and file logging\n- Plugin handler provides an interface to easily extend your application\n- Output handler interface renders return dictionaries to console\n- Cache handler interface adds caching support for improved performance\n- Controller handler supports sub-commands, and nested controllers\n- Hook support adds a bit of magic to apps and also ties into framework\n- Zero external dependencies* (not including optional extensions)\n- 100% test coverage (`pytest`, `coverage`)\n- 100% PEP8 compliance (`ruff`)\n- Type annotation compliance (`mypy`)\n- Extensive API Reference (`sphinx`)\n- Tested on Python 3.8+\n\n\n## Optional Extensions\n\nSome extensions that are shipped with the mainline Cement source do require external dependencies. It is the responsibility of the application developer to include these dependencies along with their application, as Cement explicitly does not include them. Dependencies can be installed via each extensions optional package (ex: `cement[colorlog]`, `cement[redis]`, etc).\n\nSee: [https://docs.builtoncement.com/extensions](https://docs.builtoncement.com/extensions)\n\n\n## More Information\n\n- [Official Website / Developer Documentation](http://builtoncement.com/)\n- [PyPi Packages](http://pypi.python.org/pypi/cement/)\n- [Github Source Code / Issue Tracking](http://github.com/datafolklabs/cement/)\n- [Travis CI](https://travis-ci.org/datafolklabs/cement/)\n- [Slack Channel](https://join.slack.com/t/cementframework/shared_invite/enQtMzU0OTc5MDQ4NDA0LWMwMzZiOTczZjM4ZjFiZDE3MDk4MzA5ZmYxNmZjNTk4NzUwMzcyN2VlMDc5NzIxYjQ1NzlmNzgyNDFjMWJmMWY)\n\n\n## License\n\nThe Cement CLI Application Framework is Open Source and is distributed under the BSD License (three clause). Please see the LICENSE file included with this software.\n\n\n## Development\n\n### Docker\n\nThis project includes a Docker Compose configuration that sets up all required services, and dependencies for development and testing. This is the recommended path for local development, and is the only fully supported option.\n\nThe following creates all required docker containers, and launches an BASH shell within the `cement` dev container for development.\n```\n$ make dev\n\n|> cement <| src #\n```\n\nThe above is the equivalent of running:\n\n```\n$ docker compose up -d\n\n$ docker compose exec cement /bin/bash\n```\n\nAll execution is done *inside the docker containers*.\n\n\n**Testing Alternative Versions of Python**\n\nThe latest stable version of Python 3 is the default, and target version accessible as the `cement` container within Docker Compose. For testing against alternative versions of python, additional containers are created (ex: `cement-py38`, `cement-py39`, etc). You can access these containers via:\n\n```\n$ docker-compose ps\n Name Command State Ports\n-------------------------------------------------------------------------\ncement_cement-py38_1 /bin/bash Up\ncement_cement-py39_1 /bin/bash Up\ncement_cement-py310_1 /bin/bash Up\ncement_cement-py311_1 /bin/bash Up\ncement_cement-py312_1 /bin/bash Up\ncement_cement_1 /bin/bash Up\ncement_memcached_1 docker-entrypoint.sh memcached Up 11211/tcp\ncement_redis_1 docker-entrypoint.sh redis ... Up 6379/tcp\n\n\n$ docker-compose exec cement-py39 /bin/bash\n\n|> cement-py39 <| src #\n```\n\n\n### Windows Targeted Development\n\n*Windows development and support is not 100% complete. Applications Built on Cement is known to run and work on Windows well, however it is not a primary target for development and as such the setup is not as streamlined and currently has several known issues.*\n\nIf you are developing on Windows, the recommended path is still Docker. However if you are specifically targeting development *for* Windows you will want to run Python/Cement natively which will require setting up a development environment on the Windows host. \n\nThis is very rough (future doc coming), however the following will be required:\n\n- Python 3.x (latest stable preferred)\n - pip\n - pipx\n - pdm\n- Visual C++ 14.0 or Greater Build Tools\n - Including: CMake\n\nAssuming Python/PIP are installed, the following will install PDM:\n\n```\npip install pipx\n\npipx install pdm\n```\n\nC++ Build Tools are install, the following will create a development virtual env:\n\n```\npdm venv create\n\npdm install --without memcached\n```\n\nYou can then run the core tests:\n\n```\npdm run pytest --cov=cement.core tests/core\n```\n\n*Note that only the core library is fully tested on Windows.*\n\nPlease explore the Makefile for helpers that may or may not work. Example, the following will run the same as the above `pdm run pytest` command:\n\n```\nmake test-core\n```\n\nAnd, you can run Cement CLI via:\n\n```\npdm run cement --help\n```\n\n\n### macOS Targeted Development\n\nSimilar to the above... if you are developing on macOS, the recommended path is still Docker. However if you are specifically targeting development *for* macOS you will want to run Python/Cement natively which will require setting up a development environment on the macOS host. \n\nThis is less nuanced than Windows, however still required some dependencies that will not be fully covered here (example: memcached). The following will get you setup to run the core library tests.\n\n```\npip install pipx\n\npipx install pdm\n\npdm venv create\n\npdm install --without memcached\n\nmake test-core\n```\n\nAnd, you can run Cement CLI via:\n\n```\npdm run cement --help\n```\n\n### Running Tests and Compliance\n\nCement has a strict policy that all code and tests meet PEP8 guidelines, therefore `ruff` is called before any unit tests run. All code submissions require 100% test coverage and PEP8 compliance:\n\nExecute the following to run all compliance and unit tests:\n\n```\n$ make test\n```\n\nA coverage report is printed to console, as well as the HTML version created in `coverage-report`:\n\n```\n$ open coverage-report/index.html\n```\n\nSee `Makefile` for all other common development actions.\n",
"bugtrack_url": null,
"license": " Copyright (c) 2009 Data Folk Labs, LLC All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Data Folk Labs, LLC. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "Application Framework for Python",
"version": "3.0.12",
"project_urls": {
"documentation": "https://docs.builtoncement.com",
"homepage": "https://builtoncement.com",
"repository": "https://github.com/datafolklabs/cement"
},
"split_keywords": [
"python",
" module",
" cli framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f8924fe3c50fbf47db221aa95a0c3e8be99bca0b168a46fc478aac88852ca44a",
"md5": "d5671e4020107f2461fcd13c5bfb75a5",
"sha256": "5e99ac3193d9ffb093c350a892eeaf346b67525bd1e1de08e4a81475025fbf82"
},
"downloads": -1,
"filename": "cement-3.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5671e4020107f2461fcd13c5bfb75a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 136449,
"upload_time": "2024-11-10T07:29:15",
"upload_time_iso_8601": "2024-11-10T07:29:15.963220Z",
"url": "https://files.pythonhosted.org/packages/f8/92/4fe3c50fbf47db221aa95a0c3e8be99bca0b168a46fc478aac88852ca44a/cement-3.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "60a9c8e506f325a472377c265e086c88a6f6f521d9473bb044c8fdd2fe7d1114",
"md5": "e17409cbf91cba60ea9dcba07bea529e",
"sha256": "9c4a7c6c644edb06d0a9d4fe246c9be06b0ba713a283e9288a6c4676c3e0c15b"
},
"downloads": -1,
"filename": "cement-3.0.12.tar.gz",
"has_sig": false,
"md5_digest": "e17409cbf91cba60ea9dcba07bea529e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 97477,
"upload_time": "2024-11-10T07:29:17",
"upload_time_iso_8601": "2024-11-10T07:29:17.879688Z",
"url": "https://files.pythonhosted.org/packages/60/a9/c8e506f325a472377c265e086c88a6f6f521d9473bb044c8fdd2fe7d1114/cement-3.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-10 07:29:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "datafolklabs",
"github_project": "cement",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "cement"
}
