ripplerack 0.2.4__py3-none-any.whl

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 (40) hide show
  1. ripplerack/__init__.py +10 -0
  2. ripplerack/cli.py +518 -0
  3. ripplerack/describe.py +93 -0
  4. ripplerack/diff.py +503 -0
  5. ripplerack/display.py +378 -0
  6. ripplerack/graph.py +118 -0
  7. ripplerack/impact.py +218 -0
  8. ripplerack/importers/__init__.py +54 -0
  9. ripplerack/importers/avro/__init__.py +74 -0
  10. ripplerack/importers/avro/logical.py +48 -0
  11. ripplerack/importers/avro/names.py +206 -0
  12. ripplerack/importers/avro/problems.py +16 -0
  13. ripplerack/importers/avro/reader.py +245 -0
  14. ripplerack/importers/base.py +115 -0
  15. ripplerack/importers/common.py +254 -0
  16. ripplerack/importers/json_schema/__init__.py +75 -0
  17. ripplerack/importers/json_schema/field_types.py +152 -0
  18. ripplerack/importers/json_schema/problems.py +16 -0
  19. ripplerack/importers/json_schema/reader.py +296 -0
  20. ripplerack/importers/json_schema/walker.py +208 -0
  21. ripplerack/importers/render.py +59 -0
  22. ripplerack/importers/sql/__init__.py +54 -0
  23. ripplerack/importers/sql/catalog.py +291 -0
  24. ripplerack/importers/sql/column_types.py +189 -0
  25. ripplerack/importers/sql/parse.py +64 -0
  26. ripplerack/importers/sql/problems.py +23 -0
  27. ripplerack/importers/sql/reader.py +168 -0
  28. ripplerack/markdown.py +503 -0
  29. ripplerack/mermaid.py +236 -0
  30. ripplerack/models.py +243 -0
  31. ripplerack/parser.py +121 -0
  32. ripplerack/py.typed +0 -0
  33. ripplerack/report.py +230 -0
  34. ripplerack/semver.py +224 -0
  35. ripplerack/simulate.py +161 -0
  36. ripplerack-0.2.4.dist-info/METADATA +521 -0
  37. ripplerack-0.2.4.dist-info/RECORD +40 -0
  38. ripplerack-0.2.4.dist-info/WHEEL +4 -0
  39. ripplerack-0.2.4.dist-info/entry_points.txt +3 -0
  40. ripplerack-0.2.4.dist-info/licenses/LICENSE +21 -0
ripplerack/__init__.py ADDED
@@ -0,0 +1,10 @@
1
+ """RippleRack: local-first datacenter & data pipeline simulator with semantic versioning."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ __version__ = version("ripplerack")
7
+ except PackageNotFoundError: # pragma: no cover - running from a source checkout
8
+ __version__ = "0.0.0"
9
+
10
+ __all__ = ["__version__"]
ripplerack/cli.py ADDED
@@ -0,0 +1,518 @@
1
+ """Command line interface for RippleRack.
2
+
3
+ Each command loads what it is given, asks the engine, and hands the result to ``display`` for
4
+ people, to ``report`` for the JSON documents or to ``mermaid`` for a diagram.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Callable
10
+ from enum import StrEnum
11
+ from pathlib import Path
12
+ from typing import Annotated, NoReturn
13
+
14
+ import networkx as nx
15
+ import typer
16
+ from rich.markup import escape
17
+
18
+ from ripplerack import __version__
19
+ from ripplerack.diff import diff_datacenters
20
+ from ripplerack.display import (
21
+ console,
22
+ err_console,
23
+ print_diff,
24
+ print_impact,
25
+ print_simulation,
26
+ print_validation,
27
+ render_tree,
28
+ )
29
+ from ripplerack.graph import to_dot, to_json
30
+ from ripplerack.impact import ImpactReport, analyze_schema_change
31
+ from ripplerack.importers import (
32
+ DIALECTABLE,
33
+ IMPORTERS,
34
+ SELECTABLE,
35
+ STDIN,
36
+ ImportResult,
37
+ SourceFormat,
38
+ is_identifier,
39
+ is_version,
40
+ read_text,
41
+ render_schema_yaml,
42
+ source_label,
43
+ sql_dialects,
44
+ )
45
+ from ripplerack.markdown import DEFAULT_MAX_ITEMS, diff_to_markdown, impact_to_markdown
46
+ from ripplerack.mermaid import MermaidHighlight, to_mermaid
47
+ from ripplerack.parser import (
48
+ ErrorCode,
49
+ LoadedDatacenter,
50
+ RippleRackError,
51
+ load_datacenter,
52
+ load_schema,
53
+ )
54
+ from ripplerack.report import diff_to_dict, dumps, error_to_dict, impact_to_dict
55
+ from ripplerack.simulate import simulate
56
+
57
+ app = typer.Typer(
58
+ name="ripplerack",
59
+ help="Simulate datacenters & data pipelines and measure the ripple effect of every change.",
60
+ no_args_is_help=True,
61
+ add_completion=False,
62
+ )
63
+
64
+ DatacenterFile = Annotated[
65
+ Path, typer.Argument(help="Datacenter YAML file.", dir_okay=False, show_default=False)
66
+ ]
67
+
68
+
69
+ class GraphFormat(StrEnum):
70
+ TREE = "tree"
71
+ DOT = "dot"
72
+ JSON = "json"
73
+ MERMAID = "mermaid"
74
+
75
+
76
+ class ImpactFormat(StrEnum):
77
+ TEXT = "text"
78
+ JSON = "json"
79
+ MERMAID = "mermaid"
80
+ MARKDOWN = "markdown"
81
+
82
+
83
+ class DiffFormat(StrEnum):
84
+ TEXT = "text"
85
+ JSON = "json"
86
+ MARKDOWN = "markdown"
87
+
88
+
89
+ MaxItems = Annotated[
90
+ int | None,
91
+ typer.Option(
92
+ "--max-items",
93
+ min=0,
94
+ help="Markdown: how many rows a table or list shows before it says how many more "
95
+ f"there are (default {DEFAULT_MAX_ITEMS}; 0 shows all).",
96
+ show_default=False,
97
+ ),
98
+ ]
99
+ Diagram = Annotated[
100
+ bool | None,
101
+ typer.Option(
102
+ "--diagram/--no-diagram",
103
+ help="Markdown: draw the diagram of the impact (default: draw it).",
104
+ show_default=False,
105
+ ),
106
+ ]
107
+
108
+ # How each format that is not the tree turns the graph into text.
109
+ GRAPH_EXPORTERS: dict[GraphFormat, Callable[[nx.DiGraph[str]], str]] = {
110
+ GraphFormat.DOT: to_dot,
111
+ GraphFormat.JSON: to_json,
112
+ GraphFormat.MERMAID: to_mermaid,
113
+ }
114
+
115
+
116
+ def _version_callback(value: bool) -> None:
117
+ if value:
118
+ console.print(f"ripplerack {__version__}")
119
+ raise typer.Exit()
120
+
121
+
122
+ @app.callback()
123
+ def main(
124
+ version: Annotated[
125
+ bool,
126
+ typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version."),
127
+ ] = False,
128
+ ) -> None:
129
+ """RippleRack: datacenter simulation + data SemVer + impact analysis."""
130
+
131
+
132
+ def _fail(message: str, *, code: ErrorCode, command: str, json_mode: bool = False) -> NoReturn:
133
+ """Report an error and exit with status 1.
134
+
135
+ In JSON mode the error is a JSON document on stderr (stdout stays empty);
136
+ otherwise it is a human-readable line. The message is escaped so that text
137
+ that looks like Rich markup, such as ``[abc]`` in a path, is printed verbatim.
138
+ """
139
+ if json_mode:
140
+ typer.echo(dumps(error_to_dict(command, code, message)), err=True, nl=False)
141
+ else:
142
+ err_console.print(f"[bold red]error:[/] {escape(message)}")
143
+ raise typer.Exit(code=1)
144
+
145
+
146
+ def _markdown_options(
147
+ *, markdown: bool, max_items: int | None, diagram: bool | None
148
+ ) -> tuple[int, bool]:
149
+ """The ``--max-items`` and ``--diagram`` of a Markdown report, with their defaults.
150
+
151
+ They shape a Markdown report, so asking for them with another format is a usage error.
152
+ """
153
+ if not markdown:
154
+ for given, option in ((max_items, "--max-items"), (diagram, "--diagram/--no-diagram")):
155
+ if given is not None:
156
+ raise typer.BadParameter(
157
+ "it only applies to --format markdown", param_hint=f"'{option}'"
158
+ )
159
+ return (
160
+ DEFAULT_MAX_ITEMS if max_items is None else max_items,
161
+ True if diagram is None else diagram,
162
+ )
163
+
164
+
165
+ def _load(path: Path, *, command: str, json_mode: bool = False) -> LoadedDatacenter:
166
+ try:
167
+ return load_datacenter(path)
168
+ except RippleRackError as exc:
169
+ _fail(str(exc), code=exc.code, command=command, json_mode=json_mode)
170
+
171
+
172
+ @app.command()
173
+ def validate(file: DatacenterFile) -> None:
174
+ """Validate a datacenter file and print a summary."""
175
+ print_validation(_load(file, command="validate"))
176
+
177
+
178
+ def _impact_report(
179
+ loaded: LoadedDatacenter, pipeline: str, schema: Path, *, json_mode: bool
180
+ ) -> ImpactReport:
181
+ """The impact of the schema in the file ``schema`` on ``pipeline``; a failure ends the run."""
182
+ try:
183
+ new_schema = load_schema(schema)
184
+ return analyze_schema_change(loaded.datacenter, loaded.graph, pipeline, new_schema)
185
+ except RippleRackError as exc:
186
+ _fail(str(exc), code=exc.code, command="impact", json_mode=json_mode)
187
+ except KeyError:
188
+ _fail(
189
+ f"unknown pipeline '{pipeline}'",
190
+ code=ErrorCode.UNKNOWN_PIPELINE,
191
+ command="impact",
192
+ json_mode=json_mode,
193
+ )
194
+
195
+
196
+ @app.command()
197
+ def impact(
198
+ file: DatacenterFile,
199
+ pipeline: Annotated[
200
+ str, typer.Option("--pipeline", "-p", help="Pipeline whose schema changes.")
201
+ ],
202
+ schema: Annotated[
203
+ Path, typer.Option("--schema", "-s", help="YAML file with the new schema.", dir_okay=False)
204
+ ],
205
+ output_format: Annotated[
206
+ ImpactFormat,
207
+ typer.Option(
208
+ "--format",
209
+ "-F",
210
+ help="Output format: text, json (documented, versioned), a mermaid diagram "
211
+ "of the graph with the impact highlighted, or a markdown report for a pull request.",
212
+ ),
213
+ ] = ImpactFormat.TEXT,
214
+ fail_on_breaking: Annotated[
215
+ bool,
216
+ typer.Option("--fail-on-breaking", help="Exit with code 2 if any consumer breaks."),
217
+ ] = False,
218
+ max_items: MaxItems = None,
219
+ diagram: Diagram = None,
220
+ ) -> None:
221
+ """Compute the cascading impact of a schema change on a pipeline."""
222
+ json_mode = output_format is ImpactFormat.JSON
223
+ rows, draw = _markdown_options(
224
+ markdown=output_format is ImpactFormat.MARKDOWN, max_items=max_items, diagram=diagram
225
+ )
226
+ loaded = _load(file, command="impact", json_mode=json_mode)
227
+ report = _impact_report(loaded, pipeline, schema, json_mode=json_mode)
228
+ if json_mode:
229
+ typer.echo(dumps(impact_to_dict(loaded.datacenter.name, report)), nl=False)
230
+ elif output_format is ImpactFormat.MERMAID:
231
+ highlight = MermaidHighlight.from_impact(report)
232
+ typer.echo(to_mermaid(loaded.graph, highlight), nl=False)
233
+ elif output_format is ImpactFormat.MARKDOWN:
234
+ text = impact_to_markdown(
235
+ loaded.datacenter.name, report, loaded.graph, max_items=rows, diagram=draw
236
+ )
237
+ typer.echo(text, nl=False)
238
+ else:
239
+ print_impact(report)
240
+ if fail_on_breaking and report.broken_consumers:
241
+ raise typer.Exit(code=2)
242
+
243
+
244
+ @app.command()
245
+ def diff(
246
+ base: Annotated[
247
+ Path,
248
+ typer.Argument(help="Base datacenter file (before).", dir_okay=False, show_default=False),
249
+ ],
250
+ head: Annotated[
251
+ Path,
252
+ typer.Argument(help="Head datacenter file (after).", dir_okay=False, show_default=False),
253
+ ],
254
+ output_format: Annotated[
255
+ DiffFormat,
256
+ typer.Option(
257
+ "--format",
258
+ "-F",
259
+ help="Output format: text, json (documented and versioned) or a markdown report "
260
+ "for a pull request.",
261
+ ),
262
+ ] = DiffFormat.TEXT,
263
+ fail_on_breaking: Annotated[
264
+ bool,
265
+ typer.Option("--fail-on-breaking", help="Exit with code 2 if any consumer breaks."),
266
+ ] = False,
267
+ max_items: MaxItems = None,
268
+ diagram: Diagram = None,
269
+ ) -> None:
270
+ """Compare two datacenter files: components, schemas and cascading impact."""
271
+ json_mode = output_format is DiffFormat.JSON
272
+ rows, draw = _markdown_options(
273
+ markdown=output_format is DiffFormat.MARKDOWN, max_items=max_items, diagram=diagram
274
+ )
275
+ base_loaded = _load(base, command="diff", json_mode=json_mode)
276
+ head_loaded = _load(head, command="diff", json_mode=json_mode)
277
+ result = diff_datacenters(base_loaded, head_loaded)
278
+
279
+ if json_mode:
280
+ typer.echo(dumps(diff_to_dict(result)), nl=False)
281
+ elif output_format is DiffFormat.MARKDOWN:
282
+ typer.echo(
283
+ diff_to_markdown(result, head_loaded.graph, max_items=rows, diagram=draw), nl=False
284
+ )
285
+ else:
286
+ print_diff(result, base, head)
287
+ if fail_on_breaking and result.broken_consumers:
288
+ raise typer.Exit(code=2)
289
+
290
+
291
+ # ------------------------------------------------------------------------------ import
292
+
293
+
294
+ def _check_schema_name(value: str | None) -> str | None:
295
+ if value is not None and not is_identifier(value):
296
+ raise typer.BadParameter("use only letters, digits, '_', '.' and '-'")
297
+ return value
298
+
299
+
300
+ def _check_schema_version(value: str) -> str:
301
+ if not is_version(value):
302
+ raise typer.BadParameter("expected MAJOR.MINOR.PATCH, for example 1.0.0")
303
+ return value
304
+
305
+
306
+ def _check_select(select: str | None, source_format: SourceFormat) -> None:
307
+ """``--select`` chooses among the schemas of a file, so it needs a format that has several."""
308
+ if select is not None and source_format not in SELECTABLE:
309
+ raise typer.BadParameter(
310
+ f"a {source_format.value} file describes one schema, so there is nothing to select",
311
+ param_hint="'--select'",
312
+ )
313
+
314
+
315
+ def _check_dialect(dialect: str | None, source_format: SourceFormat) -> str | None:
316
+ """``--dialect`` names the flavour of a SQL file; it is lower case and one that exists."""
317
+ if dialect is None:
318
+ return None
319
+ if source_format not in DIALECTABLE:
320
+ raise typer.BadParameter(
321
+ f"a {source_format.value} file is not SQL, so it has no dialect",
322
+ param_hint="'--dialect'",
323
+ )
324
+ name = dialect.lower()
325
+ if name not in sql_dialects():
326
+ raise typer.BadParameter(
327
+ f"unknown dialect {dialect!r}; the dialects are {', '.join(sql_dialects())}",
328
+ param_hint="'--dialect'",
329
+ )
330
+ return name
331
+
332
+
333
+ def _check_output(output: Path, source: Path, *, force: bool) -> None:
334
+ """Refuse to overwrite the input, or any existing file unless ``--force`` is given."""
335
+ if source != STDIN and output.resolve() == source.resolve():
336
+ raise RippleRackError(
337
+ f"refusing to overwrite the input file {output}", ErrorCode.OUTPUT_EXISTS
338
+ )
339
+ if output.exists() and not force:
340
+ raise RippleRackError(
341
+ f"{output} already exists; use --force to overwrite it", ErrorCode.OUTPUT_EXISTS
342
+ )
343
+
344
+
345
+ def _write_text(target: Path, text: str) -> None:
346
+ """Write ``text`` to ``target``; a file that cannot be written is a ``RippleRackError``."""
347
+ try:
348
+ target.write_text(text, encoding="utf-8")
349
+ except OSError as exc:
350
+ raise RippleRackError(f"cannot write {target}: {exc}", ErrorCode.IO_ERROR) from exc
351
+
352
+
353
+ def _report_import(result: ImportResult, text: str, target: Path | None) -> None:
354
+ """The warnings on standard error, then the schema on standard output or a summary line."""
355
+ for issue in result.issues:
356
+ typer.secho(str(issue), err=True, fg=typer.colors.YELLOW)
357
+ if target is None:
358
+ typer.echo(text, nl=False)
359
+ return
360
+ schema = result.schema
361
+ console.print(
362
+ f"[green]✓[/] schema [bold]{escape(schema.name)}[/] {schema.version} "
363
+ f"({len(schema.fields)} fields) written to {escape(str(target))}"
364
+ )
365
+
366
+
367
+ @app.command("import")
368
+ def import_command(
369
+ file: Annotated[
370
+ Path,
371
+ typer.Argument(
372
+ help="File to import; - reads standard input.",
373
+ allow_dash=True,
374
+ dir_okay=False,
375
+ show_default=False,
376
+ ),
377
+ ],
378
+ source_format: Annotated[
379
+ SourceFormat, typer.Option("--from", help="Format of FILE.", show_default=False)
380
+ ],
381
+ output: Annotated[
382
+ Path | None,
383
+ typer.Option(
384
+ "--output",
385
+ "-o",
386
+ allow_dash=True,
387
+ dir_okay=False,
388
+ help="Write the schema to this file instead of standard output (- is standard output).",
389
+ ),
390
+ ] = None,
391
+ name: Annotated[
392
+ str | None,
393
+ typer.Option(
394
+ "--name",
395
+ callback=_check_schema_name,
396
+ help="Name of the schema. Default: the title or $id of a JSON Schema, the name "
397
+ "of an Avro record, then the file name.",
398
+ show_default=False,
399
+ ),
400
+ ] = None,
401
+ version: Annotated[
402
+ str,
403
+ typer.Option(
404
+ "--version",
405
+ callback=_check_schema_version,
406
+ help="Version to give the schema; the source has none.",
407
+ ),
408
+ ] = "1.0.0",
409
+ select: Annotated[
410
+ str | None,
411
+ typer.Option(
412
+ "--select",
413
+ help="The record (Avro) or the table (SQL) to import when the file defines several, "
414
+ "by name or full name.",
415
+ show_default=False,
416
+ ),
417
+ ] = None,
418
+ dialect: Annotated[
419
+ str | None,
420
+ typer.Option(
421
+ "--dialect",
422
+ help="SQL: the flavour the file is written in, such as postgres, mysql or sqlite. "
423
+ "Without it the standard syntax is assumed.",
424
+ show_default=False,
425
+ ),
426
+ ] = None,
427
+ lenient: Annotated[
428
+ bool,
429
+ typer.Option(
430
+ "--lenient",
431
+ help="Import what has no equivalent as json fields, with a warning, "
432
+ "instead of failing.",
433
+ ),
434
+ ] = False,
435
+ force: Annotated[
436
+ bool, typer.Option("--force", help="Overwrite the output file if it exists.")
437
+ ] = False,
438
+ ) -> None:
439
+ """Import a schema from another format and write it as RippleRack YAML.
440
+
441
+ The result is a schema file: `impact --schema` reads it as is, and under a pipeline's
442
+ `schema:` key it describes what the pipeline produces. Warnings go to standard error.
443
+ """
444
+ _check_select(select, source_format)
445
+ dialect = _check_dialect(dialect, source_format)
446
+ target = None if output is None or output == STDIN else output
447
+ try:
448
+ if target is not None:
449
+ _check_output(target, file, force=force)
450
+ result = IMPORTERS[source_format](
451
+ read_text(file),
452
+ source=source_label(file),
453
+ name=name,
454
+ version=version,
455
+ lenient=lenient,
456
+ select=select,
457
+ dialect=dialect,
458
+ )
459
+ text = render_schema_yaml(result.schema)
460
+ if target is not None:
461
+ _write_text(target, text)
462
+ except RippleRackError as exc:
463
+ _fail(str(exc), code=exc.code, command="import")
464
+ _report_import(result, text, target)
465
+
466
+
467
+ # --------------------------------------------------------------- simulate and graph
468
+
469
+
470
+ @app.command("simulate")
471
+ def simulate_command(
472
+ file: DatacenterFile,
473
+ load: Annotated[
474
+ float, typer.Option("--load", "-l", min=0.0, help="Multiplier applied to service demand.")
475
+ ] = 1.0,
476
+ fail: Annotated[
477
+ list[str] | None,
478
+ typer.Option("--fail", "-f", help="Component id to take down (repeatable)."),
479
+ ] = None,
480
+ ) -> None:
481
+ """Simulate capacity under load and the cascade of component failures."""
482
+ loaded = _load(file, command="simulate")
483
+ try:
484
+ report = simulate(loaded.datacenter, loaded.graph, load_factor=load, failures=fail)
485
+ except KeyError as exc:
486
+ err_console.print(f"[bold red]error:[/] unknown component(s): {escape(exc.args[0])}")
487
+ raise typer.Exit(code=1) from exc
488
+ print_simulation(report)
489
+
490
+
491
+ @app.command()
492
+ def graph(
493
+ file: DatacenterFile,
494
+ output_format: Annotated[
495
+ GraphFormat, typer.Option("--format", "-F", help="Output format.")
496
+ ] = GraphFormat.TREE,
497
+ output: Annotated[
498
+ Path | None, typer.Option("--output", "-o", help="Write to a file instead of stdout.")
499
+ ] = None,
500
+ ) -> None:
501
+ """Show or export the dependency graph."""
502
+ loaded = _load(file, command="graph")
503
+ if output_format is GraphFormat.TREE:
504
+ if output is not None:
505
+ err_console.print("[bold red]error:[/] --output requires --format dot, json or mermaid")
506
+ raise typer.Exit(code=1)
507
+ console.print(render_tree(loaded))
508
+ return
509
+
510
+ text = GRAPH_EXPORTERS[output_format](loaded.graph)
511
+ if output is None:
512
+ typer.echo(text, nl=False)
513
+ return
514
+ try:
515
+ _write_text(output, text)
516
+ except RippleRackError as exc:
517
+ _fail(str(exc), code=exc.code, command="graph")
518
+ console.print(f"[green]✓[/] graph written to {escape(str(output))}")
ripplerack/describe.py ADDED
@@ -0,0 +1,93 @@
1
+ """The words that say what changed between two datacenters, as plain text.
2
+
3
+ Several outputs say the same things (the terminal tables, the Markdown report), so the sentences
4
+ are written once here. Nothing is escaped: each output makes the text safe for its own syntax.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any
10
+
11
+ from ripplerack.diff import AttributeChange, DatacenterDiff
12
+ from ripplerack.graph import NodeKind
13
+
14
+ PARENT_LABELS = {NodeKind.SERVER: "in", NodeKind.SERVICE: "on", NodeKind.PIPELINE: "runs on"}
15
+
16
+
17
+ def diff_counts(result: DatacenterDiff) -> str:
18
+ """How much differs, in one line; ``No differences.`` when nothing does."""
19
+ if not result.has_differences:
20
+ return "No differences."
21
+ return (
22
+ f"{len(result.added)} added · {len(result.removed)} removed · "
23
+ f"{len(result.modified)} modified · {len(result.schema_impacts)} schema change(s) · "
24
+ f"{len(result.broken_consumers)} broken consumer(s)"
25
+ )
26
+
27
+
28
+ def describe_change(change: AttributeChange, *, details: str = "below") -> str:
29
+ """One changed attribute as a line; schema fields and inputs have their own words.
30
+
31
+ The schema fields are analysed field by field elsewhere in the output, ``details`` says where.
32
+ """
33
+ if change.attribute == "schema.fields":
34
+ return f"schema.fields: changed (see {details})"
35
+ if (
36
+ change.attribute == "inputs"
37
+ and isinstance(change.before, list)
38
+ and isinstance(change.after, list)
39
+ ):
40
+ return f"inputs: {_describe_inputs_change(change.before, change.after)}"
41
+ before, after = _format_value(change.before), _format_value(change.after)
42
+ return f"{change.attribute}: {before} → {after}"
43
+
44
+
45
+ def _describe_inputs_change(before: list[Any], after: list[Any]) -> str:
46
+ """Summarize how a pipeline's inputs changed, e.g. ``orders: -amount +amount_cents``."""
47
+ old = {item["pipeline"]: item["fields"] for item in before}
48
+ new = {item["pipeline"]: item["fields"] for item in after}
49
+ if len(old) != len(before) or len(new) != len(after): # same upstream listed twice
50
+ return f"{_format_value(before)} → {_format_value(after)}"
51
+ parts = (_describe_input(upstream, old, new) for upstream in sorted(old.keys() | new.keys()))
52
+ return "; ".join(part for part in parts if part)
53
+
54
+
55
+ def _describe_input(
56
+ upstream: str, old: dict[str, list[str] | None], new: dict[str, list[str] | None]
57
+ ) -> str:
58
+ """How the input from ``upstream`` changed; nothing when it did not."""
59
+ if upstream not in new:
60
+ return f"-{upstream}"
61
+ if upstream not in old:
62
+ return f"+{upstream}"
63
+ was, now = old[upstream], new[upstream]
64
+ if was == now:
65
+ return ""
66
+ return f"{upstream}: {_describe_fields_change(was, now)}"
67
+
68
+
69
+ def _describe_fields_change(was: list[str] | None, now: list[str] | None) -> str:
70
+ """The fields an input reads, before and after; ``None`` is all the fields of the upstream."""
71
+ if was is None or now is None:
72
+ shown = [", ".join(fields) if fields is not None else "all fields" for fields in (was, now)]
73
+ return " → ".join(shown)
74
+ gone, added = sorted(set(was) - set(now)), sorted(set(now) - set(was))
75
+ return " ".join([*(f"-{field}" for field in gone), *(f"+{field}" for field in added)])
76
+
77
+
78
+ def _format_value(value: object) -> str:
79
+ """A value as a comparison shows it: no float noise, lists joined, empty said so."""
80
+ if isinstance(value, float):
81
+ return f"{value:g}"
82
+ if isinstance(value, list):
83
+ return ", ".join(_format_input(item) for item in value) or "(none)"
84
+ return str(value) if value != "" else "(empty)"
85
+
86
+
87
+ def _format_input(item: object) -> str:
88
+ if not isinstance(item, dict):
89
+ return str(item)
90
+ fields = item.get("fields")
91
+ if isinstance(fields, list):
92
+ return f"{item.get('pipeline')}({', '.join(fields)})"
93
+ return str(item.get("pipeline"))