databar 2.2.0__tar.gz → 2.5.0__tar.gz

{databar-2.2.0/src/databar.egg-info → databar-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databar
-Version: 2.2.0
+Version: 2.5.0
 Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
 Author-email: "Databar.ai Team" <info@databar.ai>
 License: MIT License
@@ -360,6 +360,22 @@ client.move_table_to_folder(table.identifier)          # remove from folder
 client.delete_folder(folder.id)                        # tables move to root
 ```
 
+### Tasks
+
+```python
+task = client.run_enrichment_bulk(123, [{"email": "a@b.com"}, {"email": "c@d.com"}])
+
+# While a bulk run is going, progress tells you whether it is advancing or stuck
+status = client.get_task(task.task_id)
+status.progress          # {"total": 2, "completed": 1, "failed": 0, "processing": 1}
+
+# Rows that have already finished, without waiting for the rest
+client.get_task(task.task_id, include_partial=True).data
+
+# Stop it — unfinished requests are refunded, finished rows keep their results
+client.cancel_task(task.task_id)
+```
+
 ### Error handling
 
 ```python
@@ -368,6 +384,7 @@ from databar import (
     DatabarAuthError,
     DatabarInsufficientCreditsError,
     DatabarNotFoundError,
+    DatabarTaskCancelledError,
     DatabarTaskFailedError,
     DatabarTimeoutError,
 )
@@ -382,6 +399,9 @@ except DatabarNotFoundError:
     print("Enrichment not found")
 except DatabarTaskFailedError as e:
     print(f"Task failed: {e.message}")
+except DatabarTaskCancelledError as e:
+    # Only the rows that finished, and not aligned to the inputs.
+    print(f"Cancelled, got {len(e.partial_data or [])} rows")
 except DatabarTimeoutError as e:
     print(f"Timed out after polling {e.max_attempts} times")
 ```
@@ -499,20 +519,29 @@ databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>
 ### Tasks
 
 ```bash
-# Check a task status
+# Check a task status — a bulk task also reports how many inputs are done
 databar task get <task-id>
 
 # Poll until complete
 databar task get <task-id> --poll
+
+# Collect the rows a running bulk task has already finished
+databar task get <task-id> --partial
+
+# Stop a running task; finished rows keep their results
+databar task cancel <task-id>
 ```
 
 ### Output formats
 
-All commands support `--format table|json|csv` (default: `table`):
+All commands support `--format table|json|csv` (default: `table`).
+
+`--format json` prints one envelope on stdout:
+`{"ok": true, "data": ...}` or `{"ok": false, "error": {"code", "message", ...}}`.
 
 ```bash
-# Pipe JSON output
-databar table rows <uuid> --format json | jq '.[].email'
+# Pipe JSON output (payload is under .data)
+databar table rows <uuid> --format json | jq '.data[].email'
 
 # Save to CSV
 databar enrich bulk 123 --input input.csv --format csv --out output.csv

{databar-2.2.0 → databar-2.5.0}/README.md

@@ -305,6 +305,22 @@ client.move_table_to_folder(table.identifier)          # remove from folder
 client.delete_folder(folder.id)                        # tables move to root
 ```
 
+### Tasks
+
+```python
+task = client.run_enrichment_bulk(123, [{"email": "a@b.com"}, {"email": "c@d.com"}])
+
+# While a bulk run is going, progress tells you whether it is advancing or stuck
+status = client.get_task(task.task_id)
+status.progress          # {"total": 2, "completed": 1, "failed": 0, "processing": 1}
+
+# Rows that have already finished, without waiting for the rest
+client.get_task(task.task_id, include_partial=True).data
+
+# Stop it — unfinished requests are refunded, finished rows keep their results
+client.cancel_task(task.task_id)
+```
+
 ### Error handling
 
 ```python
@@ -313,6 +329,7 @@ from databar import (
     DatabarAuthError,
     DatabarInsufficientCreditsError,
     DatabarNotFoundError,
+    DatabarTaskCancelledError,
     DatabarTaskFailedError,
     DatabarTimeoutError,
 )
@@ -327,6 +344,9 @@ except DatabarNotFoundError:
     print("Enrichment not found")
 except DatabarTaskFailedError as e:
     print(f"Task failed: {e.message}")
+except DatabarTaskCancelledError as e:
+    # Only the rows that finished, and not aligned to the inputs.
+    print(f"Cancelled, got {len(e.partial_data or [])} rows")
 except DatabarTimeoutError as e:
     print(f"Timed out after polling {e.max_attempts} times")
 ```
@@ -444,20 +464,29 @@ databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>
 ### Tasks
 
 ```bash
-# Check a task status
+# Check a task status — a bulk task also reports how many inputs are done
 databar task get <task-id>
 
 # Poll until complete
 databar task get <task-id> --poll
+
+# Collect the rows a running bulk task has already finished
+databar task get <task-id> --partial
+
+# Stop a running task; finished rows keep their results
+databar task cancel <task-id>
 ```
 
 ### Output formats
 
-All commands support `--format table|json|csv` (default: `table`):
+All commands support `--format table|json|csv` (default: `table`).
+
+`--format json` prints one envelope on stdout:
+`{"ok": true, "data": ...}` or `{"ok": false, "error": {"code", "message", ...}}`.
 
 ```bash
-# Pipe JSON output
-databar table rows <uuid> --format json | jq '.[].email'
+# Pipe JSON output (payload is under .data)
+databar table rows <uuid> --format json | jq '.data[].email'
 
 # Save to CSV
 databar enrich bulk 123 --input input.csv --format csv --out output.csv

{databar-2.2.0 → databar-2.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databar"
-version = "2.2.0"
+version = "2.5.0"
 description = "Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai"
 readme = "README.md"
 license = { file = "LICENSE" }

{databar-2.2.0 → databar-2.5.0}/src/databar/__init__.py

@@ -27,10 +27,12 @@ from .client import DatabarClient
 from .exceptions import (
     DatabarAuthError,
     DatabarError,
+    DatabarConflictError,
     DatabarGoneError,
     DatabarInsufficientCreditsError,
     DatabarNotFoundError,
     DatabarRateLimitError,
+    DatabarTaskCancelledError,
     DatabarTaskFailedError,
     DatabarTimeoutError,
     DatabarValidationError,
@@ -61,8 +63,13 @@ from .models import (
     WaterfallEnrichment,
     # Flows
     Flow,
+    FlowConfigOpsResult,
+    FlowDetail,
     FlowInput,
     FlowOutput,
+    FlowVersion,
+    FlowVersionDetail,
+    RestoreFlowVersionResult,
     # Tables
     Table,
     Column,
@@ -88,6 +95,7 @@ from .models import (
     Exporter,
     ExporterListResponse,
     ExporterParam,
+    ExporterAdditionalParam,
     ExporterResponseField,
     Connection,
     AuthorizationInfo,
@@ -99,7 +107,7 @@ from .models import (
     Folder,
 )
 
-__version__ = "2.2.0"
+__version__ = "2.5.0"
 __all__ = [
     "DatabarClient",
     # exceptions
@@ -107,9 +115,11 @@ __all__ = [
     "DatabarAuthError",
     "DatabarNotFoundError",
     "DatabarInsufficientCreditsError",
+    "DatabarConflictError",
     "DatabarGoneError",
     "DatabarValidationError",
     "DatabarRateLimitError",
+    "DatabarTaskCancelledError",
     "DatabarTaskFailedError",
     "DatabarTimeoutError",
     # pricing / category
@@ -137,8 +147,13 @@ __all__ = [
     "WaterfallEnrichment",
     # flows
     "Flow",
+    "FlowConfigOpsResult",
+    "FlowDetail",
     "FlowInput",
     "FlowOutput",
+    "FlowVersion",
+    "FlowVersionDetail",
+    "RestoreFlowVersionResult",
     # tables
     "Table",
     "Column",
@@ -164,6 +179,7 @@ __all__ = [
     "Exporter",
     "ExporterListResponse",
     "ExporterParam",
+    "ExporterAdditionalParam",
     "ExporterResponseField",
     "Connection",
     "AuthorizationInfo",

{databar-2.2.0 → databar-2.5.0}/src/databar/cli/_auth.py

@@ -46,7 +46,8 @@ def get_api_key() -> str:
         "No API key found.\n"
         "  Run [bold]databar login[/bold] to save your key, or set the "
         "[bold]DATABAR_API_KEY[/bold] environment variable.\n"
-        "  Get your key at [link=https://databar.ai]databar.ai[/link] → Integrations."
+        "  Get your key at [link=https://databar.ai]databar.ai[/link] → Integrations.",
+        code="auth_missing",
     )
     raise typer.Exit(1)  # unreachable but satisfies type checkers
 
@@ -111,7 +112,7 @@ def whoami(
     try:
         user = client.get_user()
     except DatabarError as e:
-        error(str(e))
+        error(e)
     finally:
         client.close()
 

{databar-2.2.0 → databar-2.5.0}/src/databar/cli/_guide.py

@@ -110,6 +110,11 @@ echo 'export PATH="$(python3 -m site --user-base)/bin:$PATH"' >> ~/.zshrc
 **Always use `--format json` when parsing or piping output.**
 The default `table` format uses Rich terminal markup — not machine-parseable.
 
+JSON output is always one envelope on stdout:
+`{"ok": true, "data": ...}` or `{"ok": false, "error": {"code", "message", "hint"?}}`.
+Read results from `.data` (e.g. `jq '.data[].name'`). Exit codes: 2 usage, 3 auth,
+4 not found, 5 validation, 1 other.
+
 ### Enrichments
 ```bash
 databar enrich list --format json
@@ -157,10 +162,17 @@ databar table run-enrichment <table-uuid> --enrichment-id <TABLE-ENRICHMENT-ID>
 NOTE: `run-enrichment` takes the TABLE-ENRICHMENT ID (from `add-enrichment` or
 `table enrichments`), NOT the catalog enrichment ID. These are different numbers.
 
+NOTE: `<table-uuid>` and `<task-id>` must be UUIDs
+(`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`). Bad values fail client-side with
+`code: validation` / exit 5 (not a 404). `--out` paths are resolved; null bytes
+are rejected.
+
 ### Tasks
 ```bash
-databar task get <task-id> --format json    # check once
+databar task get <task-id> --format json    # check once; bulk tasks report progress
 databar task get <task-id> --poll           # poll until complete
+databar task get <task-id> --partial        # rows a running bulk task already finished
+databar task cancel <task-id>               # stop it; finished rows keep their results
 ```
 
 ---
@@ -202,6 +214,12 @@ resp  = client.get_rows(table.identifier)
 
 from databar import InsertRow
 client.create_rows(table.identifier, [InsertRow(fields={"email": "alice@example.com"})])
+
+# Tasks
+task = client.get_task(task_id)
+# task.progress → {"total", "completed", "failed", "processing"} while a bulk run is going
+# client.get_task(task_id, include_partial=True).data → rows already finished
+client.cancel_task(task_id)   # stops it; poll_task then raises DatabarTaskCancelledError
 ```
 
 ---

databar-2.5.0/src/databar/cli/_output.py

@@ -0,0 +1,332 @@
+"""
+Shared output formatting helpers for the Databar CLI.
+
+All CLI commands use these helpers to ensure consistent output.
+Supports three output formats:
+  - table  (default) — rich-rendered terminal table
+  - json   — envelope JSON to stdout, pipe-friendly
+  - csv    — CSV to stdout or --out file
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import os
+import re
+import sys
+from enum import Enum
+from pathlib import Path
+from typing import Any, NoReturn, Optional, Union
+
+import click
+import typer
+from rich import print_json as rich_print_json
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+from rich.text import Text
+
+from databar.exceptions import (
+    DatabarAuthError,
+    DatabarError,
+    DatabarGoneError,
+    DatabarInsufficientCreditsError,
+    DatabarNotFoundError,
+    DatabarRateLimitError,
+    DatabarTaskCancelledError,
+    DatabarTaskFailedError,
+    DatabarTimeoutError,
+    DatabarValidationError,
+)
+
+# Canonical 8-4-4-4-12 only — uuid.UUID() also accepts braces / urn:uuid:.
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+
+# Force UTF-8 on stdout/stderr before any Console is created. On Windows, a
+# redirected pipe uses the locale encoding (e.g. cp1251) and crashes on
+# characters outside that codepage (DEV-5080).
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        try:
+            _stream.reconfigure(encoding="utf-8", errors="backslashreplace")
+        except Exception:
+            pass
+
+console = Console()
+# soft_wrap=True: don't hard-wrap mid-word (breaks naive stderr matching).
+err_console = Console(stderr=True, soft_wrap=True)
+
+
+class OutputFormat(str, Enum):
+    TABLE = "table"
+    JSON = "json"
+    CSV = "csv"
+
+
+# Exit codes by error class (ticket DEV-5133).
+_EXIT_USAGE = 2
+_EXIT_AUTH = 3
+_EXIT_NOT_FOUND = 4
+_EXIT_VALIDATION = 5
+_EXIT_GENERIC = 1
+
+_HINTS = {
+    "auth_missing": "Run `databar login` or set the DATABAR_API_KEY environment variable.",
+    "auth_invalid": "Check your API key at databar.ai → Settings → API Keys.",
+}
+
+
+def _current_format() -> OutputFormat:
+    """Read --format from the active Click/Typer context, defaulting to table."""
+    ctx = click.get_current_context(silent=True)
+    if ctx is None:
+        return OutputFormat.TABLE
+    fmt = ctx.params.get("fmt")
+    if isinstance(fmt, OutputFormat):
+        return fmt
+    if isinstance(fmt, str):
+        try:
+            return OutputFormat(fmt)
+        except ValueError:
+            return OutputFormat.TABLE
+    return OutputFormat.TABLE
+
+
+def _plain(message: str) -> str:
+    """Strip Rich markup so JSON/stderr consumers get clean text."""
+    try:
+        return Text.from_markup(message).plain
+    except Exception:
+        return message
+
+
+def _classify(
+    err: Union[str, DatabarError, BaseException],
+    code: Optional[str],
+) -> tuple[str, int, str, Optional[str]]:
+    """Return (code, exit_code, message, hint)."""
+    if isinstance(err, DatabarError):
+        message = _plain(err.message if hasattr(err, "message") else str(err))
+        if code is None:
+            if isinstance(err, DatabarAuthError):
+                code = "auth_invalid"
+            elif isinstance(err, DatabarNotFoundError):
+                code = "not_found"
+            elif isinstance(err, DatabarValidationError):
+                code = "validation"
+            elif isinstance(err, DatabarRateLimitError):
+                code = "rate_limit"
+            elif isinstance(err, DatabarInsufficientCreditsError):
+                code = "insufficient_credits"
+            elif isinstance(err, DatabarGoneError):
+                code = "gone"
+            elif isinstance(err, DatabarTaskFailedError):
+                code = "task_failed"
+            elif isinstance(err, DatabarTaskCancelledError):
+                code = "task_cancelled"
+            elif isinstance(err, DatabarTimeoutError):
+                code = "timeout"
+            else:
+                code = "server_error"
+    else:
+        message = _plain(str(err))
+        if code is None:
+            code = "usage"
+
+    exit_map = {
+        "auth_missing": _EXIT_AUTH,
+        "auth_invalid": _EXIT_AUTH,
+        "not_found": _EXIT_NOT_FOUND,
+        "usage": _EXIT_USAGE,
+        "validation": _EXIT_VALIDATION,
+    }
+    exit_code = exit_map.get(code, _EXIT_GENERIC)
+    hint = _HINTS.get(code)
+    return code, exit_code, message, hint
+
+
+# ---------------------------------------------------------------------------
+# Core output functions
+# ---------------------------------------------------------------------------
+
+
+def _print_json(payload: Any) -> None:
+    """Print a JSON payload to stdout (Rich-highlighted when on a TTY)."""
+    rich_print_json(json.dumps(payload, default=str))
+
+
+def output_json(data: Any) -> None:
+    """Print data as a success envelope: {"ok": true, "data": ...}."""
+    _print_json({"ok": True, "data": data})
+
+
+def output_table(rows: list[dict], columns: list[str] | None = None) -> None:
+    """
+    Render a list of dicts as a rich table.
+
+    columns controls the column order/subset. If None, all keys from the
+    first row are used.
+    """
+    if not rows:
+        console.print("[dim]No results.[/dim]")
+        return
+
+    cols = columns or list(rows[0].keys())
+    table = Table(show_header=True, header_style="bold cyan")
+    for col in cols:
+        table.add_column(col)
+
+    for row in rows:
+        table.add_row(*[_cell(row.get(col)) for col in cols])
+
+    console.print(table)
+
+
+def require_uuid(value: str, kind: str = "identifier") -> str:
+    """Reject non-UUID path args before they hit the API (DEV-5135)."""
+    if not _UUID_RE.fullmatch(value):
+        error(
+            f"Invalid {kind}: {value!r}.",
+            code="validation",
+            hint="Expected a UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).",
+        )
+    return value
+
+
+def normalize_out(out: Union[str, Path]) -> Path:
+    """Resolve --out; reject null bytes; note when the path leaves CWD."""
+    raw = out if isinstance(out, str) else os.fspath(out)
+    if "\0" in raw:
+        error("Invalid --out path: contains a null byte.", code="validation")
+    resolved = Path(raw).expanduser().resolve()
+    try:
+        resolved.relative_to(Path.cwd().resolve())
+    except ValueError:
+        info(f"Note: --out resolves outside the current directory: {resolved}")
+    return resolved
+
+
+def output_csv(
+    rows: list[dict],
+    columns: list[str] | None = None,
+    out: Union[str, Path] | None = None,
+) -> None:
+    """
+    Write rows as CSV.
+
+    If out is given, writes to that file. Otherwise writes to stdout.
+    """
+    if not rows:
+        return
+
+    cols = columns or list(rows[0].keys())
+    if out is not None:
+        out = normalize_out(out)
+    dest = open(out, "w", newline="", encoding="utf-8") if out else sys.stdout
+    writer = csv.DictWriter(dest, fieldnames=cols, extrasaction="ignore")
+    writer.writeheader()
+    writer.writerows(rows)
+    if out and not dest.closed:
+        dest.close()
+        console.print(f"[green]Saved to {out}[/green]")
+
+
+def output(
+    data: Any,
+    fmt: OutputFormat,
+    table_columns: list[str] | None = None,
+    out: Union[str, Path] | None = None,
+) -> None:
+    """
+    Unified output dispatcher — routes to the right format handler.
+
+    data may be:
+      - a list of dicts  → table/csv renders rows
+      - a dict           → wrapped in a list for table, raw for json
+      - any other value  → rendered as json
+    """
+    if fmt == OutputFormat.JSON:
+        output_json(data)
+        return
+
+    rows = _to_rows(data)
+
+    if fmt == OutputFormat.CSV:
+        output_csv(rows, columns=table_columns, out=out)
+    else:
+        output_table(rows, columns=table_columns)
+
+
+def error(
+    message: Union[str, DatabarError, BaseException],
+    *,
+    code: Optional[str] = None,
+    hint: Optional[str] = None,
+    exit_code: Optional[int] = None,
+) -> NoReturn:
+    """
+    Emit an error and exit.
+
+    When --format json: write {"ok": false, "error": {...}} to stdout.
+    Otherwise: styled prose to stderr (no mid-word hard wrap).
+    """
+    err_code, default_exit, plain_msg, default_hint = _classify(message, code)
+    final_hint = hint if hint is not None else default_hint
+    final_exit = exit_code if exit_code is not None else default_exit
+
+    if _current_format() == OutputFormat.JSON:
+        payload: dict[str, Any] = {
+            "ok": False,
+            "error": {"code": err_code, "message": plain_msg},
+        }
+        if final_hint:
+            payload["error"]["hint"] = final_hint
+        _print_json(payload)
+    else:
+        # Escape user text so accidental [bold] in messages isn't re-parsed;
+        # auth_missing still embeds intentional Rich markup in the source string.
+        if isinstance(message, str) and "[" in message and not isinstance(message, DatabarError):
+            # Keep intentional Rich markup from our own string literals.
+            err_console.print(f"[bold red]Error:[/bold red] {message}")
+        else:
+            err_console.print(f"[bold red]Error:[/bold red] {escape(plain_msg)}")
+
+    raise typer.Exit(code=final_exit)
+
+
+def success(message: str) -> None:
+    """Print a styled success message (no-op in JSON mode — keep stdout clean)."""
+    if _current_format() == OutputFormat.JSON:
+        return
+    console.print(f"[bold green]{message}[/bold green]")
+
+
+def info(message: str) -> None:
+    """Print a dim informational message (no-op in JSON mode)."""
+    if _current_format() == OutputFormat.JSON:
+        return
+    console.print(f"[dim]{message}[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, default=str)
+    return str(value)
+
+
+def _to_rows(data: Any) -> list[dict]:
+    if isinstance(data, list):
+        return [r if isinstance(r, dict) else {"value": r} for r in data]
+    if isinstance(data, dict):
+        return [data]
+    return [{"value": str(data)}]

{databar-2.2.0 → databar-2.5.0}/src/databar/cli/app.py

@@ -6,6 +6,8 @@ Registers all subcommand groups and exposes top-level login/whoami commands.
 
 from __future__ import annotations
 
+import os
+
 import typer
 
 from databar import __version__
@@ -21,6 +23,7 @@ app = typer.Typer(
     ),
     no_args_is_help=True,
     rich_markup_mode="rich",
+    pretty_exceptions_enable=os.environ.get("DATABAR_DEBUG") == "1",
 )
 
 # Top-level auth commands (login + whoami) live directly on the root app