{"id":25861477,"url":"https://github.com/m-k-l-s/python-project-template","last_synced_at":"2026-05-17T19:04:37.782Z","repository":{"id":43702712,"uuid":"338453357","full_name":"m-k-l-s/python-project-template","owner":"m-k-l-s","description":"Runs on poetry and supports both conda and pip.","archived":false,"fork":false,"pushed_at":"2022-02-23T13:23:44.000Z","size":56,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T23:36:55.730Z","etag":null,"topics":["conda","cookiecutter","pip","poetry","python","template"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/m-k-l-s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-02-12T23:00:43.000Z","updated_at":"2022-06-01T19:24:59.000Z","dependencies_parsed_at":"2022-09-04T12:40:38.651Z","dependency_job_id":null,"html_url":"https://github.com/m-k-l-s/python-project-template","commit_stats":null,"previous_names":["m-k-l-s/python-project-template"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/m-k-l-s/python-project-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-k-l-s%2Fpython-project-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-k-l-s%2Fpython-project-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-k-l-s%2Fpython-project-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-k-l-s%2Fpython-project-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/m-k-l-s","download_url":"https://codeload.github.com/m-k-l-s/python-project-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/m-k-l-s%2Fpython-project-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33151625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conda","cookiecutter","pip","poetry","python","template"],"created_at":"2025-03-01T23:36:28.806Z","updated_at":"2026-05-17T19:04:37.761Z","avatar_url":"https://github.com/m-k-l-s.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python project template\n\nA minimal, slightly opinionated template for Python projects.\n\nIncludes convenient configuration (everything is in [pyproject.toml]) and automatic checks ([pre-commit config]).\n\n## Setup\n\n0. (optional) If you require packages only provided by `conda`, first install and activate the conda environment\n   (refer to the [conda directory](conda)).\n\n2. [Install](https://python-poetry.org/docs/#installation) [poetry] and `cd` to this folder.\n\n3. `poetry install`\n\n4. `poetry run pre-commit install`\n\nYou are now ready to [run your project using poetry](https://python-poetry.org/docs/basic-usage/#using-poetry-run).\n\n\n## Usage\n\n### Running your python code\n\n```shell\npoetry run python your_script.py\n```\n\nAlternatively, you can\n[activate your project env's shell](https://python-poetry.org/docs/basic-usage/#activating-the-virtual-environment)\nto run any relevant commands in your env:\n\n```shell\npoetry shell\n\u003e pip list\n\u003e python first_script.py\n\u003e python second_script.py\n```\n\n### Managing dependencies\n\nAdding a dependency is as simple as running [`add`](https://python-poetry.org/docs/cli/#add)\n```shell\npoetry add loguru\n```\n\nThe dependency will then automatically be added to your [pyproject.toml],\nalthough you can also [work with pyproject.toml directly](https://python-poetry.org/docs/basic-usage/#specifying-dependencies).\n\nThere's many more useful features (like dependency grouping), please see the\n[poetry docs](https://python-poetry.org/docs/dependency-specification/).\n\n### Git workflow\n\nWhenever you try to `git commit`, the [pre-commit config] hooks\nwill automatically run [the tools mentioned](#approach).\n\nNote that they only run on your currently `staged` files (see `git status`).\nYour unstaged files will be automatically stashed for the pre-commit run, and then unstashed back.\nThis just means that the check is run against the file state that would actually\nappear in the repository if the commit succeeded.\n\n- If there are no changes (formatting) or problems (linting, testing) during the process,\nthe commit will simply succeed.\n\n- If there are changes or linting or testing fails, the commit fails,\n  optionally updating your files in the process (`black`, `isort`)\n    - In order to then try again, first stage the changed files iff the changes look good:\n      - `git add -u` - to add only modified but unstaged files\n    - And then you can commit again, now the changes are taken into account: `git commit`\n\nIf for some reason you want to skip the pre-commit checks, you can do so with `git commit -n`\n(where `-n` is a shortcut for `--no-verify`).\nHowever, this is usually not advised.\n\nIn the future, we would like to have these automatic hook checks set up in our GitHub CI,\nso that they'd be automatically run for pull requests as well.\n\n## Approach\n\n- [poetry] as the main package manager/runner\n- [black] – code formatting ([compatible configs](https://github.com/psf/black/tree/main/docs/compatible_configs))\n- [isort] – import formatting\n- [flake8] – linting ([pflake8] is used as a wrapper that supports [pyproject.toml])\n- [pytest] – testing\n- [pre-commit] to run all above automa[tg]ically\n\n## Guidelines\n\n### Dependencies, building, publishing\n\nSee the [poetry docs](https://python-poetry.org/docs/basic-usage/).\n\n### Coding style and formatting\n\nAs dictated by [black], [isort] and [flake8].\n\nSet and configured in [pyproject.toml].\n\n### Docstrings\n\nUse the [Google docstring style](https://google.github.io/styleguide/pyguide#38-comments-and-docstrings)\n([all-in-one example](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)).\n\nMost IDEs should support it out of the box\n([PyCharm](https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000218290-Configure-google-docstring),\n[VSCode](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring)).\n\n### Logging\n\nIt is recommended to use [loguru].\n\nAdditional resources:\n\n- https://blog.guilatrova.dev/how-to-log-in-python-like-a-pro/\n\n---\n\n## TODO\n\n- [x] [mypy]\n- [ ] [tox] with [conda support](https://github.com/tox-dev/tox-conda)\n  - Testing different major Python versions  + OSs is already supported even without `tox`\n- [x] [GitHub Actions]\n  - [x] Only run when necessary and also cache:\n    - [x] conda packages\n    - [ ] pip packages\n    - [ ] conda envs\n    - [ ] poetry installation\n  - [x] Multiplatform support (`conda init` and similar on Win/MacOS)\n- [ ] [coverage]\n- [ ] [sphinx] ([Read the Docs]) for automatic documentation generation\n- [ ] Decide on `tests` structure: top-level vs scattered across the repo\n- [ ] spellchecker ([codespell](https://github.com/codespell-project/codespell)?)\n- [x] [poetry] is [already supported in PyCharm](https://www.jetbrains.com/help/pycharm/poetry.html)\n- ~~logging template~~\n    - likely not needed thanks to the [loguru] preference over the standard python `logging` module\n- [cookiecutter]\n    - consider turing this into a cookiecutter template\n      (or at least have that as a version, perhaps it's a bit clearer without the template)\n    - examples:\n        - https://github.com/johanvergeer/cookiecutter-poetry\n        - https://github.com/audreyfeldroy/cookiecutter-pypackage\n        - https://github.com/sourcery-ai/python-best-practices-cookiecutter\n\n### References\n\n- https://github.com/pronovic/apologies\n- https://github.com/rochacbruno/python-project-template\n\n\n[poetry]: https://github.com/python-poetry/poetry\n[black]: https://github.com/psf/black\n[isort]: https://github.com/PyCQA/isort\n[flake8]: https://github.com/PyCQA/flake8\n[pflake8]: https://github.com/csachs/pyproject-flake8\n[pytest]: https://docs.pytest.org\n[pre-commit]: https://pre-commit.com/\n\n[loguru]: https://github.com/Delgan/loguru\n\n[cookiecutter]: https://github.com/cookiecutter/cookiecutter\n[coverage]: https://coverage.readthedocs.io\n[mypy]: https://github.com/python/mypy\n[sphinx]: https://www.sphinx-doc.org/en/master/\n[Read the Docs]: https://readthedocs.org/\n[tox]: https://github.com/tox-dev/tox\n[GitHub Actions]: https://github.com/features/actions\n\n[pyproject.toml]: pyproject.toml\n[pre-commit config]: .pre-commit-config.yaml\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-k-l-s%2Fpython-project-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fm-k-l-s%2Fpython-project-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fm-k-l-s%2Fpython-project-template/lists"}