scikit-view 0.0.4__tar.gz

scikit_view-0.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 兮尘
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scikit_view-0.0.4/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: scikit-view
+Version: 0.0.4
+Summary: science viewer kit for coding agents
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,framework,AI,tool,skill,plugin,toolkit,library,python
+Author: Xueyuan Lin
+Author-email: linxy59@mail2.sysu.edu.cn
+Requires-Python: >=3.10
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.1.0)
+Requires-Dist: loguru (>=0.7.0)
+Requires-Dist: stevedore (>=5.0.0)
+Project-URL: Homepage, https://linxueyuan.online/scikit-view
+Project-URL: Repository, https://github.com/LinXueyuanStdio/scikit-view
+Description-Content-Type: text/markdown
+
+# scikit
+universal science kit for coding agents
+

scikit_view-0.0.4/README.md

@@ -0,0 +1,2 @@
+# scikit
+universal science kit for coding agents

scikit_view-0.0.4/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "scikit-view"
+version = "0.0.4"
+description = "science viewer kit for coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Xueyuan Lin", email = "linxy59@mail2.sysu.edu.cn" },
+]
+
+[tool.poetry]
+name = "scikit-view"
+version = "0.0.4"
+description = "science viewer kit for coding agents"
+authors = ["Xueyuan Lin <linxy59@mail2.sysu.edu.cn>"]
+packages = [{ include = "scikit_view" }]
+homepage = "https://linxueyuan.online/scikit-view"
+repository = "https://github.com/LinXueyuanStdio/scikit-view"
+keywords = ["agent", "framework", "AI", "tool", "skill", "plugin", "toolkit", "library", "python"]
+classifiers = [
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.poetry.scripts]
+scikit-view = "scikit_view.__main__:main"
+sv = "scikit_view.__main__:main"
+
+[tool.poetry.dependencies]
+
+stevedore = ">=5.0.0"
+click = ">=8.1.0"
+loguru = ">=0.7.0"

scikit_view-0.0.4/scikit_view/__init__.py

@@ -0,0 +1,26 @@
+"""scikit — produce agent-readable views of scientific files.
+
+The public surface is deliberately small: a :func:`view` entry point, the
+:class:`Viewer` contract plugins implement, the :class:`ViewResult` returned
+on success, and the exception types the call can raise.
+"""
+
+from .api import view
+from .types import (
+    NoViewerFound,
+    OutputDirNotEmpty,
+    ScikitError,
+    ViewFailed,
+    Viewer,
+    ViewResult,
+)
+
+__all__ = [
+    "view",
+    "Viewer",
+    "ViewResult",
+    "ScikitError",
+    "NoViewerFound",
+    "ViewFailed",
+    "OutputDirNotEmpty",
+]

scikit_view-0.0.4/scikit_view/__main__.py

@@ -0,0 +1,11 @@
+"""Console entry point for ``scikit``."""
+
+from .cli import cli
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

scikit_view-0.0.4/scikit_view/api.py

@@ -0,0 +1,117 @@
+"""The public ``view()`` entry point and its output-directory handling."""
+
+import shutil
+from pathlib import Path
+from typing import Optional
+
+from .registry import Registry
+from .types import OutputDirNotEmpty, ScikitError, ViewFailed, Viewer, ViewResult
+
+DEFAULT_ROOT = Path(".scikit") / "files"
+
+
+def default_output_dir(source: Path) -> Path:
+    """The default output directory for ``source``: ``./.scikit/files/<name>/``."""
+    name = source.name
+    if not name:
+        raise ScikitError(
+            f"Cannot derive an output directory for {str(source)!r}: it has no file name"
+        )
+    return DEFAULT_ROOT / name
+
+
+def _clear_dir(path: Path) -> None:
+    """Remove ``path``, never following a symlink to its target."""
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+    elif path.is_dir():
+        shutil.rmtree(path)
+
+
+def _is_empty(path: Path) -> bool:
+    return path.is_dir() and not any(path.iterdir())
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    return path.resolve().is_relative_to(root.resolve())
+
+
+def resolve_output_dir(
+    source: Path,
+    output_dir: Optional[Path],
+    force: bool,
+) -> Path:
+    """Resolve the output directory, applying the rebuild/overwrite rules.
+
+    scikit-owned directories (under ``.scikit/files/``) are rebuilt freely;
+    user-specified directories are only overwritten with ``force``. Clearing a
+    scikit-owned directory that resolves outside ``.scikit/files/`` (e.g. via a
+    symlink) is refused.
+    """
+    source = Path(source)
+
+    if output_dir is None:
+        outdir = default_output_dir(source)
+        if outdir.exists():
+            if not _is_within(outdir, DEFAULT_ROOT):
+                raise ScikitError(
+                    f"Refusing to clear {outdir}: it resolves outside {DEFAULT_ROOT}"
+                )
+            _clear_dir(outdir)
+        outdir.mkdir(parents=True, exist_ok=True)
+        return outdir
+
+    outdir = Path(output_dir)
+    if outdir.exists() and not _is_empty(outdir):
+        if not force:
+            raise OutputDirNotEmpty(
+                f"Output directory {outdir} is not empty; pass force=True to overwrite"
+            )
+        _clear_dir(outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    return outdir
+
+
+def build_view(source: Path, output_dir: Path, viewer_obj: Viewer) -> ViewResult:
+    """Run ``viewer_obj``, write its markdown to ``index.md`` and collect artifacts."""
+    source = Path(source)
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        markdown = viewer_obj.view(source, output_dir)
+    except Exception as exc:
+        raise ViewFailed(f"viewer {viewer_obj.name!r} failed on {str(source)!r}") from exc
+
+    markdown_path = output_dir / "index.md"
+    markdown_path.write_text(markdown, encoding="utf-8")
+
+    artifacts = tuple(sorted(p for p in output_dir.rglob("*") if p.is_file()))
+    return ViewResult(
+        source=source,
+        output_dir=output_dir,
+        viewer=viewer_obj.name,
+        markdown_path=markdown_path,
+        artifacts=artifacts,
+    )
+
+
+def view(
+    source,
+    output_dir=None,
+    *,
+    viewer: Optional[str] = None,
+    force: bool = False,
+    registry: Optional[Registry] = None,
+) -> ViewResult:
+    """Produce an agent-readable view of ``source``.
+
+    Selects a viewer (routing, or the explicit ``viewer`` name), resolves the
+    output directory, runs the viewer and returns a :class:`ViewResult`.
+    """
+    if registry is None:
+        registry = Registry()
+    source = Path(source)
+    viewer_obj = registry.select(source, requested=viewer)
+    resolved = resolve_output_dir(source, output_dir, force)
+    return build_view(source, resolved, viewer_obj)

scikit_view-0.0.4/scikit_view/cli.py

@@ -0,0 +1,66 @@
+"""The ``scikit`` command-line interface."""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+import click
+
+from .api import view as _run_view
+from .types import NoViewerFound, OutputDirNotEmpty, ScikitError, ViewFailed, ViewResult
+
+
+def _fail(exc: ScikitError, code: int) -> None:
+    click.echo(str(exc), err=True)
+    raise click.exceptions.Exit(code)
+
+
+def _result_to_dict(result: ViewResult) -> dict:
+    return {
+        "source": str(result.source),
+        "output_dir": str(result.output_dir),
+        "viewer": result.viewer,
+        "markdown_path": str(result.markdown_path),
+        "artifacts": [str(a) for a in result.artifacts],
+    }
+
+
+@click.group(name="scikit")
+def cli() -> None:
+    """Produce agent-readable views of scientific files."""
+
+
+@cli.command()
+@click.argument("source", type=click.Path(path_type=Path))
+@click.option("-o", "--output-dir", type=click.Path(path_type=Path), default=None)
+@click.option("--viewer", default=None)
+@click.option("--force", is_flag=True, default=False)
+@click.option("--json", "as_json", is_flag=True, default=False)
+def view(
+    source: Path,
+    output_dir: Optional[Path],
+    viewer: Optional[str],
+    force: bool,
+    as_json: bool,
+) -> None:
+    """Produce an agent-readable view of SOURCE (markdown on stdout by default)."""
+    try:
+        result = _run_view(source, output_dir=output_dir, viewer=viewer, force=force)
+    except NoViewerFound as exc:
+        _fail(exc, 3)
+    except OutputDirNotEmpty as exc:
+        _fail(exc, 4)
+    except ViewFailed as exc:
+        _fail(exc, 1)
+    except ScikitError as exc:
+        _fail(exc, 1)
+
+    if as_json:
+        click.echo(json.dumps(_result_to_dict(result), indent=2))
+    else:
+        click.echo(result.markdown_path.read_text(encoding="utf-8"))
+
+    click.echo(
+        f"viewer={result.viewer} artifacts={len(result.artifacts)} output={result.output_dir}",
+        err=True,
+    )

scikit_view-0.0.4/scikit_view/registry.py

@@ -0,0 +1,88 @@
+"""Viewer discovery and routing.
+
+Discovery is delegated to stevedore (setuptools entry points under the
+``scikit.viewers`` namespace). Routing is a pure function so it can be tested
+without a real entry-point environment.
+"""
+
+from pathlib import Path
+from typing import Iterable, Optional
+
+from loguru import logger
+from stevedore.extension import ExtensionManager
+
+from .types import NoViewerFound, Viewer
+
+NAMESPACE = "scikit.viewers"
+
+
+def select_viewer(
+    viewers: Iterable[Viewer],
+    source: Path,
+    requested: Optional[str] = None,
+) -> Viewer:
+    """Pick the viewer that should handle ``source``.
+
+    An explicit ``requested`` name bypasses routing entirely: ``can_view`` is
+    not consulted and the viewer runs even if it would say no. Otherwise
+    viewers are ordered by ``(-priority, name)`` and the first whose
+    ``can_view`` returns True wins.
+
+    A ``can_view`` that raises is logged and treated as ``False`` so a broken
+    viewer cannot take down routing for everyone else.
+    """
+    viewers = list(viewers)
+    available = ", ".join(sorted(v.name for v in viewers))
+
+    if requested is not None:
+        for viewer in viewers:
+            if viewer.name == requested:
+                return viewer
+        raise NoViewerFound(
+            f"No viewer named {requested!r}. Available: {available or '(none)'}"
+        )
+
+    ordered = sorted(viewers, key=lambda v: (-v.priority, v.name))
+    for viewer in ordered:
+        try:
+            if viewer.can_view(source):
+                return viewer
+        except Exception as exc:  # noqa: BLE001 - a broken viewer must not break routing
+            logger.warning("viewer {!r}.can_view() raised: {}", viewer.name, exc)
+
+    raise NoViewerFound(
+        f"No viewer can handle {str(source)!r}. Available: {available or '(none)'}"
+    )
+
+
+class Registry:
+    """Loads viewers from entry points and remembers load failures."""
+
+    def __init__(self, namespace: str = NAMESPACE):
+        self.namespace = namespace
+        self._failed: list[tuple[str, Exception]] = []
+        self._manager = ExtensionManager(
+            namespace,
+            invoke_on_load=True,
+            on_load_failure_callback=self._on_load_failure,
+        )
+
+    def _on_load_failure(self, manager, entrypoint, exception):
+        self._failed.append((entrypoint.name, exception))
+
+    @property
+    def viewers(self) -> list[Viewer]:
+        return [ext.obj for ext in self._manager.extensions]
+
+    @property
+    def failed(self) -> list[tuple[str, Exception]]:
+        return list(self._failed)
+
+    def select(self, source: Path, requested: Optional[str] = None) -> Viewer:
+        try:
+            return select_viewer(self.viewers, source, requested)
+        except NoViewerFound as exc:
+            if self._failed:
+                detail = "; ".join(f"{name}: {err}" for name, err in self._failed)
+                raise NoViewerFound(f"{exc}\nLoad failures: {detail}") from exc
+            raise

scikit_view-0.0.4/scikit_view/types.py

@@ -0,0 +1,64 @@
+"""Core types for the scikit view framework.
+
+This module defines the contract a viewer author implements, the result the
+core builds, and the exception hierarchy callers branch on. It deliberately
+contains no logic beyond that contract — routing, output-dir handling and the
+CLI live elsewhere.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class ScikitError(Exception):
+    """Base class for all scikit errors. Catch this to handle them at once."""
+
+
+class NoViewerFound(ScikitError):
+    """No viewer can handle the source, or the requested viewer name is unknown."""
+
+
+class ViewFailed(ScikitError):
+    """A viewer claimed the source but failed to produce a view."""
+
+
+class OutputDirNotEmpty(ScikitError):
+    """A user-specified output directory is non-empty and force is not set."""
+
+
+class Viewer(ABC):
+    """Abstract base class a viewer implements.
+
+    A viewer turns one source file into an agent-readable markdown view,
+    writing any accompanying images into ``output_dir``.
+    """
+
+    #: Unique viewer name, used for explicit selection (``--viewer``).
+    name: str
+    #: Routing priority; higher is consulted first. Ties broken by name.
+    priority: int = 0
+
+    @abstractmethod
+    def can_view(self, source: Path) -> bool:
+        """Return True if this viewer can handle ``source``."""
+
+    @abstractmethod
+    def view(self, source: Path, output_dir: Path) -> str:
+        """Produce the view.
+
+        Write images/attachments into ``output_dir`` and return the markdown
+        text. Attachments must be referenced with paths relative to
+        ``output_dir`` so the directory can be moved as a whole.
+        """
+
+
+@dataclass(frozen=True)
+class ViewResult:
+    """The outcome of a successful ``view()`` call, built entirely by the core."""
+
+    source: Path
+    output_dir: Path
+    viewer: str
+    markdown_path: Path
+    artifacts: tuple[Path, ...]