course-setup 3.1.0__tar.gz → 3.2.1__tar.gz

{course_setup-3.1.0 → course_setup-3.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: course-setup
-Version: 3.1.0
+Version: 3.2.1
 Summary: CLI tools for setting up and retiring GitHub-backed course repositories
 Author: Reuven Lerner
 Author-email: Reuven Lerner <reuven@lernerpython.com>
@@ -74,7 +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. |
+| `[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. |
@@ -226,36 +226,67 @@ 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). It lists:
+reads your config file but does not use the network).
 
-- **Active courses**: for each scan directory, its immediate subdirectories
-  that qualify as a *course* — a directory containing both a `.git`
-  subdirectory and at least one notebook (`.ipynb`, or a marimo `.py`).
-- **Archived courses**: courses found under `{archive}/{year}/{course}`,
-  grouped by year, using your configured `[paths] archive` directory.
+> **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`.
 
-Each course is shown as:
+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):
 
 ```
-name — N notebooks (first-date → last-date)
+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.
 ```
 
-with dates parsed from notebook filenames (`n/a` if none are found). If there
-are no active or archived courses, it prints `No active courses found` /
-`No archived courses found` respectively.
+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 | Description |
+| Argument / Option | Description |
 |----------|-------------|
-| `DIR...` | Optional directories to scan (overrides `course_dirs` from config) |
+| `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 are resolved in this order:
+Directories to scan for active courses are resolved in this order:
 
-1. Positional directories passed on the command line (`list-courses DIR ...`)
+1. `--dir PATH` values passed on the command line (repeatable)
 2. Otherwise, `[paths] course_dirs` from your config file
 3. Otherwise, the current directory
 
-Like the other commands, `list-courses --version` prints the version number,
-PyPI URL, author name, and email.
+#### 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.1.0 → course_setup-3.2.1}/README.md

@@ -54,7 +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. |
+| `[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. |
@@ -206,36 +206,67 @@ 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). It lists:
+reads your config file but does not use the network).
 
-- **Active courses**: for each scan directory, its immediate subdirectories
-  that qualify as a *course* — a directory containing both a `.git`
-  subdirectory and at least one notebook (`.ipynb`, or a marimo `.py`).
-- **Archived courses**: courses found under `{archive}/{year}/{course}`,
-  grouped by year, using your configured `[paths] archive` directory.
+> **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`.
 
-Each course is shown as:
+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):
 
 ```
-name — N notebooks (first-date → last-date)
+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.
 ```
 
-with dates parsed from notebook filenames (`n/a` if none are found). If there
-are no active or archived courses, it prints `No active courses found` /
-`No archived courses found` respectively.
+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 | Description |
+| Argument / Option | Description |
 |----------|-------------|
-| `DIR...` | Optional directories to scan (overrides `course_dirs` from config) |
+| `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 are resolved in this order:
+Directories to scan for active courses are resolved in this order:
 
-1. Positional directories passed on the command line (`list-courses DIR ...`)
+1. `--dir PATH` values passed on the command line (repeatable)
 2. Otherwise, `[paths] course_dirs` from your config file
 3. Otherwise, the current directory
 
-Like the other commands, `list-courses --version` prints the version number,
-PyPI URL, author name, and email.
+#### 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.1.0 → course_setup-3.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
     name = "course-setup"
-    version = "3.1.0"
+    version = "3.2.1"
     description = "CLI tools for setting up and retiring GitHub-backed course repositories"
     readme = "README.md"
     requires-python = ">=3.13"

course_setup-3.2.1/src/setup_course_github/list_courses.py

@@ -0,0 +1,254 @@
+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]}"
+    noun = "course" if total == 1 else "courses"
+    return (
+        f"Archived: {total} {noun}{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.1.0/src/setup_course_github/list_courses.py

@@ -1,104 +0,0 @@
-import argparse
-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
-
-
-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 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 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]} found under archive_path/<year>/<course>."""
-    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():
-            continue
-        courses = sorted(c for c in year_dir.iterdir() if c.is_dir())
-        if courses:
-            result[year_dir.name] = courses
-    return result
-
-
-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(
-        "dirs",
-        nargs="*",
-        help="Directories to scan (overrides course_dirs from config)",
-    )
-    args = parser.parse_args(argv)
-
-    config = load_config()
-    scan_dirs = resolve_scan_dirs(args.dirs, config)
-
-    active = find_active_courses(scan_dirs)
-    print("Active courses:")
-    if active:
-        for course in active:
-            print(f"  {course_summary_line(course)}")
-    else:
-        print("  No active courses found")
-
-    archived = find_archived_courses(config.archive_path)
-    print("\nArchived courses:")
-    if archived:
-        for year, courses in archived.items():
-            print(f"  {year}:")
-            for course in courses:
-                print(f"    {course_summary_line(course)}")
-    else:
-        print("  No archived courses found")
-
-
-if __name__ == "__main__":  # pragma: no cover
-    main()