podman-spawner 0.1.0__tar.gz

podman_spawner-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: podman-spawner
+Version: 0.1.0
+Summary: a Podman interface for container management
+Keywords: podman,containers,docker
+Author: Nicolas Pourcelot
+Author-email: Nicolas Pourcelot <nicolas.pourcelot@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Education :: Testing
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: colored-messages>=0.1.0
+Requires-Dist: fire>=0.6.0
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/wxgeo/podman-spawner
+Description-Content-Type: text/markdown
+
+# Podman Spawner — a Podman interface for container management
+
+`podman-spawner` automates the creation and lifecycle management of [Podman](https://podman.io/)
+containers, easing the creation of temporary podman images.
+
+It was originally developed to review students projects, enabling to create containers on the fly for each student group
+and submission version.
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [Using `pod`](#using-pod)
+
+---
+
+## Prerequisites
+
+`pod` is a thin wrapper around Podman (a rootless Docker alternative).
+Install it before anything else:
+
+```sh
+sudo apt install podman containers-storage
+```
+
+`containers-storage` is not strictly required, but it switches the storage
+driver from `vfs` to `overlay`, which makes image builds significantly faster.
+Verify it worked:
+
+```sh
+podman info | grep graphDriverName   # should print: overlay
+```
+
+To pull images from Docker Hub, register it as an unqualified search registry:
+
+```sh
+mkdir -p ~/.config/containers/
+echo 'unqualified-search-registries = ["docker.io"]' >> ~/.config/containers/registries.conf
+```
+
+For a small Podman introduction, see [podman-intro.md](podman-intro.md).
+
+---
+
+## Using `pod`
+
+### Installation
+
+Install [uv](https://docs.astral.sh/uv/) if you do not have it already:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then, from the root of the `pod` repository:
+
+```sh
+uv tool install -e .
+```
+
+The `pod` command is now available for the current user.
+
+### Configuration
+
+Every `pod` command reads `config.toml` from the **current working directory**.
+A default file is created by `pod init` (see below); its keys are:
+
+| Key      | Default  | Description                                          |
+|----------|----------|------------------------------------------------------|
+| `prefix` | `POD`    | Prefix prepended to every container name.            |
+| `port`   | `2026`   | Guest port exposed by the container.                 |
+| `user`   | `tester` | Username created inside the container at build time. |
+
+### Workflow overview
+
+```
+pod init        # create the pod-build/ scaffold
+  ↓ (edit Dockerfile, home-dir/, on_build.bash as needed)
+pod build       # build the Podman image
+pod test        # smoke-test the image interactively
+  ↓
+pod go <name>   # open a container for a group / version
+```
+
+### Commands
+
+#### `pod init`
+
+Creates a `pod-build/` directory in the current directory (or uses the current
+directory itself if it is already named `pod-build`), populated with a default
+`Dockerfile`, `config.toml`, `on_build.bash`, and `home-dir/`.
+
+```sh
+pod init                      # create pod-build/ (fails if it already exists)
+pod init --force              # overwrite an existing pod-build/
+pod init --update Dockerfile  # refresh only one file, keeping local changes
+```
+
+#### `pod build`
+
+Builds the Podman image from the `pod-build/` directory.
+Must be run from inside `pod-build/` (or a directory that contains it).
+
+```sh
+pod build
+```
+
+The image is tagged `<prefix>:latest` (lower-cased), e.g. `pod:latest`.
+
+#### `pod test`
+
+Starts the dedicated test container (`<prefix>-test-0.0`) and attaches to it
+interactively. Use this to verify that a freshly built image behaves correctly
+before deploying it to students. The container is created if it does not exist.
+
+```sh
+pod test
+```
+
+#### `pod go <name>`
+
+Attaches to a container, creating or restarting it as needed.
+
+```sh
+pod go GROUP-1.0
+```
+
+The host port is derived deterministically from the container name, so the
+same container always gets the same port across restarts.
+
+#### `pod list`
+
+Lists all containers belonging to this project (filtered by prefix).
+
+```sh
+pod list
+```
+
+#### `pod info <name>`
+
+Prints the state and port-forwarding details of a container.
+
+```sh
+pod info GROUP-1.0
+```
+
+#### `pod rm <name>`
+
+Removes a container permanently.
+
+```sh
+pod rm GROUP-1.0           # fails if the container is still running
+pod rm GROUP-1.0 --force   # stops and removes unconditionally
+```
+
+> **Note:** due to a limitation in python-fire, `--force` must come *after*
+> the container name.
+
+#### `pod purge <regex>`
+
+Removes all containers whose full name matches `regex`
+(matched with `re.fullmatch`, i.e. the pattern must cover the entire name
+including the prefix).
+
+```sh
+pod purge 'POD-GROUP-1.*'           # remove all versions for GROUP-1
+pod purge 'POD-GROUP-1.*' --force   # also remove running containers
+```
+
+#### `pod purge-all`
+
+Removes every container belonging to this project, including the test container.
+
+```sh
+pod purge-all
+pod purge-all --force
+```
+
+

podman_spawner-0.1.0/README.md

@@ -0,0 +1,178 @@
+# Podman Spawner — a Podman interface for container management
+
+`podman-spawner` automates the creation and lifecycle management of [Podman](https://podman.io/)
+containers, easing the creation of temporary podman images.
+
+It was originally developed to review students projects, enabling to create containers on the fly for each student group
+and submission version.
+
+## Table of contents
+
+- [Prerequisites](#prerequisites)
+- [Using `pod`](#using-pod)
+
+---
+
+## Prerequisites
+
+`pod` is a thin wrapper around Podman (a rootless Docker alternative).
+Install it before anything else:
+
+```sh
+sudo apt install podman containers-storage
+```
+
+`containers-storage` is not strictly required, but it switches the storage
+driver from `vfs` to `overlay`, which makes image builds significantly faster.
+Verify it worked:
+
+```sh
+podman info | grep graphDriverName   # should print: overlay
+```
+
+To pull images from Docker Hub, register it as an unqualified search registry:
+
+```sh
+mkdir -p ~/.config/containers/
+echo 'unqualified-search-registries = ["docker.io"]' >> ~/.config/containers/registries.conf
+```
+
+For a small Podman introduction, see [podman-intro.md](podman-intro.md).
+
+---
+
+## Using `pod`
+
+### Installation
+
+Install [uv](https://docs.astral.sh/uv/) if you do not have it already:
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then, from the root of the `pod` repository:
+
+```sh
+uv tool install -e .
+```
+
+The `pod` command is now available for the current user.
+
+### Configuration
+
+Every `pod` command reads `config.toml` from the **current working directory**.
+A default file is created by `pod init` (see below); its keys are:
+
+| Key      | Default  | Description                                          |
+|----------|----------|------------------------------------------------------|
+| `prefix` | `POD`    | Prefix prepended to every container name.            |
+| `port`   | `2026`   | Guest port exposed by the container.                 |
+| `user`   | `tester` | Username created inside the container at build time. |
+
+### Workflow overview
+
+```
+pod init        # create the pod-build/ scaffold
+  ↓ (edit Dockerfile, home-dir/, on_build.bash as needed)
+pod build       # build the Podman image
+pod test        # smoke-test the image interactively
+  ↓
+pod go <name>   # open a container for a group / version
+```
+
+### Commands
+
+#### `pod init`
+
+Creates a `pod-build/` directory in the current directory (or uses the current
+directory itself if it is already named `pod-build`), populated with a default
+`Dockerfile`, `config.toml`, `on_build.bash`, and `home-dir/`.
+
+```sh
+pod init                      # create pod-build/ (fails if it already exists)
+pod init --force              # overwrite an existing pod-build/
+pod init --update Dockerfile  # refresh only one file, keeping local changes
+```
+
+#### `pod build`
+
+Builds the Podman image from the `pod-build/` directory.
+Must be run from inside `pod-build/` (or a directory that contains it).
+
+```sh
+pod build
+```
+
+The image is tagged `<prefix>:latest` (lower-cased), e.g. `pod:latest`.
+
+#### `pod test`
+
+Starts the dedicated test container (`<prefix>-test-0.0`) and attaches to it
+interactively. Use this to verify that a freshly built image behaves correctly
+before deploying it to students. The container is created if it does not exist.
+
+```sh
+pod test
+```
+
+#### `pod go <name>`
+
+Attaches to a container, creating or restarting it as needed.
+
+```sh
+pod go GROUP-1.0
+```
+
+The host port is derived deterministically from the container name, so the
+same container always gets the same port across restarts.
+
+#### `pod list`
+
+Lists all containers belonging to this project (filtered by prefix).
+
+```sh
+pod list
+```
+
+#### `pod info <name>`
+
+Prints the state and port-forwarding details of a container.
+
+```sh
+pod info GROUP-1.0
+```
+
+#### `pod rm <name>`
+
+Removes a container permanently.
+
+```sh
+pod rm GROUP-1.0           # fails if the container is still running
+pod rm GROUP-1.0 --force   # stops and removes unconditionally
+```
+
+> **Note:** due to a limitation in python-fire, `--force` must come *after*
+> the container name.
+
+#### `pod purge <regex>`
+
+Removes all containers whose full name matches `regex`
+(matched with `re.fullmatch`, i.e. the pattern must cover the entire name
+including the prefix).
+
+```sh
+pod purge 'POD-GROUP-1.*'           # remove all versions for GROUP-1
+pod purge 'POD-GROUP-1.*' --force   # also remove running containers
+```
+
+#### `pod purge-all`
+
+Removes every container belonging to this project, including the test container.
+
+```sh
+pod purge-all
+pod purge-all --force
+```
+
+

podman_spawner-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "podman-spawner"
+version = "0.1.0"
+description = "a Podman interface for container management"
+authors = [{ name = "Nicolas Pourcelot", email = "nicolas.pourcelot@gmail.com" }]
+keywords = ["podman", "containers", "docker"]
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Education :: Testing",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "colored-messages>=0.1.0",
+    "fire >= 0.6.0",
+]
+
+[project.urls]
+Repository = "https://github.com/wxgeo/podman-spawner"
+
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "python-semantic-release>=10.5.3",
+    "ruff>=0.15.15",
+]
+
+[project.scripts]
+pod = 'podman_spawner.cli:main'
+
+[build-system]
+requires = ["uv_build>=0.9.6,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "podman_spawner"
+
+[tool.semantic_release]
+major_on_zero = false

podman_spawner-0.1.0/src/podman_spawner/assets/defaults/pod-build/Dockerfile

@@ -0,0 +1,44 @@
+# L'image de base. C'est une version très allégée de Debian.
+FROM bitnami/minideb:trixie
+
+ENV LANG='en_US.UTF-8' LANGUAGE='en_US:en' LC_ALL='en_US.UTF-8'
+# Installation des dépendences.
+# Par défaut, il n'y a pas de navigateur, on installe donc Firefox.
+# Ne pas installer la version de base de firefox (qui utilise snap !)
+RUN apt update; apt upgrade -y
+RUN install_packages openjdk-21-jre openjdk-21-jdk junit5 firefox-esr ipython3 \
+    bash-completion command-not-found python3 git tree locales nano passwd sudo \
+    xdg-utils git-delta curl
+RUN apt update; apt upgrade -y
+RUN echo "LC_ALL=en_US.UTF-8" >> /etc/environment && \
+    echo "en_US.UTF-8 UTF-8" >> /etc/locale.gen && \
+    echo "LANG=en_US.UTF-8" > /etc/locale.conf && \
+    locale-gen en_US.UTF-8
+
+# Ajout de Junit 5
+# ADD https://repo1.maven.org/maven2/org/junit/platform/junit-platform-console-standalone/1.13.1/junit-platform-console-standalone-1.13.1.jar /root/junit
+
+
+# Installation de uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Utilisateur par défaut
+ARG USER=tester
+# Regex check: Allow only alphanumeric characters and underscores
+RUN echo "$USER" | grep -qE '^[a-zA-Z_][a-zA-Z0-9_]*$' || \
+    (echo "ERROR: Invalid username format detected! ($USER)" && exit 1)
+# Create the user and add to the sudo group
+RUN useradd -m -s /bin/bash "$USER" && usermod -aG sudo "$USER"
+# Allow the user to run sudo without a password
+RUN echo "$USER ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+
+USER $USER
+WORKDIR /home/$USER
+
+# Copy defaults user's home files.
+COPY "home-dir/" "/home/$USER"
+RUN ls -a "/home/$USER" && bash "/home/$USER/.on_build.bash"
+
+
+
+

podman_spawner-0.1.0/src/podman_spawner/assets/defaults/pod-build/config.toml

@@ -0,0 +1,3 @@
+prefix = "POD"
+port = 2026
+user = "tester"

podman_spawner-0.1.0/src/podman_spawner/assets/defaults/pod-build/home-dir/.bashrc

@@ -0,0 +1,29 @@
+# ~/.bashrc: executed by bash(1) for non-login shells.
+
+# Note: PS1 and umask are already set in /etc/profile. You should not
+# need this unless you want different defaults for root.
+# PS1='${debian_chroot:+($debian_chroot)}\h:\w\$ '
+# umask 022
+
+# You may uncomment the following lines if you want `ls' to be colorized:
+export LS_OPTIONS='--color=auto'
+# eval "$(dircolors)"
+# alias ls='ls $LS_OPTIONS'
+# alias ll='ls $LS_OPTIONS -l'
+# alias l='ls $LS_OPTIONS -lA'
+#
+# Some more alias to avoid making mistakes:
+# alias rm='rm -i'
+# alias cp='cp -i'
+# alias mv='mv -i'
+# Some color, please! :)
+export PS1='\[\e[1;36m\]\H\[\e[0;36m\]:\w # \[\e[0m\]'
+# set PATH so it includes user's private bin if it exists
+if [ -d "$HOME/bin" ] ; then
+    PATH="$HOME/bin:$PATH"
+    for d in "$HOME/bin"/*/; do PATH="$d:$PATH"; done
+fi
+# set PATH so it includes user's private bin if it exists
+if [ -d "$HOME/.local/bin" ] ; then
+    PATH="$HOME/.local/bin:$PATH"
+fi

podman_spawner-0.1.0/src/podman_spawner/assets/defaults/pod-build/home-dir/.on_build.bash

@@ -0,0 +1,2 @@
+#!/bin/bash
+# Actions to execute at the end of the build process.

podman_spawner-0.1.0/src/podman_spawner/cli.py

@@ -0,0 +1,324 @@
+import re
+import shutil
+import sys
+from pathlib import Path
+
+import fire  # type: ignore
+from colored_messages import print_error, print_info, print_success, print_warning
+
+from podman_spawner.config import (
+    ASSETS_DIR,
+    POD_BUILD_DIRNAME,
+    TEST,
+)
+from podman_spawner.port import port_from_name
+from podman_spawner.tools import (
+    State,
+    config,
+    containers_states,
+    get_state,
+    podman,
+)
+
+
+# pod info
+def info(name: str) -> None:
+    """Print state and port-forwarding information for a container."""
+    print("Container name:", name)
+    print("State:", get_state(name).name)
+    print("Port forwarding:")
+    podman("port", name)
+
+
+# pod list
+def list_containers() -> None:
+    """List all containers whose name starts with the configured prefix."""
+    podman(
+        "ps",
+        "-a",
+        "--format",
+        "table {{.Names}}\t{{.Status}}\t{{.Ports}}",
+        "--filter",
+        f"name=^{config().prefix}",
+    )
+
+
+def initialize_directory(force: bool = False, update: str | Path | None = None) -> None:
+    """Initialize (or update) the pod-build directory.
+
+    Without ``--update``, copies the full default skeleton into the target
+    directory.  If the current working directory is named ``pod-build`` it is
+    used directly; otherwise a ``pod-build/`` subdirectory is created.  The
+    operation is refused if the target already exists and is non-empty, unless
+    ``--force`` is passed.
+
+    With ``--update <path>``, only the single file or subdirectory at
+    ``<path>`` (relative to the skeleton root) is refreshed, leaving the rest
+    of the directory untouched.  This is useful for pulling in an updated
+    ``Dockerfile`` or ``home-dir/`` without clobbering local changes.
+    """
+    cwd = Path.cwd()
+    dst = cwd if cwd.name == POD_BUILD_DIRNAME else cwd / POD_BUILD_DIRNAME
+    dst = Path(dst).absolute()
+    if update is None:
+        # If the directory exists and is not empty, it should not be overwritten, unless `force` is set to True.
+        if dst.exists() and any(dst.iterdir()) and not force:
+            print_error(f"Path already exists: '{dst}'.")
+            print_info("Use `pod init --force` to overwrite it.")
+            sys.exit(1)
+        shutil.copytree(ASSETS_DIR / "defaults/pod-build", dst, dirs_exist_ok=True)
+        print_success(f"The directory `{dst.name}` was successfully initialized.")
+    else:
+        src = ASSETS_DIR / "defaults/pod-build" / update
+        if not src.exists():
+            print_error(f"Path does not exist: '{src}'.")
+            sys.exit(1)
+        dst = dst / update
+        if src.is_dir():
+            shutil.copytree(src, dst, dirs_exist_ok=True)
+        elif src.is_file():
+            shutil.copy(src, dst)
+        print_success(f"File or directory updated: `{dst.name}`.")
+
+
+# pod build
+def build_image() -> None:
+    """Build the Podman image from the current pod-build directory.
+
+    The current working directory must look like a valid build context:
+    it must contain an ``on_build.bash`` file and a ``home-dir/``
+    subdirectory.  Use ``pod init`` to create a conforming directory first.
+
+    The username baked into the image is taken from ``config.toml``
+    (``user`` key) and must match ``^[a-zA-Z_][a-zA-Z0-9_]*$``.
+    """
+    cwd = Path.cwd()
+    invalid_dir = False
+    # Test that the current directory looks like a correct build context.
+    if not (script := cwd / "on_build.bash").is_file():
+        invalid_dir = True
+        print_error(f"File not found: '{script}'.")
+    if not (home_dir := cwd / "home-dir").is_dir():
+        print_error(f"Directory not found: '{home_dir}'.")
+    if invalid_dir:
+        print_info("Hint: use `pod init` to initialize a pod directory.")
+        sys.exit(1)
+    user = config().user
+    if not re.fullmatch("^[a-zA-Z_][a-zA-Z0-9_]*$", user):
+        print_error(f"Invalid user name: {user!r}.")
+        sys.exit(1)
+    image_name = config().image_name
+    podman_args = [
+        "build",
+        "-t",
+        image_name,
+        "--build-arg",
+        f"USER={user}",
+        str(cwd),
+    ]
+    if podman(*podman_args):
+        print_success(f"Image {image_name} built.")
+    else:
+        print_error("Build process failed. (See details above).")
+
+
+def _run_container(name: str, host_port: int) -> bool:
+    """Ensure the named container is running, creating it if necessary.
+
+    Behaviour by current container state:
+
+    - **UP** — nothing to do, returns ``True`` immediately.
+    - **EXITED / CREATED** — attempts ``podman start``.  If that fails (e.g.
+      the port stored in the container's config is already in use), the stale
+      container is removed and the function recurses once to recreate it via
+      the NOT_FOUND branch.
+    - **NOT_FOUND** — creates a new detached container with ``podman run``,
+      forwarding ``host_port`` on the host to the guest port defined in
+      ``config.toml``.
+
+    Returns ``True`` on success, ``False`` if the underlying podman command
+    failed.
+    """
+    guest_port = config().port
+    match get_state(name):
+        case State.UP:
+            return True
+        case State.EXITED | State.CREATED:
+            if podman("start", name):
+                return True
+            print_warning(
+                f"Could not restart {name!r}; recreating with current port mapping."
+            )
+            podman("rm", "-f", name)
+            return _run_container(name, host_port)
+        case State.NOT_FOUND:
+            print(f"Port forwarding: {host_port}->{guest_port}")
+            return podman(
+                "run",
+                "-d",
+                "-t",
+                "--name",
+                name,
+                "--env=DISPLAY",
+                "-v",
+                "/tmp/.X11-unix:/tmp/.X11-unix",
+                "--hostname",
+                name,
+                "--env",
+                "TERM=xterm-256color",
+                "--publish",
+                f"{host_port}:{guest_port}",
+                config().image_name,
+            )
+        case _:
+            raise NotImplementedError
+
+
+def run_container(
+        name: str,
+        host_port: int | None = None,
+        copy: str | Path | None = None,
+        script: str | Path | None = None,
+) -> None:
+    """Start a container, optionally copying files or running a script inside it.
+
+    If the container does not exist it is created.  If it already exists but
+    is stopped it is restarted (with automatic recreation if the port binding
+    is stale — see :func:`_run_container`).
+
+    Args:
+        name: Container name.
+        host_port: Port to forward on the host side.  Derived deterministically
+            from ``name`` via :func:`port_from_name` when omitted.
+        copy: Local directory whose *contents* are copied into the container's
+            home directory (equivalent to ``podman cp <copy>/. <name>:<home>``).
+        script: Local script file to copy into the container's home directory
+            and execute there in a detached bash session.
+    """
+    if host_port is None:
+        host_port = port_from_name(name)
+    _run_container(name, host_port)
+    home = Path(f"/home/{config().user}/")
+    if copy is not None:
+        # Docker documentation specifies to add "/." at the end of the source
+        # path, so as to copy the folder content (and not the folder itself).
+        podman("cp", f"{copy}/.", f"{name}:{home}")
+    if script is not None:
+        script = Path(script)
+        podman("cp", f"{script}", f"{name}:{home / script.name}")
+        podman(
+            "exec",
+            "-d",
+            name,
+            "bash",
+            f"{home / script.name}",
+        )
+
+
+# pod test
+def test_image() -> None:
+    """Start and attach to the ephemeral test container.
+
+    The test container is named ``<prefix>-<TEST>`` (e.g. ``POD-test-0.0``).
+    It is created from the current image if it does not exist yet.  Use this
+    command to verify that a freshly built image behaves as expected before
+    deploying containers to students.
+    """
+    attach_container(f"{config().prefix}-{TEST}")
+
+
+# pod go
+def attach_container(name: str) -> None:
+    """Attach to a container, starting or creating it first if needed.
+
+    Delegates start/create logic to :func:`_run_container` so that stale port
+    bindings are handled consistently: if ``podman start`` fails the container
+    is automatically recreated with the current port mapping.
+    """
+    _run_container(name, port_from_name(name))
+    podman("attach", name)
+
+
+# pod rm
+def remove_container(name: str, force: bool = False) -> bool:
+    """Remove a container permanently.
+
+    Pass ``--force`` to remove a running container without stopping it first.
+    Note: due to a limitation in python-fire, ``--force`` must come *after*
+    the container name on the command line.
+    """
+    if not isinstance(force, bool):
+        print_error(f"Invalid argument for --force: {force!r}.")
+        sys.exit(1)
+    if force:
+        return podman("rm", "-f", name)
+    else:
+        return podman("rm", name)
+
+
+# pod purge
+def purge_containers(regex: str, force: bool = False) -> None:
+    """Remove all containers whose full name matches ``regex``.
+
+    The regex is matched against the complete container name (including the
+    configured prefix), using :func:`re.fullmatch`.  Running containers are
+    flagged with a warning; pass ``--force`` to remove them without stopping
+    first.
+    """
+    print("Removing containers:")
+    count = 0
+    for name in containers_states():
+        assert name.startswith(config().prefix)
+        if re.fullmatch(regex, name):
+            count += 1
+            if get_state(name) == State.UP:
+                print_warning(
+                    f"Container {name} is still running. Use pod go {name} to show it."
+                )
+            remove_container(name, force=force)
+    if count == 0:
+        print_warning(f"No matching container found for '{regex}'.")
+
+
+# pod purge-all
+def purge_all_containers(force: bool = False) -> None:
+    """Remove all containers, including the test container.
+
+    Running containers are flagged with a warning; pass ``--force`` to remove
+    them without stopping first.
+    """
+    print("Removing containers:")
+    prefix = config().prefix
+    name = f"{prefix}-{TEST}"
+    if get_state(name) != State.NOT_FOUND:
+        remove_container(name, force=force)
+    containers = containers_states()
+    for name, state in containers.items():
+        assert name.startswith(prefix)
+        if state == State.UP:
+            print_warning(
+                f"Container {name} is still running. Use `pod go {name}` to show it."
+            )
+        remove_container(name, force=force)
+    if len(containers) == 0:
+        print_warning("No container found.")
+
+
+def main() -> None:
+    fire.Fire(
+        {
+            "init": initialize_directory,
+            "build": build_image,
+            "test": test_image,
+            "go": attach_container,
+            "rm": remove_container,
+            "purge": purge_containers,
+            "purge-all": purge_all_containers,
+            "info": info,
+            "list": list_containers,
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

podman_spawner-0.1.0/src/podman_spawner/config.py

@@ -0,0 +1,20 @@
+"""Package-level constants and paths.
+
+These are static values baked in at install time.  Runtime configuration
+(prefix, port, user) lives in ``config.toml`` and is accessed via
+:func:`pod.tools.config`.
+"""
+
+from pathlib import Path
+
+# Name shown in pod test containers and used as the TEST suffix.
+TEST = "test-0.0"
+
+# Absolute path to the installed package directory.
+POD_DIR = Path(__file__).parent
+
+# Absolute path to the bundled asset tree (Dockerfile skeleton, etc.).
+ASSETS_DIR = POD_DIR / "assets"
+
+# Expected name of the pod build context directory.
+POD_BUILD_DIRNAME = "pod-build"

podman_spawner-0.1.0/src/podman_spawner/port.py

@@ -0,0 +1,52 @@
+"""Deterministic port allocation.
+
+Derives a stable host port from a container name so that the same container
+always gets the same port across restarts, while avoiding collisions with
+ports already in use on the host.
+"""
+
+import hashlib
+import socket
+
+
+def port_from_name(name: str, start: int = 1024, end: int = 65535) -> int:
+    """Derive a free host port from ``name``.
+
+    Uses SHA-256 to map ``name`` to a deterministic starting point in
+    ``[start, end)``, then scans forward (wrapping around) until a port that
+    is free on both TCP and UDP is found.
+
+    The determinism guarantee means the same container name always resolves to
+    the same base port, making port assignments stable and predictable for
+    operators and students alike.
+
+    Raises:
+        RuntimeError: If every port in the range is occupied.
+    """
+    hash_int = int(hashlib.sha256(name.encode()).hexdigest(), 16)
+    base_port = start + (hash_int % (end - start) if end - start else 0)
+
+    for offset in range(end - start):
+        port = start + (base_port - start + offset) % (end - start)
+        if _is_port_free(port):
+            return port
+
+    raise RuntimeError("No free port found in range")
+
+
+def _is_port_free(port: int) -> bool:
+    """Return ``True`` if ``port`` is available on both TCP and UDP."""
+    for kind in (socket.SOCK_STREAM, socket.SOCK_DGRAM):
+        with socket.socket(socket.AF_INET, kind) as s:
+            s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                s.bind(("", port))
+            except OSError:
+                return False
+    return True
+
+
+if __name__ == "__main__":
+    for _name in ("my-service", "postgres", "redis"):
+        _port = port_from_name(_name)
+        print(f"{_name!r:20} → port {_port}")

podman_spawner-0.1.0/src/podman_spawner/tools.py

@@ -0,0 +1,135 @@
+import json
+import sys
+import tomllib
+from dataclasses import dataclass, fields
+from enum import Enum
+from functools import cache
+from subprocess import run
+from typing import Any
+
+from colored_messages import print_error, print_info
+
+
+class State(Enum):
+    """Lifecycle state of a Podman container.
+
+    Mirrors the subset of states returned by ``podman ps --format json``:
+
+    - ``UP``        — container is running.
+    - ``CREATED``   — container was created but never started.
+    - ``EXITED``    — container ran and has stopped.
+    - ``NOT_FOUND`` — no container with that name exists (local addition,
+                      not a Podman state).
+    """
+
+    UP = 0
+    CREATED = 2
+    EXITED = 3
+    NOT_FOUND = 4
+
+
+# Maps the lowercase state strings from `podman ps --format json` to State.
+_PODMAN_STATE_MAP: dict[str, State] = {
+    "running": State.UP,
+    "created": State.CREATED,
+    "exited": State.EXITED,
+}
+
+
+@dataclass
+class Config:
+    """Runtime configuration loaded from ``config.toml``.
+
+    Attributes:
+        prefix: Prefix prepended to every container name (e.g. ``"POD"``).
+        port:   Guest port exposed by every container.
+        user:   Username created inside the container at build time.
+    """
+
+    prefix: str
+    port: int
+    user: str
+
+    @property
+    def image_name(self) -> str:
+        """Fully-qualified image tag used by ``podman build`` and ``podman run``."""
+        return f"{self.prefix}:latest".lower()
+
+
+@cache
+def config() -> Config:
+    """Load and return the project configuration.
+
+    Reads ``config.toml`` from the *current working directory* and returns a
+    :class:`Config` instance.  The result is cached so the file is read only
+    once per process; run ``pod`` from the directory that contains
+    ``config.toml``.
+    """
+    try:
+        with open("config.toml", "rb") as f:
+            data = tomllib.load(f)
+    except FileNotFoundError:
+        print_error("File `config.toml` was not found")
+        print_info("Hint: use `pod init` to initialize a pod directory.")
+        sys.exit(1)
+    try:
+        config_ = Config(**data)
+    except TypeError:
+        # Compare data keys and Config fields, to report a useful message.
+        expected = {f.name for f in fields(Config)}
+        actual = set(data.keys())
+        missing = expected - actual
+        unexpected = actual - expected
+        if missing:
+            print_error(f"Missing keys in `config.toml`: {', '.join(sorted(missing))}")
+        if unexpected:
+            print_error(
+                f"Unknown keys in `config.toml`: {', '.join(sorted(unexpected))}"
+            )
+        sys.exit(1)
+    return config_
+
+
+def containers_states() -> dict[str, State]:
+    """Return the state of every container whose name matches the configured prefix.
+
+    Calls ``podman ps -a --format json`` and filters by :attr:`Config.prefix`.
+    Containers not belonging to this project are ignored.
+
+    Raises:
+        NotImplementedError: If Podman reports a state string not present in
+            ``_PODMAN_STATE_MAP`` (i.e. a state this code does not yet handle).
+    """
+    completed_process = run(
+        ["podman", "ps", "-a", "--format", "json"],
+        encoding="utf8",
+        capture_output=True,
+    )
+    entries = json.loads(completed_process.stdout or "[]")
+    prefix = config().prefix
+    result = {}
+    for entry in entries:
+        names = entry.get("Names") or []
+        raw_state = entry.get("State", "").lower()
+        state = _PODMAN_STATE_MAP.get(raw_state)
+        if state is None:
+            raise NotImplementedError(f"Unrecognised container state: {raw_state!r}")
+        for name in names:
+            if name.startswith(prefix):
+                result[name] = state
+    return result
+
+
+def get_state(name: str) -> State:
+    """Return the :class:`State` of a single container.
+
+    Returns ``State.NOT_FOUND`` if no container with that name exists,
+    rather than raising an exception.
+    """
+    return containers_states().get(name, State.NOT_FOUND)
+
+
+def podman(*args: str, **kw: Any) -> bool:
+    """Run a podman command and return ``True`` on success, ``False`` otherwise."""
+    print(" ".join(["podman", *args]))
+    return run(["podman", *args], **kw).returncode == 0