databar 2.9.0__tar.gz → 2.10.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. {databar-2.9.0/src/databar.egg-info → databar-2.10.0}/PKG-INFO +5 -1
  2. {databar-2.9.0 → databar-2.10.0}/README.md +4 -0
  3. {databar-2.9.0 → databar-2.10.0}/pyproject.toml +1 -1
  4. {databar-2.9.0 → databar-2.10.0}/src/databar/__init__.py +1 -1
  5. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/_guide.py +2 -0
  6. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/flows.py +11 -0
  7. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/tasks.py +36 -2
  8. {databar-2.9.0 → databar-2.10.0}/src/databar/client.py +11 -2
  9. {databar-2.9.0 → databar-2.10.0}/src/databar/models.py +36 -3
  10. {databar-2.9.0 → databar-2.10.0/src/databar.egg-info}/PKG-INFO +5 -1
  11. {databar-2.9.0 → databar-2.10.0}/tests/test_cli.py +26 -2
  12. {databar-2.9.0 → databar-2.10.0}/tests/test_client.py +54 -0
  13. {databar-2.9.0 → databar-2.10.0}/LICENSE +0 -0
  14. {databar-2.9.0 → databar-2.10.0}/setup.cfg +0 -0
  15. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/__init__.py +0 -0
  16. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/_auth.py +0 -0
  17. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/_oauth.py +0 -0
  18. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/_onboard.py +0 -0
  19. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/_output.py +0 -0
  20. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/app.py +0 -0
  21. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/enrichments.py +0 -0
  22. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/tables.py +0 -0
  23. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/waterfalls.py +0 -0
  24. {databar-2.9.0 → databar-2.10.0}/src/databar/cli/workbooks.py +0 -0
  25. {databar-2.9.0 → databar-2.10.0}/src/databar/exceptions.py +0 -0
  26. {databar-2.9.0 → databar-2.10.0}/src/databar.egg-info/SOURCES.txt +0 -0
  27. {databar-2.9.0 → databar-2.10.0}/src/databar.egg-info/dependency_links.txt +0 -0
  28. {databar-2.9.0 → databar-2.10.0}/src/databar.egg-info/entry_points.txt +0 -0
  29. {databar-2.9.0 → databar-2.10.0}/src/databar.egg-info/requires.txt +0 -0
  30. {databar-2.9.0 → databar-2.10.0}/src/databar.egg-info/top_level.txt +0 -0
  31. {databar-2.9.0 → databar-2.10.0}/tests/test_new_features.py +0 -0
  32. {databar-2.9.0 → databar-2.10.0}/tests/test_oauth_login.py +0 -0
  33. {databar-2.9.0 → databar-2.10.0}/tests/test_workbooks.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: databar
3
- Version: 2.9.0
3
+ Version: 2.10.0
4
4
  Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
5
5
  Author-email: "Databar.ai Team" <info@databar.ai>
6
6
  License: MIT License
@@ -409,6 +409,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
409
409
  # Rows that have already finished, without waiting for the rest
410
410
  client.get_task(task.task_id, include_partial=True).data
411
411
 
412
+ # A flow task: what each step did, and which Output step (branch) answered
413
+ client.get_task(task.task_id, include_trace=True).trace["returned_by"]
414
+
412
415
  # Stop it — unfinished requests are refunded, finished rows keep their results
413
416
  client.cancel_task(task.task_id)
414
417
  ```
@@ -592,6 +595,7 @@ databar task get <task-id> --poll
592
595
 
593
596
  # Collect the rows a running bulk task has already finished
594
597
  databar task get <task-id> --partial
598
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
595
599
 
596
600
  # Stop a running task; finished rows keep their results
597
601
  databar task cancel <task-id>
@@ -354,6 +354,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
354
354
  # Rows that have already finished, without waiting for the rest
355
355
  client.get_task(task.task_id, include_partial=True).data
356
356
 
357
+ # A flow task: what each step did, and which Output step (branch) answered
358
+ client.get_task(task.task_id, include_trace=True).trace["returned_by"]
359
+
357
360
  # Stop it — unfinished requests are refunded, finished rows keep their results
358
361
  client.cancel_task(task.task_id)
359
362
  ```
@@ -537,6 +540,7 @@ databar task get <task-id> --poll
537
540
 
538
541
  # Collect the rows a running bulk task has already finished
539
542
  databar task get <task-id> --partial
543
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
540
544
 
541
545
  # Stop a running task; finished rows keep their results
542
546
  databar task cancel <task-id>
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "databar"
7
- version = "2.9.0"
7
+ version = "2.10.0"
8
8
  description = "Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai"
9
9
  readme = "README.md"
10
10
  license = { file = "LICENSE" }
@@ -116,7 +116,7 @@ from .models import (
116
116
  TrashItem,
117
117
  )
118
118
 
119
- __version__ = "2.9.0"
119
+ __version__ = "2.10.0"
120
120
  __all__ = [
121
121
  "DatabarClient",
122
122
  # exceptions
@@ -173,6 +173,7 @@ are rejected.
173
173
  databar task get <task-id> --format json # check once; bulk tasks report progress
174
174
  databar task get <task-id> --poll # poll until complete
175
175
  databar task get <task-id> --partial # rows a running bulk task already finished
176
+ databar task get <task-id> --trace # flow task: what each step did, which Output step answered
176
177
  databar task cancel <task-id> # stop it; finished rows keep their results
177
178
  ```
178
179
 
@@ -220,6 +221,7 @@ client.create_rows(table.identifier, [InsertRow(fields={"email": "alice@example.
220
221
  task = client.get_task(task_id)
221
222
  # task.progress → {"total", "completed", "no_data", "failed", "processing"} while a bulk run is going
222
223
  # client.get_task(task_id, include_partial=True).data → rows already finished
224
+ # client.get_task(task_id, include_trace=True).trace → flow steps + returned_by (branch taken)
223
225
  client.cancel_task(task_id) # stops it; poll_task then raises DatabarTaskCancelledError
224
226
  ```
225
227
 
@@ -100,6 +100,17 @@ def get_flow(
100
100
  ]
101
101
  output(rows, OutputFormat.TABLE, table_columns=["id", "required", "type", "description"])
102
102
 
103
+ declared = [out for out in f.outputs if out.type or out.description or out.fields]
104
+ if declared:
105
+ # Fields of a flow that answers through Output steps: the keys of every run's result.
106
+ console.print("[bold]Returns:[/bold]")
107
+ rows = []
108
+ for out in declared:
109
+ rows.append({"field": out.id, "type": out.type or "", "description": out.description or ""})
110
+ for sub in out.fields or []:
111
+ rows.append({"field": f"{out.id}.{sub.id}", "type": sub.type or "", "description": sub.description or ""})
112
+ output(rows, OutputFormat.TABLE, table_columns=["field", "type", "description"])
113
+
103
114
 
104
115
  @app.command("run")
105
116
  def run_flow(
@@ -1,7 +1,7 @@
1
1
  """
2
2
  CLI commands for tasks.
3
3
 
4
- databar task get <task-id> [--format] [--poll] [--partial]
4
+ databar task get <task-id> [--format] [--poll] [--partial] [--trace]
5
5
  databar task cancel <task-id>
6
6
  """
7
7
 
@@ -49,6 +49,27 @@ def _print_status(task) -> None:
49
49
  )
50
50
 
51
51
 
52
+ def _print_trace(trace) -> None:
53
+ """Which Output step answered and what each step did, for one flow run (or each of a bulk run)."""
54
+ runs = trace if isinstance(trace, list) else [trace]
55
+ for index, run in enumerate(runs):
56
+ if run is None:
57
+ continue
58
+ if len(runs) > 1:
59
+ console.print(f"[bold]Input {index}:[/bold]")
60
+ returned_by = run.get("returned_by")
61
+ if returned_by:
62
+ name = returned_by.get("name") or returned_by.get("id")
63
+ console.print(f"[dim]Returned by:[/dim] {name} ({returned_by.get('id')})")
64
+ rows = [
65
+ {"node_id": step.get("node_id", ""), "type": step.get("type", ""), "cost": step.get("cost", "")}
66
+ for step in run.get("steps") or []
67
+ if isinstance(step, dict)
68
+ ]
69
+ if rows:
70
+ output(rows, OutputFormat.TABLE, table_columns=["node_id", "type", "cost"])
71
+
72
+
52
73
  @app.command("get")
53
74
  def get_task(
54
75
  task_id: str = _TASK_ID,
@@ -63,6 +84,11 @@ def get_task(
63
84
  "--partial",
64
85
  help="For a running bulk task, also show the rows that have already finished.",
65
86
  ),
87
+ trace: bool = typer.Option(
88
+ False,
89
+ "--trace",
90
+ help="For a flow task, also show what each step did and which Output step answered.",
91
+ ),
66
92
  ) -> None:
67
93
  """Get the status and result of a task."""
68
94
  client = get_client()
@@ -72,9 +98,17 @@ def get_task(
72
98
  data = client.poll_task(task_id)
73
99
  output(data, fmt)
74
100
  else:
75
- task = client.get_task(task_id, include_partial=partial)
101
+ task = client.get_task(task_id, include_partial=partial, include_trace=trace)
76
102
  if fmt != OutputFormat.JSON:
77
103
  _print_status(task)
104
+ if trace and fmt == OutputFormat.JSON:
105
+ output(
106
+ {"task_id": task.task_id, "status": task.status, "data": task.data, "trace": task.trace},
107
+ fmt,
108
+ )
109
+ return
110
+ if trace and task.trace:
111
+ _print_trace(task.trace)
78
112
  if task.data is not None:
79
113
  output(task.data, fmt)
80
114
  elif task.error:
@@ -309,14 +309,23 @@ class DatabarClient:
309
309
  # Task polling
310
310
  # -----------------------------------------------------------------------
311
311
 
312
- def get_task(self, task_id: str, include_partial: bool = False) -> TaskResponse:
312
+ def get_task(self, task_id: str, include_partial: bool = False, include_trace: bool = False) -> TaskResponse:
313
313
  """Get the current status of a task.
314
314
 
315
315
  While a bulk task is still running, ``progress`` carries per-input counts. Pass
316
316
  ``include_partial=True`` to also get back the rows that have already finished —
317
317
  off by default because it makes the API read the whole result set on every poll.
318
+
319
+ ``include_trace=True`` (flow tasks) fills ``trace``: what each step did, and
320
+ ``returned_by`` — the Output step that answered, i.e. which branch ran. Ask for it
321
+ when a flow completes with less in ``data`` than you expected.
318
322
  """
319
- params = {"include_partial": "true"} if include_partial else None
323
+ params: Optional[Dict[str, str]] = {}
324
+ if include_partial:
325
+ params["include_partial"] = "true"
326
+ if include_trace:
327
+ params["include_trace"] = "true"
328
+ params = params or None
320
329
  data = self._request("GET", f"/tasks/{task_id}", params=params)
321
330
  return TaskResponse.model_validate(data)
322
331
 
@@ -282,6 +282,16 @@ class TaskResponse(BaseModel):
282
282
  )
283
283
  error: Optional[Union[str, List[str]]] = None
284
284
  credits_spent: float = 0
285
+ trace: Optional[Union[Dict[str, Any], List[Optional[Dict[str, Any]]]]] = Field(
286
+ default=None,
287
+ description=(
288
+ "Flow tasks fetched with include_trace=True: what each step of the run did — "
289
+ "run_status, termination_reason, steps (one per node, in execution order) and "
290
+ "returned_by, the {id, name} of the Output step that built `data`, so you can tell "
291
+ "which branch the run took (None when no Output step answered). A bulk flow task "
292
+ "gets a list aligned to the inputs."
293
+ ),
294
+ )
285
295
 
286
296
  @classmethod
287
297
  def model_validate(cls, obj: Any, **kwargs: Any) -> "TaskResponse":
@@ -354,13 +364,27 @@ class FlowInput(BaseModel):
354
364
 
355
365
 
356
366
  class FlowOutput(BaseModel):
357
- """A field produced by a flow node.
367
+ """A field the flow returns.
368
+
369
+ Fields: id, key, name, response_field_id, type, description, fields.
358
370
 
359
- Fields: id, response_field_id.
371
+ For a flow that answers through Output steps, ``id`` is the key in the run
372
+ result and ``type`` / ``description`` are what the flow's author declared
373
+ (``type`` is text, number, boolean, list, object or any). An ``object``
374
+ field lists its sub-fields in ``fields``. The extra fields are None for a
375
+ flow without Output steps.
360
376
  """
361
377
 
362
378
  id: str
379
+ key: Optional[str] = None
380
+ name: Optional[str] = None
363
381
  response_field_id: Optional[int] = None
382
+ type: Optional[str] = Field(
383
+ default=None,
384
+ description="Declared type of an Output step field: text, number, boolean, list, object or any.",
385
+ )
386
+ description: Optional[str] = Field(default=None, description="What the field holds, as its author described it.")
387
+ fields: Optional[List["FlowOutput"]] = Field(default=None, description="Sub-fields of an object field.")
364
388
 
365
389
 
366
390
  class Flow(BaseModel):
@@ -453,9 +477,13 @@ class FlowConfigOpsResult(BaseModel):
453
477
 
454
478
 
455
479
  class FlowConfigError(BaseModel):
456
- """One reason a flow config would be rejected on save."""
480
+ """One reason a flow config would be rejected on save (or, in ``warnings``, a heads-up).
481
+
482
+ ``field`` is the path inside the node (or the config) the message is about, when known.
483
+ """
457
484
 
458
485
  node_id: Optional[str] = None
486
+ field: Optional[str] = None
459
487
  message: str
460
488
 
461
489
 
@@ -464,10 +492,15 @@ class FlowValidateResult(BaseModel):
464
492
 
465
493
  An invalid config is a valid answer — ``valid`` is False and ``errors``
466
494
  names the node (when known) rather than raising.
495
+
496
+ ``warnings`` lists what saves but may not do what you meant: a condition
497
+ branch with no Output step (its rows return nothing), a Custom JSON
498
+ response without the declared output fields. They never affect ``valid``.
467
499
  """
468
500
 
469
501
  valid: bool
470
502
  errors: List[FlowConfigError] = Field(default_factory=list)
503
+ warnings: List[FlowConfigError] = Field(default_factory=list)
471
504
 
472
505
 
473
506
  class FlowCostEstimate(BaseModel):
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: databar
3
- Version: 2.9.0
3
+ Version: 2.10.0
4
4
  Summary: Official Databar.ai Python SDK and CLI — connect to enrichments, waterfalls, and tables via api.databar.ai
5
5
  Author-email: "Databar.ai Team" <info@databar.ai>
6
6
  License: MIT License
@@ -409,6 +409,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
409
409
  # Rows that have already finished, without waiting for the rest
410
410
  client.get_task(task.task_id, include_partial=True).data
411
411
 
412
+ # A flow task: what each step did, and which Output step (branch) answered
413
+ client.get_task(task.task_id, include_trace=True).trace["returned_by"]
414
+
412
415
  # Stop it — unfinished requests are refunded, finished rows keep their results
413
416
  client.cancel_task(task.task_id)
414
417
  ```
@@ -592,6 +595,7 @@ databar task get <task-id> --poll
592
595
 
593
596
  # Collect the rows a running bulk task has already finished
594
597
  databar task get <task-id> --partial
598
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
595
599
 
596
600
  # Stop a running task; finished rows keep their results
597
601
  databar task cancel <task-id>
@@ -730,7 +730,31 @@ def test_task_get_partial_asks_for_finished_rows(monkeypatch):
730
730
  monkeypatch.setattr("databar.cli.tasks.get_client", lambda: mock)
731
731
  result = invoke(["task", "get", TASK_ID, "--partial"])
732
732
  assert result.exit_code == 0
733
- mock.get_task.assert_called_once_with(TASK_ID, include_partial=True)
733
+ mock.get_task.assert_called_once_with(TASK_ID, include_partial=True, include_trace=False)
734
+
735
+
736
+ def test_task_get_trace_names_the_output_step_that_answered(monkeypatch):
737
+ mock = _client_mock()
738
+ mock.get_task.return_value = TaskResponse(
739
+ task_id=TASK_ID,
740
+ status="completed",
741
+ data={"email": "a@b.co"},
742
+ trace={
743
+ "run_status": "completed",
744
+ "returned_by": {"id": "out_hot", "name": "Hot lead"},
745
+ "steps": [{"node_id": "check", "type": "condition"}, {"node_id": "out_hot", "type": "output"}],
746
+ },
747
+ )
748
+ monkeypatch.setattr("databar.cli.tasks.get_client", lambda: mock)
749
+ result = invoke(["task", "get", TASK_ID, "--trace"])
750
+ assert result.exit_code == 0
751
+ mock.get_task.assert_called_once_with(TASK_ID, include_partial=False, include_trace=True)
752
+ assert "Hot lead" in result.output
753
+
754
+ result = invoke(["task", "get", TASK_ID, "--trace", "--format", "json"])
755
+ payload = json.loads(result.stdout)["data"]
756
+ assert payload["trace"]["returned_by"]["id"] == "out_hot"
757
+ assert payload["data"] == {"email": "a@b.co"}
734
758
 
735
759
 
736
760
  def test_task_cancel(monkeypatch):
@@ -759,7 +783,7 @@ def test_task_cancel_reports_a_finished_task(monkeypatch):
759
783
  def test_version_flag():
760
784
  result = runner.invoke(app, ["--version"])
761
785
  assert result.exit_code == 0
762
- assert "2.9.0" in result.output
786
+ assert "2.10.0" in result.output
763
787
 
764
788
 
765
789
  def test_output_module_does_not_import_click():
@@ -453,6 +453,60 @@ def test_validate_flow_config_posts_the_config(client: DatabarClient, httpx_mock
453
453
  assert body == {"config": {"nodes": []}}
454
454
 
455
455
 
456
+ def test_validate_flow_config_returns_warnings_apart_from_errors(client: DatabarClient, httpx_mock: HTTPXMock):
457
+ httpx_mock.add_response(
458
+ url=f"{BASE_URL}/flows/validate-config",
459
+ method="POST",
460
+ json={
461
+ "valid": True,
462
+ "errors": [],
463
+ "warnings": [{"node_id": "cond1", "field": "else_nodes", "message": "this branch returns nothing"}],
464
+ },
465
+ )
466
+ result = client.validate_flow_config({"nodes": []})
467
+ assert result.valid is True
468
+ assert result.warnings[0].node_id == "cond1"
469
+ assert result.warnings[0].field == "else_nodes"
470
+
471
+
472
+ def test_flow_outputs_carry_the_declared_output_fields(client: DatabarClient, httpx_mock: HTTPXMock):
473
+ httpx_mock.add_response(
474
+ url=f"{BASE_URL}/flows/flow-uuid-1",
475
+ method="GET",
476
+ json={
477
+ "id": "flow-uuid-1",
478
+ "name": "Qualify",
479
+ "description": "",
480
+ "inputs": [],
481
+ "outputs": [
482
+ {"id": "email", "type": "text", "description": "Work email", "response_field_id": None},
483
+ {"id": "company", "type": "object", "fields": [{"id": "size", "type": "number"}]},
484
+ ],
485
+ "config": {},
486
+ },
487
+ )
488
+ flow = client.get_flow("flow-uuid-1")
489
+ assert flow.outputs[0].type == "text"
490
+ assert flow.outputs[0].description == "Work email"
491
+ assert flow.outputs[1].fields[0].id == "size"
492
+ assert flow.outputs[1].fields[0].type == "number"
493
+
494
+
495
+ def test_get_task_asks_for_the_trace(client: DatabarClient, httpx_mock: HTTPXMock):
496
+ httpx_mock.add_response(
497
+ url=f"{BASE_URL}/tasks/t1?include_trace=true",
498
+ method="GET",
499
+ json={
500
+ "task_id": "t1",
501
+ "status": "completed",
502
+ "data": {"email": "a@b.co"},
503
+ "trace": {"run_status": "completed", "returned_by": {"id": "out1", "name": "Output"}, "steps": []},
504
+ },
505
+ )
506
+ task = client.get_task("t1", include_trace=True)
507
+ assert task.trace["returned_by"]["id"] == "out1"
508
+
509
+
456
510
  def test_estimate_flow_cost_posts_the_config(client: DatabarClient, httpx_mock: HTTPXMock):
457
511
  httpx_mock.add_response(
458
512
  url=f"{BASE_URL}/flows/cost-estimate",
File without changes
File without changes
File without changes