datbox-core 0.0.1__tar.gz

datbox_core-0.0.1/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.duckdb
+*.sqlite
+.env
+.env.*
+!.env.example
+.idea/
+.vscode/
+.DS_Store

datbox_core-0.0.1/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.5
+Name: datbox-core
+Version: 0.0.1
+Summary: Core of the Data Analyst Toolbox: the `dat` CLI, plugin registry, config, secrets, and output writers.
+Project-URL: Homepage, https://github.com/nick-hebert/datbox
+Project-URL: Repository, https://github.com/nick-hebert/datbox
+Project-URL: Issues, https://github.com/nick-hebert/datbox/issues
+Author: Nick Hebert
+License-Expression: Apache-2.0
+Keywords: analytics,cli,data,toolbox
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.7
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# datbox-core
+
+The core of **dat**, the Data Analyst Toolbox. Provides the `dat` command-line entry point
+and the plugin registry that other `datbox-*` packages register their subcommands with.
+
+```bash
+pip install datbox-core
+dat --help
+```
+
+Other modules (`datbox-viz`, `datbox-fake`, ...) add subcommands automatically when installed.

datbox_core-0.0.1/README.md

@@ -0,0 +1,11 @@
+# datbox-core
+
+The core of **dat**, the Data Analyst Toolbox. Provides the `dat` command-line entry point
+and the plugin registry that other `datbox-*` packages register their subcommands with.
+
+```bash
+pip install datbox-core
+dat --help
+```
+
+Other modules (`datbox-viz`, `datbox-fake`, ...) add subcommands automatically when installed.

datbox_core-0.0.1/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "datbox-core"
+version = "0.0.1"
+description = "Core of the Data Analyst Toolbox: the `dat` CLI, plugin registry, config, secrets, and output writers."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+authors = [{ name = "Nick Hebert" }]
+keywords = ["data", "analytics", "cli", "toolbox"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "typer>=0.12",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/nick-hebert/datbox"
+Repository = "https://github.com/nick-hebert/datbox"
+Issues = "https://github.com/nick-hebert/datbox/issues"
+
+[project.scripts]
+dat = "datbox_core.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/datbox_core"]

datbox_core-0.0.1/src/datbox_core/__init__.py

@@ -0,0 +1,10 @@
+"""datbox-core: the `dat` CLI, plugin registry, and shared foundations."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("datbox-core")
+except PackageNotFoundError:  # pragma: no cover - source checkout without install
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

datbox_core-0.0.1/src/datbox_core/cli.py

@@ -0,0 +1,68 @@
+"""The `dat` root command."""
+
+from __future__ import annotations
+
+import typer
+
+from datbox_core import __version__
+from datbox_core.plugins import discover
+
+app = typer.Typer(
+    name="dat",
+    help="dat: the Data Analyst Toolbox. Portable, zero-infrastructure utilities for analysts.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"dat {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show the dat version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Root callback; subcommands are supplied by installed datbox-* plugins."""
+
+
+@app.command()
+def plugins() -> None:
+    """List installed dat modules and report any that failed to load."""
+    loaded, failed = discover()
+    if not loaded and not failed:
+        typer.echo("No plugins installed. Try: pip install datbox-viz")
+        return
+    for plugin in loaded:
+        dist = f" ({plugin.distribution})" if plugin.distribution else ""
+        typer.echo(f"  {plugin.name}{dist}")
+    for broken in failed:
+        typer.secho(f"  {broken.name}  FAILED: {broken.error}", fg=typer.colors.RED, err=True)
+    if failed:
+        raise typer.Exit(code=1)
+
+
+def build_app() -> typer.Typer:
+    """Attach every discovered plugin to the root app and return it."""
+    loaded, _failed = discover()
+    for plugin in loaded:
+        app.add_typer(plugin.app, name=plugin.name)
+    return app
+
+
+def main() -> None:
+    """Console-script entry point."""
+    build_app()()
+
+
+if __name__ == "__main__":
+    main()

datbox_core-0.0.1/src/datbox_core/plugins.py

@@ -0,0 +1,67 @@
+"""Plugin discovery for `dat` subcommands.
+
+Any installed distribution can register a Typer app under the ``datbox.plugins``
+entry-point group. The entry-point *name* becomes the subcommand name and the
+*value* must resolve to a ``typer.Typer`` instance.
+
+Example ``pyproject.toml`` for a module::
+
+    [project.entry-points."datbox.plugins"]
+    viz = "datbox_viz.cli:app"
+
+Modules never import each other; they only depend on ``datbox-core``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.metadata import EntryPoint, entry_points
+
+import typer
+
+PLUGIN_GROUP = "datbox.plugins"
+
+
+@dataclass(frozen=True)
+class LoadedPlugin:
+    """A successfully loaded plugin subcommand."""
+
+    name: str
+    app: typer.Typer
+    distribution: str | None
+
+
+@dataclass(frozen=True)
+class FailedPlugin:
+    """A plugin that was found but could not be loaded."""
+
+    name: str
+    error: str
+
+
+def discover() -> tuple[list[LoadedPlugin], list[FailedPlugin]]:
+    """Find and load every registered plugin.
+
+    A plugin that fails to import never breaks the root CLI; it is reported
+    instead so the user can see what is broken.
+    """
+    loaded: list[LoadedPlugin] = []
+    failed: list[FailedPlugin] = []
+    for ep in _iter_entry_points():
+        try:
+            obj = ep.load()
+        except Exception as exc:
+            failed.append(FailedPlugin(name=ep.name, error=f"{type(exc).__name__}: {exc}"))
+            continue
+        if not isinstance(obj, typer.Typer):
+            failed.append(
+                FailedPlugin(name=ep.name, error=f"entry point is {type(obj).__name__}, not Typer")
+            )
+            continue
+        dist = ep.dist.name if ep.dist is not None else None
+        loaded.append(LoadedPlugin(name=ep.name, app=obj, distribution=dist))
+    return loaded, failed
+
+
+def _iter_entry_points() -> list[EntryPoint]:
+    return sorted(entry_points(group=PLUGIN_GROUP), key=lambda ep: ep.name)

datbox_core-0.0.1/tests/test_cli.py

@@ -0,0 +1,24 @@
+from typer.testing import CliRunner
+
+from datbox_core import __version__
+from datbox_core.cli import build_app
+
+runner = CliRunner()
+
+
+def test_help_runs() -> None:
+    result = runner.invoke(build_app(), ["--help"])
+    assert result.exit_code == 0
+    assert "Data Analyst Toolbox" in result.output
+
+
+def test_version_flag() -> None:
+    result = runner.invoke(build_app(), ["--version"])
+    assert result.exit_code == 0
+    assert __version__ in result.output
+
+
+def test_plugins_command_with_none_installed() -> None:
+    result = runner.invoke(build_app(), ["plugins"])
+    assert result.exit_code == 0
+    assert "No plugins installed" in result.output

datbox_core-0.0.1/tests/test_plugins.py

@@ -0,0 +1,33 @@
+from importlib.metadata import EntryPoint
+
+import typer
+
+from datbox_core import plugins
+
+
+def test_discover_loads_valid_typer_app(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    fake_app = typer.Typer()
+
+    class FakeEP(EntryPoint):
+        def load(self):  # type: ignore[override]
+            return fake_app
+
+    ep = FakeEP(name="fake", value="x:y", group=plugins.PLUGIN_GROUP)
+    monkeypatch.setattr(plugins, "_iter_entry_points", lambda: [ep])
+    loaded, failed = plugins.discover()
+    assert [p.name for p in loaded] == ["fake"]
+    assert loaded[0].app is fake_app
+    assert failed == []
+
+
+def test_discover_reports_broken_plugin(monkeypatch) -> None:  # type: ignore[no-untyped-def]
+    class BrokenEP(EntryPoint):
+        def load(self):  # type: ignore[override]
+            raise ImportError("boom")
+
+    ep = BrokenEP(name="broken", value="x:y", group=plugins.PLUGIN_GROUP)
+    monkeypatch.setattr(plugins, "_iter_entry_points", lambda: [ep])
+    loaded, failed = plugins.discover()
+    assert loaded == []
+    assert failed[0].name == "broken"
+    assert "ImportError" in failed[0].error