{"id":22643182,"url":"https://github.com/hochfrequenz/python_template_repository","last_synced_at":"2026-03-08T08:34:37.568Z","repository":{"id":39920882,"uuid":"345632887","full_name":"Hochfrequenz/python_template_repository","owner":"Hochfrequenz","description":"A template repository that comes up with a pre-defined tox setup and CI actions. ","archived":false,"fork":false,"pushed_at":"2024-04-12T04:56:25.000Z","size":171,"stargazers_count":7,"open_issues_count":3,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-12T12:20:52.320Z","etag":null,"topics":["black","githubactions-ci","mypy","pylint","pytest","python3","tox"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Hochfrequenz.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,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-03-08T11:29:15.000Z","updated_at":"2024-04-15T15:26:12.175Z","dependencies_parsed_at":"2023-02-17T16:00:44.352Z","dependency_job_id":"b289e6dd-2d00-4595-8ac9-f339ce1b4b4a","html_url":"https://github.com/Hochfrequenz/python_template_repository","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hochfrequenz%2Fpython_template_repository","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hochfrequenz%2Fpython_template_repository/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hochfrequenz%2Fpython_template_repository/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hochfrequenz%2Fpython_template_repository/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hochfrequenz","download_url":"https://codeload.github.com/Hochfrequenz/python_template_repository/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248493454,"owners_count":21113262,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["black","githubactions-ci","mypy","pylint","pytest","python3","tox"],"created_at":"2024-12-09T05:09:36.382Z","updated_at":"2026-03-08T08:34:37.522Z","avatar_url":"https://github.com/Hochfrequenz.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python Template Repository including a `tox.ini`, Unittests\u0026Coverage, Pylint \u0026 MyPy Linting Actions and a PyPI Publishing Workflow\n\n\u003c!--- you need to replace the `organization/repo_name` in the status badge URLs ---\u003e\n\n![Unittests status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Unittests/badge.svg)\n![Coverage status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Coverage/badge.svg)\n![Linting status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Linting/badge.svg)\n![Black status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Formatting/badge.svg)\n\nThis is a template repository.\nIt doesn't contain any useful code but only a minimal working setup for a Python project including:\n\n- a basic **project structure** with\n  - tox.ini\n  - `pyproject.toml` where the project metadata and dependencies are defined\n  - and a requirements.txt derived from it\n  - an example class\n  - an example unit test (using pytest)\n- ready to use **Github Actions** for\n  - [pytest](https://pytest.org)\n  - [code coverage measurement](https://coverage.readthedocs.io) (fails below 80% by default)\n  - [pylint](https://pylint.org/) (only accepts 10/10 code rating by default)\n  - [mypy](https://github.com/python/mypy) (static type checks where possible)\n  - [black](https://github.com/psf/black) code formatter check\n  - [isort](https://pycqa.github.io/isort/) import order check\n  - [codespell](https://github.com/codespell-project/codespell) spell check (including an ignore list)\n  - autoresolve dev-dependencies with `tox -e compile_requirements`\n  - ready-to-use publishing workflow for pypi (see readme section below)\n\nBy default, it uses Python version 3.13.\n\nThis repository uses a [`src`-based layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).\nThis approach has many advantages and basically means for developers, that all business logic lives in the `src` directory.\n\n## How to use this Repository on Your Machine\n\n### Installation of Tox / Creating the tox base venv\nIf you ever set up your toxbase virtual environment already, skip this first step and continue with the project-specific setup.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n Creating the toxbase from scratch (windows)\n\u003c/summary\u003e\n\nYou can either follow the [installation instructions](https://tox.readthedocs.io/en/latest/installation.html)) and that a `.toxbase` environment has been created.\nHere we repeat the most important steps.\n\n#### Enure you are allowed to execute scripts in powershell (Windows only)\nOn new Windows machines it is possible that the execution policy is set to restricted and you are not allowed execute scripts. You can find detailed information [here](https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.3).\n\nThe quickest way to solve this problem: Open an Administrator Powershell (e.g. Windows PowerShell App, right click: 'Run as Adminstrator')\n```ps\nSet-ExecutionPolicy -ExecutionPolicy AllSigned\n```\nThen close the admin powershell and continue in the regular shell.\n\n#### Create the `.toxbase` environment\n`.toxbase` is a project independent virtual environment-template for all the tox environments on your machine. If anything is weird during the tox installation or after the installation, try turning your computer off and on again before getting too frustrated.\nAsk your Hochfrequenz colleagues for help.\n\n```ps\n# Change to your user directory, create tools directory if it does not exist\n$ cd C:\\Users\\YourUserName\n# Create a virtual environment called .toxbase\n$ python -m venv .toxbase\n```\n\nthen\n```ps\n# Windows Powershell\n$ .\\.toxbase\\Scripts\\Activate.ps1\n# XOR Windows default (e.g. cmder)\nλ .toxbase\\Scripts\\activate.bat\n# the virtual environment is active\n# if you see the environment name at the beginning of the line\n(.toxbase) $ python -m pip install --upgrade pip\n(.toxbase) $ pip install tox\n(.toxbase) $ tox --version\n```\n\n#### Add the toxbase interpreter to the Path environment variable\nFinally, we need to make the tox command available in all future terminal sessions.\nThere are ways to achieve this goal using only the powershell commands, but we just use the \"regular\" way:\n\n* Type systemvariable in the search field of your windows taskbar.\n* Click on Edit system variables, then on environment variables.\n* In the next window select Path in the upper part (User variables for YourUserName) and click on edit.\n* Add a new path with `C:\\Users\\YourUserName\\.toxbase\\Scripts\\`\n  * ⚠️ You have to replace YourUserName with your actual username in the path!\n     the path up to .toxbase has already been printed to the CLI in the tox --version command above\n\n* Save the settings.\n* Now you have to sign out and in again to make the changes work.\n\nYou should now be able to type the following and get a reasonable answer\n```\ntox --version\n```\nin every shell, no matter if you activated the toxbase again.\n\n#### Umlaute in Paths\nTox has an issue if you have an umlaut in your username. [This issue](https://github.com/tox-dev/tox/issues/1550#issuecomment-727824763) is well known.\n\nTo solve it you have to add another environment variable `PYTHONIOENCODING` with the value `utf-8` ([source](https://github.com/tox-dev/tox/issues/1550#issuecomment-1011952057)).\n\nStart a new PowerShell session and try to run tox -e dev in your repository again.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n Creating the toxbase from scratch (unix)\n\u003c/summary\u003e\nOpen a terminal and execute the following commands\n\n```sh\n# Change to your user directory\n$ cd ~\n# Create a virtual environment called .toxbase\n$ python -m venv .toxbase\n```\nNow we activate the virtual environment, update pip and install tox:\n\n```\n$ source .toxbase/bin/activate\n# the virtual environment is active\n# if you see the environment name at the beginning of the line\n(.toxbase) $ python -m pip install --upgrade pip\n(.toxbase) $ pip install tox\n(.toxbase) $ tox --version\n```\nCreate a new folder bin in the home directory and add a symbolic link inside\n```\ncd\n# create a `bin` directory\nmkdir bin\n# set link to ~/bin/tox\nln -s ~/.toxbase/bin/tox ~/bin/tox\n```\nSet the PATH variable\n\n```\ncd\n# open the config file .bashrc\nnano .bashrc\n# Go to the bottom of the file and insert\n# make tox accessible in each session from everywhere\nPATH = \"${HOME}/bin:${PATH}\"\nexport PATH\n# save and close the file with CTRL+O and CTRL+X\n```\n#### fish\n```\ncd\n# open the config.fish file\nnano ~/.config/fish/config.fish\n# Go to the bottom of the file and insert\n# make tox accessible in each session from everywhere\nset PATH {$HOME}/bin $PATH\n# save and close the file with CTRL+O and CTRL+X\n```\nCheck if everything works by opening a new terminal window and run\n```bash\ntox --version\n```\n\n\u003c/details\u003e\n\n### Creating the project-specific dev environment.\nIf tox is set up, you're ready to start:\n   1. clone the repository, you want to work in\n   2. create the `dev` environment on your machine. To do this:\n       a) Open a Powershell\n       b) change directory to your repository\nand finally type\n\n```bash\ntox -e dev\n```\n\nYou have now created the development environment (dev environment). It is the environment which contains both the usual requirements as well as the testing and linting tools.\n\n### How to use with PyCharm\n\n1. You have cloned the repository, you want to work in, and have created the virtual environment, in which the repository should be executed (`your_repo/.tox/dev`). Now, to actually work inside the newly created environment, you need to tell PyCharm (your IDE) that it should use the virtual environment - to be more precise: the interpreter of this dev environment. How to do this:\na) navigate to: File ➡ Settings (Strg + Alt + S) ➡ Project: your_project ➡ Python Interpreter ➡ Add interpreter ➡ Existing\nb) Choose as interpreter: `your_repo\\.tox\\dev\\Scripts\\python.exe` (under windows)\n2. Set the default test runner of your project to pytest. How to do it:\na) navigate to Files ➡ Settings ➡ Tools ➡ Python integrated tools ➡ Testing: Default test runner\nb) Change to \"pytest\"\nIf this doesn't work anymore, see [the PyCharm docs](https://www.jetbrains.com/help/pycharm/choosing-your-testing-framework.html)\n3. Set the `src` directory as sources root. How to do this:\nright click on 'src' ➡ \"Mark directory as…\" ➡ sources root\nIf this doesn't work anymore, see: [PyCharm docs](https://www.jetbrains.com/help/pycharm/content-root.html).\nSetting the `src` directory right, allows PyCharm to effectively suggest import paths.\nIf you ever see something like `from src.mypackage.mymodule import ...`, then you probably forgot this step.\n5. Set the working directory of the unit tests to the project root (instead of the unittest directory). How to do this:\na) Open any test file whose name starts with `test_` in unit tests/tests\nb) Right click inside the code ➡ More Run/Debug ➡ Modify Run Configuration ➡ expand Environment collapsible ➡ Working directory\nc) Change to `your_repo` instead of `your_repo\\unittests`\nBy doing so, the import and other file paths in the tests are relative to the repo root.\nIf this doesn't work anymore, see: [working directory of the unit tests](https://www.jetbrains.com/help/pycharm/creating-run-debug-configuration-for-tests.html)\n\n### How to use with VS Code\nAll paths mentioned in this section are relative to the repository root.\n\n1. Open the folder with VS Code.\n2. **Select the python interpreter** ([official docs](https://code.visualstudio.com/docs/python/environments#_manually-specify-an-interpreter)) which is created by tox. Open the command pallett with `CTRL + P` and type `Python: Select Interpreter`. Select the interpreter which is placed in `.tox/dev/Scripts/python.exe` under Windows or `.tox/dev/bin/python` under Linux and macOS.\n3. **Set up pytest and pylint**. Therefore we open the file `.vscode/settings.json` which should be automatically generated during the interpreter setup. If it doesn't exist, create it. Insert the following lines into the settings:\n\n```json\n{\n  \"python.testing.unittestEnabled\": false,\n  \"python.testing.nosetestsEnabled\": false,\n  \"python.testing.pytestEnabled\": true,\n  \"pythonTestExplorer.testFramework\": \"pytest\",\n  \"python.testing.pytestArgs\": [\"unittests\"],\n  \"python.linting.pylintEnabled\": true\n}\n```\n\n4. Create a `.env` file and insert the following line\n\nFor Windows:\n\n```\nPYTHONPATH=src;${PYTHONPATH}\n```\n\nFor Linux and Mac:\n\n```\nPYTHONPATH=src:${PYTHONPATH}\n```\n\nThis makes sure, that the imports are working for the unittests.\nAt the moment I am not totally sure that it is the best practise, but it's getting the job done.\n\n5. Enjoy 🤗\n\n## Publishing on PyPI\n\nThis repository contains all necessary CI steps to publish any project created from it on PyPI.\nIt uses the trusted publishers workflow as described in the [official Python documentation](https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/).\nIt just requires some manual adjustments/settings depending on your project:\n\n1. Fill out the metadata in the [`pyproject.toml`](pyproject.toml); Namely the package name and the dependencies which should be in sync with your `requirements.in`.\n2. Uncomment the lines in [`.github/workflows/python-publish.yml`](.github/workflows/python-publish.yml)\n3. Create a [new environment in your GitHub repository](https://github.com/Hochfrequenz/python_template_repository/settings/environments) and call it `release`.\n4. Set up a new trusted publisher [in your PYPI account](https://pypi.org/manage/account/publishing/).\n   1. PyPI Project Name: The name which you defined in the `pyproject.toml` is the name of the project which you have to enter here.\n   2. Owner: The GitHub organization name or GitHub username that owns the repository\n   3. Repository name: The name of the GitHub repository that contains the publishing workflow\n   4. Workflow name: The filename of the publishing workflow. This file should exist in the .github/workflows/ directory in the repository configured above. Here in our case: `python-publish.yml`\n   5. Environment name: The name of the GitHub Actions environment that the above workflow uses for publishing. Here in our case: `release`\n5. Now create a release by clicking on \"Create new release\" in the right Github sidebar (or visit `github.com/your-username/your-reponame/releases/new`). This should trigger the workflow (see the \"Actions\" tab of your repo).\n6. Check if the action failed. If it succeeded your PyPI account should now show the new project. It might take some minutes until the package can be installed via `pip install packagename` because the index has to be updated.\n7. Now create another PyPI token with limited scope and update the Github repository secret accordingly.\n\n## Contribute\n\nYou are very welcome to contribute to this template repository by opening a pull request against the main branch.\n\n### GitHub Actions\n\n- Dependabot auto-approve / -merge:\n  - If the actor is the Dependabot bot (i.e. on every commit by Dependabot)\n    the pull request is automatically approved and auto merge gets activated\n    (using squash merge).\n    Note that if you haven't enabled \"auto merge\" for your repository, the auto merge activation will fail.\n    If you want to use a merge type other than \"squash merge\" you have to edit the workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhochfrequenz%2Fpython_template_repository","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhochfrequenz%2Fpython_template_repository","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhochfrequenz%2Fpython_template_repository/lists"}