svc-infra 0.1.619__py3-none-any.whl → 0.1.621__py3-none-any.whl

svc_infra/cli/cmds/docs/docs_cmds.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import importlib.util
 import os
+import sys
 from importlib.metadata import PackageNotFoundError, distribution
 from pathlib import Path
 from typing import Dict, List
@@ -9,7 +11,15 @@ import click
 import typer
 from typer.core import TyperGroup
 
-from svc_infra.app.root import resolve_project_root
+
+def _norm(name: str) -> str:
+    """Normalize a topic name for stable CLI commands.
+
+    - Lowercase
+    - Replace spaces and underscores with hyphens
+    - Strip leading/trailing whitespace
+    """
+    return name.strip().lower().replace(" ", "-").replace("_", "-")
 
 
 def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
@@ -17,99 +27,192 @@ def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
     if docs_dir.exists() and docs_dir.is_dir():
         for p in sorted(docs_dir.glob("*.md")):
             if p.is_file():
-                topics[p.stem.replace(" ", "-")] = p
+                topics[_norm(p.stem)] = p
     return topics
 
 
 def _discover_pkg_topics() -> Dict[str, Path]:
     """Discover docs packaged under 'docs/' in the installed distribution.
 
-    This lets 'svc-infra docs' work from external projects that don't have a
-    local docs/ directory by falling back to files shipped in the wheel.
+    Works in external projects without a local docs/ by inspecting the wheel
+    metadata and, as a fallback, searching for a top-level docs/ next to the
+    installed package directory in site-packages.
     """
     topics: Dict[str, Path] = {}
-    try:
-        dist = distribution("svc-infra")
-    except PackageNotFoundError:
-        return topics
-
-    files = getattr(dist, "files", None) or []
-    for f in files:
-        # f is a PackagePath; string form like 'docs/topic.md'
-        s = str(f)
-        if not s.startswith("docs/") or not s.endswith(".md"):
-            continue
-        name = Path(s).stem.replace(" ", "-")
+
+    # 1) Prefer distribution metadata (RECORD) for both hyphen/underscore names
+    dist = None
+    for name in ("svc-infra", "svc_infra"):
         try:
-            abs_path = dist.locate_file(f)
-            # Ensure it's a file before adding
-            abs_p = Path(abs_path)
-            if abs_p.exists() and abs_p.is_file():
-                topics[name] = abs_p
-        except Exception:
-            # best-effort; skip unreadable entries
-            continue
+            dist = distribution(name)
+            break
+        except PackageNotFoundError:
+            dist = None
+
+    if dist is not None:
+        files = getattr(dist, "files", None) or []
+        for f in files:
+            s = str(f)
+            if not s.startswith("docs/") or not s.endswith(".md"):
+                continue
+            topic_name = _norm(Path(s).stem)
+            try:
+                abs_path = Path(dist.locate_file(f))
+                if abs_path.exists() and abs_path.is_file():
+                    topics[topic_name] = abs_path
+            except Exception:
+                # Best effort; continue to next
+                continue
+
+    # 2) Fallback: site-packages sibling 'docs/' directory (and repo-root docs in editable installs)
+    try:
+        spec = importlib.util.find_spec("svc_infra")
+        if spec and spec.submodule_search_locations:
+            pkg_dir = Path(next(iter(spec.submodule_search_locations)))
+            candidates = [
+                pkg_dir.parent / "docs",  # site-packages/docs OR src/docs
+                pkg_dir / "docs",  # site-packages/svc_infra/docs OR src/svc_infra/docs
+                pkg_dir.parent.parent
+                / "docs",  # repo-root/docs when running editable from repo (src/svc_infra → ../../docs)
+            ]
+            for candidate in candidates:
+                if candidate.exists() and candidate.is_dir():
+                    for p in sorted(candidate.glob("*.md")):
+                        if p.is_file():
+                            topics.setdefault(_norm(p.stem), p)
+                    # If one candidate had docs, that's sufficient
+                    if any(k for k in topics):
+                        break
+    except Exception:
+        # Optional fallback only
+        pass
+
+    # 3) Last-resort: scan sys.path entries that look like site-/dist-packages for a top-level docs/
+    #    directory containing markdown files. This covers non-standard installs/editable modes.
+    try:
+        if not topics:
+            for entry in sys.path:
+                try:
+                    if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
+                        continue
+                    docs_dir = Path(entry) / "docs"
+                    if docs_dir.exists() and docs_dir.is_dir():
+                        found = _discover_fs_topics(docs_dir)
+                        if found:
+                            # Merge but do not override anything already found
+                            for k, v in found.items():
+                                topics.setdefault(k, v)
+                            # If we found one valid docs dir, it's enough
+                            break
+                except Exception:
+                    continue
+    except Exception:
+        pass
+
+    # 4) Parse dist-info/RECORD or egg-info/SOURCES.txt to enumerate docs if available
+    try:
+        if not topics:
+            spec = importlib.util.find_spec("svc_infra")
+            base_dir: Path | None = None
+            if spec and spec.submodule_search_locations:
+                base_dir = Path(next(iter(spec.submodule_search_locations))).parent
+            # Fallback to first site-packages on sys.path
+            if base_dir is None:
+                for entry in sys.path:
+                    if entry and "site-packages" in entry:
+                        base_dir = Path(entry)
+                        break
+            if base_dir and base_dir.exists():
+                # Check for both hyphen and underscore dist-info names
+                candidates = list(base_dir.glob("svc_infra-*.dist-info")) + list(
+                    base_dir.glob("svc-infra-*.dist-info")
+                )
+                for di in candidates:
+                    record = di / "RECORD"
+                    if record.exists():
+                        try:
+                            for line in record.read_text(
+                                encoding="utf-8", errors="ignore"
+                            ).splitlines():
+                                rel = line.split(",", 1)[0]
+                                if rel.startswith("docs/") and rel.endswith(".md"):
+                                    abs_p = base_dir / rel
+                                    if abs_p.exists() and abs_p.is_file():
+                                        topics.setdefault(_norm(Path(rel).stem), abs_p)
+                        except Exception:
+                            continue
+                # egg-info fallback
+                if not topics:
+                    egg_candidates = list(base_dir.glob("svc_infra-*.egg-info")) + list(
+                        base_dir.glob("svc-infra-*.egg-info")
+                    )
+                    for ei in egg_candidates:
+                        sources = ei / "SOURCES.txt"
+                        if sources.exists():
+                            try:
+                                for rel in sources.read_text(
+                                    encoding="utf-8", errors="ignore"
+                                ).splitlines():
+                                    rel = rel.strip()
+                                    if rel.startswith("docs/") and rel.endswith(".md"):
+                                        abs_p = base_dir / rel
+                                        if abs_p.exists() and abs_p.is_file():
+                                            topics.setdefault(_norm(Path(rel).stem), abs_p)
+                            except Exception:
+                                continue
+    except Exception:
+        pass
+
+    # 5) Deep fallback: recursively search site-packages/dist-packages for any 'docs' folder
+    #    containing markdown files (limited depth to keep overhead reasonable).
+    try:
+        if not topics:
+            for entry in sys.path:
+                if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
+                    continue
+                base = Path(entry)
+                if not base.exists() or not base.is_dir():
+                    continue
+                base_parts = len(base.parts)
+                for root, dirs, files in os.walk(base):
+                    root_path = Path(root)
+                    # Limit search depth to avoid expensive scans
+                    if len(root_path.parts) - base_parts > 4:
+                        # prune
+                        dirs[:] = []
+                        continue
+                    if root_path.name == "docs":
+                        for p in sorted(root_path.glob("*.md")):
+                            if p.is_file():
+                                topics.setdefault(_norm(p.stem), p)
+                        # do not break; there might be multiple doc dirs
+    except Exception:
+        pass
+
     return topics
 
 
 def _resolve_docs_dir(ctx: click.Context) -> Path | None:
-    # CLI option takes precedence; walk up parent contexts because Typer
-    # executes subcommands in child contexts that do not inherit params.
-    current: click.Context | None = ctx
-    while current is not None:
-        docs_dir = (current.params or {}).get("docs_dir")
-        if docs_dir:
-            path = docs_dir if isinstance(docs_dir, Path) else Path(docs_dir)
-            path = path.expanduser()
-            if path.exists():
-                return path
-        current = current.parent
-    # Env var next
-    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
-    if env_dir:
-        p = Path(env_dir).expanduser()
-        if p.exists():
-            return p
-    # Project docs
-    root = resolve_project_root()
-    proj_docs = root / "docs"
-    if proj_docs.exists():
-        return proj_docs
+    # Deprecated: we no longer read docs from arbitrary paths or env.
+    # All docs are sourced from the packaged svc-infra distribution only.
     return None
 
 
 class DocsGroup(TyperGroup):
     def list_commands(self, ctx: click.Context) -> List[str]:
         names: List[str] = list(super().list_commands(ctx) or [])
-        dir_to_use = _resolve_docs_dir(ctx)
-        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
         pkg = _discover_pkg_topics()
-        # FS topics win on conflicts; add both for visibility
-        names.extend([k for k in fs.keys()])
-        names.extend([k for k in pkg.keys() if k not in fs])
+        names.extend([k for k in pkg.keys()])
         # Deduplicate and sort
-        uniq = sorted({*names})
-        return uniq
+        return sorted({*names})
 
     def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
-        # Built-ins first (e.g., list)
+        # Built-ins first (e.g., list, show)
         cmd = super().get_command(ctx, name)
         if cmd is not None:
             return cmd
 
-        # Dynamic topic resolution
-        dir_to_use = _resolve_docs_dir(ctx)
-        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
-        if name in fs:
-            file_path = fs[name]
-
-            @click.command(name=name)
-            def _show_fs() -> None:
-                click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
-
-            return _show_fs
-
-        # Packaged fallback
+        # Packaged topics only
         pkg = _discover_pkg_topics()
         if name in pkg:
             file_path = pkg[name]
@@ -130,55 +233,30 @@ def register(app: typer.Typer) -> None:
 
     @docs_app.callback(invoke_without_command=True)
     def _docs_options(
-        docs_dir: Path | None = typer.Option(
-            None,
-            "--docs-dir",
-            help="Path to a docs directory to read from (overrides env/project root)",
-        ),
         topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
     ) -> None:
-        """Support --docs-dir and --topic at group level."""
+        """Support --topic at group level (packaged docs only)."""
         if topic:
-            ctx = click.get_current_context()
-            dir_to_use = _resolve_docs_dir(ctx)
-            fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
-            if topic in fs:
-                typer.echo(fs[topic].read_text(encoding="utf-8", errors="replace"))
+            pkg = _discover_pkg_topics()
+            if topic in pkg:
+                typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
                 raise typer.Exit(code=0)
             raise typer.BadParameter(f"Unknown topic: {topic}")
 
     @docs_app.command("list", help="List available documentation topics")
     def list_topics() -> None:
-        ctx = click.get_current_context()
-        root = resolve_project_root()
-        dir_to_use = _resolve_docs_dir(ctx)
-        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
         pkg = _discover_pkg_topics()
 
-        # Print FS topics first (project/env/option), then packaged topics not shadowed by FS
+        # Print packaged topics only
         def _print(name: str, path: Path) -> None:
-            try:
-                rel = path.relative_to(root)
-                typer.echo(f"{name}\t{rel}")
-            except Exception:
-                # For packaged topics, path will be site-packages absolute path
-                typer.echo(f"{name}\t{path}")
+            typer.echo(f"{name}\t{path}")
 
-        for name, path in fs.items():
-            _print(name, path)
         for name, path in pkg.items():
-            if name not in fs:
-                _print(name, path)
+            _print(name, path)
 
     # Also support a generic "show" command
     @docs_app.command("show", help="Show docs for a topic (alternative to dynamic subcommand)")
     def show(topic: str) -> None:
-        ctx = click.get_current_context()
-        dir_to_use = _resolve_docs_dir(ctx)
-        fs = _discover_fs_topics(dir_to_use) if dir_to_use else {}
-        if topic in fs:
-            typer.echo(fs[topic].read_text(encoding="utf-8", errors="replace"))
-            return
         pkg = _discover_pkg_topics()
         if topic in pkg:
             typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))

{svc_infra-0.1.619.dist-info → svc_infra-0.1.621.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.619
+Version: 0.1.621
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic

{svc_infra-0.1.619.dist-info → svc_infra-0.1.621.dist-info}/RECORD

@@ -142,7 +142,7 @@ svc_infra/cli/cmds/db/sql/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJW
 svc_infra/cli/cmds/db/sql/alembic_cmds.py,sha256=uCreHg69Zf6B5gbv9Dm39jCRk6q2KQy_05A-75IP0Fg,9650
 svc_infra/cli/cmds/db/sql/sql_export_cmds.py,sha256=YpkguUJFeFApMphVkhOJllTi25ejlsQaJarMe6vJD54,2685
 svc_infra/cli/cmds/db/sql/sql_scaffold_cmds.py,sha256=MKc_T_tY1Y_wQl7XTlq8GhYWMMI1q1_vcFZVPOEcNUg,4601
-svc_infra/cli/cmds/docs/docs_cmds.py,sha256=nvqxkqeYNSV79Eeq0Kv8PN1M8CbyS3lnrFNjHNlO53w,6661
+svc_infra/cli/cmds/docs/docs_cmds.py,sha256=fbdnTEfzx3HNNXK3zL5fa_Lk3FowzHBcfS_VHQah7VQ,10720
 svc_infra/cli/cmds/dx/__init__.py,sha256=wQtl3-kOgoESlpVkjl3YFtqkOnQSIvVsOdutiaZFejM,197
 svc_infra/cli/cmds/dx/dx_cmds.py,sha256=XTKUJzS3UIYn6h3CHzDEWKYJaWn0TzGiUCq3OeW27E0,3326
 svc_infra/cli/cmds/help.py,sha256=wGfZFMYaR2ZPwW2JwKDU7M3m4AtdCd8GRQ412AmEBUM,758
@@ -296,7 +296,7 @@ svc_infra/webhooks/fastapi.py,sha256=BCNvGNxukf6dC2a4i-6en-PrjBGV19YvCWOot5lXWsA
 svc_infra/webhooks/router.py,sha256=6JvAVPMEth_xxHX-IsIOcyMgHX7g1H0OVxVXKLuMp9w,1596
 svc_infra/webhooks/service.py,sha256=hWgiJRXKBwKunJOx91C7EcLUkotDtD3Xp0RT6vj2IC0,1797
 svc_infra/webhooks/signing.py,sha256=NCwdZzmravUe7HVIK_uXK0qqf12FG-_MVsgPvOw6lsM,784
-svc_infra-0.1.619.dist-info/METADATA,sha256=yoqsuCYdTjgJVgqMPZDDVIjbd5xDW7KQ7XbNRlbsPfA,8106
-svc_infra-0.1.619.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-svc_infra-0.1.619.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
-svc_infra-0.1.619.dist-info/RECORD,,
+svc_infra-0.1.621.dist-info/METADATA,sha256=QD-ETuukvgwtsMr9N5ylyIOBUgPW6yms4kDLJbFN1H4,8106
+svc_infra-0.1.621.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.621.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.621.dist-info/RECORD,,