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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: course-setup
-Version: 3.2.0
+Version: 3.3.0
 Summary: CLI tools for setting up and retiring GitHub-backed course repositories
 Author: Reuven Lerner
 Author-email: Reuven Lerner <reuven@lernerpython.com>
@@ -226,7 +226,8 @@ 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).
+reads your config file, and each course's local `git` remote, 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
@@ -243,13 +244,21 @@ directory (an archived course is any non-hidden, non-junk directory under a
 ```
 Active courses:
   Acme-python-intro-2026-03 — 5 notebooks (2026-03-17 → 2026-03-21)
+    https://github.com/acme/python-intro-2026-03
   Beta-pandas-2026-02 — 3 notebooks (2026-02-02 → 2026-02-16)
+    https://github.com/beta/pandas-2026-02
 
 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).
+with dates parsed from notebook filenames (`n/a` if none are found). By
+default, an indented line below each *listed* course (active courses, and
+archived courses in the expanded `--archived`/`--year` views) shows its GitHub
+URL, read from the course's local `git` `origin` remote — no network call. A
+course with no usable GitHub remote shows `(no GitHub remote)` instead. Pass
+`--no-urls` to hide these lines. URLs are not shown in the one-line archive
+summary or with `--count`.
 
 | Argument / Option | Description |
 |----------|-------------|
@@ -257,8 +266,9 @@ with dates parsed from notebook filenames (`n/a` if none are found).
 | `--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 |
+| `--year YYYY[-YYYY]` | Restrict archived courses to a year or an inclusive `YYYY-YYYY` range (repeatable; singles and ranges mix freely); implies `--archived` unless `--active` is also given, in which case `--year` is ignored. A reversed range (e.g. `2022-2020`) is auto-swapped, printing `Note: swapped reversed year range 2022-2020 → 2020-2022` to stderr. |
 | `--count` | Print counts instead of course lines, honoring all other filters |
+| `--no-urls` | Hide the per-course GitHub URL line shown by default under each listed course |
 | `--version` | Show the version number, PyPI URL, author name, and email |
 
 Directories to scan for active courses are resolved in this order:
@@ -278,11 +288,14 @@ Directories to scan for active courses are resolved in this order:
 | `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 --year 2020-2022` | archive for 2020 through 2022 only (inclusive range) |
+| `list-courses --year 2019 --year 2021-2023` | archive for 2019, 2021, 2022, 2023 (singles and ranges mix) |
 | `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` |
+| `list-courses --no-urls` | active courses in full, without the per-course GitHub URL lines |
 
 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

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

@@ -206,7 +206,8 @@ 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).
+reads your config file, and each course's local `git` remote, 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
@@ -223,13 +224,21 @@ directory (an archived course is any non-hidden, non-junk directory under a
 ```
 Active courses:
   Acme-python-intro-2026-03 — 5 notebooks (2026-03-17 → 2026-03-21)
+    https://github.com/acme/python-intro-2026-03
   Beta-pandas-2026-02 — 3 notebooks (2026-02-02 → 2026-02-16)
+    https://github.com/beta/pandas-2026-02
 
 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).
+with dates parsed from notebook filenames (`n/a` if none are found). By
+default, an indented line below each *listed* course (active courses, and
+archived courses in the expanded `--archived`/`--year` views) shows its GitHub
+URL, read from the course's local `git` `origin` remote — no network call. A
+course with no usable GitHub remote shows `(no GitHub remote)` instead. Pass
+`--no-urls` to hide these lines. URLs are not shown in the one-line archive
+summary or with `--count`.
 
 | Argument / Option | Description |
 |----------|-------------|
@@ -237,8 +246,9 @@ with dates parsed from notebook filenames (`n/a` if none are found).
 | `--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 |
+| `--year YYYY[-YYYY]` | Restrict archived courses to a year or an inclusive `YYYY-YYYY` range (repeatable; singles and ranges mix freely); implies `--archived` unless `--active` is also given, in which case `--year` is ignored. A reversed range (e.g. `2022-2020`) is auto-swapped, printing `Note: swapped reversed year range 2022-2020 → 2020-2022` to stderr. |
 | `--count` | Print counts instead of course lines, honoring all other filters |
+| `--no-urls` | Hide the per-course GitHub URL line shown by default under each listed course |
 | `--version` | Show the version number, PyPI URL, author name, and email |
 
 Directories to scan for active courses are resolved in this order:
@@ -258,11 +268,14 @@ Directories to scan for active courses are resolved in this order:
 | `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 --year 2020-2022` | archive for 2020 through 2022 only (inclusive range) |
+| `list-courses --year 2019 --year 2021-2023` | archive for 2019, 2021, 2022, 2023 (singles and ranges mix) |
 | `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` |
+| `list-courses --no-urls` | active courses in full, without the per-course GitHub URL lines |
 
 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

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

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

{course_setup-3.2.0 → course_setup-3.3.0}/src/setup_course_github/list_courses.py

@@ -1,5 +1,7 @@
 import argparse
 import re
+import subprocess
+import sys
 from pathlib import Path
 
 from setup_course_github import __author__, __email__, __version__
@@ -10,6 +12,8 @@ JUNK_NAMES = frozenset(
     {"__pycache__", "build", "dist", "bin", "include", "lib", "node_modules"}
 )
 _YEAR_RE = re.compile(r"^\d{4}$")
+_YEAR_TOKEN_RE = re.compile(r"^\d{4}(-\d{4})?$")
+_GITHUB_RE = re.compile(r"github\.com[:/](?P<path>[^/]+/[^/]+?)(?:\.git)?/?$")
 
 
 def _is_junk_name(name: str) -> bool:
@@ -45,6 +49,32 @@ def course_summary_line(path: Path) -> str:
     return f"{path.name} — {count} notebooks ({span})"
 
 
+def _github_url(remote: str) -> str | None:
+    """Normalize a GitHub SSH/HTTPS remote to https://github.com/<owner>/<repo>.
+
+    Returns None for an empty string or a non-GitHub remote.
+    """
+    match = _GITHUB_RE.search(remote)
+    if not match:
+        return None
+    return f"https://github.com/{match.group('path')}"
+
+
+def github_url(course_path: Path) -> str | None:
+    """Return the course repo's GitHub URL from its local origin remote, or None.
+
+    Reads ``git config --get remote.origin.url`` in *course_path*; no network.
+    """
+    result = subprocess.run(
+        ["git", "config", "--get", "remote.origin.url"],
+        cwd=str(course_path),
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        return None
+    return _github_url(result.stdout.decode().strip())
+
+
 def _matches_names(name: str, patterns: list[str]) -> bool:
     """True if *name* (case-insensitively) contains any of *patterns*.
 
@@ -90,8 +120,9 @@ def archive_summary_line(archived: dict[str, list[Path]], patterns: list[str]) -
         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} courses{match_clause} across {span}"
+        f"Archived: {total} {noun}{match_clause} across {span}"
         " — use --archived to list them."
     )
 
@@ -138,12 +169,46 @@ def find_archived_courses(archive_path: Path) -> dict[str, list[Path]]:
 
 
 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)")
+    """argparse type: accept a 4-digit year or an inclusive YYYY-YYYY range."""
+    if not _YEAR_TOKEN_RE.match(value):
+        raise argparse.ArgumentTypeError(
+            f"invalid year '{value}' (expected YYYY or YYYY-YYYY)"
+        )
     return value
 
 
+def _expand_year_tokens(tokens: list[str]) -> tuple[list[str], list[str]]:
+    """Flatten single-year and range tokens into individual 4-digit years.
+
+    Returns ``(years, notes)`` where *notes* holds a message for each reversed
+    range that was auto-swapped. Ranges are inclusive; a reversed range like
+    ``2022-2020`` is swapped to ``2020-2022``.
+    """
+    years: list[str] = []
+    notes: list[str] = []
+    for token in tokens:
+        if "-" in token:
+            start_s, end_s = token.split("-")
+            start, end = int(start_s), int(end_s)
+            if start > end:
+                notes.append(
+                    f"swapped reversed year range {start_s}-{end_s} → {end_s}-{start_s}"
+                )
+                start, end = end, start
+            years.extend(f"{year:04d}" for year in range(start, end + 1))
+        else:
+            years.append(token)
+    return years, notes
+
+
+def _print_course(course: Path, indent: int, show_urls: bool) -> None:
+    """Print a course summary line and, when *show_urls*, its indented URL line."""
+    print(f"{' ' * indent}{course_summary_line(course)}")
+    if show_urls:
+        url = github_url(course)
+        print(f"{' ' * (indent + 2)}{url or '(no GitHub remote)'}")
+
+
 def main(argv: list[str] | None = None) -> None:
     pypi_url = "https://pypi.org/project/course-setup/"
     author_line = f"{__author__} <{__email__}>"
@@ -187,15 +252,24 @@ def main(argv: list[str] | None = None) -> None:
         dest="years",
         type=_year_arg,
         metavar="YYYY",
-        help="Restrict archived courses to a year (repeatable; hides active)",
+        help="Restrict archived courses to a year or YYYY-YYYY range (repeatable)",
     )
     parser.add_argument(
         "--count",
         action="store_true",
         help="Show counts instead of individual course lines",
     )
+    parser.add_argument(
+        "--no-urls",
+        action="store_true",
+        help="Do not show each course's GitHub URL",
+    )
     args = parser.parse_args(argv)
 
+    years, year_notes = _expand_year_tokens(args.years)
+    for note in year_notes:
+        print(f"Note: {note}", file=sys.stderr)
+
     config = load_config()
     scan_dirs = resolve_scan_dirs(args.dir, config)
 
@@ -208,6 +282,7 @@ def main(argv: list[str] | None = None) -> None:
     show_active = not (only_archived or year_focus)
     show_archived = not only_active
     archive_expanded = args.archived or has_years
+    show_urls = not args.no_urls
 
     if show_active:
         active = filter_active(find_active_courses(scan_dirs), patterns)
@@ -217,7 +292,7 @@ def main(argv: list[str] | None = None) -> None:
             print("Active courses:")
             if active:
                 for course in active:
-                    print(f"  {course_summary_line(course)}")
+                    _print_course(course, 2, show_urls)
             elif has_names:
                 print(f"  No active courses match: {', '.join(patterns)}")
             else:
@@ -225,7 +300,7 @@ def main(argv: list[str] | None = None) -> None:
 
     if show_archived:
         archived = filter_archived(
-            find_archived_courses(config.archive_path), args.years, patterns
+            find_archived_courses(config.archive_path), years, patterns
         )
         if show_active:
             print()
@@ -240,7 +315,7 @@ def main(argv: list[str] | None = None) -> None:
                 for year in sorted(archived):
                     print(f"  {year}:")
                     for course in archived[year]:
-                        print(f"    {course_summary_line(course)}")
+                        _print_course(course, 4, show_urls)
             elif has_names or has_years:
                 print("  No archived courses match your filters")
             else: