cogames 0.3.49__py3-none-any.whl → 0.3.64__py3-none-any.whl

cogames/cli/docsync/_utils.py

@@ -0,0 +1,76 @@
+import subprocess
+import tempfile
+from pathlib import Path
+
+import jupytext
+import nbformat
+import typer
+from nbstripout import strip_output
+
+
+def get_cogames_root() -> Path:
+    """Get cogames root path by finding pyproject.toml."""
+    for parent in Path(__file__).resolve().parents:
+        if (parent / "pyproject.toml").exists():
+            return parent
+    raise RuntimeError("Could not find cogames root (no pyproject.toml found)")
+
+
+def lint_py_file(path: Path, /) -> None:
+    """Run ruff format on a Python file."""
+    subprocess.run(["ruff", "format", str(path)], check=True, capture_output=True)
+
+
+def run_notebook(*, nb_path: Path) -> None:
+    """Execute notebook in place."""
+    typer.echo(f"  Executing {nb_path.name}...")
+    result = subprocess.run(
+        ["jupyter", "execute", nb_path.name, "--inplace"],
+        cwd=nb_path.parent,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        typer.echo(f"  Error: notebook execution failed: {result.stderr}", err=True)
+        raise typer.Exit(1)
+    typer.echo(f"  Executed {nb_path.name}")
+
+
+def clean_notebook_metadata(*, nb_path: Path) -> None:
+    """Strip metadata (execution counts, cell IDs, execution timestamps) but keep outputs.
+
+    Also ensures accelerator is set to GPU for Colab.
+    """
+    typer.echo(f"  Cleaning metadata from {nb_path.name}...")
+    nb = nbformat.read(nb_path, as_version=4)
+    nb = strip_output(
+        nb,
+        keep_output=True,
+        keep_count=False,
+        keep_id=False,
+        extra_keys=["cell.metadata.execution"],
+    )
+    # Ensure GPU accelerator for Colab
+    # See: https://github.com/mwouts/jupytext/pull/235#issuecomment-495010137
+    nb.metadata["accelerator"] = "GPU"
+    nbformat.write(nb, nb_path)
+    typer.echo(f"  Cleaned metadata from {nb_path.name}")
+
+
+def files_equal(path1: str | Path, path2: str | Path, /) -> bool:
+    """Check if two files have identical content."""
+    return Path(path1).read_bytes() == Path(path2).read_bytes()
+
+
+def py_nb_content_equal(*, py_path: Path, nb_path: Path) -> bool:
+    """Check if .py and .ipynb have equivalent content (ignoring outputs and linting)."""
+    with tempfile.NamedTemporaryFile(suffix=".py", delete=False) as tmp:
+        tmp_py = Path(tmp.name)
+    try:
+        # Convert current .ipynb to .py and compare with existing .py
+        nb = jupytext.read(nb_path)
+        jupytext.write(nb, tmp_py, fmt="py:percent")
+        lint_py_file(tmp_py)  # Format generated .py for fair comparison
+        return files_equal(py_path, tmp_py)
+    finally:
+        tmp_py.unlink(missing_ok=True)

cogames/cli/docsync/docsync.py

@@ -0,0 +1,156 @@
+"""
+`cogames docsync` is a dev-only tool to sync cogames docs between .ipynb, .py, and .md formats.
+
+Tests for this module are in tests/docsync/
+"""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from cogames.cli.docsync._nb_md_sync import convert_nb_to_md
+from cogames.cli.docsync._nb_py_sync import convert_nb_to_py, convert_py_to_nb
+from cogames.cli.docsync._three_way_sync import get_stem_paths, is_stem_in_sync_three_way, sync_stem_three_way
+from cogames.cli.docsync._utils import get_cogames_root
+
+app = typer.Typer(
+    help="""Sync cogames docs between .ipynb, .py, and .md formats
+
+Directives (first line of code cell):
+  # <<hide>>            - skip entire cell (code + output)
+  # <<hide-input>>      - skip code, show output
+  # <<hide-output>>     - show code, skip output
+  # <<collapse-input>>  - wrap code in <details>
+  # <<collapse-output>> - wrap output in <details>
+
+Placeholders (in markdown cells):
+  <<colab-link>>        - replaced with Colab URL for this notebook
+"""
+)
+
+
+@app.command()
+def nb_to_md(
+    nb_path: Annotated[Path, typer.Argument(help="Path to .ipynb file")],
+    skip_rerun: Annotated[bool, typer.Option("--skip-rerun", help="Skip re-running notebook")] = False,
+    cogames_root_raw: Annotated[
+        Path | None, typer.Option("--cogames-root", hidden=True, help="Override root path (for testing)")
+    ] = None,
+):
+    """Convert .ipynb to .md (reruns notebook by default to update outputs)."""
+
+    if not nb_path.exists():
+        typer.echo(f"Error: {nb_path} not found", err=True)
+        raise typer.Exit(1)
+    if nb_path.suffix != ".ipynb":
+        typer.echo(f"Error: expected .ipynb file, got {nb_path.suffix}", err=True)
+        raise typer.Exit(1)
+
+    cogames_root = cogames_root_raw or get_cogames_root()
+    typer.echo(f"Exporting {nb_path.name}...")
+    convert_nb_to_md(nb_path=nb_path, should_rerun=not skip_rerun, cogames_root=cogames_root)
+
+
+@app.command()
+def nb_to_py(
+    nb_path: Annotated[Path, typer.Argument(help="Path to .ipynb file")],
+):
+    """Convert notebook to .py percent format (ignores outputs, keeps code)."""
+
+    if not nb_path.exists():
+        typer.echo(f"Error: {nb_path} not found", err=True)
+        raise typer.Exit(1)
+    if nb_path.suffix != ".ipynb":
+        typer.echo(f"Error: expected .ipynb file, got {nb_path.suffix}", err=True)
+        raise typer.Exit(1)
+
+    py_path = nb_path.with_suffix(".py")
+    typer.echo(f"Converting {nb_path.name} to .py...")
+    convert_nb_to_py(nb_path=nb_path, py_path=py_path)
+    typer.echo(f"Created {py_path.name}")
+
+
+@app.command()
+def py_to_nb(
+    py_path: Annotated[Path, typer.Argument(help="Path to .py file")],
+    skip_rerun: Annotated[bool, typer.Option("--skip-rerun", help="Skip re-running notebook")] = False,
+):
+    """Convert .py percent format to .ipynb (runs notebook by default to populate outputs)."""
+
+    if not py_path.exists():
+        typer.echo(f"Error: {py_path} not found", err=True)
+        raise typer.Exit(1)
+    if py_path.suffix != ".py":
+        typer.echo(f"Error: expected .py file, got {py_path.suffix}", err=True)
+        raise typer.Exit(1)
+
+    nb_path = py_path.with_suffix(".ipynb")
+    typer.echo(f"Converting {py_path.name} to .ipynb...")
+    convert_py_to_nb(py_path=py_path, nb_path=nb_path, should_rerun=not skip_rerun)
+    typer.echo(f"Created {nb_path.name}")
+
+
+@app.command()
+def check(
+    skip_rerun: Annotated[bool, typer.Option("--skip-rerun", help="Skip re-running notebooks")] = False,
+    cogames_root_raw: Annotated[
+        Path | None, typer.Option("--cogames-root", hidden=True, help="Override root path (for testing)")
+    ] = None,
+):
+    """Verify that .py, .ipynb, and .md files are all in sync (without modifying files)."""
+    cogames_root = cogames_root_raw or get_cogames_root()
+    stem_paths = get_stem_paths(cogames_root=cogames_root)
+    should_rerun = not skip_rerun
+
+    typer.echo(f"Checking {len(stem_paths)} notebook(s)...")
+
+    errors: list[str] = []
+    for stem_path in stem_paths:
+        stem_errors = is_stem_in_sync_three_way(
+            stem_path=stem_path, should_rerun=should_rerun, cogames_root=cogames_root
+        )
+        if stem_errors:
+            typer.echo(f"  ✗ {stem_path.name}")
+        else:
+            typer.echo(f"  ✓ {stem_path.name}")
+        errors.extend(stem_errors)
+
+    if errors:
+        typer.echo("\nNotebook documentation is out of sync!", err=True)
+        for error in errors:
+            typer.echo(f"  {error}", err=True)
+        typer.echo("\nTo fix: run 'cogames docsync all'", err=True)
+        raise typer.Exit(1)
+
+    typer.echo("All notebooks are in sync!")
+
+
+@app.command()
+def all(
+    skip_rerun: Annotated[bool, typer.Option("--skip-rerun", help="Skip re-running notebooks")] = False,
+    cogames_root_raw: Annotated[
+        Path | None, typer.Option("--cogames-root", hidden=True, help="Override root path (for testing)")
+    ] = None,
+):
+    """Resyncs README and tutorials/ .py and .ipynb files with each other and exports to .md files."""
+    cogames_root = cogames_root_raw or get_cogames_root()
+    stem_paths = get_stem_paths(cogames_root=cogames_root)
+    should_rerun = not skip_rerun
+
+    typer.echo(f"Found {len(stem_paths)} notebook(s) to process")
+
+    for stem_path in stem_paths:
+        stem_path_relative = stem_path.relative_to(cogames_root)
+        typer.echo(f"Processing {stem_path_relative}...")
+        sync_stem_three_way(
+            stem_path=stem_path,
+            should_rerun=should_rerun,
+            cogames_root=cogames_root,
+        )
+
+    typer.echo(f"Done! Processed {len(stem_paths)} notebook(s)")
+
+
+if __name__ == "__main__":
+    app()

cogames/cli/leaderboard.py

@@ -36,6 +36,22 @@ def parse_policy_identifier(identifier: str) -> tuple[str, int | None]:
     return identifier, None
 
 
+def parse_season_ref(season_ref: str) -> tuple[str, int | None]:
+    if ":v" in season_ref:
+        name, version_str = season_ref.rsplit(":v", 1)
+        try:
+            return name, int(version_str)
+        except ValueError:
+            return season_ref, None
+    if ":" in season_ref:
+        name, version_str = season_ref.rsplit(":", 1)
+        try:
+            return name, int(version_str)
+        except ValueError:
+            return season_ref, None
+    return season_ref, None
+
+
 def _format_timestamp(value: Optional[str]) -> str:
     """Format ISO timestamps for CLI output."""
     if not value:
@@ -64,40 +80,60 @@ def _get_client(login_server: str, server: str) -> TournamentServerClient | None
     return TournamentServerClient.from_login(server_url=server, login_server=login_server)
 
 
+def _help_callback(ctx: typer.Context, value: bool) -> None:
+    """Callback for custom help option."""
+    if value:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+
 def submissions_cmd(
-    policy_name: Optional[str] = typer.Argument(
+    policy_name: Optional[str] = typer.Option(
         None,
-        help="Policy name to filter (e.g., 'my-policy' or 'my-policy:v3')",
+        "--policy",
+        "-p",
+        metavar="POLICY",
+        help="Filter by policy name (e.g., 'my-policy' or 'my-policy:v3')",
+        rich_help_panel="Filter",
     ),
     season: Optional[str] = typer.Option(
         None,
         "--season",
+        metavar="SEASON",
         help="Filter by tournament season",
+        rich_help_panel="Filter",
     ),
     login_server: str = typer.Option(
         DEFAULT_COGAMES_SERVER,
         "--login-server",
-        help="Login/authentication server URL",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
     ),
     server: str = typer.Option(
         DEFAULT_SUBMIT_SERVER,
         "--server",
         "-s",
-        help="Observatory API base URL",
+        metavar="URL",
+        help="Tournament server URL",
+        rich_help_panel="Server",
     ),
     json_output: bool = typer.Option(
         False,
         "--json",
-        help="Print the raw JSON response instead of a table",
+        help="Print raw JSON instead of table",
+        rich_help_panel="Output",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
-    """Show your uploaded policies and tournament submissions.
-
-    Examples:
-      cogames submissions                    # All uploads
-      cogames submissions --season beta      # Submissions in beta season
-      cogames submissions my-policy          # Info on a specific policy
-    """
     client = _get_client(login_server, server)
     if not client:
         return
@@ -167,7 +203,7 @@ def _show_season_submissions(
 ) -> None:
     """Show submissions for a specific season."""
     try:
-        entries = client.get_season_policies(season, mine=True)
+        entries = client.get_season_policies(season, mine=True, include_hidden_seasons=True)
     except httpx.HTTPStatusError as exc:
         if exc.response.status_code == 404:
             console.print(f"[red]Season '{season}' not found[/red]")
@@ -219,39 +255,50 @@ def _show_season_submissions(
 
 def leaderboard_cmd(
     season: str = typer.Option(
-        ...,
+        "beta-cogsguard",
         "--season",
-        help="Tournament season name (required)",
+        metavar="SEASON",
+        help="Tournament season name",
+        rich_help_panel="Tournament",
     ),
     login_server: str = typer.Option(
         DEFAULT_COGAMES_SERVER,
         "--login-server",
-        help="Login/authentication server URL",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
     ),
     server: str = typer.Option(
         DEFAULT_SUBMIT_SERVER,
         "--server",
         "-s",
-        help="Observatory API base URL",
+        metavar="URL",
+        help="Tournament server URL",
+        rich_help_panel="Server",
     ),
     json_output: bool = typer.Option(
         False,
         "--json",
-        help="Print the raw JSON response instead of a table",
+        help="Print raw JSON instead of table",
+        rich_help_panel="Output",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
-    """Display the tournament leaderboard for a season.
-
-    Example:
-      cogames leaderboard --season beta
-    """
     client = _get_client(login_server, server)
     if not client:
         return
 
     try:
         with client:
-            entries = client.get_leaderboard(season)
+            entries = client.get_leaderboard(season, include_hidden_seasons=True)
     except httpx.HTTPStatusError as exc:
         if exc.response.status_code == 404:
             console.print(f"[red]Season '{season}' not found[/red]")
@@ -290,30 +337,67 @@ def leaderboard_cmd(
 
 
 def seasons_cmd(
+    season_name: Optional[str] = typer.Argument(None, help="Show versions of a specific season"),
+    versions: bool = typer.Option(False, "--versions", "-v", help="List all versions of the season"),
     login_server: str = typer.Option(
         DEFAULT_COGAMES_SERVER,
         "--login-server",
-        help="Login/authentication server URL",
+        metavar="URL",
+        help="Authentication server URL",
+        rich_help_panel="Server",
     ),
     server: str = typer.Option(
         DEFAULT_SUBMIT_SERVER,
         "--server",
         "-s",
-        help="Observatory API base URL",
+        metavar="URL",
+        help="Tournament server URL",
+        rich_help_panel="Server",
     ),
     json_output: bool = typer.Option(
         False,
         "--json",
-        help="Print the raw JSON response instead of a table",
+        help="Print raw JSON instead of table",
+        rich_help_panel="Output",
+    ),
+    _help: bool = typer.Option(
+        False,
+        "--help",
+        "-h",
+        help="Show this message and exit",
+        is_eager=True,
+        callback=_help_callback,
+        rich_help_panel="Other",
     ),
 ) -> None:
-    """List available tournament seasons."""
     client = _get_client(login_server, server)
     if not client:
         return
 
     try:
         with client:
+            if season_name and versions:
+                season_versions = client.get_season_versions(season_name)
+                if json_output:
+                    console.print(json.dumps([v.model_dump() for v in season_versions], indent=2))
+                    return
+
+                if not season_versions:
+                    console.print(f"[yellow]No versions found for season '{season_name}'.[/yellow]")
+                    return
+
+                table = Table(title=f"Versions: {season_name}", box=box.SIMPLE_HEAVY, show_lines=False, pad_edge=False)
+                table.add_column("Version", style="bold cyan")
+                table.add_column("Status", style="white")
+                table.add_column("Created", style="dim")
+
+                for v in season_versions:
+                    status = "[green]canonical[/green]" if v.canonical else "[dim]historical[/dim]"
+                    table.add_row(f"v{v.version}", status, _format_timestamp(v.created_at))
+
+                console.print(table)
+                return
+
             seasons = client.get_seasons()
     except httpx.HTTPError as exc:
         console.print(f"[red]Failed to reach server:[/red] {exc}")