From 6ff32a6662c758c2a8220a201df654a0bfe890d0 Mon Sep 17 00:00:00 2001 From: DeltaDaniel <139119540+DeltaDaniel@users.noreply.github.com> Date: Mon, 16 Oct 2023 15:49:19 +0200 Subject: [PATCH] set up initial CI/CD workflows and tools --- .../workflows/{unittests.yml => tests.yml} | 2 +- README.md | 106 +++--------------- pyproject.toml | 15 +-- src/{mypackage => }/__init__.py | 0 src/_borm_version.py | 0 src/mypackage/mymodule.py | 23 ---- src/mypackage/py.typed | 2 - {unittests => tests}/.pylintrc | 2 +- {unittests => tests}/__init__.py | 0 tox.ini | 6 +- unittests/test_myclass.py | 11 -- 11 files changed, 28 insertions(+), 139 deletions(-) rename .github/workflows/{unittests.yml => tests.yml} (96%) rename src/{mypackage => }/__init__.py (100%) create mode 100644 src/_borm_version.py delete mode 100644 src/mypackage/mymodule.py delete mode 100644 src/mypackage/py.typed rename {unittests => tests}/.pylintrc (96%) rename {unittests => tests}/__init__.py (100%) delete mode 100644 unittests/test_myclass.py diff --git a/.github/workflows/unittests.yml b/.github/workflows/tests.yml similarity index 96% rename from .github/workflows/unittests.yml rename to .github/workflows/tests.yml index 05a6641..165f5fa 100644 --- a/.github/workflows/unittests.yml +++ b/.github/workflows/tests.yml @@ -1,4 +1,4 @@ -name: "Unittests" +name: "tests" on: [push] jobs: diff --git a/README.md b/README.md index 84b94c7..c2e849d 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,28 @@ -# Python Template Repository including a `tox.ini`, Unittests&Coverage, Pylint & MyPy Linting Actions and a PyPI Publishing Workflow +# Python BO4E ORM - -![Unittests status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Unittests/badge.svg) -![Coverage status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Coverage/badge.svg) -![Linting status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Linting/badge.svg) -![Black status badge](https://github.com/Hochfrequenz/python_template_repository/workflows/Formatting/badge.svg) +![Unittests status badge](https://github.com/Hochfrequenz/b04e-python-orm/workflows/tests/badge.svg) +![Coverage status badge](https://github.com/Hochfrequenz/b04e-python-orm/workflows/Coverage/badge.svg) +![Linting status badge](https://github.com/Hochfrequenz/b04e-python-orm/workflows/Linting/badge.svg) +![Black status badge](https://github.com/Hochfrequenz/b04e-python-orm/workflows/Formatting/badge.svg) -This is a template repository. It doesn't contain any useful code but only a minimal working setup for a Python project including: +A ORM tool to map between SQL databases and bo4e classes using: +... -- a basic **project structure** with - - tox.ini - - requirements.in - - and a requirements.txt derived from it - - an example class - - an example unit test (using pytest) -- ready to use **Github Actions** for - - [pytest](https://pytest.org) - - [code coverage measurement](https://coverage.readthedocs.io) (fails below 80% by default) - - [pylint](https://pylint.org/) (only accepts 10/10 code rating by default) - - [mypy](https://github.com/python/mypy) (static type checks where possible) - - [black](https://github.com/psf/black) code formatter check - - [isort](https://pycqa.github.io/isort/) import order check - - [codespell](https://github.com/codespell-project/codespell) spell check (including an ignore list) - - ready-to-use publishing workflow for pypi (see readme section below) - - -By default, it uses Python version 3.11. - -## How to use this Repository on Your Machine - -This introduction assumes that you have tox installed already ( -see [installation instructions](https://tox.readthedocs.io/en/latest/installation.html)) and that a `.toxbase` environment -has been created. -`.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. - -Also on 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). - -If this is the case, clone this repository and create the `dev` environment on your machine. +### Installation +It will also be [available on pypi](https://pypi.org/project/borm/). ```bash -tox -e dev +pip install borm ``` -### How to use with PyCharm - -1. Create a new project using existing sources with your local working copy of this repository as root directory. Choose - the path `your_repo/.tox/dev/` as path of the "previously configured interpreter". -2. Set the - default [test runner of your project](https://www.jetbrains.com/help/pycharm/choosing-your-testing-framework.html) to - pytest. -3. Set the `src` directory as sources root (via right click, [docs](https://www.jetbrains.com/help/pycharm/content-root.html)). -4. Set - the [working directory of the unit tests](https://www.jetbrains.com/help/pycharm/creating-run-debug-configuration-for-tests.html) - to the project root (instead of the unittest directory). - -### How to use with VS Code - -1. Open the folder with VS Code. -2. **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. -3. **Setup pytest and pylint**. Therefore we open the file `.vscode/settings.json` which should be automatically generated during the interpreter setup. Insert the following lines into the settings: +### Documentation +Will be implemented soon -```json -{ - "python.testing.unittestEnabled": false, - "python.testing.nosetestsEnabled": false, - "python.testing.pytestEnabled": true, - "pythonTestExplorer.testFramework": "pytest", - "python.testing.pytestArgs": [ - "unittests" - ], - "python.linting.pylintEnabled": true -} -``` -4. Create a `.env` file and insert the following line - -For Windows: -``` -PYTHONPATH=src;${PYTHONPATH} -``` -For Linux and Mac: -``` -PYTHONPATH=src:${PYTHONPATH} -``` -This makes sure, that the imports are working for the unittests. -At the moment I am not totally sure that it is the best practise, but it's getting the job done. - -5. Enjoy 🤗 +## How to use this Repository on Your Machine -## Publishing on PyPI -This repository contains all necessary CI steps to publish any project created from it on PyPI. -It just requires some manual adjustments/settings depending on your project: -1. 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`. -2. Uncomment the lines in [`.github/workflows/python-publish.yml`](.github/workflows/python-publish.yml) -3. In [your PyPI account create a new API token](https://pypi.org/manage/account/#api-tokens). You have to create a token valid for your entire account first, only when the initial push happened, you can create a new token whose scope is limited to this project. -4. Copy the token and paste it as a new repository secret under `github.com/your-username/your-reponame/settings/secrets/actions/new`. The secrets name should be `PYPI_API_TOKEN` as in the last line of the workflow file you edited in step 2. -5. 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). -6. 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. -7. Now create another PyPI token with limited scope and update the Github repository secret accordingly. +Follow the instructions in our [Python template repository](https://github.com/Hochfrequenz/python_template_repository#how-to-use-this-repository-on-your-machine). ## Contribute -You are very welcome to contribute to this template repository by opening a pull request against the main branch. +You are very welcome to contribute to this repository by opening a pull request against the main branch. diff --git a/pyproject.toml b/pyproject.toml index 6aac10c..1534523 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,10 +1,10 @@ [project] -name = "your-favourite-package-name" -description = "Description of your package" +name = "borm" +description = "A ORM tool to map between SQL databases and bo4e classes" license = { text = "MIT" } requires-python = ">=3.11" -authors = [{ name = "your name", email = "your@email.address" }] -keywords = ["your", "important", "keywords"] +authors = [{ name = "Hochfrequenz Unternehmensberatung GmbH", email = "info@hochfrequenz.de" }] +keywords = ["bo4e", "orm", "sql"] classifiers = [ "Development Status :: 4 - Beta", "Environment :: Console", @@ -14,13 +14,14 @@ classifiers = [ "Programming Language :: Python", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12" ] dependencies = [] # add all the dependencies from requirements.in here, too dynamic = ["readme", "version"] [project.urls] -Changelog = "https://github.com/Hochfrequenz/python_template_repository/releases" -Homepage = "https://github.com/Hochfrequenz/python_template_repository" +Changelog = "https://github.com/Hochfrequenz/bo4e-python-orm/releases" +Homepage = "https://github.com/Hochfrequenz/bo4e-python-orm" [tool.black] line-length = 120 @@ -56,4 +57,4 @@ exclude = ["/unittests"] [tool.hatch.build.targets.wheel] only-include = ["src"] -sources = ["src"] \ No newline at end of file +sources = ["src"] diff --git a/src/mypackage/__init__.py b/src/__init__.py similarity index 100% rename from src/mypackage/__init__.py rename to src/__init__.py diff --git a/src/_borm_version.py b/src/_borm_version.py new file mode 100644 index 0000000..e69de29 diff --git a/src/mypackage/mymodule.py b/src/mypackage/mymodule.py deleted file mode 100644 index 2afc797..0000000 --- a/src/mypackage/mymodule.py +++ /dev/null @@ -1,23 +0,0 @@ -""" -This a docstring for the module. -""" - - -class MyClass: # pylint: disable=too-few-public-methods - """ - This is a docstring for the class. - """ - - def __init__(self): - """ - Initialize for the sake of initializing - """ - self.my_instance_var: str = "abc" - - def do_something(self) -> str: - """ - Actually does nothing. - :return: the value of an instance variable - """ - # this is a super long line with: 100 < line length <= 120 to demonstrate the purpose of pyproject.toml - return self.my_instance_var diff --git a/src/mypackage/py.typed b/src/mypackage/py.typed deleted file mode 100644 index 65a800b..0000000 --- a/src/mypackage/py.typed +++ /dev/null @@ -1,2 +0,0 @@ -# This file marks mypackage as PEP561 compatible. -# Further reading: https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages diff --git a/unittests/.pylintrc b/tests/.pylintrc similarity index 96% rename from unittests/.pylintrc rename to tests/.pylintrc index cc123a6..f6cc96b 100644 --- a/unittests/.pylintrc +++ b/tests/.pylintrc @@ -8,4 +8,4 @@ disable = W0621, # disable redefined-outer-name (this is for the use of pytest fixtures) R0801, # disable duplicate-code (we prefer our test to be explicit rather than perfectly redundancy free) [pylint."MESSAGES CONTROL"] -max-line-length = 120 \ No newline at end of file +max-line-length = 120 diff --git a/unittests/__init__.py b/tests/__init__.py similarity index 100% rename from unittests/__init__.py rename to tests/__init__.py diff --git a/tox.ini b/tox.ini index 42737d0..9619e5c 100644 --- a/tox.ini +++ b/tox.ini @@ -54,15 +54,15 @@ commands = [testenv:coverage] # the coverage environment is called by the Github Action that runs the coverage measurement -changedir = unittests +changedir = tests deps = {[testenv:tests]deps} -r dev_requirements/requirements-coverage.txt setenv = PYTHONPATH = {toxinidir}/src commands = coverage run -m pytest --basetemp={envtmpdir} {posargs} - coverage html --omit .tox/*,unittests/* - coverage report --fail-under 80 --omit .tox/*,unittests/* + coverage html --omit .tox/*,tests/* + coverage report --fail-under 80 --omit .tox/*,tests/* [testenv:dev] diff --git a/unittests/test_myclass.py b/unittests/test_myclass.py deleted file mode 100644 index 768a9e4..0000000 --- a/unittests/test_myclass.py +++ /dev/null @@ -1,11 +0,0 @@ -from mypackage.mymodule import MyClass - - -class TestMyClass: - """ - A class with pytest unit tests. - """ - - def test_something(self): - my_class = MyClass() - assert my_class.do_something() == "abc"