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

svc_infra/cli/cmds/docs/docs_cmds.py

@@ -11,36 +11,79 @@ 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.
+# ---------- small helpers ----------
 
-    - Lowercase
-    - Replace spaces and underscores with hyphens
-    - Strip leading/trailing whitespace
-    """
+
+def _norm(name: str) -> str:
     return name.strip().lower().replace(" ", "-").replace("_", "-")
 
 
-def _discover_fs_topics(docs_dir: Path) -> Dict[str, Path]:
+def _md_topics_in(dirpath: Path) -> Dict[str, Path]:
     topics: Dict[str, Path] = {}
-    if docs_dir.exists() and docs_dir.is_dir():
-        for p in sorted(docs_dir.glob("*.md")):
+    if dirpath.exists() and dirpath.is_dir():
+        for p in sorted(dirpath.glob("*.md")):
             if p.is_file():
                 topics[_norm(p.stem)] = p
     return topics
 
 
-def _discover_pkg_topics() -> Dict[str, Path]:
-    """Discover docs packaged under 'docs/' in the installed distribution.
+# ---------- where could docs live after install? ----------
 
-    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] = {}
 
-    # 1) Prefer distribution metadata (RECORD) for both hyphen/underscore names
+def _candidate_docs_dirs(ctx: click.Context) -> List[Path]:
+    """
+    Return likely directories that contain the shipped docs (*.md), ordered by priority.
+    Covers:
+      1) explicit --docs-dir / env var
+      2) in-repo (editable install):   <repo>/docs  relative to src/svc_infra
+      3) wheel installs:               <site-packages>/docs
+      4) wheel .data area:             <site-packages>/{name}-{ver}.data/**/docs
+    """
+    out: List[Path] = []
+
+    # 1) explicit override (--docs-dir or env)
+    #    Walk up parent contexts to see Typer's group option.
+    cur: click.Context | None = ctx
+    while cur is not None:
+        docs_dir_opt = (cur.params or {}).get("docs_dir")
+        if docs_dir_opt:
+            p = docs_dir_opt if isinstance(docs_dir_opt, Path) else Path(docs_dir_opt)
+            p = p.expanduser()
+            if p.exists():
+                out.append(p)
+                return out  # explicit override wins
+        cur = cur.parent
+
+    env_dir = os.getenv("SVC_INFRA_DOCS_DIR")
+    if env_dir:
+        p = Path(env_dir).expanduser()
+        if p.exists():
+            out.append(p)
+            return out  # explicit override wins
+
+    # locate installed package dir: .../site-packages/svc_infra
+    pkg_dir: Path | None = None
+    spec = importlib.util.find_spec("svc_infra")
+    if spec and spec.submodule_search_locations:
+        pkg_dir = Path(next(iter(spec.submodule_search_locations)))
+
+    # 2) in-repo editable install: src/svc_infra -> ../../docs
+    if pkg_dir:
+        repo_root_docs = pkg_dir.parent.parent / "docs"
+        if repo_root_docs.exists():
+            out.append(repo_root_docs)
+
+        # 3) wheel installs often end up with a top-level site-packages/docs
+        top_level_docs = pkg_dir.parent / "docs"
+        if top_level_docs.exists():
+            out.append(top_level_docs)
+
+    # 4) wheel .data layout: <site-packages>/{dist-name}-{version}.data/**/docs
+    #    This catches Poetry's include=docs/**/* paths installed by pip.
+    #    We compute sibling candidates off site-packages base.
+    site_pkgs: Path | None = pkg_dir.parent if pkg_dir else None
     dist = None
     for name in ("svc-infra", "svc_infra"):
         try:
@@ -49,217 +92,133 @@ def _discover_pkg_topics() -> Dict[str, Path]:
         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
+    if site_pkgs and dist is not None:
+        # normalized dist name (hyphen/underscore forms both happen in practice)
+        dist_name = dist.metadata.get("Name", "svc-infra")
+        dist_ver = dist.version
+        data_candidates = [
+            site_pkgs / f"{dist_name}-{dist_ver}.data",
+            site_pkgs / f"{dist_name.replace('-', '_')}-{dist_ver}.data",
+            site_pkgs / f"{dist_name.replace('_', '-')}-{dist_ver}.data",
+        ]
+        for data_dir in data_candidates:
+            if not data_dir.exists():
                 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():
+            # common wheel data subfolders
+            for sub in ("purelib", "platlib", "data"):
+                d = data_dir / sub / "docs"
+                if d.exists():
+                    out.append(d)
+            # fallback: search shallowly for any docs/ folder inside .data
+            for root, dirs, _files in os.walk(data_dir):
+                root_path = Path(root)
+                # limit depth (cheap)
+                if len(root_path.parts) - len(data_dir.parts) > 3:
+                    dirs[:] = []
                     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
-
+                if root_path.name == "docs":
+                    out.append(root_path)
+
+    # 5) extremely defensive: scan sys.path entries that look like site-/dist-packages for top-level docs/
+    for entry in sys.path:
+        if not entry or ("site-packages" not in entry and "dist-packages" not in entry):
+            continue
+        p = Path(entry) / "docs"
+        if p.exists():
+            out.append(p)
+
+    # de-dup while preserving order
+    seen = set()
+    uniq: List[Path] = []
+    for p in out:
+        if p.exists():
+            key = str(p.resolve())
+            if key not in seen:
+                seen.add(key)
+                uniq.append(p)
+    return uniq
+
+
+def _discover_topics(ctx: click.Context) -> Dict[str, Path]:
+    topics: Dict[str, Path] = {}
+    for d in _candidate_docs_dirs(ctx):
+        found = _md_topics_in(d)
+        # do not override earlier (higher-priority) sources
+        for k, v in found.items():
+            topics.setdefault(k, v)
+        if topics:
+            # one dir with content is enough for most setups
+            # (comment out this break if you *want* deep merging)
+            break
     return topics
 
 
-def _resolve_docs_dir(ctx: click.Context) -> Path | None:
-    # Deprecated: we no longer read docs from arbitrary paths or env.
-    # All docs are sourced from the packaged svc-infra distribution only.
-    return None
+# ---------- Typer group ----------
 
 
 class DocsGroup(TyperGroup):
     def list_commands(self, ctx: click.Context) -> List[str]:
-        names: List[str] = list(super().list_commands(ctx) or [])
-        pkg = _discover_pkg_topics()
-        names.extend([k for k in pkg.keys()])
-        # Deduplicate and sort
-        return sorted({*names})
+        topics = _discover_topics(ctx)
+        return sorted(topics.keys())
 
     def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
-        # Built-ins first (e.g., list, show)
         cmd = super().get_command(ctx, name)
         if cmd is not None:
             return cmd
 
-        # Packaged topics only
-        pkg = _discover_pkg_topics()
-        if name in pkg:
-            file_path = pkg[name]
+        key = _norm(name)
+        topics = _discover_topics(ctx)
+        if key in topics:
+            file_path = topics[key]
 
             @click.command(name=name)
-            def _show_pkg() -> None:
+            def _show() -> None:
                 click.echo(file_path.read_text(encoding="utf-8", errors="replace"))
 
-            return _show_pkg
+            return _show
 
         return None
 
 
 def register(app: typer.Typer) -> None:
-    """Register the `docs` command group with dynamic topic subcommands."""
-
     docs_app = typer.Typer(no_args_is_help=True, add_completion=False, cls=DocsGroup)
 
     @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 packaged docs)",
+        ),
         topic: str | None = typer.Option(None, "--topic", help="Topic to show directly"),
     ) -> None:
-        """Support --topic at group level (packaged docs only)."""
         if topic:
-            pkg = _discover_pkg_topics()
-            if topic in pkg:
-                typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
+            key = _norm(topic)
+            topics = _discover_topics(click.get_current_context())
+            if key in topics:
+                typer.echo(topics[key].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:
-        pkg = _discover_pkg_topics()
-
-        # Print packaged topics only
-        def _print(name: str, path: Path) -> None:
-            typer.echo(f"{name}\t{path}")
+        ctx = click.get_current_context()
+        root = resolve_project_root()
+        topics = _discover_topics(ctx)
 
-        for name, path in pkg.items():
-            _print(name, path)
+        for name, path in topics.items():
+            try:
+                rel = path.relative_to(root)
+                typer.echo(f"{name}\t{rel}")
+            except Exception:
+                typer.echo(f"{name}\t{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:
-        pkg = _discover_pkg_topics()
-        if topic in pkg:
-            typer.echo(pkg[topic].read_text(encoding="utf-8", errors="replace"))
+        key = _norm(topic)
+        topics = _discover_topics(click.get_current_context())
+        if key in topics:
+            typer.echo(topics[key].read_text(encoding="utf-8", errors="replace"))
             return
         raise typer.BadParameter(f"Unknown topic: {topic}")
 

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

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

{svc_infra-0.1.621.dist-info → svc_infra-0.1.622.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=fbdnTEfzx3HNNXK3zL5fa_Lk3FowzHBcfS_VHQah7VQ,10720
+svc_infra/cli/cmds/docs/docs_cmds.py,sha256=zauAUG04yI3qbGXSyb5p_UhvvHvXSvirx1fuaA6HMOI,7816
 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.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,,
+svc_infra-0.1.622.dist-info/METADATA,sha256=GrIXBicqMBcCZRf97UzGyQwQJmCl_9eRKXJzfTfmvdE,8106
+svc_infra-0.1.622.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
+svc_infra-0.1.622.dist-info/entry_points.txt,sha256=6x_nZOsjvn6hRZsMgZLgTasaCSKCgAjsGhACe_CiP0U,48
+svc_infra-0.1.622.dist-info/RECORD,,