pythonlings 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

pythonlings/cli.py

@@ -6,6 +6,8 @@ import sys
 from importlib.metadata import PackageNotFoundError, version as _package_version
 from pathlib import Path
 
+from pythonlings.core.workspace import default_workspace_root
+
 try:
     __version__ = _package_version("pythonlings")
 except PackageNotFoundError:  # running from a source checkout without an install
@@ -21,19 +23,19 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "--root",
         type=Path,
-        default=Path.cwd(),
-        help="Project root containing info.toml (default: cwd).",
+        default=None,
+        help="Workspace root containing info.toml (default: auto-resolve).",
     )
     sub = parser.add_subparsers(dest="command")
 
     p_init = sub.add_parser("init", help="Create a pythonlings workspace.")
-    p_init.add_argument("--path", type=Path, default=Path.cwd())
+    p_init.add_argument("--path", type=Path, default=default_workspace_root())
     p_init.add_argument(
         "--force", action="store_true", help="Overwrite managed workspace files."
     )
 
     p_update = sub.add_parser("update", help="Update an existing pythonlings workspace.")
-    p_update.add_argument("--path", type=Path, default=Path.cwd())
+    p_update.add_argument("--path", type=Path, default=default_workspace_root())
 
     sub.add_parser("watch", help="Launch the TUI in watch mode (default).")
     sub.add_parser("topics", help="Launch the TUI on the topic picker.")
@@ -70,6 +72,14 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
+def _display_path(path: Path) -> str:
+    """Render `path` with a leading `~/` when inside the home directory."""
+    try:
+        return "~/" + str(path.relative_to(Path.home()))
+    except ValueError:
+        return str(path)
+
+
 def _resolve_topic(manifest, topic: str):
     """Return the topic name if valid, else write an error and return None."""
     if topic in manifest.topics():
@@ -83,13 +93,18 @@ def _resolve_topic(manifest, topic: str):
 
 def _cmd_init(path: Path, force: bool) -> int:
     from pythonlings.core.curriculum import WorkspaceError, init_workspace
+    from pythonlings.core.workspace import is_workspace
 
+    path = path.expanduser().resolve()
+    if is_workspace(path) and not force:
+        print(f"Already set up at {path} — just run `pythonlings`")
+        return 0
     try:
         root = init_workspace(path, force=force)
     except WorkspaceError as e:
         sys.stderr.write(f"pythonlings: {e}\n")
         return 1
-    print(f"initialized: {root}")
+    print(f"Created your workspace at {_display_path(root)}")
     return 0
 
 
@@ -258,19 +273,29 @@ def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv if argv is not None else sys.argv[1:])
 
-    # Migrate any legacy .pylings/ state dir. init/update target --path; the
-    # in-workspace commands target --root. Both are no-ops without a legacy dir.
     from pythonlings.core.curriculum import migrate_legacy_state_dir
-
-    for attr in ("path", "root"):
-        workspace = getattr(args, attr, None)
-        if workspace is not None:
-            migrate_legacy_state_dir(Path(workspace))
+    from pythonlings.core.workspace import resolve_workspace_root
 
     try:
-        if getattr(args, "debug", False):
+        root: Path | None = None
+        if args.command in ("init", "update"):
+            migrate_legacy_state_dir(Path(args.path))
+        else:
+            launches_tui = args.command in (None, "watch", "start", "topics")
+            resolved = resolve_workspace_root(
+                Path.cwd(), args.root, create_if_missing=launches_tui
+            )
+            root = resolved.root
+            migrate_legacy_state_dir(root)
+            if resolved.created:
+                print(
+                    f"Created your workspace at {_display_path(root)} "
+                    "(edit in-app, or open that folder in your editor)"
+                )
+
+        if getattr(args, "debug", False) and root is not None:
             try:
-                (args.root / ".pythonlings_debug.log").write_text(
+                (root / ".pythonlings_debug.log").write_text(
                     f"argv={argv if argv is not None else sys.argv[1:]!r}\n",
                     encoding="utf-8",
                 )
@@ -282,30 +307,31 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "update":
             return _cmd_update(args.path)
 
+        assert root is not None
         if args.command == "verify":
-            return _cmd_verify(args.root, args.topic)
+            return _cmd_verify(root, args.topic)
         if args.command == "list":
-            return _cmd_list(args.root, args.topic)
+            return _cmd_list(root, args.topic)
         if args.command == "hint":
-            return _cmd_hint(args.root, args.name)
+            return _cmd_hint(root, args.name)
         if args.command == "run":
-            return _cmd_run(args.root, args.name)
+            return _cmd_run(root, args.name)
         if args.command == "dry-run":
-            return _cmd_run(args.root, args.name)
+            return _cmd_run(root, args.name)
         if args.command in {"solution", "sol"}:
-            return _cmd_solution(args.root, args.name)
+            return _cmd_solution(root, args.name)
         if args.command == "reset":
-            return _cmd_reset(args.root, args.name, args.yes)
+            return _cmd_reset(root, args.name, args.yes)
 
         if args.command in (None, "watch", "start", "topics"):
             start_topic = getattr(args, "topic", None)
             if start_topic is not None:
                 from pythonlings.core.manifest import load as load_manifest
-                if _resolve_topic(load_manifest(args.root), start_topic) is None:
+                if _resolve_topic(load_manifest(root), start_topic) is None:
                     return 2
             from pythonlings.app import run_tui  # lazy: Textual is heavy
             return run_tui(
-                args.root,
+                root,
                 start_topic,
                 force_picker=args.command == "topics",
             )

pythonlings/core/curriculum.py

@@ -79,7 +79,10 @@ def _sync_originals(root: Path, src_root: Path) -> None:
 def init_workspace(path: Path, *, force: bool = False) -> Path:
     path = path.expanduser().resolve()
     if path.exists() and any(path.iterdir()) and not force:
-        raise WorkspaceError(f"{path} already exists and is not empty")
+        raise WorkspaceError(
+            f"{path} isn't empty and isn't a pythonlings workspace. "
+            "Pick another location with --path <dir>, or --force to set up here anyway."
+        )
     path.mkdir(parents=True, exist_ok=True)
 
     src_root = source_root()

pythonlings/core/manifest.py

@@ -50,7 +50,7 @@ def load(root: Path) -> Manifest:
     info_path = root / "info.toml"
     if not info_path.exists():
         raise ManifestError(
-            f"no pythonlings workspace here ({info_path} not found). "
+            f"no pythonlings workspace at {root} (info.toml not found). "
             "Run 'pythonlings init' to create one."
         )
 

pythonlings/core/workspace.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from pythonlings.core.curriculum import init_workspace
+
+
+@dataclass(frozen=True)
+class ResolvedWorkspace:
+    root: Path
+    created: bool
+
+
+def default_workspace_root() -> Path:
+    """Where a no-argument `pythonlings` keeps its workspace.
+
+    `PYTHONLINGS_HOME` overrides; otherwise a hidden `~/.pythonlings`.
+    """
+    env = os.environ.get("PYTHONLINGS_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+    return (Path.home() / ".pythonlings").resolve()
+
+
+def is_workspace(path: Path) -> bool:
+    """True if `path` is a pythonlings workspace (has an `info.toml`)."""
+    return (path / "info.toml").is_file()
+
+
+def resolve_workspace_root(
+    cwd: Path,
+    explicit_root: Path | None = None,
+    *,
+    create_if_missing: bool = False,
+) -> ResolvedWorkspace:
+    """Pick the workspace root for a command.
+
+    Order: an explicit `--root`, then the current directory if it is a
+    workspace, then the default home workspace, then (only when
+    `create_if_missing`) a freshly created home workspace.
+    """
+    if explicit_root is not None:
+        return ResolvedWorkspace(explicit_root.expanduser().resolve(), created=False)
+
+    cwd = cwd.resolve()
+    if is_workspace(cwd):
+        return ResolvedWorkspace(cwd, created=False)
+
+    home = default_workspace_root()
+    if is_workspace(home):
+        return ResolvedWorkspace(home, created=False)
+
+    if create_if_missing:
+        return ResolvedWorkspace(init_workspace(home), created=True)
+    return ResolvedWorkspace(home, created=False)

{pythonlings-0.3.1.dist-info → pythonlings-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythonlings
-Version: 0.3.1
+Version: 0.4.0
 Summary: Python learnings, Rustlings-style, in a terminal TUI.
 Project-URL: Homepage, https://github.com/abhiksark/pythonlings
 Project-URL: Repository, https://github.com/abhiksark/pythonlings
@@ -55,14 +55,13 @@ Python documentation snippets so learners can work without leaving the terminal.
 and [uv](https://docs.astral.sh/uv/):
 
 ```bash
-uvx pythonlings init --path ./learn-python
-cd learn-python && uvx pythonlings
+uvx pythonlings
 ```
 
 How it works: **edit** the broken exercise in the built-in editor → checks
 rerun as you type and advance you to the next one. That's the whole loop.
 
-Status: `v0.3.1`, alpha — published on PyPI as `pythonlings`.
+Status: `v0.4.0`, alpha — published on PyPI as `pythonlings`.
 
 ![Coding screen](docs/assets/screenshots/coding-screen.png)
 
@@ -84,8 +83,9 @@ Status: `v0.3.1`, alpha — published on PyPI as `pythonlings`.
 
 ## What Happens When You Run It
 
-1. `pythonlings init` creates a self-contained learner workspace with exercises,
-   hidden checks, local docs, and original snapshots for reset.
+1. `pythonlings` with no workspace creates a self-contained one at
+   `~/.pythonlings` (override with `PYTHONLINGS_HOME` or `pythonlings init
+   --path <dir>`) and opens the first exercise.
 2. `pythonlings` opens the first pending exercise in the terminal UI.
 3. You edit the broken code, remove `# I AM NOT DONE`, and checks rerun as you
    work.

{pythonlings-0.3.1.dist-info → pythonlings-0.4.0.dist-info}/RECORD

@@ -1,16 +1,17 @@
 pythonlings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pythonlings/__main__.py,sha256=uSvclvHiv4C9zXiw2cdtV_56ba4i6VeKB0wyCd06k-s,90
 pythonlings/app.py,sha256=aaj3CtSP08_fN8d7OZxHccC8A1TQOcqZkE5BGncQmmg,2605
-pythonlings/cli.py,sha256=UtsMFibL5_ZwTRW6e9ZYT9hXv4yG9w3m_5CCSjCg7wU,10838
+pythonlings/cli.py,sha256=BJ5zR3WCP0loUH5TlmOwJdQi3bL2r8cVUkRqmLGE7h4,11809
 pythonlings/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pythonlings/core/curriculum.py,sha256=VM4Z854vY-Udq511-7DHv1scPgvji0wTQnJkItmOMvQ,3449
+pythonlings/core/curriculum.py,sha256=cPlHYHXu95X24YjB_aNMC7H2EkYSlYXKYF7JFFpKBU8,3576
 pythonlings/core/docs.py,sha256=caRAYtu-bYd7qetL9ZfgBOVcFRR0SyI0hfXPP5_VDtQ,1892
 pythonlings/core/exercise.py,sha256=V_LVXXcdS7JLplGGCdZv54rYxAhxCTiG8v7wcViFI2o,652
-pythonlings/core/manifest.py,sha256=HpFZ3pDcUxt62yZERGuIx9bs-xqaz6QKt3BCcnhi-xQ,3453
+pythonlings/core/manifest.py,sha256=gg0LiSYgJy7mTGCnKVY-8es2KUC0y9F6MCx9hWObyBo,3456
 pythonlings/core/reset.py,sha256=tqrwbjU-1V0q4fHAny0NrwK_IVAU4rHhziWtaaS5X1k,1414
 pythonlings/core/runner.py,sha256=h7JX7FGIzGa5cuggEOJN4nov2u7BDiuURpEfV-si0oM,3745
 pythonlings/core/solutions.py,sha256=06srf3SNjTnBn4u0QGk55-Tjjt9SfnxsUigD7JnD4rE,507
 pythonlings/core/state.py,sha256=0CGLIBwaZH86QjmacjX60jCkjrY8bYNOsTUpMHvsOmE,2532
+pythonlings/core/workspace.py,sha256=A29P7dUSQezfzSOxAsnvCsS8c0gWrabz_BrRf9lge4U,1629
 pythonlings/docs/NOTICE.md,sha256=t9FfUSDE2wT5amf3PYI1Vs8CLYUVtzPq0PdArvmtss4,450
 pythonlings/docs/__init__.py,sha256=Oj4hwHUM_Ssj-1vs8U52o491Ogy2mDbas7Y8q_dw3UY,51
 pythonlings/docs/index.json,sha256=BlKHcCw9N9oNP0qfVi230QtTzZ_jUc_MA17b0ITpB8k,5422
@@ -935,8 +936,8 @@ pythonlings/curriculum/solutions/variables6.py,sha256=7UIUOJNTTWft93V4pDFNZlriym
 pythonlings/curriculum/solutions/variables7.py,sha256=7UIUOJNTTWft93V4pDFNZlriymc-fjEhdWotp8wxIWo,64
 pythonlings/curriculum/solutions/variables8.py,sha256=7UIUOJNTTWft93V4pDFNZlriymc-fjEhdWotp8wxIWo,64
 pythonlings/curriculum/solutions/variables9.py,sha256=7UIUOJNTTWft93V4pDFNZlriymc-fjEhdWotp8wxIWo,64
-pythonlings-0.3.1.dist-info/METADATA,sha256=-4kMLeSYt69qsvsjOsRRg1KiCqDv1a_LOq4H_mPBVto,9542
-pythonlings-0.3.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-pythonlings-0.3.1.dist-info/entry_points.txt,sha256=x3HLcXJL_k5cqbwij4PL_Rr-q_BsBbm2ofJHMpeFbr8,53
-pythonlings-0.3.1.dist-info/licenses/LICENSE,sha256=FV2UAm_ETO065zJVIcDAWp2kWCShPts33fXrNASIMXs,1069
-pythonlings-0.3.1.dist-info/RECORD,,
+pythonlings-0.4.0.dist-info/METADATA,sha256=Sfph4XHU6h336Y2lCOelPaFMlsrWVk1NFjAbzkknhaY,9525
+pythonlings-0.4.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pythonlings-0.4.0.dist-info/entry_points.txt,sha256=x3HLcXJL_k5cqbwij4PL_Rr-q_BsBbm2ofJHMpeFbr8,53
+pythonlings-0.4.0.dist-info/licenses/LICENSE,sha256=FV2UAm_ETO065zJVIcDAWp2kWCShPts33fXrNASIMXs,1069
+pythonlings-0.4.0.dist-info/RECORD,,