# calcipy
`calcipy` is a Python package that implements best practices such as code style (linting, auto-fixes), documentation, CI/CD, and logging. Like the calcium carbonate in hard coral, packages can be built on the `calcipy` foundation.
`calcipy` has some configurability, but is tailored for my particular use cases. If you want the same sort of functionality, there are a number of alternatives to consider:
- [pyscaffold](https://github.com/pyscaffold/pyscaffold) is a much more mature project that aims for the same goals, but with a slightly different approach and tech stack (tox vs. nox, cookiecutter vs. copier, etc.)
- [tidypy](https://github.com/jayclassless/tidypy#features), [pylama](https://github.com/klen/pylama), and [codecheck](https://pypi.org/project/codecheck/) offer similar functionality of bundling and running static checkers, but makes far fewer assumptions
- [pytoil](https://github.com/FollowTheProcess/pytoil) is a general CLI tool for developer automation
- And many more such as [pyta](https://github.com/pyta-uoft/pyta), [prospector](https://github.com/PyCQA/prospector), [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide) / [cjolowicz/cookiecutter-hypermodern-python](https://github.com/cjolowicz/cookiecutter-hypermodern-python), [formate](https://github.com/python-formate/formate), [johnthagen/python-blueprint](https://github.com/johnthagen/python-blueprint), [oxsecurity/megalinter](https://github.com/oxsecurity/megalinter), [trialandsuccess/su6](https://github.com/trialandsuccess/su6), etc.
## Installation
Calcipy needs a few static files managed using copier and a template project: [kyleking/calcipy_template](https://github.com/KyleKing/calcipy_template/)
You can quickly use the template to create a new project or add calcipy to an existing one:
```sh
# Below examples assume you have Astral uv installed (which provides uvx)
# If you have your shell configured, `uv tool install copier` allows usage of `copier ...` instead of `uvx copier ...`
# To create a new project
uvx copier copy gh:KyleKing/calcipy_template new_project
cd new_project
# Or convert/update an existing one
cd my_project
uvx copier copy gh:KyleKing/calcipy_template .
uvx copier update
```
### Calcipy CLI
Additionally, `calcipy` can be run as a CLI application without adding the package as a dependency.
Quick Start:
```sh
# For the CLI, only install a few of the extras which can be used from a few different CLI commands
uv tool install 'calcipy[lint,tags]'
# Use 'tags' to create a CODE_TAG_SUMMARY of the specified directory
calcipy-tags tags --help
calcipy-tags tags --base-dir=~/path/to/my_project
```
Note: the CLI output below is compressed for readability, but you can try running each of these commands locally to see the most up-to-date documentation and the full set of options. The "Usage", "Core options", and "Global Task Options" are the same for each subsequent command, so they are excluded for brevity.
```txt
> calcipy-lint
Usage: calcipy-lint [--core-opts] <subcommand> [--subcommand-opts] ...
Core options:
--complete Print tab-completion candidates for given parse remainder.
--hide=STRING Set default value of run()'s 'hide' kwarg.
--print-completion-script=STRING Print the tab-completion script for your preferred shell (bash|zsh|fish).
--prompt-for-sudo-password Prompt user at start of session for the sudo.password config value.
--write-pyc Enable creation of .pyc files.
-d, --debug Enable debug output.
-D INT, --list-depth=INT When listing tasks, only show the first INT levels.
-e, --echo Echo executed commands before running.
-f STRING, --config=STRING Runtime configuration file to use.
-F STRING, --list-format=STRING Change the display format used when listing tasks. Should be one of: flat (default), nested, json.
-h [STRING], --help[=STRING] Show core or per-task help and exit.
-l [STRING], --list[=STRING] List available tasks, optionally limited to a namespace.
-p, --pty Use a pty when executing shell commands.
-R, --dry Echo commands instead of running.
-T INT, --command-timeout=INT Specify a global command execution timeout, in seconds.
-V, --version Show version and exit.
-w, --warn-only Warn, instead of failing, when shell commands fail.
Subcommands:
lint.check (lint) Run ruff as check-only.
lint.fix Run ruff and apply fixes.
lint.pre-commit Run pre-commit.
lint.watch Run ruff as check-only.
Global Task Options:
*file_args List of Paths available globally to all tasks. Will resolve paths with working_dir
--keep-going Continue running tasks even on failure
--working_dir=STRING Set the cwd for the program. Example: "../run --working-dir .. lint test"
-v,-vv,-vvv Globally configure logger verbosity (-vvv for most verbose)
> calcipy-pack
Subcommands:
pack.bump-tag Experiment with bumping the git tag using `griffe` (experimental).
pack.check-licenses Check licenses for compatibility with `licensecheck`.
pack.install-extras Run poetry install with all extras.
pack.lock Ensure poetry.lock is up-to-date.
pack.publish Build the distributed format(s) and publish.
pack.sync-pyproject-versions Experiment with setting the pyproject.toml dependencies to the version from poetry.lock (experimental).
> calcipy-tags
Subcommands:
tags.collect-code-tags (tags) Create a `CODE_TAG_SUMMARY.md` with a table for TODO- and FIXME-style code comments.
> calcipy-types
Subcommands:
types.mypy Run mypy.
types.pyright Run pyright using the config in `pyproject.toml`.
```
### Calcipy Pre-Commit
`calcipy` can also be used as a `pre-commit` task by adding the below snippet to your `pre-commit` file:
```yaml
repos:
- repo: https://github.com/KyleKing/calcipy
rev: main
hooks:
- id: tags
- id: lint-fix
- id: types
```
## Project Status
See the `Open Issues` and/or the [CODE_TAG_SUMMARY]. For release history, see the [CHANGELOG].
## Contributing
We welcome pull requests! For your pull request to be accepted smoothly, we suggest that you first open a GitHub issue to discuss your idea. For resources on getting started with the code base, see the below documentation:
- [DEVELOPER_GUIDE]
- [STYLE_GUIDE]
## Code of Conduct
We follow the [Contributor Covenant Code of Conduct][contributor-covenant].
### Open Source Status
We try to reasonably meet most aspects of the "OpenSSF scorecard" from [Open Source Insights](https://deps.dev/pypi/calcipy)
## Responsible Disclosure
If you have any security issue to report, please contact the project maintainers privately. You can reach us at [dev.act.kyle@gmail.com](mailto:dev.act.kyle@gmail.com).
## License
[LICENSE]
[changelog]: https://calcipy.kyleking.me/docs/CHANGELOG
[code_tag_summary]: https://calcipy.kyleking.me/docs/CODE_TAG_SUMMARY
[contributor-covenant]: https://www.contributor-covenant.org
[developer_guide]: https://calcipy.kyleking.me/docs/DEVELOPER_GUIDE
[license]: https://github.com/kyleking/calcipy/blob/main/LICENSE
[style_guide]: https://calcipy.kyleking.me/docs/STYLE_GUIDE
Raw data
{
"_id": null,
"home_page": "https://github.com/kyleking/calcipy",
"name": "calcipy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.9.13",
"maintainer_email": null,
"keywords": "calcipy_template",
"author": "Kyle King",
"author_email": "dev.act.kyle@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/62/8f/946c889a98f72d23d0438572b8c5915471393c957eca634ce550e25c99cd/calcipy-4.3.0.tar.gz",
"platform": null,
"description": "# calcipy\n\n\n\n`calcipy` is a Python package that implements best practices such as code style (linting, auto-fixes), documentation, CI/CD, and logging. Like the calcium carbonate in hard coral, packages can be built on the `calcipy` foundation.\n\n`calcipy` has some configurability, but is tailored for my particular use cases. If you want the same sort of functionality, there are a number of alternatives to consider:\n\n- [pyscaffold](https://github.com/pyscaffold/pyscaffold) is a much more mature project that aims for the same goals, but with a slightly different approach and tech stack (tox vs. nox, cookiecutter vs. copier, etc.)\n- [tidypy](https://github.com/jayclassless/tidypy#features), [pylama](https://github.com/klen/pylama), and [codecheck](https://pypi.org/project/codecheck/) offer similar functionality of bundling and running static checkers, but makes far fewer assumptions\n- [pytoil](https://github.com/FollowTheProcess/pytoil) is a general CLI tool for developer automation\n- And many more such as [pyta](https://github.com/pyta-uoft/pyta), [prospector](https://github.com/PyCQA/prospector), [wemake-python-styleguide](https://github.com/wemake-services/wemake-python-styleguide) / [cjolowicz/cookiecutter-hypermodern-python](https://github.com/cjolowicz/cookiecutter-hypermodern-python), [formate](https://github.com/python-formate/formate), [johnthagen/python-blueprint](https://github.com/johnthagen/python-blueprint), [oxsecurity/megalinter](https://github.com/oxsecurity/megalinter), [trialandsuccess/su6](https://github.com/trialandsuccess/su6), etc.\n\n## Installation\n\nCalcipy needs a few static files managed using copier and a template project: [kyleking/calcipy_template](https://github.com/KyleKing/calcipy_template/)\n\nYou can quickly use the template to create a new project or add calcipy to an existing one:\n\n```sh\n# Below examples assume you have Astral uv installed (which provides uvx)\n# If you have your shell configured, `uv tool install copier` allows usage of `copier ...` instead of `uvx copier ...`\n\n# To create a new project\nuvx copier copy gh:KyleKing/calcipy_template new_project\ncd new_project\n\n# Or convert/update an existing one\ncd my_project\nuvx copier copy gh:KyleKing/calcipy_template .\nuvx copier update\n```\n\n### Calcipy CLI\n\nAdditionally, `calcipy` can be run as a CLI application without adding the package as a dependency.\n\nQuick Start:\n\n```sh\n# For the CLI, only install a few of the extras which can be used from a few different CLI commands\nuv tool install 'calcipy[lint,tags]'\n\n# Use 'tags' to create a CODE_TAG_SUMMARY of the specified directory\ncalcipy-tags tags --help\ncalcipy-tags tags --base-dir=~/path/to/my_project\n```\n\nNote: the CLI output below is compressed for readability, but you can try running each of these commands locally to see the most up-to-date documentation and the full set of options. The \"Usage\", \"Core options\", and \"Global Task Options\" are the same for each subsequent command, so they are excluded for brevity.\n\n```txt\n> calcipy-lint\nUsage: calcipy-lint [--core-opts] <subcommand> [--subcommand-opts] ...\n\nCore options:\n\n --complete Print tab-completion candidates for given parse remainder.\n --hide=STRING Set default value of run()'s 'hide' kwarg.\n --print-completion-script=STRING Print the tab-completion script for your preferred shell (bash|zsh|fish).\n --prompt-for-sudo-password Prompt user at start of session for the sudo.password config value.\n --write-pyc Enable creation of .pyc files.\n -d, --debug Enable debug output.\n -D INT, --list-depth=INT When listing tasks, only show the first INT levels.\n -e, --echo Echo executed commands before running.\n -f STRING, --config=STRING Runtime configuration file to use.\n -F STRING, --list-format=STRING Change the display format used when listing tasks. Should be one of: flat (default), nested, json.\n -h [STRING], --help[=STRING] Show core or per-task help and exit.\n -l [STRING], --list[=STRING] List available tasks, optionally limited to a namespace.\n -p, --pty Use a pty when executing shell commands.\n -R, --dry Echo commands instead of running.\n -T INT, --command-timeout=INT Specify a global command execution timeout, in seconds.\n -V, --version Show version and exit.\n -w, --warn-only Warn, instead of failing, when shell commands fail.\n\nSubcommands:\n\n lint.check (lint) Run ruff as check-only.\n lint.fix Run ruff and apply fixes.\n lint.pre-commit Run pre-commit.\n lint.watch Run ruff as check-only.\n\nGlobal Task Options:\n\n *file_args List of Paths available globally to all tasks. Will resolve paths with working_dir\n --keep-going Continue running tasks even on failure\n --working_dir=STRING Set the cwd for the program. Example: \"../run --working-dir .. lint test\"\n -v,-vv,-vvv Globally configure logger verbosity (-vvv for most verbose)\n\n> calcipy-pack\n\nSubcommands:\n\n pack.bump-tag Experiment with bumping the git tag using `griffe` (experimental).\n pack.check-licenses Check licenses for compatibility with `licensecheck`.\n pack.install-extras Run poetry install with all extras.\n pack.lock Ensure poetry.lock is up-to-date.\n pack.publish Build the distributed format(s) and publish.\n pack.sync-pyproject-versions Experiment with setting the pyproject.toml dependencies to the version from poetry.lock (experimental).\n\n> calcipy-tags\n\nSubcommands:\n\n tags.collect-code-tags (tags) Create a `CODE_TAG_SUMMARY.md` with a table for TODO- and FIXME-style code comments.\n\n> calcipy-types\n\nSubcommands:\n\n types.mypy Run mypy.\n types.pyright Run pyright using the config in `pyproject.toml`.\n```\n\n### Calcipy Pre-Commit\n\n`calcipy` can also be used as a `pre-commit` task by adding the below snippet to your `pre-commit` file:\n\n```yaml\nrepos:\n - repo: https://github.com/KyleKing/calcipy\n rev: main\n hooks:\n - id: tags\n - id: lint-fix\n - id: types\n```\n\n## Project Status\n\nSee the `Open Issues` and/or the [CODE_TAG_SUMMARY]. For release history, see the [CHANGELOG].\n\n## Contributing\n\nWe welcome pull requests! For your pull request to be accepted smoothly, we suggest that you first open a GitHub issue to discuss your idea. For resources on getting started with the code base, see the below documentation:\n\n- [DEVELOPER_GUIDE]\n- [STYLE_GUIDE]\n\n## Code of Conduct\n\nWe follow the [Contributor Covenant Code of Conduct][contributor-covenant].\n\n### Open Source Status\n\nWe try to reasonably meet most aspects of the \"OpenSSF scorecard\" from [Open Source Insights](https://deps.dev/pypi/calcipy)\n\n## Responsible Disclosure\n\nIf you have any security issue to report, please contact the project maintainers privately. You can reach us at [dev.act.kyle@gmail.com](mailto:dev.act.kyle@gmail.com).\n\n## License\n\n[LICENSE]\n\n[changelog]: https://calcipy.kyleking.me/docs/CHANGELOG\n[code_tag_summary]: https://calcipy.kyleking.me/docs/CODE_TAG_SUMMARY\n[contributor-covenant]: https://www.contributor-covenant.org\n[developer_guide]: https://calcipy.kyleking.me/docs/DEVELOPER_GUIDE\n[license]: https://github.com/kyleking/calcipy/blob/main/LICENSE\n[style_guide]: https://calcipy.kyleking.me/docs/STYLE_GUIDE\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python package to simplify development",
"version": "4.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/kyleking/calcipy/issues",
"Changelog": "https://github.com/kyleking/calcipy/blob/main/docs/docs/CHANGELOG.md",
"Documentation": "https://calcipy.kyleking.me",
"Homepage": "https://github.com/kyleking/calcipy",
"Repository": "https://github.com/kyleking/calcipy"
},
"split_keywords": [
"calcipy_template"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eb1368cb74bc0d3fa751cbfa253edb5b8b955411c043f21d6c57f590b07f3efe",
"md5": "34ad708699df56272a046c3b51f38289",
"sha256": "573c165e29455dfb1c072bc5fc6680fff8a297243db87527976be5d93cfb5eef"
},
"downloads": -1,
"filename": "calcipy-4.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34ad708699df56272a046c3b51f38289",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.9.13",
"size": 47620,
"upload_time": "2024-10-31T14:34:14",
"upload_time_iso_8601": "2024-10-31T14:34:14.941405Z",
"url": "https://files.pythonhosted.org/packages/eb/13/68cb74bc0d3fa751cbfa253edb5b8b955411c043f21d6c57f590b07f3efe/calcipy-4.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "628f946c889a98f72d23d0438572b8c5915471393c957eca634ce550e25c99cd",
"md5": "d3adf0ebc426734d3722bb9ef50b4c2a",
"sha256": "94d22700fffee4c209b91cc932decf09bb45df56fe8193c21c423ce566c7a76e"
},
"downloads": -1,
"filename": "calcipy-4.3.0.tar.gz",
"has_sig": false,
"md5_digest": "d3adf0ebc426734d3722bb9ef50b4c2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.9.13",
"size": 37210,
"upload_time": "2024-10-31T14:34:16",
"upload_time_iso_8601": "2024-10-31T14:34:16.472901Z",
"url": "https://files.pythonhosted.org/packages/62/8f/946c889a98f72d23d0438572b8c5915471393c957eca634ce550e25c99cd/calcipy-4.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 14:34:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kyleking",
"github_project": "calcipy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "calcipy"
}
JSON
