course-setup 3.0.14__tar.gz → 3.2.0__tar.gz

{course_setup-3.0.14 → course_setup-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: course-setup
-Version: 3.0.14
+Version: 3.2.0
 Summary: CLI tools for setting up and retiring GitHub-backed course repositories
 Author: Reuven Lerner
 Author-email: Reuven Lerner <reuven@lernerpython.com>
@@ -33,9 +33,9 @@ uv tool install course-setup
 ```
 
 This makes `setup-course`, `retire-course`, `unretire-course`,
-`archive-course`, and `setup-course-config` available on your PATH. All five
-commands support `--version` and `--help`, which display the version number,
-PyPI URL, author name (Reuven Lerner), and email. To upgrade:
+`archive-course`, `list-courses`, and `setup-course-config` available on your
+PATH. All six commands support `--version` and `--help`, which display the
+version number, PyPI URL, author name (Reuven Lerner), and email. To upgrade:
 
 ```bash
 uv tool upgrade course-setup
@@ -74,6 +74,7 @@ notebook_type = "jupyter"   # or "marimo"
 | `[paths] archive` | Yes | Directory where retired courses are archived. |
 | `[paths] readme_source` | No | Local path or URL to a custom README for new courses. Omit to use the bundled default. |
 | `[paths] additional_files` | No | List of file/directory paths to copy into every new course (e.g. data files, exercise notebooks). |
+| `[paths] course_dirs` | No | List of directories that `list-courses` scans for active courses (e.g. `["~/Courses/Current"]`). `~` is expanded. Overridden by `--dir` on the `list-courses` command line. |
 | `[defaults] notebook_type` | No | `"jupyter"` (default) or `"marimo"`. |
 | `[defaults] verbose` | No | `true` or `false` (default). Sets the default verbosity for `setup-course`. |
 | `[defaults] private` | No | `true` or `false` (default). When `true`, `setup-course` creates private GitHub repos by default. |
@@ -162,6 +163,7 @@ retire-course ./Acme-python-intro-2026-03
 |-----------------|-------------|
 | `DIRNAME...` | One or more course directories to retire |
 | `--keep-public` | Archive without making the GitHub repo private |
+| `--dry-run` | Preview the retirement without making any changes |
 
 This will (for each directory):
 
@@ -171,6 +173,13 @@ This will (for each directory):
 3. Print a retirement summary showing: notebook count, date range, dependencies,
    archive location, and GitHub URL
 
+With `--dry-run`, none of that happens: the GitHub repo is not touched, the
+archive directory is not created, and the course directory is not moved.
+Instead, `retire-course` prints a `[DRY RUN]` banner followed by the same
+retirement summary the real run would show. It reads your config file but makes
+no GitHub API calls, so a dry run touches nothing on the network. `--dry-run`
+applies to every directory passed on the command line.
+
 You can retire multiple courses at once:
 
 ```bash
@@ -193,14 +202,91 @@ archive-course ./Acme-python-intro-2026-03
 |------|-------------|
 | `--output`, `-o` | Custom output zip path (defaults to `{dirname}.zip`) |
 | `--no-html` | Skip HTML export of Jupyter notebooks |
+| `--no-pdf` | Skip PDF export of Jupyter notebooks |
 
 This archives **all files** in the course directory (`.py`, `.csv`, `.toml`,
 notebooks, etc.), excluding `.git`, `.venv`, `__pycache__`, and
 `.ipynb_checkpoints` directories. For Jupyter notebooks, each `.ipynb` is also
-exported to HTML via `nbconvert` and the `.html` is included alongside the
-original; use `--no-html` to skip the HTML export. After creating the archive,
-a summary is printed listing the archive path, file count, size, notebooks,
-and all other included files.
+exported to HTML and to PDF, and both are included alongside the original;
+use `--no-html` / `--no-pdf` to skip either export. PDF export is **on by
+default**, via `nbconvert --to webpdf` (headless Chromium — no LaTeX
+installation required). The first time you export to PDF, you may need to
+run `uv run playwright install chromium` inside the course directory to
+download the Chromium binary. If the PDF engine isn't available, `archive-course`
+prints a warning and skips PDF for that notebook rather than failing — the
+rest of the archive is still produced. After creating the archive, a summary
+is printed listing the archive path, file count, size, notebooks (shown as
+`notebook.ipynb + notebook.html + notebook.pdf`), export counts, and all
+other included files.
+
+### `list-courses` — List active and archived courses
+
+```bash
+list-courses
+```
+
+A read-only command: nothing is modified, and no GitHub API calls are made (it
+reads your config file but does not use the network).
+
+> **Breaking change (3.2.0):** the positional argument used to be a
+> scan-directory override (`list-courses ~/Other`). It is now a **name
+> filter** instead. To scan a different directory, use the repeatable
+> `--dir PATH` flag: `list-courses --dir ~/Other`.
+
+By default, `list-courses` prints the full list of **active courses** — a
+directory qualifies as a course if it has a `.git` subdirectory and at least
+one notebook (`.ipynb`, or a marimo `.py`) — followed by a one-line summary of
+the **archived courses** found under your configured `[paths] archive`
+directory (an archived course is any non-hidden, non-junk directory under a
+4-digit-year folder that contains at least one notebook):
+
+```
+Active courses:
+  Acme-python-intro-2026-03 — 5 notebooks (2026-03-17 → 2026-03-21)
+  Beta-pandas-2026-02 — 3 notebooks (2026-02-02 → 2026-02-16)
+
+Archived: 412 courses across 2018–2026 — use --archived to list them.
+```
+
+Each course line is shown as `name — N notebooks (first-date → last-date)`,
+with dates parsed from notebook filenames (`n/a` if none are found).
+
+| Argument / Option | Description |
+|----------|-------------|
+| `NAME...` | Filter courses by case-insensitive name substring. Multiple names match as OR. Narrows whatever is shown; does not by itself expand the archive. |
+| `--dir PATH` | Directory to scan for active courses (repeatable; replaces `course_dirs` from config for this run) |
+| `--active` | Show only the active-courses section |
+| `--archived` | Show only the archived-courses section, expanded and grouped by year |
+| `--year YYYY` | Restrict archived courses to a year (repeatable, 4-digit years only); implies `--archived` unless `--active` is also given, in which case `--year` is ignored |
+| `--count` | Print counts instead of course lines, honoring all other filters |
+| `--version` | Show the version number, PyPI URL, author name, and email |
+
+Directories to scan for active courses are resolved in this order:
+
+1. `--dir PATH` values passed on the command line (repeatable)
+2. Otherwise, `[paths] course_dirs` from your config file
+3. Otherwise, the current directory
+
+#### Examples
+
+| Command | Result |
+|---|---|
+| `list-courses` | active courses in full + `Archived: N courses across 2018–2026 — use --archived …` |
+| `list-courses --archived` | archive only, expanded and grouped by year |
+| `list-courses --active` | active courses only |
+| `list-courses cisco` | active courses matching "cisco" + a name-filtered archive summary line |
+| `list-courses cisco --archived` | archived courses matching "cisco" (all years, expanded) |
+| `list-courses --year 2024` | archive for 2024 only (active section suppressed) |
+| `list-courses --year 2024 --year 2025` | archive for 2024 and 2025 only |
+| `list-courses cisco --year 2024` | archived courses matching "cisco" from 2024 only |
+| `list-courses --active --year 2024` | active only (`--year` is ignored for active) |
+| `list-courses --count` | `Active courses: 3` + `Archived courses: 412` + per-year counts |
+| `list-courses cisco --count` | counts of active + archived courses matching "cisco" |
+| `list-courses --dir ~/Other` | scan `~/Other` for active courses instead of config `course_dirs` |
+
+If there are no matching active or archived courses, it prints an empty-state
+line (e.g. `No active courses found`, or `No active courses match: cisco` when
+a name filter excludes everything).
 
 ### `unretire-course` — Restore a retired course
 

{course_setup-3.0.14 → course_setup-3.2.0}/README.md

@@ -13,9 +13,9 @@ uv tool install course-setup
 ```
 
 This makes `setup-course`, `retire-course`, `unretire-course`,
-`archive-course`, and `setup-course-config` available on your PATH. All five
-commands support `--version` and `--help`, which display the version number,
-PyPI URL, author name (Reuven Lerner), and email. To upgrade:
+`archive-course`, `list-courses`, and `setup-course-config` available on your
+PATH. All six commands support `--version` and `--help`, which display the
+version number, PyPI URL, author name (Reuven Lerner), and email. To upgrade:
 
 ```bash
 uv tool upgrade course-setup
@@ -54,6 +54,7 @@ notebook_type = "jupyter"   # or "marimo"
 | `[paths] archive` | Yes | Directory where retired courses are archived. |
 | `[paths] readme_source` | No | Local path or URL to a custom README for new courses. Omit to use the bundled default. |
 | `[paths] additional_files` | No | List of file/directory paths to copy into every new course (e.g. data files, exercise notebooks). |
+| `[paths] course_dirs` | No | List of directories that `list-courses` scans for active courses (e.g. `["~/Courses/Current"]`). `~` is expanded. Overridden by `--dir` on the `list-courses` command line. |
 | `[defaults] notebook_type` | No | `"jupyter"` (default) or `"marimo"`. |
 | `[defaults] verbose` | No | `true` or `false` (default). Sets the default verbosity for `setup-course`. |
 | `[defaults] private` | No | `true` or `false` (default). When `true`, `setup-course` creates private GitHub repos by default. |
@@ -142,6 +143,7 @@ retire-course ./Acme-python-intro-2026-03
 |-----------------|-------------|
 | `DIRNAME...` | One or more course directories to retire |
 | `--keep-public` | Archive without making the GitHub repo private |
+| `--dry-run` | Preview the retirement without making any changes |
 
 This will (for each directory):
 
@@ -151,6 +153,13 @@ This will (for each directory):
 3. Print a retirement summary showing: notebook count, date range, dependencies,
    archive location, and GitHub URL
 
+With `--dry-run`, none of that happens: the GitHub repo is not touched, the
+archive directory is not created, and the course directory is not moved.
+Instead, `retire-course` prints a `[DRY RUN]` banner followed by the same
+retirement summary the real run would show. It reads your config file but makes
+no GitHub API calls, so a dry run touches nothing on the network. `--dry-run`
+applies to every directory passed on the command line.
+
 You can retire multiple courses at once:
 
 ```bash
@@ -173,14 +182,91 @@ archive-course ./Acme-python-intro-2026-03
 |------|-------------|
 | `--output`, `-o` | Custom output zip path (defaults to `{dirname}.zip`) |
 | `--no-html` | Skip HTML export of Jupyter notebooks |
+| `--no-pdf` | Skip PDF export of Jupyter notebooks |
 
 This archives **all files** in the course directory (`.py`, `.csv`, `.toml`,
 notebooks, etc.), excluding `.git`, `.venv`, `__pycache__`, and
 `.ipynb_checkpoints` directories. For Jupyter notebooks, each `.ipynb` is also
-exported to HTML via `nbconvert` and the `.html` is included alongside the
-original; use `--no-html` to skip the HTML export. After creating the archive,
-a summary is printed listing the archive path, file count, size, notebooks,
-and all other included files.
+exported to HTML and to PDF, and both are included alongside the original;
+use `--no-html` / `--no-pdf` to skip either export. PDF export is **on by
+default**, via `nbconvert --to webpdf` (headless Chromium — no LaTeX
+installation required). The first time you export to PDF, you may need to
+run `uv run playwright install chromium` inside the course directory to
+download the Chromium binary. If the PDF engine isn't available, `archive-course`
+prints a warning and skips PDF for that notebook rather than failing — the
+rest of the archive is still produced. After creating the archive, a summary
+is printed listing the archive path, file count, size, notebooks (shown as
+`notebook.ipynb + notebook.html + notebook.pdf`), export counts, and all
+other included files.
+
+### `list-courses` — List active and archived courses
+
+```bash
+list-courses
+```
+
+A read-only command: nothing is modified, and no GitHub API calls are made (it
+reads your config file but does not use the network).
+
+> **Breaking change (3.2.0):** the positional argument used to be a
+> scan-directory override (`list-courses ~/Other`). It is now a **name
+> filter** instead. To scan a different directory, use the repeatable
+> `--dir PATH` flag: `list-courses --dir ~/Other`.
+
+By default, `list-courses` prints the full list of **active courses** — a
+directory qualifies as a course if it has a `.git` subdirectory and at least
+one notebook (`.ipynb`, or a marimo `.py`) — followed by a one-line summary of
+the **archived courses** found under your configured `[paths] archive`
+directory (an archived course is any non-hidden, non-junk directory under a
+4-digit-year folder that contains at least one notebook):
+
+```
+Active courses:
+  Acme-python-intro-2026-03 — 5 notebooks (2026-03-17 → 2026-03-21)
+  Beta-pandas-2026-02 — 3 notebooks (2026-02-02 → 2026-02-16)
+
+Archived: 412 courses across 2018–2026 — use --archived to list them.
+```
+
+Each course line is shown as `name — N notebooks (first-date → last-date)`,
+with dates parsed from notebook filenames (`n/a` if none are found).
+
+| Argument / Option | Description |
+|----------|-------------|
+| `NAME...` | Filter courses by case-insensitive name substring. Multiple names match as OR. Narrows whatever is shown; does not by itself expand the archive. |
+| `--dir PATH` | Directory to scan for active courses (repeatable; replaces `course_dirs` from config for this run) |
+| `--active` | Show only the active-courses section |
+| `--archived` | Show only the archived-courses section, expanded and grouped by year |
+| `--year YYYY` | Restrict archived courses to a year (repeatable, 4-digit years only); implies `--archived` unless `--active` is also given, in which case `--year` is ignored |
+| `--count` | Print counts instead of course lines, honoring all other filters |
+| `--version` | Show the version number, PyPI URL, author name, and email |
+
+Directories to scan for active courses are resolved in this order:
+
+1. `--dir PATH` values passed on the command line (repeatable)
+2. Otherwise, `[paths] course_dirs` from your config file
+3. Otherwise, the current directory
+
+#### Examples
+
+| Command | Result |
+|---|---|
+| `list-courses` | active courses in full + `Archived: N courses across 2018–2026 — use --archived …` |
+| `list-courses --archived` | archive only, expanded and grouped by year |
+| `list-courses --active` | active courses only |
+| `list-courses cisco` | active courses matching "cisco" + a name-filtered archive summary line |
+| `list-courses cisco --archived` | archived courses matching "cisco" (all years, expanded) |
+| `list-courses --year 2024` | archive for 2024 only (active section suppressed) |
+| `list-courses --year 2024 --year 2025` | archive for 2024 and 2025 only |
+| `list-courses cisco --year 2024` | archived courses matching "cisco" from 2024 only |
+| `list-courses --active --year 2024` | active only (`--year` is ignored for active) |
+| `list-courses --count` | `Active courses: 3` + `Archived courses: 412` + per-year counts |
+| `list-courses cisco --count` | counts of active + archived courses matching "cisco" |
+| `list-courses --dir ~/Other` | scan `~/Other` for active courses instead of config `course_dirs` |
+
+If there are no matching active or archived courses, it prints an empty-state
+line (e.g. `No active courses found`, or `No active courses match: cisco` when
+a name filter excludes everything).
 
 ### `unretire-course` — Restore a retired course
 

{course_setup-3.0.14 → course_setup-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
     name = "course-setup"
-    version = "3.0.14"
+    version = "3.2.0"
     description = "CLI tools for setting up and retiring GitHub-backed course repositories"
     readme = "README.md"
     requires-python = ">=3.13"
@@ -31,6 +31,7 @@
     setup-course-config = "setup_course_github.init_config:main"
     unretire-course = "setup_course_github.unretire_course:main"
     archive-course = "setup_course_github.archive_course:main"
+    list-courses = "setup_course_github.list_courses:main"
 
 
 [build-system]

{course_setup-3.0.14 → course_setup-3.2.0}/src/setup_course_github/archive_course.py

@@ -8,14 +8,17 @@ from pathlib import Path
 from setup_course_github import __author__, __email__, __version__
 
 
-def _export_notebook_to_html(nb_path: Path, course_path: Path) -> bool:
-    """Export a single notebook to HTML. Returns True on success."""
+def _export_notebook(nb_path: Path, course_path: Path, fmt: str, label: str) -> bool:
+    """Export a notebook to *fmt* via nbconvert. Returns True on success.
+
+    *label* is the human-readable format name used in warning messages.
+    """
     # Use the notebook's relative path from the course dir so nbconvert
     # can find it regardless of spaces in the name.
     relative = nb_path.relative_to(course_path)
     try:
         subprocess.run(
-            ["uv", "run", "jupyter", "nbconvert", "--to", "html", str(relative)],
+            ["uv", "run", "jupyter", "nbconvert", "--to", fmt, str(relative)],
             cwd=str(course_path),
             capture_output=True,
             check=True,
@@ -23,21 +26,34 @@ def _export_notebook_to_html(nb_path: Path, course_path: Path) -> bool:
         return True
     except subprocess.CalledProcessError as exc:
         stderr = exc.stderr.decode() if exc.stderr else ""
-        print(f"  Warning: failed to export {nb_path.name}: {stderr.strip()}")
+        print(
+            f"  Warning: failed to export {nb_path.name} to {label}: {stderr.strip()}"
+        )
         return False
     except FileNotFoundError:
-        print("  Warning: jupyter nbconvert not found, skipping HTML export")
+        print(f"  Warning: jupyter nbconvert not found, skipping {label} export")
         return False
 
 
+def _export_notebook_to_html(nb_path: Path, course_path: Path) -> bool:
+    """Export a single notebook to HTML. Returns True on success."""
+    return _export_notebook(nb_path, course_path, "html", "HTML")
+
+
+def _export_notebook_to_pdf(nb_path: Path, course_path: Path) -> bool:
+    """Export a single notebook to PDF via webpdf. Returns True on success."""
+    return _export_notebook(nb_path, course_path, "webpdf", "PDF")
+
+
 def archive_course(
     dirname: str,
     output: str | None = None,
     export_html: bool = True,
+    export_pdf: bool = True,
 ) -> Path:
     """Create a zip archive of a course directory.
 
-    Optionally exports notebooks to HTML first.
+    Optionally exports notebooks to HTML and/or PDF first.
     """
     course_path = Path(dirname)
     if not course_path.is_dir():
@@ -58,6 +74,14 @@ def archive_course(
             if _export_notebook_to_html(nb_path, course_path):
                 html_exported += 1
 
+    # Export notebooks to PDF if requested
+    pdf_exported = 0
+    if export_pdf and notebooks:
+        print("Exporting notebooks to PDF...")
+        for nb_path in notebooks:
+            if _export_notebook_to_pdf(nb_path, course_path):
+                pdf_exported += 1
+
     # Determine output path
     if output is not None:
         zip_path = Path(output)
@@ -88,15 +112,17 @@ def archive_course(
         else f"{zip_size / (1024 * 1024):.1f} MB"
     )
 
-    # Collect non-notebook, non-HTML files for the summary
+    # Collect non-notebook, non-HTML, non-PDF files for the summary
     notebook_names = {nb.name for nb in notebooks}
     html_names = {nb.with_suffix(".html").name for nb in notebooks}
+    pdf_names = {nb.with_suffix(".pdf").name for nb in notebooks}
     with zipfile.ZipFile(zip_path, "r") as zf:
         other_files = sorted(
             Path(name).name
             for name in zf.namelist()
             if Path(name).name not in notebook_names
             and Path(name).name not in html_names
+            and Path(name).name not in pdf_names
         )
 
     # Print summary
@@ -107,13 +133,18 @@ def archive_course(
     if notebooks:
         print("Notebooks:")
         for nb in notebooks:
+            parts = [nb.name]
             html_path = nb.with_suffix(".html")
             if export_html and html_path.exists():
-                print(f"  {nb.name} + {html_path.name}")
-            else:
-                print(f"  {nb.name}")
+                parts.append(html_path.name)
+            pdf_path = nb.with_suffix(".pdf")
+            if export_pdf and pdf_path.exists():
+                parts.append(pdf_path.name)
+            print("  " + " + ".join(parts))
     if export_html and html_exported > 0:
         print(f"HTML exports: {html_exported}")
+    if export_pdf and pdf_exported > 0:
+        print(f"PDF exports: {pdf_exported}")
 
     if other_files:
         print("Other files:")
@@ -153,12 +184,19 @@ def main() -> None:
         default=False,
         help="Skip HTML export of notebooks",
     )
+    parser.add_argument(
+        "--no-pdf",
+        action="store_true",
+        default=False,
+        help="Skip PDF export of notebooks",
+    )
     args = parser.parse_args()
 
     archive_course(
         dirname=args.dirname,
         output=args.output,
         export_html=not args.no_html,
+        export_pdf=not args.no_pdf,
     )
 
 

{course_setup-3.0.14 → course_setup-3.2.0}/src/setup_course_github/config.py

@@ -27,6 +27,7 @@ class CourseConfig:
     custom_extras: dict[str, list[str]] = field(default_factory=dict)
     default_weekend: str | None = None
     additional_files: list[str] = field(default_factory=list)
+    course_dirs: list[str] = field(default_factory=list)
     default_private: bool = False
 
 
@@ -128,6 +129,12 @@ def load_config(path: Path = CONFIG_PATH) -> CourseConfig:
         raise ConfigError("additional_files must be a list of file/directory paths")
     additional_files: list[str] = [str(f) for f in raw_additional_files]
 
+    # Course directories: optional list of dirs scanned by `list-courses`
+    raw_course_dirs: object = paths_section.get("course_dirs", [])
+    if not isinstance(raw_course_dirs, list):
+        raise ConfigError("course_dirs must be a list of directory paths")
+    course_dirs: list[str] = [str(d) for d in raw_course_dirs]
+
     return CourseConfig(
         github_token=github_token,
         archive_path=archive_path,
@@ -139,4 +146,5 @@ def load_config(path: Path = CONFIG_PATH) -> CourseConfig:
         default_weekend=default_weekend,
         additional_files=additional_files,
         default_private=default_private,
+        course_dirs=course_dirs,
     )

{course_setup-3.0.14 → course_setup-3.2.0}/src/setup_course_github/init_config.py

@@ -31,6 +31,14 @@ archive = "/path/to/your/archive"
 # Examples: data files, exercise notebooks, solutions folder
 # additional_files = ["/path/to/exercises", "/path/to/data.csv"]
 
+# Optional: directories that `list-courses` scans for active courses.
+# Each entry is a directory whose immediate subdirectories may be courses
+# (a course = a subdir containing a .git folder and at least one notebook).
+# Examples:
+#   course_dirs = ["~/Courses/Current"]
+#   course_dirs = ["~/Courses/Current", "~/Courses/Consulting"]
+# course_dirs = []
+
 [defaults]
 # Default notebook type when running setup-course.
 # Options: "jupyter" or "marimo"

course_setup-3.2.0/src/setup_course_github/list_courses.py

@@ -0,0 +1,253 @@
+import argparse
+import re
+from pathlib import Path
+
+from setup_course_github import __author__, __email__, __version__
+from setup_course_github.config import CourseConfig, load_config
+from setup_course_github.notebooks import date_range, find_notebooks
+
+JUNK_NAMES = frozenset(
+    {"__pycache__", "build", "dist", "bin", "include", "lib", "node_modules"}
+)
+_YEAR_RE = re.compile(r"^\d{4}$")
+
+
+def _is_junk_name(name: str) -> bool:
+    """True for hidden (dot-prefixed) or known build/cache directory names."""
+    return name.startswith(".") or name in JUNK_NAMES
+
+
+def is_course(path: Path) -> bool:
+    """A course is a directory with a .git subdir and at least one notebook."""
+    if not (path / ".git").is_dir():
+        return False
+    ipynb_files, marimo_files = find_notebooks(path)
+    return bool(ipynb_files or marimo_files)
+
+
+def is_archived_course(path: Path) -> bool:
+    """An archived course: a non-junk directory containing at least one notebook.
+
+    Unlike active courses, a ``.git`` subdir is NOT required (archived repos may
+    have had it stripped).
+    """
+    if _is_junk_name(path.name):
+        return False
+    ipynb_files, marimo_files = find_notebooks(path)
+    return bool(ipynb_files or marimo_files)
+
+
+def course_summary_line(path: Path) -> str:
+    """Return '<name> — <N> notebooks (<date range>)' for a course directory."""
+    ipynb_files, marimo_files = find_notebooks(path)
+    count = len(ipynb_files) + len(marimo_files)
+    span = date_range(ipynb_files + marimo_files)
+    return f"{path.name} — {count} notebooks ({span})"
+
+
+def _matches_names(name: str, patterns: list[str]) -> bool:
+    """True if *name* (case-insensitively) contains any of *patterns*.
+
+    An empty *patterns* list matches everything.
+    """
+    if not patterns:
+        return True
+    lowered = name.lower()
+    return any(p.lower() in lowered for p in patterns)
+
+
+def filter_active(courses: list[Path], patterns: list[str]) -> list[Path]:
+    """Keep only active-course paths whose name matches *patterns*."""
+    return [c for c in courses if _matches_names(c.name, patterns)]
+
+
+def filter_archived(
+    archived: dict[str, list[Path]], years: list[str], patterns: list[str]
+) -> dict[str, list[Path]]:
+    """Filter the {year: courses} map by *years* (if non-empty) and *patterns*.
+
+    Years not in *years* are dropped; within a kept year, courses are filtered by
+    name; years left with no matching courses are omitted.
+    """
+    result: dict[str, list[Path]] = {}
+    for year, courses in archived.items():
+        if years and year not in years:
+            continue
+        matched = [c for c in courses if _matches_names(c.name, patterns)]
+        if matched:
+            result[year] = matched
+    return result
+
+
+def archive_summary_line(archived: dict[str, list[Path]], patterns: list[str]) -> str:
+    """One-line summary of the archived-course count and year span."""
+    total = sum(len(courses) for courses in archived.values())
+    match_clause = ""
+    if patterns:
+        quoted = ", ".join(f'"{p}"' for p in patterns)
+        match_clause = f" matching {quoted}"
+    if total == 0:
+        return f"Archived: none{match_clause}"
+    years = sorted(archived.keys())
+    span = years[0] if len(years) == 1 else f"{years[0]}–{years[-1]}"
+    return (
+        f"Archived: {total} courses{match_clause} across {span}"
+        " — use --archived to list them."
+    )
+
+
+def resolve_scan_dirs(cli_dirs: list[str], config: CourseConfig) -> list[Path]:
+    """Choose which directories to scan: CLI args, else config, else cwd."""
+    if cli_dirs:
+        return [Path(d).expanduser() for d in cli_dirs]
+    if config.course_dirs:
+        return [Path(d).expanduser() for d in config.course_dirs]
+    return [Path(".")]
+
+
+def find_active_courses(scan_dirs: list[Path]) -> list[Path]:
+    """Return course directories found directly under each scan dir, sorted."""
+    courses: list[Path] = []
+    for scan_dir in scan_dirs:
+        if not scan_dir.is_dir():
+            continue
+        for child in sorted(scan_dir.iterdir()):
+            if child.is_dir() and is_course(child):
+                courses.append(child)
+    return courses
+
+
+def find_archived_courses(archive_path: Path) -> dict[str, list[Path]]:
+    """Return {year: [course dirs]} under archive_path/<YYYY>/<course>.
+
+    Only directories named like a 4-digit year are treated as year groups, and
+    only ``is_archived_course`` children are included.
+    """
+    result: dict[str, list[Path]] = {}
+    if not archive_path.is_dir():
+        return result
+    for year_dir in sorted(archive_path.iterdir()):
+        if not (year_dir.is_dir() and _YEAR_RE.match(year_dir.name)):
+            continue
+        courses = sorted(
+            c for c in year_dir.iterdir() if c.is_dir() and is_archived_course(c)
+        )
+        if courses:
+            result[year_dir.name] = courses
+    return result
+
+
+def _year_arg(value: str) -> str:
+    """argparse type: accept only a 4-digit year."""
+    if not _YEAR_RE.match(value):
+        raise argparse.ArgumentTypeError(f"invalid year '{value}' (expected 4 digits)")
+    return value
+
+
+def main(argv: list[str] | None = None) -> None:
+    pypi_url = "https://pypi.org/project/course-setup/"
+    author_line = f"{__author__} <{__email__}>"
+
+    parser = argparse.ArgumentParser(
+        description="List active and archived courses.",
+        epilog=f"Version {__version__} — {pypi_url}\n{author_line}",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}\n{pypi_url}\n{author_line}",
+    )
+    parser.add_argument(
+        "names",
+        nargs="*",
+        help="Filter courses by case-insensitive name substring (any match)",
+    )
+    parser.add_argument(
+        "--dir",
+        action="append",
+        default=[],
+        metavar="PATH",
+        help="Directory to scan for active courses (repeatable; overrides config)",
+    )
+    parser.add_argument(
+        "--active",
+        action="store_true",
+        help="Show only active courses",
+    )
+    parser.add_argument(
+        "--archived",
+        action="store_true",
+        help="Show only archived courses (expanded, grouped by year)",
+    )
+    parser.add_argument(
+        "--year",
+        action="append",
+        default=[],
+        dest="years",
+        type=_year_arg,
+        metavar="YYYY",
+        help="Restrict archived courses to a year (repeatable; hides active)",
+    )
+    parser.add_argument(
+        "--count",
+        action="store_true",
+        help="Show counts instead of individual course lines",
+    )
+    args = parser.parse_args(argv)
+
+    config = load_config()
+    scan_dirs = resolve_scan_dirs(args.dir, config)
+
+    patterns: list[str] = args.names
+    has_names = bool(patterns)
+    has_years = bool(args.years)
+    only_active = args.active and not args.archived
+    only_archived = args.archived and not args.active
+    year_focus = has_years and not args.active and not args.archived
+    show_active = not (only_archived or year_focus)
+    show_archived = not only_active
+    archive_expanded = args.archived or has_years
+
+    if show_active:
+        active = filter_active(find_active_courses(scan_dirs), patterns)
+        if args.count:
+            print(f"Active courses: {len(active)}")
+        else:
+            print("Active courses:")
+            if active:
+                for course in active:
+                    print(f"  {course_summary_line(course)}")
+            elif has_names:
+                print(f"  No active courses match: {', '.join(patterns)}")
+            else:
+                print("  No active courses found")
+
+    if show_archived:
+        archived = filter_archived(
+            find_archived_courses(config.archive_path), args.years, patterns
+        )
+        if show_active:
+            print()
+        if args.count:
+            total = sum(len(courses) for courses in archived.values())
+            print(f"Archived courses: {total}")
+            for year in sorted(archived):
+                print(f"  {year}: {len(archived[year])}")
+        elif archive_expanded:
+            print("Archived courses:")
+            if archived:
+                for year in sorted(archived):
+                    print(f"  {year}:")
+                    for course in archived[year]:
+                        print(f"    {course_summary_line(course)}")
+            elif has_names or has_years:
+                print("  No archived courses match your filters")
+            else:
+                print("  No archived courses found")
+        else:
+            print(archive_summary_line(archived, patterns))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

course_setup-3.2.0/src/setup_course_github/notebooks.py

@@ -0,0 +1,34 @@
+import re
+from collections.abc import Iterable
+from pathlib import Path
+
+_DATE_PATTERN = re.compile(r"(\d{4}-\d{2}-\d{2})\.\w+$")
+
+
+def is_marimo_notebook(path: Path) -> bool:
+    """Return True if a .py file looks like a marimo notebook."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+    return "import marimo" in text and "marimo.App()" in text
+
+
+def find_notebooks(path: Path) -> tuple[list[Path], list[Path]]:
+    """Return (ipynb_files, marimo_files) found directly in *path*, each sorted."""
+    ipynb_files = sorted(path.glob("*.ipynb"))
+    marimo_files = sorted(p for p in path.glob("*.py") if is_marimo_notebook(p))
+    return ipynb_files, marimo_files
+
+
+def date_range(files: Iterable[Path]) -> str:
+    """Return '<first> → <last>' parsed from filenames, or 'n/a' if none match."""
+    dates: list[str] = []
+    for p in files:
+        match = _DATE_PATTERN.search(p.name)
+        if match:
+            dates.append(match.group(1))
+    dates.sort()
+    if dates:
+        return f"{dates[0]} → {dates[-1]}"
+    return "n/a"

{course_setup-3.0.14 → course_setup-3.2.0}/src/setup_course_github/retire_course.py

@@ -12,6 +12,7 @@ from pathlib import Path
 
 from setup_course_github import __author__, __email__, __version__, get_github
 from setup_course_github.config import load_config
+from setup_course_github.notebooks import date_range, find_notebooks
 
 
 class InsideCourseDirectoryError(RuntimeError):
@@ -77,15 +78,6 @@ def _confirm_create_dir(dest: Path, confirm: Callable[[str], str] = input) -> No
             raise RuntimeError(f"Aborted: archive directory {dest} not created")
 
 
-def _is_marimo_notebook(path: Path) -> bool:
-    """Return True if a .py file looks like a marimo notebook."""
-    try:
-        text = path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
-        return False
-    return "import marimo" in text and "marimo.App()" in text
-
-
 def _build_retirement_summary(
     dirname: str, repo_name: str, dest: Path, *, kept_public: bool = False
 ) -> str:
@@ -96,8 +88,7 @@ def _build_retirement_summary(
     dirpath = Path(dirname)
 
     # --- count notebooks ---------------------------------------------------
-    ipynb_files = list(dirpath.glob("*.ipynb"))
-    marimo_files = [p for p in dirpath.glob("*.py") if _is_marimo_notebook(p)]
+    ipynb_files, marimo_files = find_notebooks(dirpath)
     nb_count = len(ipynb_files) + len(marimo_files)
 
     if ipynb_files and marimo_files:
@@ -110,17 +101,7 @@ def _build_retirement_summary(
         nb_label = "0"
 
     # --- date range from filenames -----------------------------------------
-    date_pattern = re.compile(r"(\d{4}-\d{2}-\d{2})\.\w+$")
-    dates: list[str] = []
-    for p in ipynb_files + marimo_files:
-        m = date_pattern.search(p.name)
-        if m:
-            dates.append(m.group(1))
-    dates.sort()
-    if dates:
-        date_range = f"{dates[0]} \u2192 {dates[-1]}"
-    else:
-        date_range = "n/a"
+    date_range_str = date_range(ipynb_files + marimo_files)
 
     # --- dependencies from pyproject.toml ----------------------------------
     pyproject_path = dirpath / "pyproject.toml"
@@ -144,7 +125,7 @@ def _build_retirement_summary(
         "\u2500\u2500 Retirement Summary \u2500\u2500",
         f"  Course: {dirpath.name}",
         f"  Notebooks: {nb_label}",
-        f"  Date range: {date_range}",
+        f"  Date range: {date_range_str}",
         f"  Dependencies: {deps_str}",
         f"  Archived to: {dest / dirpath.name}",
         f"  GitHub repo: {repo_url} (still public)"
@@ -154,8 +135,14 @@ def _build_retirement_summary(
     return "\n".join(lines)
 
 
-def retire_course(dirname: str, keep_public: bool = False) -> None:
-    """Move the local directory to the archive, optionally making the repo private."""
+def retire_course(
+    dirname: str, keep_public: bool = False, dry_run: bool = False
+) -> None:
+    """Move the local directory to the archive, optionally making the repo private.
+
+    When *dry_run* is True, no repo is modified, no directory is created, and
+    nothing is moved \u2014 only a preview of the intended actions is printed.
+    """
     _check_not_inside_course(dirname)
 
     config = load_config()
@@ -163,13 +150,22 @@ def retire_course(dirname: str, keep_public: bool = False) -> None:
     remote_url = get_remote_url(dirname)
     repo_name = parse_repo_name(remote_url)
 
+    year = datetime.datetime.now().year
+    dest = config.archive_path / str(year)
+
+    if dry_run:
+        summary = _build_retirement_summary(
+            dirname, repo_name, dest, kept_public=keep_public
+        )
+        print(f"[DRY RUN] Would retire {dirname} \u2192 {dest / Path(dirname).name}")
+        print(summary)
+        return
+
     g = get_github()
     repo = g.get_repo(repo_name)
     if not keep_public:
         repo.edit(private=True)
 
-    year = datetime.datetime.now().year
-    dest = config.archive_path / str(year)
     _confirm_create_dir(dest)
 
     summary = _build_retirement_summary(
@@ -200,6 +196,12 @@ def main() -> None:
         default=False,
         help="archive without making the GitHub repo private",
     )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        default=False,
+        help="preview the retirement without changing GitHub or moving files",
+    )
     parser.add_argument(
         "dirnames", nargs="+", help="Path(s) to course directories to retire"
     )
@@ -208,7 +210,7 @@ def main() -> None:
     errors: list[tuple[str, str]] = []
     for dirname in args.dirnames:
         try:
-            retire_course(dirname, keep_public=args.keep_public)
+            retire_course(dirname, keep_public=args.keep_public, dry_run=args.dry_run)
         except Exception as e:
             print(f"Error retiring {dirname}: {e}")
             errors.append((dirname, str(e)))