Add local dev environment setup (#331)

* Add local dev environment setup options

Add support for uv and pip installation methods as alternatives to
Conda/Docker. Update pyproject.toml with proper project metadata and
structured development dependencies.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update README.md

* Ignore UP038 rule in Ruff linter configuration

The rule is deprecated, but somewhat enforced in Python >=3.10

* Remove tutorial tests from docker build triggers

* Remove unneeded per-file ignore

* Update IPython auto-imports for modern typing practices

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: edoardob90

.github/workflows/docker-build.yml

@@ -10,7 +10,6 @@ on:
       - "docker/**"
       - "binder/**"
       - "**/environment.yml"
-      - "tutorial/tests/testsuite/**"
       - ".github/workflows/docker-build.yml"
     tags:
       - "v*.*"
@@ -21,7 +20,6 @@ on:
       - "docker/**"
       - "binder/**"
       - "**/environment.yml"
-      - "tutorial/tests/testsuite/**"
       - ".github/workflows/docker-build.yml"
   workflow_dispatch:
 

.gitignore

@@ -80,6 +80,9 @@ target/
 # IPython
 profile_default/
 
+# uv
+uv.lock
+
 # pyenv
 .python-version
 

README.md

@@ -127,3 +127,56 @@ You can now use the Jupyter in the Docker container to run the python-tutorial.
 > [!NOTE]
 >
 > If you want to restart the container, you can simply run the command `docker container start python_tutorial`.
+
+## Setup a local dev environment
+
+If you prefer not to use Conda and/or Docker, you can set up a *lightweight* development environment using either "uv" (a faster alternative to pip) or traditional "pip". Both methods will install the development dependencies specified in the `pyproject.toml` file.
+
+Both setups assume that you have already cloned the repository with `git clone https://github.com/empa-scientific-it/python-tutorial`. The commands below should be run from inside the tutorial directory.
+
+### Using `uv` (Recommended for speed)
+
+[uv](https://github.com/astral-sh/uv) is a fast, Python package installer and resolver written in Rust.
+
+1. Install uv via `pip` or [any other method](https://docs.astral.sh/uv/getting-started/installation/):
+   ```console
+   pip install uv
+   ```
+
+2. Create a virtual environment and install dev dependencies:
+   ```console
+   # Create and activate a virtual environment
+   uv venv
+   # On Windows
+   .venv\Scripts\activate
+   # On macOS/Linux
+   source .venv/bin/activate
+
+   # Install dev dependencies
+   uv pip install -e ".[dev]"
+   ```
+
+3. Launch JupyterLab:
+   ```console
+   jupyter lab
+   ```
+
+### Using `pip`
+
+1. Create a virtual environment and install dev dependencies:
+   ```console
+   # Create and activate a virtual environment
+   python -m venv .venv
+   # On Windows
+   .venv\Scripts\activate
+   # On macOS/Linux
+   source .venv/bin/activate
+
+   # Install dev dependencies
+   pip install -e ".[dev]"
+   ```
+
+2. Launch JupyterLab:
+   ```console
+   jupyter lab
+   ```

docker/ipython_config.py

@@ -6,5 +6,6 @@
 
 # Automatically import some modules
 c.InteractiveShellApp.exec_lines = [
-    "from typing import Any, Callable, Dict, List, Optional, Tuple, Union"
+    "from typing import Any, ClassVar",
+    "from collections.abc import List, Tuple, Callable, Dict",
 ]

pyproject.toml

@@ -1,7 +1,38 @@
 [project]
 name = "python-tutorial"
+version = "v2025.05"
+description = "Jupyter-based Python programming tutorial"
 requires-python = ">=3.10"
 
+[project.optional-dependencies]
+dev = [
+  "numpy",
+  "matplotlib",
+  "pandas",
+  "ipywidgets",
+  "ipynbname",
+  "jupyterlab",
+  "pytest",
+  "pytest-timeout",
+  "markdown",
+  "pre-commit",
+  "geostatspy",
+  "gstools",
+  "scikit-learn",
+  "attrs",
+  "multiprocess",
+  "openai",
+  "tenacity",
+  "markdown2",
+  "python-dotenv",
+  "pillow",
+  "opencv-python",
+  "albumentations",
+  "grad-cam",
+  "plotly",
+  "torch==2.7.0",  # pinned to last stable version as of 2025-05-14
+]
+
 # pytest
 [tool.pytest.ini_options]
 addopts = "-v --tb=short"
@@ -58,3 +89,7 @@ select = [
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
+
+# Setuptools: suppress package discovery
+[tool.setuptools]
+packages = []