Day 0: The Training Ground
Goal: set up uv, Python 3.14, ruff and pytest and build the first tool
halloas a uv project · Duration: approx. 45 min · Prerequisite: none
Briefing
- uv replaces pyenv, venv, pip and pipx: one binary, very fast, with a lockfile.
- Every tool is a project of its own with
pyproject.toml,src/layout and its own.venv. uv run <befehl>syncs the environment and runs the command in it – nosource .venv/bin/activateneeded.- ruff checks and formats, pytest tests. Both are dev dependencies, not part of the tool.
uv init --package ──► pyproject.toml + src/hallo/
uv run hallo ──► create .venv ──► install package ──► hallo:main()
uv add --dev ──► pyproject.toml [dependency-groups] + uv.lock
Drill 1: Check uv and get Python 3.14
uv --version || brew install uvExpected (version may differ):
uv 0.9.26 (ee4f00362 2026-01-15)
Without Homebrew:
curl -LsSf https://astral.sh/uv/install.sh | sh (installs
to ~/.local/bin).
uv python install 3.14
uv python find 3.14Expected (shortened, may differ by version):
Installed Python 3.14.2 in 4.77s
+ cpython-3.14.2-macos-aarch64-none (python3.14)
/Users/thomas/.local/share/uv/python/cpython-3.14.2-macos-aarch64-none/bin/python3.14
Why? uv manages its own Python builds under
~/.local/share/uv/python. The macOS system Python stays
untouched, and every project pins its version.
Save your progress? Sign up for free
Drill 2: Create the project
mkdir -p ~/py-lab && cd ~/py-lab
uv init --package --name hallo tag00-hallo
cd tag00-hallo
find . -type f -not -path './.git/*' | sortExpected:
Initialized project `hallo` at `…/py-lab/tag00-hallo`
./.gitignore
./.python-version
./README.md
./pyproject.toml
./src/hallo/__init__.py
--package creates an installable package in the
src/ layout including a console script; without the option
you would only get a loose main.py. uv also creates a Git
repo right away.
cat .python-version pyproject.tomlExpected (authors comes from your git configuration):
3.14
[project]
name = "hallo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
{ name = "Thomas Zachmann", email = "[email protected]" }
]
requires-python = ">=3.14"
dependencies = []
[project.scripts]
hallo = "hallo:main"
[build-system]
requires = ["uv_build>=0.9.26,<0.10.0"]
build-backend = "uv_build"
Why? [project.scripts] turns the function
main in the module hallo into a command
hallo. uv_build is uv’s build backend; more on
that on Day 5.
Save your progress? Sign up for free
Drill 3: First run
uv run hallo
ls -aExpected:
Using CPython 3.14.2
Creating virtual environment at: .venv
Building hallo @ file:///…/py-lab/tag00-hallo
Built hallo @ file:///…/py-lab/tag00-hallo
Installed 1 package in 2ms
Hello from hallo!
. .. .git .gitignore .python-version .venv README.md pyproject.toml src uv.lock
The first uv run creates .venv (the
environment, never commit it) and uv.lock (exact versions,
always commit it).
uv run python -c 'import sys; print(sys.version)'
uv run which pythonExpected:
3.14.2 (main, Jan 14 2026, 23:37:46) [Clang 21.1.4 ]
…/py-lab/tag00-hallo/.venv/bin/python
Tip:
uv run pythonstarts the REPL in the project. For trying out snippets that is faster than any file.
Save your progress? Sign up for free
Drill 4: Your own code
cat > src/hallo/__init__.py <<'EOF'
"""hallo – das erste Tool im Trainingslager."""
import sys
def greet(name: str = "Welt") -> str:
"""Gibt den Gruß zurück, statt ihn zu drucken – so ist er testbar."""
return f"Hallo, {name}!"
def main() -> None:
name = sys.argv[1] if len(sys.argv) > 1 else "Welt"
print(greet(name))
EOF
cat > src/hallo/__main__.py <<'EOF'
from hallo import main
main()
EOF
uv run hallo
uv run hallo Thomas
uv run python -m hallo LabExpected:
Hallo, Welt!
Hallo, Thomas!
Hallo, Lab!
Why? Logic (greet) and input/output (main)
are separated: functions that return values can be tested.
__main__.py makes python -m hallo possible,
handy without an installed script. name: str and
-> str are type hints: Python does not check them at
runtime, but your editor and mypy (Day 5) do.
Tip: No reinstall needed: uv installs your own package editable, changes in
src/take effect immediately.
Save your progress? Sign up for free
Drill 5: Dev tools and the first test
uv add --dev pytest ruff
tail -6 pyproject.tomlExpected (shortened):
+ pytest==9.1.1
+ ruff==0.17.0
[dependency-groups]
dev = [
"pytest>=9.1.1",
"ruff>=0.17.0",
]
The dev group does not end up in the package’s
dependencies; whoever installs hallo does not get
pytest.
mkdir -p tests
cat > tests/test_hallo.py <<'EOF'
from hallo import greet
def test_greet_default():
assert greet() == "Hallo, Welt!"
def test_greet_name():
assert greet("Thomas") == "Hallo, Thomas!"
EOF
uv run pytest -qExpected:
.. [100%]
2 passed in 0.00s
Why? pytest finds test_*.py files and
test_* functions on its own. A plain assert is
enough; if it fails, pytest shows both sides of the comparison.
Save your progress? Sign up for free
Drill 6: ruff – lint and format
Deliberately build a messy file:
cat > src/hallo/kaputt.py <<'EOF'
import os
def laut(text:str)->str:
return text.upper( )
EOF
uv run ruff check; echo "exit=$?"Expected (shortened):
I001 [*] Import block is un-sorted or un-formatted
--> src/hallo/kaputt.py:1:1
F401 [*] `os` imported but unused
--> src/hallo/kaputt.py:1:8
Found 2 errors.
[*] 2 fixable with `--fix`.
exit=1
uv run ruff check --fix
uv run ruff format
cat src/hallo/kaputt.pyExpected:
Found 1 error (1 fixed, 0 remaining).
1 file reformatted, 4 files left unchanged
def laut(text: str) -> str:
return text.upper()
ruff check finds errors and bad style (exit code 1, so
CI-ready), ruff format formats like Black. Clean up:
rm src/hallo/kaputt.pySave your progress? Sign up for free
Drill 7: The tool is done
cd ~/py-lab/tag00-hallo
uv run hallo Thomas
uv run pytest -q
uv run ruff check && uv run ruff format --check
uv treeExpected:
Hallo, Thomas!
.. [100%]
2 passed in 0.00s
All checks passed!
4 files already formatted
Resolved 8 packages in 3ms
hallo v0.1.0
├── pytest v9.1.1 (group: dev)
│ ├── iniconfig v2.3.1
│ ├── packaging v26.3
│ ├── pluggy v1.6.0
│ └── pygments v2.21.0
└── ruff v0.17.0 (group: dev)
This trio – uv run <tool>,
uv run pytest -q, uv run ruff check – closes
every day from now on.
The finished code for each day is available for comparison in the companion code on GitHub. Get it now; first you type yourself, then you take a look:
git clone https://github.com/thomaszachmann/python-zum-anfassen.git \
~/python-zum-anfassen
ls -1 ~/python-zum-anfassen/tag00-halloExpected:
Cloning into '…/python-zum-anfassen'...
pyproject.toml
README.md
src
tests
The folders are named like yours in ~/py-lab. After Day
1, for example,
diff -r ~/py-lab/tag01-wc ~/python-zum-anfassen/tag01-wc
shows where you differ.
Save your progress? Sign up for free
Checkpoint
#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/py-lab/tag00-hallo
check "uv installiert" "uv --version"
check "Projekt nutzt Python 3.14" \
"uv run python -c 'import sys; assert sys.version_info[:2] == (3, 14)'"
check "hallo grüßt" "uv run hallo Lab | grep -q 'Hallo, Lab!'"
check "python -m hallo geht" "uv run python -m hallo | grep -q Welt"
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check && uv run ruff format --check"
check "uv.lock vorhanden" "test -f uv.lock"Expected:
✔ uv installiert
✔ Projekt nutzt Python 3.14
✔ hallo grüßt
✔ python -m hallo geht
✔ Tests grün
✔ ruff sauber
✔ uv.lock vorhanden
Challenge
Make hallo multilingual: with HALLO_LANG=en
it greets in English, with da in Danish, otherwise in
German. Add a test.
Hint: A dict maps language to greeting,
os.environ.get() reads the variable with a default
value.
Solution
cat > src/hallo/__init__.py <<'EOF'
"""hallo – das erste Tool im Trainingslager."""
import os
import sys
GREETINGS = {"de": "Hallo", "en": "Hello", "da": "Hej"}
def greet(name: str = "Welt", lang: str = "de") -> str:
"""Gibt den Gruß zurück, statt ihn zu drucken – so ist er testbar."""
return f"{GREETINGS.get(lang, 'Hallo')}, {name}!"
def main() -> None:
name = sys.argv[1] if len(sys.argv) > 1 else "Welt"
print(greet(name, os.environ.get("HALLO_LANG", "de")))
EOF
cat >> tests/test_hallo.py <<'EOF'
def test_greet_lang():
assert greet("Mette", "da") == "Hej, Mette!"
assert greet("Bob", "xx") == "Hallo, Bob!"
EOF
HALLO_LANG=en uv run hallo Thomas
HALLO_LANG=da uv run hallo Thomas
uv run pytest -qExpected:
Hello, Thomas!
Hej, Thomas!
... [100%]
3 passed in 0.01s
dict.get(key, default) returns the default value instead
of raising a KeyError – this way unknown languages fall
back to German.
Save your progress? Sign up for free
Enterprise Note
uv.lockand.python-versionbelong in the repo; CI installs withuv sync --lockedand aborts if the lockfile andpyproject.tomldrift apart.- Behind a corporate proxy with its own CA:
uv --native-tlsorUV_NATIVE_TLS=1, so that uv uses the system certificate store. - Internal package sources (Artifactory, Nexus) via
[[tool.uv.index]]inpyproject.toml– credentials only via environment variable, never in the repo. - uv caches Python builds and packages under
~/.cache/uv; caching this folder in CI saves minutes. - Define the approved Python versions centrally (e.g. 3.13 and 3.14)
and reflect them in
requires-python.