databar 2.8.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.8.0/src/databar.egg-info → databar-2.10.0}/PKG-INFO +66 -1
  2. {databar-2.8.0 → databar-2.10.0}/README.md +65 -0
  3. {databar-2.8.0 → databar-2.10.0}/pyproject.toml +1 -1
  4. {databar-2.8.0 → databar-2.10.0}/src/databar/__init__.py +1 -1
  5. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/_guide.py +2 -0
  6. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/flows.py +11 -0
  7. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/tables.py +34 -0
  8. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/tasks.py +36 -2
  9. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/workbooks.py +34 -0
  10. {databar-2.8.0 → databar-2.10.0}/src/databar/client.py +11 -2
  11. {databar-2.8.0 → databar-2.10.0}/src/databar/models.py +36 -3
  12. {databar-2.8.0 → databar-2.10.0/src/databar.egg-info}/PKG-INFO +66 -1
  13. {databar-2.8.0 → databar-2.10.0}/tests/test_cli.py +98 -2
  14. {databar-2.8.0 → databar-2.10.0}/tests/test_client.py +54 -0
  15. {databar-2.8.0 → databar-2.10.0}/LICENSE +0 -0
  16. {databar-2.8.0 → databar-2.10.0}/setup.cfg +0 -0
  17. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/__init__.py +0 -0
  18. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/_auth.py +0 -0
  19. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/_oauth.py +0 -0
  20. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/_onboard.py +0 -0
  21. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/_output.py +0 -0
  22. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/app.py +0 -0
  23. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/enrichments.py +0 -0
  24. {databar-2.8.0 → databar-2.10.0}/src/databar/cli/waterfalls.py +0 -0
  25. {databar-2.8.0 → databar-2.10.0}/src/databar/exceptions.py +0 -0
  26. {databar-2.8.0 → databar-2.10.0}/src/databar.egg-info/SOURCES.txt +0 -0
  27. {databar-2.8.0 → databar-2.10.0}/src/databar.egg-info/dependency_links.txt +0 -0
  28. {databar-2.8.0 → databar-2.10.0}/src/databar.egg-info/entry_points.txt +0 -0
  29. {databar-2.8.0 → databar-2.10.0}/src/databar.egg-info/requires.txt +0 -0
  30. {databar-2.8.0 → databar-2.10.0}/src/databar.egg-info/top_level.txt +0 -0
  31. {databar-2.8.0 → databar-2.10.0}/tests/test_new_features.py +0 -0
  32. {databar-2.8.0 → databar-2.10.0}/tests/test_oauth_login.py +0 -0
  33. {databar-2.8.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.8.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
@@ -264,6 +264,35 @@ client.upsert_rows(table.identifier, rows)
264
264
 
265
265
  # Delete specific rows
266
266
  client.delete_rows(table.identifier, ["row-uuid-1", "row-uuid-2"])
267
+
268
+ # Duplicate, clear, export, dedupe
269
+ copy = client.duplicate_table(table.identifier)
270
+ client.clear_table(table.identifier)
271
+ client.export_table(table.identifier, format="csv")
272
+ print(client.get_table_export(table.identifier).file)
273
+ client.dedupe_table_rows(table.identifier)
274
+ ```
275
+
276
+ ### Workbooks and trash
277
+
278
+ ```python
279
+ workbooks = client.list_workbooks()
280
+ wb = client.get_workbook(workbooks[0].identifier)
281
+ client.rename_workbook(wb.identifier, "Q4 leads")
282
+ client.add_workbook_table(wb.identifier, name="Sheet 2")
283
+ # Set the tab order: list every sheet of the workbook exactly once
284
+ sheets = client.get_workbook(wb.identifier).tables
285
+ client.reorder_workbook_tables(wb.identifier, [s.identifier for s in reversed(sheets)])
286
+ client.duplicate_workbook(wb.identifier)
287
+ client.merge_workbooks(wb.identifier, ["wb_other"])
288
+ client.move_table(table.identifier, workbook=wb.identifier)
289
+ client.move_table(table.identifier, new_workbook=True, name="Split out")
290
+ client.delete_workbook(wb.identifier)
291
+
292
+ for item in client.list_trash():
293
+ print(item.kind, item.identifier)
294
+ client.restore_trash(workbooks=[wb.identifier])
295
+ client.purge_trash(workbooks=[wb.identifier])
267
296
  ```
268
297
 
269
298
  ### Enrichments on tables
@@ -281,6 +310,12 @@ result = client.add_enrichment(
281
310
  )
282
311
  print(f"Added enrichment #{result.id}: {result.enrichment_name}")
283
312
 
313
+ client.update_enrichment(
314
+ table.identifier,
315
+ result.id,
316
+ launch_strategy="run_on_update",
317
+ )
318
+
284
319
  # Run it (run_strategy: run_all | run_empty | run_errors)
285
320
  status = client.run_table_enrichment(
286
321
  table.identifier,
@@ -374,6 +409,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
374
409
  # Rows that have already finished, without waiting for the rest
375
410
  client.get_task(task.task_id, include_partial=True).data
376
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
+
377
415
  # Stop it — unfinished requests are refunded, finished rows keep their results
378
416
  client.cancel_task(task.task_id)
379
417
  ```
@@ -518,6 +556,32 @@ databar table upsert <uuid> --key-col email --input data.csv
518
556
  databar table enrichments <uuid>
519
557
  databar table add-enrichment <uuid> --enrichment-id 123 --mapping '{"email": "email_col"}'
520
558
  databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>
559
+
560
+ # Duplicate, clear, export, dedupe
561
+ databar table duplicate <uuid>
562
+ databar table clear <uuid>
563
+ databar table export <uuid> --export-format csv
564
+ databar table get-export <uuid>
565
+ databar table dedupe <uuid>
566
+ ```
567
+
568
+ ### Workbooks and trash
569
+
570
+ ```bash
571
+ databar workbook list
572
+ databar workbook get <wb_id>
573
+ databar workbook rename <wb_id> --name "Q4 leads"
574
+ databar workbook duplicate <wb_id>
575
+ databar workbook add-table <wb_id> --name "Sheet 2"
576
+ databar workbook reorder <wb_id> --tables <uuid_1>,<uuid_2> # every sheet, once
577
+ databar workbook merge --target <wb_id> --sources <wb_a>,<wb_b>
578
+ databar table move <table-uuid> --workbook <wb_id>
579
+ databar table move <table-uuid> --new-workbook --name "Split out"
580
+ databar workbook delete <wb_id>
581
+
582
+ databar trash list
583
+ databar trash restore --workbooks <wb_id>
584
+ databar trash purge --workbooks <wb_id>
521
585
  ```
522
586
 
523
587
  ### Tasks
@@ -531,6 +595,7 @@ databar task get <task-id> --poll
531
595
 
532
596
  # Collect the rows a running bulk task has already finished
533
597
  databar task get <task-id> --partial
598
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
534
599
 
535
600
  # Stop a running task; finished rows keep their results
536
601
  databar task cancel <task-id>
@@ -209,6 +209,35 @@ client.upsert_rows(table.identifier, rows)
209
209
 
210
210
  # Delete specific rows
211
211
  client.delete_rows(table.identifier, ["row-uuid-1", "row-uuid-2"])
212
+
213
+ # Duplicate, clear, export, dedupe
214
+ copy = client.duplicate_table(table.identifier)
215
+ client.clear_table(table.identifier)
216
+ client.export_table(table.identifier, format="csv")
217
+ print(client.get_table_export(table.identifier).file)
218
+ client.dedupe_table_rows(table.identifier)
219
+ ```
220
+
221
+ ### Workbooks and trash
222
+
223
+ ```python
224
+ workbooks = client.list_workbooks()
225
+ wb = client.get_workbook(workbooks[0].identifier)
226
+ client.rename_workbook(wb.identifier, "Q4 leads")
227
+ client.add_workbook_table(wb.identifier, name="Sheet 2")
228
+ # Set the tab order: list every sheet of the workbook exactly once
229
+ sheets = client.get_workbook(wb.identifier).tables
230
+ client.reorder_workbook_tables(wb.identifier, [s.identifier for s in reversed(sheets)])
231
+ client.duplicate_workbook(wb.identifier)
232
+ client.merge_workbooks(wb.identifier, ["wb_other"])
233
+ client.move_table(table.identifier, workbook=wb.identifier)
234
+ client.move_table(table.identifier, new_workbook=True, name="Split out")
235
+ client.delete_workbook(wb.identifier)
236
+
237
+ for item in client.list_trash():
238
+ print(item.kind, item.identifier)
239
+ client.restore_trash(workbooks=[wb.identifier])
240
+ client.purge_trash(workbooks=[wb.identifier])
212
241
  ```
213
242
 
214
243
  ### Enrichments on tables
@@ -226,6 +255,12 @@ result = client.add_enrichment(
226
255
  )
227
256
  print(f"Added enrichment #{result.id}: {result.enrichment_name}")
228
257
 
258
+ client.update_enrichment(
259
+ table.identifier,
260
+ result.id,
261
+ launch_strategy="run_on_update",
262
+ )
263
+
229
264
  # Run it (run_strategy: run_all | run_empty | run_errors)
230
265
  status = client.run_table_enrichment(
231
266
  table.identifier,
@@ -319,6 +354,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
319
354
  # Rows that have already finished, without waiting for the rest
320
355
  client.get_task(task.task_id, include_partial=True).data
321
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
+
322
360
  # Stop it — unfinished requests are refunded, finished rows keep their results
323
361
  client.cancel_task(task.task_id)
324
362
  ```
@@ -463,6 +501,32 @@ databar table upsert <uuid> --key-col email --input data.csv
463
501
  databar table enrichments <uuid>
464
502
  databar table add-enrichment <uuid> --enrichment-id 123 --mapping '{"email": "email_col"}'
465
503
  databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>
504
+
505
+ # Duplicate, clear, export, dedupe
506
+ databar table duplicate <uuid>
507
+ databar table clear <uuid>
508
+ databar table export <uuid> --export-format csv
509
+ databar table get-export <uuid>
510
+ databar table dedupe <uuid>
511
+ ```
512
+
513
+ ### Workbooks and trash
514
+
515
+ ```bash
516
+ databar workbook list
517
+ databar workbook get <wb_id>
518
+ databar workbook rename <wb_id> --name "Q4 leads"
519
+ databar workbook duplicate <wb_id>
520
+ databar workbook add-table <wb_id> --name "Sheet 2"
521
+ databar workbook reorder <wb_id> --tables <uuid_1>,<uuid_2> # every sheet, once
522
+ databar workbook merge --target <wb_id> --sources <wb_a>,<wb_b>
523
+ databar table move <table-uuid> --workbook <wb_id>
524
+ databar table move <table-uuid> --new-workbook --name "Split out"
525
+ databar workbook delete <wb_id>
526
+
527
+ databar trash list
528
+ databar trash restore --workbooks <wb_id>
529
+ databar trash purge --workbooks <wb_id>
466
530
  ```
467
531
 
468
532
  ### Tasks
@@ -476,6 +540,7 @@ databar task get <task-id> --poll
476
540
 
477
541
  # Collect the rows a running bulk task has already finished
478
542
  databar task get <task-id> --partial
543
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
479
544
 
480
545
  # Stop a running task; finished rows keep their results
481
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.8.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.8.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(
@@ -12,6 +12,7 @@ CLI commands for tables and rows.
12
12
  databar table enrichments <uuid>
13
13
  databar table add-enrichment <uuid> --enrichment-id <n> --mapping '{...}'
14
14
  databar table run-enrichment <uuid> --enrichment-id <n> [--run-strategy]
15
+ databar table move <uuid> (--workbook <wb_id> | --new-workbook [--name])
15
16
  """
16
17
 
17
18
  from __future__ import annotations
@@ -469,6 +470,39 @@ def dedupe_table(
469
470
  output(result.model_dump(), fmt)
470
471
 
471
472
 
473
+ @app.command("move")
474
+ def move_table(
475
+ table_uuid: str = _TABLE_UUID,
476
+ workbook: Optional[str] = typer.Option(None, "--workbook", "-w", help="Target workbook id (wb_…)."),
477
+ new_workbook: bool = typer.Option(False, "--new-workbook", help="Split the sheet out into a new workbook."),
478
+ name: Optional[str] = typer.Option(
479
+ None, "--name", "-n", help="Name of the new workbook (with --new-workbook). Default: the sheet name."
480
+ ),
481
+ fmt: OutputFormat = typer.Option(OutputFormat.TABLE, "--format", "--output", "-f"),
482
+ ) -> None:
483
+ """Move a sheet into another workbook, or split it out into a new one."""
484
+ if bool(workbook) == new_workbook:
485
+ error("Pass --workbook <wb_id> or --new-workbook, not both.")
486
+ if name is not None and not new_workbook:
487
+ error("--name names the new workbook; use it with --new-workbook.")
488
+ client = get_client()
489
+ try:
490
+ result = client.move_table(table_uuid, workbook=workbook, new_workbook=new_workbook, name=name)
491
+ except DatabarError as e:
492
+ error(e)
493
+ finally:
494
+ client.close()
495
+ target = result.get("workbook")
496
+ status = result.get("status")
497
+ if status == "unchanged":
498
+ info(f"Table is already in workbook {target}.")
499
+ elif status == "created":
500
+ success(f"Moved into new workbook {target}")
501
+ else:
502
+ success(f"Moved into workbook {target}")
503
+ output(result, fmt)
504
+
505
+
472
506
  # ---------------------------------------------------------------------------
473
507
  # Helpers
474
508
  # ---------------------------------------------------------------------------
@@ -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:
@@ -8,6 +8,7 @@ CLI commands for workbooks and trash.
8
8
  databar workbook duplicate <id>
9
9
  databar workbook merge --target <id> --sources id1,id2
10
10
  databar workbook add-table <id> [--name]
11
+ databar workbook reorder <id> --tables uuid1,uuid2,...
11
12
  databar trash list
12
13
  databar trash restore --workbooks id1 [--tables uuid]
13
14
  databar trash purge --workbooks id1 [--tables uuid]
@@ -163,6 +164,39 @@ def add_workbook_table(
163
164
  success(f"Added table {table.get('identifier')}")
164
165
 
165
166
 
167
+ @workbook_app.command("reorder")
168
+ def reorder_workbook_tables(
169
+ workbook_id: str = typer.Argument(..., help="Workbook identifier (wb_…)."),
170
+ tables: str = typer.Option(
171
+ ...,
172
+ "--tables",
173
+ "-t",
174
+ help="Comma-separated table UUIDs in the new order. List every sheet of the workbook exactly once.",
175
+ ),
176
+ fmt: OutputFormat = typer.Option(OutputFormat.TABLE, "--format", "--output", "-f"),
177
+ ) -> None:
178
+ """Set the order of a workbook's sheets (tabs)."""
179
+ table_ids = [s.strip() for s in tables.split(",") if s.strip()]
180
+ if not table_ids:
181
+ error("Pass --tables with the workbook's table UUIDs in the new order.")
182
+ if len(set(table_ids)) != len(table_ids):
183
+ error("--tables lists a table more than once; list each sheet exactly once.")
184
+ client = get_client()
185
+ try:
186
+ wb = client.reorder_workbook_tables(workbook_id, table_ids)
187
+ except DatabarError as e:
188
+ error(e)
189
+ finally:
190
+ client.close()
191
+ success(f"Reordered {len(table_ids)} sheets in {wb.identifier}")
192
+ sheets = sorted(wb.tables, key=lambda t: t.position)
193
+ output(
194
+ [{"position": t.position, "uuid": t.identifier, "name": t.name} for t in sheets],
195
+ fmt,
196
+ table_columns=["position", "uuid", "name"],
197
+ )
198
+
199
+
166
200
  @trash_app.command("list")
167
201
  def list_trash(
168
202
  fmt: OutputFormat = typer.Option(OutputFormat.TABLE, "--format", "--output", "-f"),
@@ -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.8.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
@@ -264,6 +264,35 @@ client.upsert_rows(table.identifier, rows)
264
264
 
265
265
  # Delete specific rows
266
266
  client.delete_rows(table.identifier, ["row-uuid-1", "row-uuid-2"])
267
+
268
+ # Duplicate, clear, export, dedupe
269
+ copy = client.duplicate_table(table.identifier)
270
+ client.clear_table(table.identifier)
271
+ client.export_table(table.identifier, format="csv")
272
+ print(client.get_table_export(table.identifier).file)
273
+ client.dedupe_table_rows(table.identifier)
274
+ ```
275
+
276
+ ### Workbooks and trash
277
+
278
+ ```python
279
+ workbooks = client.list_workbooks()
280
+ wb = client.get_workbook(workbooks[0].identifier)
281
+ client.rename_workbook(wb.identifier, "Q4 leads")
282
+ client.add_workbook_table(wb.identifier, name="Sheet 2")
283
+ # Set the tab order: list every sheet of the workbook exactly once
284
+ sheets = client.get_workbook(wb.identifier).tables
285
+ client.reorder_workbook_tables(wb.identifier, [s.identifier for s in reversed(sheets)])
286
+ client.duplicate_workbook(wb.identifier)
287
+ client.merge_workbooks(wb.identifier, ["wb_other"])
288
+ client.move_table(table.identifier, workbook=wb.identifier)
289
+ client.move_table(table.identifier, new_workbook=True, name="Split out")
290
+ client.delete_workbook(wb.identifier)
291
+
292
+ for item in client.list_trash():
293
+ print(item.kind, item.identifier)
294
+ client.restore_trash(workbooks=[wb.identifier])
295
+ client.purge_trash(workbooks=[wb.identifier])
267
296
  ```
268
297
 
269
298
  ### Enrichments on tables
@@ -281,6 +310,12 @@ result = client.add_enrichment(
281
310
  )
282
311
  print(f"Added enrichment #{result.id}: {result.enrichment_name}")
283
312
 
313
+ client.update_enrichment(
314
+ table.identifier,
315
+ result.id,
316
+ launch_strategy="run_on_update",
317
+ )
318
+
284
319
  # Run it (run_strategy: run_all | run_empty | run_errors)
285
320
  status = client.run_table_enrichment(
286
321
  table.identifier,
@@ -374,6 +409,9 @@ status.progress # {"total": 2, "completed": 1, "failed": 0, "processing
374
409
  # Rows that have already finished, without waiting for the rest
375
410
  client.get_task(task.task_id, include_partial=True).data
376
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
+
377
415
  # Stop it — unfinished requests are refunded, finished rows keep their results
378
416
  client.cancel_task(task.task_id)
379
417
  ```
@@ -518,6 +556,32 @@ databar table upsert <uuid> --key-col email --input data.csv
518
556
  databar table enrichments <uuid>
519
557
  databar table add-enrichment <uuid> --enrichment-id 123 --mapping '{"email": "email_col"}'
520
558
  databar table run-enrichment <uuid> --enrichment-id <table-enrichment-id>
559
+
560
+ # Duplicate, clear, export, dedupe
561
+ databar table duplicate <uuid>
562
+ databar table clear <uuid>
563
+ databar table export <uuid> --export-format csv
564
+ databar table get-export <uuid>
565
+ databar table dedupe <uuid>
566
+ ```
567
+
568
+ ### Workbooks and trash
569
+
570
+ ```bash
571
+ databar workbook list
572
+ databar workbook get <wb_id>
573
+ databar workbook rename <wb_id> --name "Q4 leads"
574
+ databar workbook duplicate <wb_id>
575
+ databar workbook add-table <wb_id> --name "Sheet 2"
576
+ databar workbook reorder <wb_id> --tables <uuid_1>,<uuid_2> # every sheet, once
577
+ databar workbook merge --target <wb_id> --sources <wb_a>,<wb_b>
578
+ databar table move <table-uuid> --workbook <wb_id>
579
+ databar table move <table-uuid> --new-workbook --name "Split out"
580
+ databar workbook delete <wb_id>
581
+
582
+ databar trash list
583
+ databar trash restore --workbooks <wb_id>
584
+ databar trash purge --workbooks <wb_id>
521
585
  ```
522
586
 
523
587
  ### Tasks
@@ -531,6 +595,7 @@ databar task get <task-id> --poll
531
595
 
532
596
  # Collect the rows a running bulk task has already finished
533
597
  databar task get <task-id> --partial
598
+ databar task get <task-id> --trace # flow task: steps and the Output step that answered
534
599
 
535
600
  # Stop a running task; finished rows keep their results
536
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.8.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():
@@ -767,3 +791,75 @@ def test_output_module_does_not_import_click():
767
791
  import databar.cli._output as out
768
792
 
769
793
  assert "click" not in out.__dict__
794
+
795
+
796
+ # ---------------------------------------------------------------------------
797
+ # Workbook sheets: move / reorder
798
+ # ---------------------------------------------------------------------------
799
+
800
+ OTHER_UUID = "33333333-3333-3333-3333-333333333333"
801
+
802
+
803
+ def test_table_move_to_workbook(monkeypatch):
804
+ mock = _client_mock()
805
+ mock.move_table.return_value = {"status": "moved", "workbook": "wb_target123", "table": TABLE_UUID}
806
+ monkeypatch.setattr("databar.cli.tables.get_client", lambda: mock)
807
+ result = invoke(["table", "move", TABLE_UUID, "--workbook", "wb_target123", "--format", "json"])
808
+ assert result.exit_code == 0, result.output
809
+ assert json.loads(result.output)["data"]["workbook"] == "wb_target123"
810
+ mock.move_table.assert_called_once_with(TABLE_UUID, workbook="wb_target123", new_workbook=False, name=None)
811
+
812
+
813
+ def test_table_move_to_new_workbook_with_name(monkeypatch):
814
+ mock = _client_mock()
815
+ mock.move_table.return_value = {"status": "created", "workbook": "wb_new12345", "table": TABLE_UUID}
816
+ monkeypatch.setattr("databar.cli.tables.get_client", lambda: mock)
817
+ result = invoke(["table", "move", TABLE_UUID, "--new-workbook", "--name", "Split out"])
818
+ assert result.exit_code == 0, result.output
819
+ mock.move_table.assert_called_once_with(TABLE_UUID, workbook=None, new_workbook=True, name="Split out")
820
+
821
+
822
+ @pytest.mark.parametrize(
823
+ "args",
824
+ [
825
+ [],
826
+ ["--workbook", "wb_target123", "--new-workbook"],
827
+ ["--workbook", "wb_target123", "--name", "X"],
828
+ ],
829
+ )
830
+ def test_table_move_needs_exactly_one_target(monkeypatch, args):
831
+ mock = _client_mock()
832
+ monkeypatch.setattr("databar.cli.tables.get_client", lambda: mock)
833
+ result = invoke(["table", "move", TABLE_UUID, *args])
834
+ assert result.exit_code == 2
835
+ mock.move_table.assert_not_called()
836
+
837
+
838
+ def test_workbook_reorder(monkeypatch):
839
+ from databar.models import Workbook
840
+
841
+ mock = _client_mock()
842
+ mock.reorder_workbook_tables.return_value = Workbook(
843
+ identifier="wb_abc12345",
844
+ name="Doc",
845
+ created_at="2026-10-30T00:00:00Z",
846
+ updated_at="2026-10-30T00:00:00Z",
847
+ tables=[
848
+ {"identifier": TABLE_UUID, "name": "B", "position": 1},
849
+ {"identifier": OTHER_UUID, "name": "A", "position": 0},
850
+ ],
851
+ tables_count=2,
852
+ )
853
+ monkeypatch.setattr("databar.cli.workbooks.get_client", lambda: mock)
854
+ result = invoke(["workbook", "reorder", "wb_abc12345", "--tables", f"{OTHER_UUID}, {TABLE_UUID}", "--format", "json"])
855
+ assert result.exit_code == 0, result.output
856
+ mock.reorder_workbook_tables.assert_called_once_with("wb_abc12345", [OTHER_UUID, TABLE_UUID])
857
+ assert [t["uuid"] for t in json.loads(result.output)["data"]] == [OTHER_UUID, TABLE_UUID]
858
+
859
+
860
+ def test_workbook_reorder_rejects_repeats(monkeypatch):
861
+ mock = _client_mock()
862
+ monkeypatch.setattr("databar.cli.workbooks.get_client", lambda: mock)
863
+ result = invoke(["workbook", "reorder", "wb_abc12345", "--tables", f"{TABLE_UUID},{TABLE_UUID}"])
864
+ assert result.exit_code == 2
865
+ mock.reorder_workbook_tables.assert_not_called()
@@ -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