datalegion-cli 1.4.0__tar.gz → 1.5.0__tar.gz

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalegion-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: CLI for the Data Legion API — agent-friendly, fully async
 Project-URL: Homepage, https://www.datalegion.ai
 Project-URL: Documentation, https://www.datalegion.ai/docs
@@ -271,12 +271,21 @@ datalegion-cli person enrich --email bad 2>/dev/null
 # {"ok": false, "error": "bad_request", "message": "..."}
 ```
 
+## Sandbox
+
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, bulk enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+
+```bash
+datalegion-cli --sandbox person enrich --email anyone@example.com
+```
+
 ## Global flags
 
 | Flag | Description |
 |------|-------------|
 | `--verbose` / `-v` | Enable debug logging to stderr |
 | `--quiet` / `-q` | Suppress all log output |
+| `--sandbox` | Return sample records from enrich, search and discover, using no credits |
 | `--help` | Show help for any command |
 
 ## Development

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/README.md

@@ -236,12 +236,21 @@ datalegion-cli person enrich --email bad 2>/dev/null
 # {"ok": false, "error": "bad_request", "message": "..."}
 ```
 
+## Sandbox
+
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, bulk enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+
+```bash
+datalegion-cli --sandbox person enrich --email anyone@example.com
+```
+
 ## Global flags
 
 | Flag | Description |
 |------|-------------|
 | `--verbose` / `-v` | Enable debug logging to stderr |
 | `--quiet` / `-q` | Suppress all log output |
+| `--sandbox` | Return sample records from enrich, search and discover, using no credits |
 | `--help` | Show help for any command |
 
 ## Development

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datalegion-cli"
-version = "1.4.0"
+version = "1.5.0"
 description = "CLI for the Data Legion API — agent-friendly, fully async"
 readme = "README.md"
 requires-python = ">=3.11"

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/src/datalegion_cli/client.py

@@ -8,7 +8,7 @@ import httpx
 from loguru import logger
 
 from datalegion_cli import __version__
-from datalegion_cli.config import get_api_key, get_base_url
+from datalegion_cli.config import get_api_key, get_base_url, get_sandbox
 
 
 class APIError(Exception):
@@ -32,6 +32,15 @@ class APIError(Exception):
         return d
 
 
+# Endpoints the API mirrors under /sandbox/: sample records (Jane Sandbox, Sandbox Corp), no credits.
+# Utilities, reports, credits and dynamic bulk have no sandbox and call the real API.
+SANDBOX_PATHS = frozenset(
+    f"/{entity}/{op}"
+    for entity in ("person", "company")
+    for op in ("enrich", "enrich/bulk", "search", "discover")
+)
+
+
 class LegionClient:
     """Async client wrapping the Data Legion API."""
 
@@ -45,6 +54,7 @@ class LegionClient:
         self._base_url = base_url or get_base_url()
         self._api_key = (api_key or "").strip() or get_api_key()
         self._timeout = timeout
+        self._sandbox = get_sandbox()
         self._client: httpx.AsyncClient | None = None
         self.last_credits_used: str | None = None
         self.last_credits_remaining: str | None = None
@@ -77,6 +87,8 @@ class LegionClient:
         params: dict[str, Any] | None = None,
     ) -> dict[str, Any] | list[Any]:
         client = await self._get_client()
+        if self._sandbox and endpoint in SANDBOX_PATHS:
+            endpoint = f"/sandbox{endpoint}"
         logger.debug("{} {}", method.upper(), endpoint)
 
         if method.upper() == "GET":

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/src/datalegion_cli/config.py

@@ -28,6 +28,7 @@ _DEFAULTS: dict[str, object] = {
     "default_output": "json",  # json | table | raw
     "install_method": "",  # brew | github | git | pip
     "device_id": "",  # random name for this machine's login key (see login.new_device_id)
+    "sandbox": False,  # sample records, no credits (see client.SANDBOX_PATHS)
 }
 
 # Fields that are stored encrypted on disk
@@ -94,6 +95,8 @@ def load_config() -> dict[str, object]:
         cfg["api_key"] = env_key
     if env_url := os.environ.get("LEGION_API_URL"):
         cfg["api_base_url"] = env_url
+    if env_sandbox := os.environ.get("LEGION_SANDBOX"):
+        cfg["sandbox"] = env_sandbox.strip().lower() in ("1", "true", "yes")
     return cfg
 
 
@@ -127,3 +130,8 @@ def get_api_key() -> str:
 
 def get_base_url() -> str:
     return str(load_config().get("api_base_url", _DEFAULTS["api_base_url"]))
+
+
+def get_sandbox() -> bool:
+    """Sandbox mode: the --sandbox flag, LEGION_SANDBOX, or `config set sandbox true`."""
+    return load_config().get("sandbox") is True

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/src/datalegion_cli/main.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 from typing import Annotated
 
 import typer
@@ -36,9 +37,19 @@ app.add_typer(credits.app, name="credits")
 def main_callback(
     verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Enable debug logging.")] = False,
     quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress all log output.")] = False,
+    sandbox: Annotated[
+        bool,
+        typer.Option(
+            "--sandbox",
+            help="Return sample records from enrich, search and discover, using no credits.",
+        ),
+    ] = False,
 ) -> None:
     """Data Legion CLI."""
     setup_logging(verbose=verbose, quiet=quiet)
+    if sandbox:
+        # Read by config.load_config, so every client this run creates is in sandbox mode.
+        os.environ["LEGION_SANDBOX"] = "1"
 
 
 # ── Top-level commands ───────────────────────────────────────────────

{datalegion_cli-1.4.0 → datalegion_cli-1.5.0}/tests/test_client.py

@@ -210,3 +210,47 @@ class TestConvenienceMethods:
         http = await self._setup_mock(mock_client, monkeypatch)
         await mock_client.credits_usage(start_date="2026-01-01", end_date="2026-03-01")
         assert http.get.call_args[0][0] == "/credits/usage"
+
+
+@pytest.mark.asyncio
+class TestSandbox:
+    """Sandbox mode sends only the endpoints the API mirrors to /sandbox/."""
+
+    async def _paths(self, monkeypatch, sandbox_env: str | None, endpoints: list[str]) -> list[str]:
+        if sandbox_env is None:
+            monkeypatch.delenv("LEGION_SANDBOX", raising=False)
+        else:
+            monkeypatch.setenv("LEGION_SANDBOX", sandbox_env)
+        client = LegionClient(base_url="https://x.local", api_key="legion_k")
+        mock_post = AsyncMock(return_value=make_response(200, {"matches": []}))
+        client._client = AsyncMock()
+        client._client.is_closed = False
+        client._client.post = mock_post
+        for endpoint in endpoints:
+            await client.request("POST", endpoint, payload={})
+        return [call.args[0] for call in mock_post.call_args_list]
+
+    async def test_sandbox_routes_only_mirrored_paths(self, monkeypatch):
+        paths = await self._paths(
+            monkeypatch, "1", ["/person/enrich", "/company/search", "/utility/clean"]
+        )
+        assert paths == ["/sandbox/person/enrich", "/sandbox/company/search", "/utility/clean"]
+
+    async def test_off_by_default(self, monkeypatch):
+        assert await self._paths(monkeypatch, None, ["/person/enrich"]) == ["/person/enrich"]
+
+    async def test_env_false_is_off(self, monkeypatch):
+        assert await self._paths(monkeypatch, "false", ["/person/enrich"]) == ["/person/enrich"]
+
+
+def test_sandbox_flag_turns_it_on(monkeypatch):
+    from typer.testing import CliRunner
+
+    from datalegion_cli.main import app
+
+    monkeypatch.delenv("LEGION_SANDBOX", raising=False)
+    CliRunner().invoke(app, ["--sandbox", "version"])
+    import os
+
+    assert os.environ.get("LEGION_SANDBOX") == "1"
+    monkeypatch.delenv("LEGION_SANDBOX", raising=False)