askhelmut 0.0.2

🤖 Exploration.

🤖 askhelmut

[!TIP] 📚 Online documentation - 📖 PDF Manual

---

Exploration.

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

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

copier copy gh:helmut-hoffer-von-ankershoffen/oe-python-template .

Step 4: Setup the local environment

uv run nox -s setup_eev

Step 5: Perform inital commit and push

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

./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 askhelmut to your project as a dependency is easy.

uv add askhelmut             # add dependency to your project

If you don't have uv installed follow these instructions. If you still prefer pip over the modern and fast package manager uv, you can install the library like this:

pip install askhelmut        # add dependency to your project

Executing the command line interface (CLI) is just as easy:

uvx askhelmut

The CLI provides extensive help:

uvx askhelmut --help              # all CLI commands
uvx askhelmut command --help      # all options for command

Highlights

• Exploration.
• Various Examples:
  • [Simple Python script]https://github.com/helmut-hoffer-von-ankershoffen/askhelmut/blob/main/examples/script.py)
  • Streamlit web application deployed on Streamlit Community Cloud
  • Jupyter and Marimo notebook
• Complete reference documenation on Read the Docs
• Transparent test coverage including unit and E2E tests (reported on Codecov)
• Matrix tested with multiple python versions to ensure compatibility (powered by Nox)
• Compliant with modern linting and formatting standards (powered by Ruff)
• Up-to-date dependencies (monitored by Renovate)
• A-grade code quality 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) or Docker
• Setup for developing inside a devcontainer included (supports VSCode and GitHub Codespaces)

Usage Examples

Minimal Python Script:

"""Example script demonstrating the usage of the service provided by askhelmut."""

from dotenv import load_dotenv
from rich.console import Console

from askhelmut import Service

console = Console()

load_dotenv()

message = Service.get_hello_world()
console.print(f"[blue]{message}[/blue]")

Show script code - Read the reference documentation

Streamlit App

Serve the functionality provided by askhelmut in the web by easily integrating the service into a Streamlit application.

Try it out! - Show the code

... or serve the app locally

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

... or run within VSCode

uv sync --all-extras                                # Install ipykernel dependency part of the examples extra, see pyproject.toml

Install the Jupyter extension for VSCode

Click on examples/notebook.ipynb in VSCode and run it.

Marimo

Show the marimo code

Execute the notebook as a WASM based web app

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

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

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

Show available commands:

uvx askhelmut --help

Execute commands:

uvx askhelmut hello-world
uvx askhelmut hello-world --json
uvx askhelmut echo "Lorem Ipsum"

Environment

The service loads environment variables including support for .env files.

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.

docker run helmuthva/askhelmut --help
docker run helmuthva/askhelmut hello-world
docker run helmuthva/askhelmut hello-world --json
docker run helmuthva/askhelmut echo "Lorem"

Execute command:

docker run --env THE_VAR=MY_VALUE helmuthva/askhelmut echo "Lorem Ipsum"

Or use docker compose

The .env is passed through from the host to the Docker container.

docker compose up
docker compose run askhelmut --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 with detailed documentation of public classes and functions.
• Our release notes provide a complete log of recent improvements and changes.
• In case you want to help us improve 🤖 askhelmut: The contribution guidelines explain how to setup your development environment and create pull requests.

Star History