oe-python-template 0.2.1__tar.gz → 0.2.2__tar.gz

oe_python_template-0.2.1/RELEASE_NOTES.md → oe_python_template-0.2.2/CHANGELOG.md

@@ -1,5 +1,12 @@
 [🧠 OE Python Template](https://oe-python-template.readthedocs.io/en/latest/)
 
+## [0.2.2](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.2.1..0.2.2) - 2025-03-02
+
+### 📚 Documentation
+
+- Update - ([ae71c31](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/commit/ae71c31c917a7439dc24fe9b86c48e38cf1d4c29))
+
+
 ## [0.2.1](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.2.0..v0.2.1) - 2025-03-02
 
 ### 📚 Documentation

oe_python_template-0.2.2/PKG-INFO

@@ -0,0 +1,341 @@
+Metadata-Version: 2.4
+Name: oe-python-template
+Version: 0.2.2
+Summary: 🧠 Copier template to scaffold Python projects compliant with best practices and modern tooling.
+Project-URL: Homepage, https://oe-python-template.readthedocs.io/en/latest/
+Project-URL: Documentation, https://oe-python-template.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/releases
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/issues
+Author-email: Helmut Hoffer von Ankershoffen <helmuthva@gmail.com>
+License: MIT License
+        
+        Copyright (c) [2025] [Helmut Hoffer von Ankershoffen (helmuthva@gmail.com)]
+        
+        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.
+License-File: LICENSE
+Keywords: codecov,docker,oe-python-template,pydantic,python,ruff,typer,uv
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.11
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: typer>=0.15.1
+Provides-Extra: examples
+Requires-Dist: jupyter>=1.1.1; extra == 'examples'
+Requires-Dist: marimo>=0.11.13; extra == 'examples'
+Requires-Dist: streamlit>=1.42.2; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# 🧠 OE Python Template
+
+[![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/oe-python-template?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
+](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oe-python-template.svg?logo=python&color=204361&labelColor=1E2933)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py)
+[![CI](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/actions/workflows/test-and-report.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/actions/workflows/test-and-report.yml)
+[![Read the Docs](https://img.shields.io/readthedocs/oe-python-template)](https://oe-python-template.readthedocs.io/en/latest/)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Security](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Coverage](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template/graph/badge.svg?token=SX34YRP30E)](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template)
+[![Ruff](https://img.shields.io/badge/style-Ruff-blue?color=D6FF65)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py)
+[![GitHub - Version](https://img.shields.io/github/v/release/helmut-hoffer-von-ankershoffen/oe-python-template?label=GitHub&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/releases)
+[![GitHub - Commits](https://img.shields.io/github/commit-activity/m/helmut-hoffer-von-ankershoffen/oe-python-template/main?label=commits&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/commits/main/)
+[![PyPI - Version](https://img.shields.io/pypi/v/oe-python-template.svg?label=PyPI&logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/oe-python-template)
+[![PyPI - Status](https://img.shields.io/pypi/status/oe-python-template?logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/oe-python-template)
+[![Docker - Version](https://img.shields.io/docker/v/helmuthva/oe-python-template?sort=semver&label=Docker&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
+[![Docker - Size](https://img.shields.io/docker/image-size/helmuthva/oe-python-templatesort=semver&arch=arm64&label=image&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/oe-python-template/)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
+<!---
+[![ghcr.io - Version](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/oe-python-template/tags?color=%2344cc11&ignore=0.0%2C0%2Clatest&n=3&label=ghcr.io&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/pkgs/container/oe-python-template)
+[![ghcr.io - Sze](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/oe-python-template/size?color=%2344cc11&tag=latest&label=size&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/pkgs/container/oe-python-template)
+-->
+
+> [!TIP]
+> 📚 [Online documentation](https://oe-python-template.readthedocs.io/en/latest/) - 📖 [PDF Manual](https://oe-python-template.readthedocs.io/_/downloads/en/latest/pdf/)
+---
+
+
+Copier template to scaffold Python projects compliant with best practices and modern tooling.
+
+Use Cases:
+1) Fast and easy to use project setup
+2) Consistent update of already scaffolded projects to benefit from new and improved features.
+3) Dummy CLI application and service demonstrating example usage of the generated directory structure and build pipeline
+
+## Scaffolding Instructions
+
+Step 1: Install uv package manager and copier
+```shell
+if [[ "$OSTYPE" == "darwin"* ]]; then                 # Install dependencies for macOS X
+  if ! command -v brew &> /dev/null; then             ## Install Homebrew if not present
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  fi
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then            # Install dependencies for Linux
+  sudo apt-get update -y && sudo apt-get install curl -y # Install curl
+fi
+if ! command -v uvx &> /dev/null; then                # Install uv package manager if not present
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  source $HOME/.local/bin/env
+fi
+uv tool install copier                                # Install copier as global tool
+```
+
+Step 2: Now create an empty repo on GitHub and clone it to your local machine in a directory of your choice. Change to that directory.
+
+Step 3: Scaffold the project
+```shell 
+copier copy gh:helmut-hoffer-von-ankershoffen/oe-python-template .
+```
+Step 4: Setup the local environment
+
+```shell
+uv run nox -s setup_eev
+```
+
+Step 5: Perform inital commit and push
+```shell
+git add .
+git commit -m "feat: Initial commit"
+```
+
+Visit your GitHub repository and check the Actions tab. The CI workflow should fail at the SonarQube step, 
+as this external service is not yet configured for our new repository.
+
+Step 6: Follow the instructions in SERVICE_CONNECTIONS.md to setup the connections to external services 
+such as Cloudcov, SonarQube Cloud, Read The Docs, Docker.io, GHCR.io and Streamlit Community Cloud.
+
+Step 7: Release the first versions
+```shell
+./bump
+```
+Notes: 
+* You can remove this section post having successfully scafolded your project.
+* The following sections refer to the dummy application and service provided by this template. 
+  Use them as inspiration and adapt them to your own project.
+
+## Overview
+
+Adding OE Python Template to your project as a dependency is easy.
+
+```shell
+uv add oe-python-template             # add dependency to your project
+```
+
+If you don't have uv installed follow [these instructions](https://docs.astral.sh/uv/getting-started/installation/). If you still prefer pip over the modern and fast package manager [uv](https://github.com/astral-sh/uv), you can install the library like this:
+
+```shell
+pip install oe-python-template        # add dependency to your project
+```
+
+Executing the command line interface (CLI) is just as easy:
+
+```shell
+uvx oe-python-template
+```
+
+The CLI provides extensive help:
+
+```shell
+uvx oe-python-template --help              # all CLI commands
+uvx oe-python-template command --help      # all options for command
+```
+
+
+## Highlights
+
+* Copier template to scaffold Python projects compliant with best practices and modern tooling.
+* Various Examples:
+  - [Simple Python script]https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py)
+  - [Streamlit web application](https://oe-python-template.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
+  - [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py) notebook
+* [Complete reference documenation](https://oe-python-template.readthedocs.io/en/latest/reference.html) on Read the Docs
+* [Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template) including unit and E2E tests (reported on Codecov)
+* Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
+* Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
+* Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate))
+* [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template) in security, maintainability, and reliability with low technical debt and low codesmell (verified by SonarQube)
+* 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
+* Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
+
+
+## Usage Examples
+
+### Minimal Python Script:
+
+```python
+"""Example script demonstrating the usage of the service provided by OE Python Template."""
+
+from dotenv import load_dotenv
+from rich.console import Console
+
+from oe_python_template import Service
+
+console = Console()
+
+load_dotenv()
+
+message = Service.get_hello_world()
+console.print(f"[blue]{message}[/blue]")
+```
+
+[Show script code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py) - [Read the reference documentation](https://oe-python-template.readthedocs.io/en/latest/reference.html)
+
+### Streamlit App
+
+Serve the functionality provided by OE Python Template in the web by easily integrating the service into a Streamlit application.
+
+[Try it out!](https://oe-python-template.streamlit.app) - [Show the code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/streamlit.py)
+
+... or serve the app locally
+```shell
+uv sync --all-extras                                # Install streamlit dependency part of the examples extra, see pyproject.toml
+uv run streamlit run examples/streamlit.py          # Serve on localhost:8501, opens browser
+```
+
+## Notebooks
+
+### Jupyter
+
+[Show the Jupyter code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb)
+
+... or run within VSCode
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+```
+Install the [Jupyter extension for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
+
+Click on `examples/notebook.ipynb` in VSCode and run it.
+
+### Marimo
+
+[Show the marimo code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py)
+
+Execute the notebook as a WASM based web app
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+uv run marimo run examples/notebook.py --watch      # Serve on localhost:2718, opens browser
+```
+
+or edit interactively in your browser
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+uv run marimo edit examples/notebook.py --watch     # Edit on localhost:2718, opens browser
+```
+
+... or edit interactively within VSCode
+
+Install the [Marimo extension for VSCode](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo)
+
+Click on `examples/notebook.py` in VSCode and click on the caret next to the Run icon above the code (looks like a pencil) > "Start in marimo editor" (edit).
+
+## Command Line Interface (CLI)
+
+### Run with [uvx](https://docs.astral.sh/uv/guides/tools/)
+
+Show available commands:
+
+```shell
+uvx oe-python-template --help
+```
+
+Execute commands:
+
+```shell
+uvx oe-python-template hello-world
+uvx oe-python-template hello-world --json
+uvx oe-python-template echo "Lorem Ipsum"
+```
+
+### Environment
+
+The service loads environment variables including support for .env files.
+
+```shell
+cp .env.example .env              # copy example file
+echo "THE_VAR=MY_VALUE" > .env    # overwrite with your values
+```
+
+Now run the usage examples again.
+
+### Run with Docker
+
+You can as well run the CLI within Docker.
+
+```shell
+docker run helmuthva/oe-python-template --help
+docker run helmuthva/oe-python-template hello-world
+docker run helmuthva/oe-python-template hello-world --json
+docker run helmuthva/oe-python-template echo "Lorem"
+```
+
+Execute command:
+
+```shell
+docker run --env THE_VAR=MY_VALUE helmuthva/oe-python-template echo "Lorem Ipsum"
+```
+
+Or use docker compose
+
+The .env is passed through from the host to the Docker container.
+
+```shell
+docker compose up
+docker compose run oe-python-template --help
+```
+
+## Extra: Lorem Ipsum
+
+Dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam.
+
+
+## Further Reading
+
+* Check out the [reference](https://oe-python-template.readthedocs.io/en/latest/reference.html) with detailed documentation of public classes and functions.
+* Our [release notes](https://oe-python-template.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
+* In case you want to help us improve 🧠 OE Python Template: The [contribution guidelines](https://oe-python-template.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
+
+## Star History
+
+<a href="https://star-history.com/#helmut-hoffer-von-ankershoffen/oe-python-template">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date" />
+ </picture>
+</a>

oe_python_template-0.2.2/README.md

@@ -0,0 +1,282 @@
+# 🧠 OE Python Template
+
+[![License](https://img.shields.io/github/license/helmut-hoffer-von-ankershoffen/oe-python-template?logo=opensourceinitiative&logoColor=3DA639&labelColor=414042&color=A41831)
+](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/LICENSE)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oe-python-template.svg?logo=python&color=204361&labelColor=1E2933)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py)
+[![CI](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/actions/workflows/test-and-report.yml/badge.svg)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/actions/workflows/test-and-report.yml)
+[![Read the Docs](https://img.shields.io/readthedocs/oe-python-template)](https://oe-python-template.readthedocs.io/en/latest/)
+[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Security](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Maintainability](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=helmut-hoffer-von-ankershoffen_oe-python-template&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template)
+[![Coverage](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template/graph/badge.svg?token=SX34YRP30E)](https://codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template)
+[![Ruff](https://img.shields.io/badge/style-Ruff-blue?color=D6FF65)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py)
+[![GitHub - Version](https://img.shields.io/github/v/release/helmut-hoffer-von-ankershoffen/oe-python-template?label=GitHub&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/releases)
+[![GitHub - Commits](https://img.shields.io/github/commit-activity/m/helmut-hoffer-von-ankershoffen/oe-python-template/main?label=commits&style=flat&labelColor=1C2C2E&color=blue&logo=GitHub&logoColor=white)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/commits/main/)
+[![PyPI - Version](https://img.shields.io/pypi/v/oe-python-template.svg?label=PyPI&logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/oe-python-template)
+[![PyPI - Status](https://img.shields.io/pypi/status/oe-python-template?logo=pypi&logoColor=%23FFD243&labelColor=%230073B7&color=FDFDFD)](https://pypi.python.org/pypi/oe-python-template)
+[![Docker - Version](https://img.shields.io/docker/v/helmuthva/oe-python-template?sort=semver&label=Docker&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
+[![Docker - Size](https://img.shields.io/docker/image-size/helmuthva/oe-python-templatesort=semver&arch=arm64&label=image&logo=docker&logoColor=white&labelColor=1354D4&color=10151B)](https://hub.docker.com/r/helmuthva/oe-python-template/)
+[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-orange.json)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template)
+<!---
+[![ghcr.io - Version](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/oe-python-template/tags?color=%2344cc11&ignore=0.0%2C0%2Clatest&n=3&label=ghcr.io&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/pkgs/container/oe-python-template)
+[![ghcr.io - Sze](https://ghcr-badge.egpl.dev/helmut-hoffer-von-ankershoffen/oe-python-template/size?color=%2344cc11&tag=latest&label=size&trim=)](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/pkgs/container/oe-python-template)
+-->
+
+> [!TIP]
+> 📚 [Online documentation](https://oe-python-template.readthedocs.io/en/latest/) - 📖 [PDF Manual](https://oe-python-template.readthedocs.io/_/downloads/en/latest/pdf/)
+---
+
+
+Copier template to scaffold Python projects compliant with best practices and modern tooling.
+
+Use Cases:
+1) Fast and easy to use project setup
+2) Consistent update of already scaffolded projects to benefit from new and improved features.
+3) Dummy CLI application and service demonstrating example usage of the generated directory structure and build pipeline
+
+## Scaffolding Instructions
+
+Step 1: Install uv package manager and copier
+```shell
+if [[ "$OSTYPE" == "darwin"* ]]; then                 # Install dependencies for macOS X
+  if ! command -v brew &> /dev/null; then             ## Install Homebrew if not present
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  fi
+elif [[ "$OSTYPE" == "linux-gnu"* ]]; then            # Install dependencies for Linux
+  sudo apt-get update -y && sudo apt-get install curl -y # Install curl
+fi
+if ! command -v uvx &> /dev/null; then                # Install uv package manager if not present
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  source $HOME/.local/bin/env
+fi
+uv tool install copier                                # Install copier as global tool
+```
+
+Step 2: Now create an empty repo on GitHub and clone it to your local machine in a directory of your choice. Change to that directory.
+
+Step 3: Scaffold the project
+```shell 
+copier copy gh:helmut-hoffer-von-ankershoffen/oe-python-template .
+```
+Step 4: Setup the local environment
+
+```shell
+uv run nox -s setup_eev
+```
+
+Step 5: Perform inital commit and push
+```shell
+git add .
+git commit -m "feat: Initial commit"
+```
+
+Visit your GitHub repository and check the Actions tab. The CI workflow should fail at the SonarQube step, 
+as this external service is not yet configured for our new repository.
+
+Step 6: Follow the instructions in SERVICE_CONNECTIONS.md to setup the connections to external services 
+such as Cloudcov, SonarQube Cloud, Read The Docs, Docker.io, GHCR.io and Streamlit Community Cloud.
+
+Step 7: Release the first versions
+```shell
+./bump
+```
+Notes: 
+* You can remove this section post having successfully scafolded your project.
+* The following sections refer to the dummy application and service provided by this template. 
+  Use them as inspiration and adapt them to your own project.
+
+## Overview
+
+Adding OE Python Template to your project as a dependency is easy.
+
+```shell
+uv add oe-python-template             # add dependency to your project
+```
+
+If you don't have uv installed follow [these instructions](https://docs.astral.sh/uv/getting-started/installation/). If you still prefer pip over the modern and fast package manager [uv](https://github.com/astral-sh/uv), you can install the library like this:
+
+```shell
+pip install oe-python-template        # add dependency to your project
+```
+
+Executing the command line interface (CLI) is just as easy:
+
+```shell
+uvx oe-python-template
+```
+
+The CLI provides extensive help:
+
+```shell
+uvx oe-python-template --help              # all CLI commands
+uvx oe-python-template command --help      # all options for command
+```
+
+
+## Highlights
+
+* Copier template to scaffold Python projects compliant with best practices and modern tooling.
+* Various Examples:
+  - [Simple Python script]https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py)
+  - [Streamlit web application](https://oe-python-template.streamlit.app/) deployed on [Streamlit Community Cloud](https://streamlit.io/cloud)
+  - [Jupyter](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb) and [Marimo](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py) notebook
+* [Complete reference documenation](https://oe-python-template.readthedocs.io/en/latest/reference.html) on Read the Docs
+* [Transparent test coverage](https://app.codecov.io/gh/helmut-hoffer-von-ankershoffen/oe-python-template) including unit and E2E tests (reported on Codecov)
+* Matrix tested with [multiple python versions](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/noxfile.py) to ensure compatibility (powered by [Nox](https://nox.thea.codes/en/stable/))
+* Compliant with modern linting and formatting standards (powered by [Ruff](https://github.com/astral-sh/ruff))
+* Up-to-date dependencies (monitored by [Renovate](https://github.com/renovatebot/renovate))
+* [A-grade code quality](https://sonarcloud.io/summary/new_code?id=helmut-hoffer-von-ankershoffen_oe-python-template) in security, maintainability, and reliability with low technical debt and low codesmell (verified by SonarQube)
+* 1-liner for installation and execution of command line interface (CLI) via [uv(x)](https://github.com/astral-sh/uv) or [Docker](https://hub.docker.com/r/helmuthva/oe-python-template/tags)
+* Setup for developing inside a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) included (supports VSCode and GitHub Codespaces)
+
+
+## Usage Examples
+
+### Minimal Python Script:
+
+```python
+"""Example script demonstrating the usage of the service provided by OE Python Template."""
+
+from dotenv import load_dotenv
+from rich.console import Console
+
+from oe_python_template import Service
+
+console = Console()
+
+load_dotenv()
+
+message = Service.get_hello_world()
+console.print(f"[blue]{message}[/blue]")
+```
+
+[Show script code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/script.py) - [Read the reference documentation](https://oe-python-template.readthedocs.io/en/latest/reference.html)
+
+### Streamlit App
+
+Serve the functionality provided by OE Python Template in the web by easily integrating the service into a Streamlit application.
+
+[Try it out!](https://oe-python-template.streamlit.app) - [Show the code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/streamlit.py)
+
+... or serve the app locally
+```shell
+uv sync --all-extras                                # Install streamlit dependency part of the examples extra, see pyproject.toml
+uv run streamlit run examples/streamlit.py          # Serve on localhost:8501, opens browser
+```
+
+## Notebooks
+
+### Jupyter
+
+[Show the Jupyter code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.ipynb)
+
+... or run within VSCode
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+```
+Install the [Jupyter extension for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter)
+
+Click on `examples/notebook.ipynb` in VSCode and run it.
+
+### Marimo
+
+[Show the marimo code](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/blob/main/examples/notebook.py)
+
+Execute the notebook as a WASM based web app
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+uv run marimo run examples/notebook.py --watch      # Serve on localhost:2718, opens browser
+```
+
+or edit interactively in your browser
+
+```shell
+uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml
+uv run marimo edit examples/notebook.py --watch     # Edit on localhost:2718, opens browser
+```
+
+... or edit interactively within VSCode
+
+Install the [Marimo extension for VSCode](https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo)
+
+Click on `examples/notebook.py` in VSCode and click on the caret next to the Run icon above the code (looks like a pencil) > "Start in marimo editor" (edit).
+
+## Command Line Interface (CLI)
+
+### Run with [uvx](https://docs.astral.sh/uv/guides/tools/)
+
+Show available commands:
+
+```shell
+uvx oe-python-template --help
+```
+
+Execute commands:
+
+```shell
+uvx oe-python-template hello-world
+uvx oe-python-template hello-world --json
+uvx oe-python-template echo "Lorem Ipsum"
+```
+
+### Environment
+
+The service loads environment variables including support for .env files.
+
+```shell
+cp .env.example .env              # copy example file
+echo "THE_VAR=MY_VALUE" > .env    # overwrite with your values
+```
+
+Now run the usage examples again.
+
+### Run with Docker
+
+You can as well run the CLI within Docker.
+
+```shell
+docker run helmuthva/oe-python-template --help
+docker run helmuthva/oe-python-template hello-world
+docker run helmuthva/oe-python-template hello-world --json
+docker run helmuthva/oe-python-template echo "Lorem"
+```
+
+Execute command:
+
+```shell
+docker run --env THE_VAR=MY_VALUE helmuthva/oe-python-template echo "Lorem Ipsum"
+```
+
+Or use docker compose
+
+The .env is passed through from the host to the Docker container.
+
+```shell
+docker compose up
+docker compose run oe-python-template --help
+```
+
+## Extra: Lorem Ipsum
+
+Dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam.
+
+
+## Further Reading
+
+* Check out the [reference](https://oe-python-template.readthedocs.io/en/latest/reference.html) with detailed documentation of public classes and functions.
+* Our [release notes](https://oe-python-template.readthedocs.io/en/latest/release-notes.html) provide a complete log of recent improvements and changes.
+* In case you want to help us improve 🧠 OE Python Template: The [contribution guidelines](https://oe-python-template.readthedocs.io/en/latest/contributing.html) explain how to setup your development environment and create pull requests.
+
+## Star History
+
+<a href="https://star-history.com/#helmut-hoffer-von-ankershoffen/oe-python-template">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=helmut-hoffer-von-ankershoffen/oe-python-template&type=Date" />
+ </picture>
+</a>

oe_python_template-0.2.1/CHANGELOG.md → oe_python_template-0.2.2/RELEASE_NOTES.md

@@ -1,6 +1,13 @@
 [🧠 OE Python Template](https://oe-python-template.readthedocs.io/en/latest/)
 
-## [0.2.1](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.2.0..0.2.1) - 2025-03-02
+## [0.2.2](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.2.1..v0.2.2) - 2025-03-02
+
+### 📚 Documentation
+
+- Update - ([ae71c31](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/commit/ae71c31c917a7439dc24fe9b86c48e38cf1d4c29))
+
+
+## [0.2.1](https://github.com/helmut-hoffer-von-ankershoffen/oe-python-template/compare/v0.2.0..v0.2.1) - 2025-03-02
 
 ### 📚 Documentation
 

oe_python_template-0.2.2/VERSION

@@ -0,0 +1 @@
+0.2.2