| Name | python-package-template-pypi JSON |
| Version |
0.2.3
JSON |
| download |
| home_page | None |
| Summary | A GitHub template with my python package configurations. |
| upload_time | 2025-01-21 00:05:25 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | MIT License Copyright (c) 2025 Daniel Mizsak Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
github
package
pypi
python
template
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
numpy
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## <div align="center"> 🐍 python-package-template</div>
<div align="center">
<a href="https://github.com/daniel-mizsak/python-package-template/actions/workflows/ci.yml" target="_blank"><img src="https://github.com/daniel-mizsak/python-package-template/actions/workflows/ci.yml/badge.svg" alt="build status"></a>
<a href="https://codecov.io/gh/daniel-mizsak/python-package-template" target="_blank"><img src="https://codecov.io/gh/daniel-mizsak/python-package-template/graph/badge.svg?token=SDXG1S8PVM"/></a>
<a href="https://results.pre-commit.ci/latest/github/daniel-mizsak/python-package-template/main" target="_blank"><img src="https://results.pre-commit.ci/badge/github/daniel-mizsak/python-package-template/main.svg" alt="pre-commit.ci status"></a>
<a href='https://python-package-template-pypi.readthedocs.io/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/python-package-template-pypi/badge/?version=latest' alt='docs status' /></a>
<a href="https://img.shields.io/github/license/daniel-mizsak/python-package-template" target="_blank"><img src="https://img.shields.io/github/license/daniel-mizsak/python-package-template" alt="license"></a>
</div>
## Overview
A GitHub template with my python package configurations.
To make sure that the all the tools are available in your [virtual environment](https://docs.python.org/3/library/venv.html) (and that you are running your code with its latest modifications), install the package in editable mode by running:
```bash
pip install --editable ".[dev]"
```
Alternatively, you can `Dev Containers: Reopen in Container` in Visual Studio Code if `Docker` is installed.
> [!WARNING]
> This template represents my personal understanding of the current best practices.\
> It is advised to do further research before implementing these configurations in your environment.
Feel free to [open a new issue](https://github.com/daniel-mizsak/python-package-template/issues/new/choose) if you have any questions or suggestions.
## Package tools
This template package relies on the synchronized cooperation of several exceptional tools.\
These tools include:
- [Codecov](https://docs.codecov.com/docs/quick-start) - Code coverage
- [Pre-Commit](https://pre-commit.com/) - Git hooks running on commits
- [MyPy](https://mypy.readthedocs.io/en/stable/) - Static type checking
- [Pytest](https://docs.pytest.org/en/latest/) - Testing and code coverage
- [Ruff](https://docs.astral.sh/ruff/) - Formatting and linting
- [Tox](https://tox.readthedocs.io/en/latest/) - Orchestration of the above tools
For documentation:
- [Sphinx](https://www.sphinx-doc.org/en/master/) - Documentation building
- [ReadTheDocs](https://readthedocs.org/) - Documentation hosting
- [GitHub Pages](https://pages.github.com/) - Documentation hosting
### Codecov
Codecov is used to check the code coverage of the tests.\
It also provides a badge that can be added to the README file.
Codecov is set up to be part of the [tox reusable workflow](https://github.com/daniel-mizsak/workflows/blob/main/.github/workflows/tox.yml), but for this action it is important to generate the coverage report. Currently it is achieved by adding `--cov-report=xml:{work_dir}/artifacts/coverage.xml` as part of the `tox.toml` configuration and uploading/downloading the results using [GitHub Artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow).
### Pre-Commit
Pre-Commit is used to run certain checks on the code before it is committed.\
These checks are defined in the `.pre-commit-config.yaml` file.\
To use pre-commit is has to be installed in the virtual environment and also added to the git hooks by running `pre-commit install`.
In this repository pre-commit is set up for a number of general issues and to run formatting and linting checks with `ruff`.
Call pre-commit by running:
```bash
pre-commit run --all-files
```
### MyPy
Python by default is a dynamically typed language, but being explicit about types can help to avoid bugs.\
MyPy makes sure that the types are correct and consistent throughout the code.
The `mypy` related settings are defined in the `pyproject.toml` file.\
In this repository MyPy is set up be `strict` and it also checks for some additional issues.
Call mypy by running:
```bash
mypy src tests
```
### Pytest
Pytest is a modern testing framework for python.\
It is way too complex to explain it here, but it runs all the tests from the `tests` directory and also checks the code coverage.
Its settings are defined in the `pyproject.toml` file.
Call pytest by running:
```bash
pytest
```
### Ruff
Ruff is a formatter and linter that is built on top of a lot of open source tools.\
It is very fast and unifies all the useful code quality solutions into a single tool.\
By default it is not too strict, but I like to make it strict by selecting all the available rules.
The exact configuration is defined in the `ruff.toml` file.
If for some reason it makes sense not to comply with a certain rule, it can be disabled for that line using `# noqa: <rule number>`.
Call ruff by running:
```bash
ruff check src tests
```
### Tox
Tox is useful for running the above tools in isolated environments.\
It makes sure that the package setup is consistent and that the tools are working as expected.\
It can be used to test different python versions and different testing scenarios.
I am also using it to automatically generate the documentation and build the package.
In this repository tox is set up to use python 3.11, 3.12 and run codecov, pytest, ruff, mypy, docs and package building.\
The settings are specified in the `tox.toml` file.
Call tox by running:
```bash
tox
```
### Documentation
The documentation is built with Sphinx and it is hosted both on ReadTheDocs and GitHub Pages.\
Both of these services are recommended, however ReadTheDocs requires a bit more setup.
## GitHub repository settings
The following settings are enabled in my repository settings:
Code/About:
- Releases
<br>
General/Features:
- Issues
- Preserve this repository
<br>
General/Pull Requests:
- Allow squash merging
- Always suggest updating pull request branches
- Automatically delete head branches
<br>
Rules/Rulesets:
`main`\
Target branches: `Default`
- Restrict deletions
- Require pull request before merging
- Dismiss stale pull request approvals when new commits are pushed
- Require review from Code Owners
- Allowed merge methods: `Squash`
- Require status checks to pass before merging
- Require branches to be up to date before merging
- `pre-commit.ci - pr`
- `tox / tox (3.11)`
- `tox / tox (3.12)`
- Block force pushes
<br>
Pages/Build and deployment:
- Source: Github Actions
The actual deployment is done by the `release` workflow.
## Setup PyPi trusted publishing
[PyPI publishing settings](https://pypi.org/manage/account/publishing/)
Add a new pending publisher:
- PyPI Project Name: `python-package-template-pypi` (has to match the project name in `pyproject.toml`)
- Owner: `daniel-mizsak`
- Repository name: `python-package-template`
- Workflow name: `release.yml`
Currently I am using a reusable GitHub workflow to test and build the package ([tox](https://github.com/daniel-mizsak/workflows/blob/main/.github/workflows/tox.yml)), and do the publishing with a separate "non-reusble" workflow, so that trusted publishing can be used.
## More examples
I am trying to use this template in all of my repositories and also contribute back here with new best practices I find.
Some of my other repositories that may be interesting to look at:
- [falcon-formation](https://github.com/daniel-mizsak/falcon-formation) - Create evenly distributed hockey teams.
- [checkmark](https://github.com/daniel-mizsak/checkmark) - Automated assessment generator and evaluator system.
- [pythonvilag-website](https://github.com/PythonVilag/pythonvilag-website) - Source code that powers the Python Világ website.
- [private-lecture-automation](https://github.com/PythonVilag/private-lecture-automation) - Automation tools for private lecture management.
I have also integrated some of the above mentioned tools into my `vscode` settings. You can find them in my [more-than-just-dotfiles](https://github.com/daniel-mizsak/mtjd/blob/main/dotfiles/vscode/settings.json) repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "python-package-template-pypi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "github, package, pypi, python, template",
"author": null,
"author_email": "Daniel Mizsak <info@pythonvilag.hu>",
"download_url": "https://files.pythonhosted.org/packages/32/74/f03bcb35e09c99adf4b1ed2e70828f26a6c419abd6a2890af41c8ee74015/python_package_template_pypi-0.2.3.tar.gz",
"platform": null,
"description": "## <div align=\"center\"> \ud83d\udc0d python-package-template</div>\n\n<div align=\"center\">\n<a href=\"https://github.com/daniel-mizsak/python-package-template/actions/workflows/ci.yml\" target=\"_blank\"><img src=\"https://github.com/daniel-mizsak/python-package-template/actions/workflows/ci.yml/badge.svg\" alt=\"build status\"></a>\n<a href=\"https://codecov.io/gh/daniel-mizsak/python-package-template\" target=\"_blank\"><img src=\"https://codecov.io/gh/daniel-mizsak/python-package-template/graph/badge.svg?token=SDXG1S8PVM\"/></a>\n<a href=\"https://results.pre-commit.ci/latest/github/daniel-mizsak/python-package-template/main\" target=\"_blank\"><img src=\"https://results.pre-commit.ci/badge/github/daniel-mizsak/python-package-template/main.svg\" alt=\"pre-commit.ci status\"></a>\n<a href='https://python-package-template-pypi.readthedocs.io/en/latest/?badge=latest'><img src='https://readthedocs.org/projects/python-package-template-pypi/badge/?version=latest' alt='docs status' /></a>\n<a href=\"https://img.shields.io/github/license/daniel-mizsak/python-package-template\" target=\"_blank\"><img src=\"https://img.shields.io/github/license/daniel-mizsak/python-package-template\" alt=\"license\"></a>\n</div>\n\n## Overview\nA GitHub template with my python package configurations.\n\n\nTo make sure that the all the tools are available in your [virtual environment](https://docs.python.org/3/library/venv.html) (and that you are running your code with its latest modifications), install the package in editable mode by running:\n\n```bash\npip install --editable \".[dev]\"\n```\n\nAlternatively, you can `Dev Containers: Reopen in Container` in Visual Studio Code if `Docker` is installed.\n\n\n> [!WARNING]\n> This template represents my personal understanding of the current best practices.\\\n> It is advised to do further research before implementing these configurations in your environment.\n\nFeel free to [open a new issue](https://github.com/daniel-mizsak/python-package-template/issues/new/choose) if you have any questions or suggestions.\n\n## Package tools\nThis template package relies on the synchronized cooperation of several exceptional tools.\\\nThese tools include:\n- [Codecov](https://docs.codecov.com/docs/quick-start) - Code coverage\n- [Pre-Commit](https://pre-commit.com/) - Git hooks running on commits\n- [MyPy](https://mypy.readthedocs.io/en/stable/) - Static type checking\n- [Pytest](https://docs.pytest.org/en/latest/) - Testing and code coverage\n- [Ruff](https://docs.astral.sh/ruff/) - Formatting and linting\n- [Tox](https://tox.readthedocs.io/en/latest/) - Orchestration of the above tools\n\nFor documentation:\n- [Sphinx](https://www.sphinx-doc.org/en/master/) - Documentation building\n- [ReadTheDocs](https://readthedocs.org/) - Documentation hosting\n- [GitHub Pages](https://pages.github.com/) - Documentation hosting\n\n### Codecov\nCodecov is used to check the code coverage of the tests.\\\nIt also provides a badge that can be added to the README file.\n\nCodecov is set up to be part of the [tox reusable workflow](https://github.com/daniel-mizsak/workflows/blob/main/.github/workflows/tox.yml), but for this action it is important to generate the coverage report. Currently it is achieved by adding `--cov-report=xml:{work_dir}/artifacts/coverage.xml` as part of the `tox.toml` configuration and uploading/downloading the results using [GitHub Artifacts](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow).\n\n### Pre-Commit\nPre-Commit is used to run certain checks on the code before it is committed.\\\nThese checks are defined in the `.pre-commit-config.yaml` file.\\\nTo use pre-commit is has to be installed in the virtual environment and also added to the git hooks by running `pre-commit install`.\n\nIn this repository pre-commit is set up for a number of general issues and to run formatting and linting checks with `ruff`.\n\nCall pre-commit by running:\n\n```bash\npre-commit run --all-files\n```\n\n### MyPy\nPython by default is a dynamically typed language, but being explicit about types can help to avoid bugs.\\\nMyPy makes sure that the types are correct and consistent throughout the code.\n\nThe `mypy` related settings are defined in the `pyproject.toml` file.\\\nIn this repository MyPy is set up be `strict` and it also checks for some additional issues.\n\nCall mypy by running:\n\n```bash\nmypy src tests\n```\n\n### Pytest\nPytest is a modern testing framework for python.\\\nIt is way too complex to explain it here, but it runs all the tests from the `tests` directory and also checks the code coverage.\n\nIts settings are defined in the `pyproject.toml` file.\n\nCall pytest by running:\n\n```bash\npytest\n```\n\n### Ruff\nRuff is a formatter and linter that is built on top of a lot of open source tools.\\\nIt is very fast and unifies all the useful code quality solutions into a single tool.\\\nBy default it is not too strict, but I like to make it strict by selecting all the available rules.\nThe exact configuration is defined in the `ruff.toml` file.\n\nIf for some reason it makes sense not to comply with a certain rule, it can be disabled for that line using `# noqa: <rule number>`.\n\nCall ruff by running:\n\n```bash\nruff check src tests\n```\n\n### Tox\nTox is useful for running the above tools in isolated environments.\\\nIt makes sure that the package setup is consistent and that the tools are working as expected.\\\nIt can be used to test different python versions and different testing scenarios.\nI am also using it to automatically generate the documentation and build the package.\n\nIn this repository tox is set up to use python 3.11, 3.12 and run codecov, pytest, ruff, mypy, docs and package building.\\\nThe settings are specified in the `tox.toml` file.\n\nCall tox by running:\n\n```bash\ntox\n```\n\n### Documentation\nThe documentation is built with Sphinx and it is hosted both on ReadTheDocs and GitHub Pages.\\\nBoth of these services are recommended, however ReadTheDocs requires a bit more setup.\n\n## GitHub repository settings\nThe following settings are enabled in my repository settings:\n\nCode/About:\n\n- Releases\n\n<br>\n\nGeneral/Features:\n\n- Issues\n- Preserve this repository\n\n<br>\n\nGeneral/Pull Requests:\n\n- Allow squash merging\n- Always suggest updating pull request branches\n- Automatically delete head branches\n\n<br>\n\nRules/Rulesets:\n`main`\\\nTarget branches: `Default`\n\n- Restrict deletions\n- Require pull request before merging\n - Dismiss stale pull request approvals when new commits are pushed\n - Require review from Code Owners\n - Allowed merge methods: `Squash`\n- Require status checks to pass before merging\n - Require branches to be up to date before merging\n - `pre-commit.ci - pr`\n - `tox / tox (3.11)`\n - `tox / tox (3.12)`\n- Block force pushes\n\n<br>\n\nPages/Build and deployment:\n\n- Source: Github Actions\nThe actual deployment is done by the `release` workflow.\n\n## Setup PyPi trusted publishing\n[PyPI publishing settings](https://pypi.org/manage/account/publishing/)\n\nAdd a new pending publisher:\n\n- PyPI Project Name: `python-package-template-pypi` (has to match the project name in `pyproject.toml`)\n- Owner: `daniel-mizsak`\n- Repository name: `python-package-template`\n- Workflow name: `release.yml`\n\nCurrently I am using a reusable GitHub workflow to test and build the package ([tox](https://github.com/daniel-mizsak/workflows/blob/main/.github/workflows/tox.yml)), and do the publishing with a separate \"non-reusble\" workflow, so that trusted publishing can be used.\n\n## More examples\nI am trying to use this template in all of my repositories and also contribute back here with new best practices I find.\nSome of my other repositories that may be interesting to look at:\n- [falcon-formation](https://github.com/daniel-mizsak/falcon-formation) - Create evenly distributed hockey teams.\n- [checkmark](https://github.com/daniel-mizsak/checkmark) - Automated assessment generator and evaluator system.\n- [pythonvilag-website](https://github.com/PythonVilag/pythonvilag-website) - Source code that powers the Python Vil\u00e1g website.\n- [private-lecture-automation](https://github.com/PythonVilag/private-lecture-automation) - Automation tools for private lecture management.\n\nI have also integrated some of the above mentioned tools into my `vscode` settings. You can find them in my [more-than-just-dotfiles](https://github.com/daniel-mizsak/mtjd/blob/main/dotfiles/vscode/settings.json) repository.\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Daniel Mizsak Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A GitHub template with my python package configurations.",
"version": "0.2.3",
"project_urls": {
"Documentation": "https://python-package-template-pypi.readthedocs.io/en/latest/",
"Homepage": "https://pythonvilag.hu/",
"Issues": "https://github.com/daniel-mizsak/python-package-template/issues",
"Repository": "https://github.com/daniel-mizsak/python-package-template"
},
"split_keywords": [
"github",
" package",
" pypi",
" python",
" template"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "dd0d42e0dffe8ab56871e0ba7efa6cc48390f6c062173f4aadc24a666cdc1d7c",
"md5": "689d8a9b3bb399cf16e57e8860c78363",
"sha256": "73e800f878639eb683c38cf3825c4418365408e097079c583f113ecf365060ae"
},
"downloads": -1,
"filename": "python_package_template_pypi-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "689d8a9b3bb399cf16e57e8860c78363",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8056,
"upload_time": "2025-01-21T00:05:23",
"upload_time_iso_8601": "2025-01-21T00:05:23.545681Z",
"url": "https://files.pythonhosted.org/packages/dd/0d/42e0dffe8ab56871e0ba7efa6cc48390f6c062173f4aadc24a666cdc1d7c/python_package_template_pypi-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3274f03bcb35e09c99adf4b1ed2e70828f26a6c419abd6a2890af41c8ee74015",
"md5": "3ac8057e3677514be082ef1df34ae633",
"sha256": "8ad7d44bcbd659a3b4e5fa3facbbd2043a0399edb0512b354824244a5b91c025"
},
"downloads": -1,
"filename": "python_package_template_pypi-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "3ac8057e3677514be082ef1df34ae633",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11056,
"upload_time": "2025-01-21T00:05:25",
"upload_time_iso_8601": "2025-01-21T00:05:25.146231Z",
"url": "https://files.pythonhosted.org/packages/32/74/f03bcb35e09c99adf4b1ed2e70828f26a6c419abd6a2890af41c8ee74015/python_package_template_pypi-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-21 00:05:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "daniel-mizsak",
"github_project": "python-package-template",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"2.2.2"
]
]
}
],
"lcname": "python-package-template-pypi"
}
