fraiseql-semis 0.1.0__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.
@@ -0,0 +1,106 @@
1
+ """
2
+ fraiseql-semis: Semantic UUID-encoded fake data generator for PostgreSQL trinity pattern schemas.
3
+
4
+ This package provides tools for generating realistic, reproducible test and seed data
5
+ for PostgreSQL databases using the trinity pattern (UUID id, integer pk_*/fk_*, human-readable identifier).
6
+
7
+ Everything about the schema itself — what tables and columns exist, in what order rows may
8
+ be inserted, which columns a writer may supply, what each value must respect, and how a
9
+ seed file is written, applied and validated — comes from ``confiture.platform``. semis
10
+ supplies the values, the scenarios and the semantic UUID encoding.
11
+ """
12
+
13
+ from importlib.metadata import version
14
+
15
+ from fraiseql_semis import emit, readback, seeds
16
+ from fraiseql_semis.codes import TableCodes
17
+ from fraiseql_semis.errors import (
18
+ CodeRegistryError,
19
+ IncomparablePinError,
20
+ PinError,
21
+ ProjectError,
22
+ ResolutionError,
23
+ RowContractError,
24
+ ScenarioError,
25
+ SemisError,
26
+ UnreachableDatabaseError,
27
+ )
28
+ from fraiseql_semis.faker_provider import (
29
+ TEXT_TYPES,
30
+ CustomProviderRegistry,
31
+ FakerProvider,
32
+ Library,
33
+ Provider,
34
+ Rule,
35
+ )
36
+ from fraiseql_semis.generator import FakeDataGenerator
37
+ from fraiseql_semis.hierarchy import Hierarchy, Paths
38
+ from fraiseql_semis.pin import SchemaPin
39
+ from fraiseql_semis.project import Project, ProjectSchema
40
+ from fraiseql_semis.resolution import PrepSeedResolver, ReadBackResolver, Resolver
41
+ from fraiseql_semis.rows import Violation, check_row, require_row
42
+ from fraiseql_semis.scenario import (
43
+ Run,
44
+ Scenario,
45
+ ScenarioEntry,
46
+ ScenarioManager,
47
+ TableSpec,
48
+ Validation,
49
+ catalogue,
50
+ init_scenario,
51
+ shared_ids,
52
+ single_table,
53
+ )
54
+ from fraiseql_semis.schema import ColumnFacts, SchemaFacts, TableFacts
55
+ from fraiseql_semis.uuid_generator import SemanticUUIDGenerator, UUIDFields
56
+
57
+ __version__ = version("fraiseql-semis")
58
+
59
+ __all__ = [
60
+ "TEXT_TYPES",
61
+ "CodeRegistryError",
62
+ "ColumnFacts",
63
+ "CustomProviderRegistry",
64
+ "FakeDataGenerator",
65
+ "FakerProvider",
66
+ "Hierarchy",
67
+ "IncomparablePinError",
68
+ "Library",
69
+ "Paths",
70
+ "PinError",
71
+ "PrepSeedResolver",
72
+ "Project",
73
+ "ProjectError",
74
+ "ProjectSchema",
75
+ "Provider",
76
+ "ReadBackResolver",
77
+ "ResolutionError",
78
+ "Resolver",
79
+ "RowContractError",
80
+ "Rule",
81
+ "Run",
82
+ "Scenario",
83
+ "ScenarioEntry",
84
+ "ScenarioError",
85
+ "ScenarioManager",
86
+ "SchemaFacts",
87
+ "SchemaPin",
88
+ "SemanticUUIDGenerator",
89
+ "SemisError",
90
+ "TableCodes",
91
+ "TableFacts",
92
+ "TableSpec",
93
+ "UUIDFields",
94
+ "UnreachableDatabaseError",
95
+ "Validation",
96
+ "Violation",
97
+ "catalogue",
98
+ "check_row",
99
+ "emit",
100
+ "init_scenario",
101
+ "readback",
102
+ "require_row",
103
+ "seeds",
104
+ "shared_ids",
105
+ "single_table",
106
+ ]
@@ -0,0 +1,5 @@
1
+ """The ``semis`` command."""
2
+
3
+ from fraiseql_semis.cli.main import app, main
4
+
5
+ __all__ = ["app", "main"]
@@ -0,0 +1,493 @@
1
+ """The ``semis`` command's entry point and its subcommands.
2
+
3
+ Each command loads what it needs and hands it to the library; none of them decides what a
4
+ row holds.
5
+ """
6
+
7
+ import re
8
+ from collections import Counter
9
+ from collections.abc import Callable
10
+ from contextlib import nullcontext
11
+ from dataclasses import dataclass
12
+ from functools import wraps
13
+ from pathlib import Path
14
+ from typing import ParamSpec, TypeVar
15
+
16
+ import typer
17
+
18
+ from fraiseql_semis.cli.options import (
19
+ Config,
20
+ Count,
21
+ DatabaseUrl,
22
+ DryRun,
23
+ Format,
24
+ Locale,
25
+ MaxLevel,
26
+ Mode,
27
+ Name,
28
+ NoPin,
29
+ Output,
30
+ ScenarioFile,
31
+ ScenarioId,
32
+ ScenarioToValidate,
33
+ Seed,
34
+ SeedsDir,
35
+ SemanticUUID,
36
+ Table,
37
+ Verbose,
38
+ )
39
+ from fraiseql_semis.errors import ProjectError, ScenarioError, SemisError
40
+ from fraiseql_semis.project import Project
41
+ from fraiseql_semis.readback import transaction
42
+ from fraiseql_semis.scenario import (
43
+ Run,
44
+ Scenario,
45
+ ScenarioEntry,
46
+ ScenarioManager,
47
+ catalogue,
48
+ shared_ids,
49
+ single_table,
50
+ )
51
+ from fraiseql_semis.scenario import init_scenario as new_scenario
52
+ from fraiseql_semis.schema import ConfiturError
53
+ from fraiseql_semis.seeds import PrepSeedReport
54
+ from fraiseql_semis.uuid_generator import SemanticUUIDGenerator
55
+
56
+ app = typer.Typer(no_args_is_help=True)
57
+ P = ParamSpec("P")
58
+ R = TypeVar("R")
59
+
60
+
61
+ def _refusals(command: Callable[P, R]) -> Callable[P, R]:
62
+ """The one error boundary: a refusal is printed to stderr and becomes the exit code.
63
+
64
+ semis' own refusals exit with their ``exit_code`` (1); confiture's propagate unwrapped
65
+ (D11) and keep theirs, with their hint. Anything else is a bug, and keeps its
66
+ traceback.
67
+ """
68
+
69
+ @wraps(command)
70
+ def run(*args: P.args, **kwargs: P.kwargs) -> R:
71
+ try:
72
+ return command(*args, **kwargs)
73
+ except (SemisError, ConfiturError) as refusal:
74
+ typer.echo(_masked(str(refusal)), err=True)
75
+ raise typer.Exit(refusal.exit_code) from refusal
76
+
77
+ return run
78
+
79
+
80
+ # A URL's password, unless it is the placeholder a format hint spells out.
81
+ _PASSWORD = re.compile(r"(\b[a-z][a-z0-9+.-]*://[^\s:/@]*:)(?!password@)[^\s@]+@")
82
+
83
+
84
+ def _masked(text: str) -> str:
85
+ """*text*, every URL's password in it replaced: a refusal may repeat the URL it was given."""
86
+ return _PASSWORD.sub(r"\1***@", text)
87
+
88
+
89
+ @app.callback()
90
+ def semis() -> None:
91
+ """Reproducible seed data for PostgreSQL trinity-pattern schemas."""
92
+
93
+
94
+ @app.command("decode-uuid")
95
+ @_refusals
96
+ def decode_uuid(value: SemanticUUID, config: Config = None) -> None:
97
+ """Print the table code, scenario id, version and sequence a UUID carries.
98
+
99
+ With a project, the table and the scenario they name are printed beside them.
100
+ """
101
+ fields = SemanticUUIDGenerator.decode(value)
102
+ project = Project.find(config)
103
+ table = scenario = ""
104
+ if project is not None:
105
+ table = project.table_codes.table_for(fields.table_code) or "no table has this code"
106
+ scenario = _scenario_names(catalogue(project.scenarios), fields.scenario_id)
107
+ _field("table_code", f"{fields.table_code:#010x}", table)
108
+ _field("scenario_id", f"{fields.scenario_id:#06x}", scenario)
109
+ _field("version", str(fields.version))
110
+ _field("sequence", str(fields.sequence))
111
+
112
+
113
+ @app.command("list-scenarios")
114
+ @_refusals
115
+ def list_scenarios(config: Config = None) -> None:
116
+ """List the project's scenarios: id, mode, name and file."""
117
+ project = _require(config)
118
+ entries = catalogue(project.scenarios)
119
+ width = max((len(entry.name) for entry in entries), default=0)
120
+ for entry in entries:
121
+ path = entry.path.relative_to(project.scenarios)
122
+ typer.echo(f"{entry.id:#06x} {entry.mode:<9} {entry.name:<{width}} {path}")
123
+ shared = shared_ids(entries)
124
+ for id_, found in shared.items():
125
+ files = " and ".join(str(entry.path.relative_to(project.scenarios)) for entry in found)
126
+ typer.echo(f"scenario id {id_:#06x} is used by {files}", err=True)
127
+ if shared:
128
+ raise typer.Exit(1)
129
+
130
+
131
+ @app.command()
132
+ @_refusals
133
+ def seeds( # noqa: PLR0913 — one argument; the rest are the run's options
134
+ scenario: ScenarioFile,
135
+ *,
136
+ output: Output = None,
137
+ config: Config = None,
138
+ database_url: DatabaseUrl = None,
139
+ format: Format = None,
140
+ dry_run: DryRun = False,
141
+ no_pin: NoPin = False,
142
+ verbose: Verbose = False,
143
+ scenario_id: ScenarioId = None,
144
+ seed: Seed = None,
145
+ locale: Locale = None,
146
+ ) -> None:
147
+ """Write a prep-seed scenario's seed files. No database is reached."""
148
+ options = _Options(output, database_url, format, dry_run, no_pin, verbose)
149
+ _, manager, loaded = _load(scenario, config, options, scenario_id, seed, locale)
150
+ if loaded.mode == "read-back":
151
+ raise ScenarioError(
152
+ f"scenario {loaded.name} runs in read-back mode: its seeds are applied as they "
153
+ "are written, so they need a database",
154
+ resolution_hint="Run it with semis apply.",
155
+ )
156
+ _write(manager, loaded, options)
157
+
158
+
159
+ @app.command()
160
+ @_refusals
161
+ def generate( # noqa: PLR0913 — one argument; the rest are the run's options
162
+ scenario: ScenarioFile,
163
+ *,
164
+ output: Output = None,
165
+ config: Config = None,
166
+ database_url: DatabaseUrl = None,
167
+ format: Format = None,
168
+ dry_run: DryRun = False,
169
+ no_pin: NoPin = False,
170
+ verbose: Verbose = False,
171
+ scenario_id: ScenarioId = None,
172
+ seed: Seed = None,
173
+ locale: Locale = None,
174
+ ) -> None:
175
+ """Run a scenario in its declared mode: prep-seed writes its seeds, read-back applies them."""
176
+ options = _Options(output, database_url, format, dry_run, no_pin, verbose)
177
+ project, manager, loaded = _load(scenario, config, options, scenario_id, seed, locale)
178
+ _in_its_mode(project, manager, loaded, options)
179
+
180
+
181
+ @app.command()
182
+ @_refusals
183
+ def apply( # noqa: PLR0913 — one argument; the rest are the run's options
184
+ scenario: ScenarioFile,
185
+ *,
186
+ output: Output = None,
187
+ config: Config = None,
188
+ database_url: DatabaseUrl = None,
189
+ format: Format = None,
190
+ dry_run: DryRun = False,
191
+ no_pin: NoPin = False,
192
+ verbose: Verbose = False,
193
+ scenario_id: ScenarioId = None,
194
+ seed: Seed = None,
195
+ locale: Locale = None,
196
+ ) -> None:
197
+ """Write a scenario's seeds and apply them, in one transaction committed at the end."""
198
+ options = _Options(output, database_url, format, dry_run, no_pin, verbose)
199
+ project, manager, loaded = _load(scenario, config, options, scenario_id, seed, locale)
200
+ _apply(project, manager, loaded, options)
201
+
202
+
203
+ @app.command()
204
+ @_refusals
205
+ def table( # noqa: PLR0913 — one argument; the rest are the run's options
206
+ name: Table,
207
+ *,
208
+ count: Count,
209
+ mode: Mode,
210
+ scenario_id: ScenarioId,
211
+ output: Output = None,
212
+ config: Config = None,
213
+ database_url: DatabaseUrl = None,
214
+ format: Format = None,
215
+ dry_run: DryRun = False,
216
+ verbose: Verbose = False,
217
+ seed: Seed = None,
218
+ ) -> None:
219
+ """Generate one table's rows, as a scenario of that table alone, in the mode given."""
220
+ assert scenario_id is not None # Typer requires it: the signature gives no default
221
+ options = _Options(output, database_url, format, dry_run, False, verbose)
222
+ project = _require(config)
223
+ manager = project.manager(database_url=database_url)
224
+ scenario = single_table(name, count, mode=mode, scenario_id=scenario_id, seed=seed)
225
+ _in_its_mode(project, manager, scenario, options)
226
+
227
+
228
+ @app.command("init-scenario")
229
+ @_refusals
230
+ def init_scenario(name: Name, *, mode: Mode, config: Config = None) -> None:
231
+ """Write a new scenario listing the project's tables, with the next free scenario id."""
232
+ project = _require(config)
233
+ path, scenario_id = new_scenario(
234
+ project.scenarios, name, mode=mode, tables=project.table_codes.tables()
235
+ )
236
+ typer.echo(f"wrote {path}: scenario {name}, scenario_id {scenario_id:#06x}, {mode}")
237
+
238
+
239
+ @app.command()
240
+ @_refusals
241
+ def validate(
242
+ scenario: ScenarioFile,
243
+ config: Config = None,
244
+ database_url: DatabaseUrl = None,
245
+ no_pin: NoPin = False,
246
+ ) -> None:
247
+ """Check a scenario against the schema and its pin, drawing no rows."""
248
+ options = _Options(None, database_url, None, False, no_pin, False)
249
+ _, manager, loaded = _load(scenario, config, options)
250
+ _notices(manager.check(loaded, no_pin=no_pin))
251
+ rows = sum(spec.count for spec in loaded.tables)
252
+ typer.echo(
253
+ f"scenario {loaded.name} is valid: {len(loaded.tables)} tables, {rows} rows, {loaded.mode}"
254
+ )
255
+
256
+
257
+ @app.command("validate-seeds")
258
+ @_refusals
259
+ def validate_seeds( # noqa: PLR0913 — one argument; the rest are the validation's options
260
+ scenario: ScenarioToValidate = None,
261
+ *,
262
+ seeds: SeedsDir = None,
263
+ max_level: MaxLevel = None,
264
+ config: Config = None,
265
+ database_url: DatabaseUrl = None,
266
+ no_pin: NoPin = False,
267
+ ) -> None:
268
+ """Judge prep-seed seeds by confiture's five levels, a scenario's or a directory's.
269
+
270
+ Levels 4-5 load the seeds and run the resolvers on the database, rolled back.
271
+ """
272
+ if (scenario is None) == (seeds is None):
273
+ raise typer.BadParameter("give a scenario, or --seeds DIR", param_hint="SCENARIO")
274
+ project = _require(config)
275
+ url = _validation_url(project, database_url, max_level)
276
+ level = max_level or (_LEVELS if url else _STATIC_LEVELS)
277
+ manager = project.manager(database_url=database_url)
278
+ schema_dir = project.resolvers()
279
+ with nullcontext() if url is None else transaction(url, commit=False) as connection:
280
+ if scenario is None:
281
+ assert seeds is not None # exactly one of the two, checked above
282
+ report = manager.validate_seeds(
283
+ seeds,
284
+ schema_dir=schema_dir,
285
+ max_level=level,
286
+ connection=connection,
287
+ catalog_schema=project.catalog_schema,
288
+ )
289
+ else:
290
+ validation = manager.validate(
291
+ manager.load(scenario),
292
+ schema_dir=schema_dir,
293
+ max_level=level,
294
+ connection=connection,
295
+ catalog_schema=project.catalog_schema,
296
+ no_pin=no_pin,
297
+ )
298
+ _notices(validation.run.notices)
299
+ report, seeds = validation.report, validation.run.pin_path.parent
300
+ files = len(report.scanned_files)
301
+ typer.echo(f"validated {files} seed file{_plural(files)} at levels 1-{level}")
302
+ if _findings(report, seeds, schema_dir):
303
+ raise typer.Exit(1)
304
+
305
+
306
+ def main() -> None:
307
+ app()
308
+
309
+
310
+ @dataclass(frozen=True)
311
+ class _Options:
312
+ """How one run is carried out, as its command line says."""
313
+
314
+ output: Path | None
315
+ database_url: str | None
316
+ format: Format
317
+ dry_run: bool
318
+ no_pin: bool
319
+ verbose: bool
320
+
321
+ def out_dir(self) -> Path:
322
+ if self.output is None:
323
+ raise typer.BadParameter("seeds are written to --output DIR", param_hint="--output")
324
+ return self.output
325
+
326
+
327
+ def _load( # noqa: PLR0913, PLR0917 — the scenario, where it is read from, one run's overrides
328
+ scenario: Path,
329
+ config: Path | None,
330
+ options: _Options,
331
+ scenario_id: int | None = None,
332
+ seed: int | None = None,
333
+ locale: str | None = None,
334
+ ) -> tuple[Project, ScenarioManager, Scenario]:
335
+ """The project, its scenario manager, and the scenario at *scenario* loaded by it
336
+ with this run's overrides, each said."""
337
+ project = _require(config)
338
+ manager = project.manager(database_url=options.database_url)
339
+ loaded, notices = manager.load(scenario).for_run(
340
+ scenario_id=scenario_id, seed=seed, locale=locale
341
+ )
342
+ _notices(notices)
343
+ return project, manager, loaded
344
+
345
+
346
+ def _in_its_mode(
347
+ project: Project, manager: ScenarioManager, scenario: Scenario, options: _Options
348
+ ) -> None:
349
+ """Prep-seed writes its seeds; read-back needs a database, and applies them."""
350
+ if scenario.mode == "read-back":
351
+ _apply(project, manager, scenario, options)
352
+ else:
353
+ _write(manager, scenario, options)
354
+
355
+
356
+ def _write(manager: ScenarioManager, scenario: Scenario, options: _Options) -> None:
357
+ """*scenario*'s seeds written, or rehearsed and reported under ``--dry-run``."""
358
+ format, no_pin = options.format, options.no_pin
359
+ if options.dry_run:
360
+ run = manager.rehearse(scenario, format=format, no_pin=no_pin)
361
+ _report(run, "would write", options.verbose)
362
+ return
363
+ run = manager.execute(scenario, options.out_dir(), format=format, no_pin=no_pin)
364
+ _report(run, "wrote", options.verbose)
365
+ _pin_written(run)
366
+
367
+
368
+ def _apply(
369
+ project: Project, manager: ScenarioManager, scenario: Scenario, options: _Options
370
+ ) -> None:
371
+ """*scenario* applied in one transaction: committed, or under ``--dry-run`` rolled back."""
372
+ url = project.database_url(options.database_url, mutating=True)
373
+ format, no_pin = options.format, options.no_pin
374
+ out_dir = None if options.dry_run else options.out_dir()
375
+ with transaction(url, commit=not options.dry_run) as connection:
376
+ if out_dir is None:
377
+ run = manager.rehearse(scenario, connection=connection, format=format, no_pin=no_pin)
378
+ else:
379
+ run = manager.apply(
380
+ scenario, out_dir, connection=connection, format=format, no_pin=no_pin
381
+ )
382
+ if out_dir is None:
383
+ _report(run, "would apply", options.verbose)
384
+ typer.echo("rolled back: nothing was written or applied")
385
+ return
386
+ _report(run, "applied", options.verbose)
387
+ _pin_written(run)
388
+ typer.echo("committed")
389
+
390
+
391
+ def _report(run: Run, verb: str, verbose: bool) -> None:
392
+ """The pin check's notices, then one line per seed file."""
393
+ _notices(run.notices)
394
+ width = max((len(seed.path.name) for seed in run.seeds), default=0)
395
+ for seed in run.seeds:
396
+ line = f"{verb} {seed.path.name:<{width}} {seed.rows} rows"
397
+ if verbose:
398
+ line += f" {seed.format}: {', '.join(seed.columns)}"
399
+ typer.echo(line)
400
+
401
+
402
+ def _pin_written(run: Run) -> None:
403
+ typer.echo(f"wrote {run.pin_path}: copy it into the scenario to pin its schema")
404
+
405
+
406
+ def _notices(notices: tuple[str, ...]) -> None:
407
+ for notice in notices:
408
+ typer.echo(notice)
409
+
410
+
411
+ def _require(config: Config) -> Project:
412
+ project = Project.find(config)
413
+ if project is None:
414
+ raise ProjectError(
415
+ "no semis.yaml here, and no --config",
416
+ resolution_hint="Run from the project's directory, or pass --config semis.yaml.",
417
+ )
418
+ return project
419
+
420
+
421
+ def _scenario_names(entries: tuple[ScenarioEntry, ...], scenario_id: int) -> str:
422
+ names = sorted(entry.name for entry in entries if entry.id == scenario_id)
423
+ if not names:
424
+ return "no scenario file has this id"
425
+ if len(names) == 1:
426
+ return names[0]
427
+ return f"{', '.join(names)} ({len(names)} scenario files share this id)"
428
+
429
+
430
+ def _field(label: str, value: str, name: str = "") -> None:
431
+ typer.echo(f"{label:<13}{value:<13}{name}".rstrip())
432
+
433
+
434
+ _STATIC_LEVELS = 3 # levels 1-3 read files; 4-5 load the seeds into a database
435
+ _LEVELS = 5
436
+ _SEVERITIES = ("CRITICAL", "ERROR", "WARNING", "INFO")
437
+ _FAILING = {"CRITICAL", "ERROR"}
438
+
439
+
440
+ def _validation_url(project: Project, flag: str | None, max_level: int | None) -> str | None:
441
+ """The database levels 4-5 run on, as a command that writes finds it.
442
+
443
+ Asked for by ``--max-level``, it must be found; by default, none found means levels
444
+ 1-3 alone, and says so.
445
+ """
446
+ if max_level is not None:
447
+ if max_level <= _STATIC_LEVELS:
448
+ return None
449
+ return project.database_url(flag, mutating=True)
450
+ url = project.find_database_url(flag, mutating=True)
451
+ if url is None:
452
+ typer.echo(
453
+ "no database URL: levels 1-3 only; levels 4-5 load the seeds and run the "
454
+ "resolvers against a database"
455
+ )
456
+ return url
457
+
458
+
459
+ def _findings(report: PrepSeedReport, seeds_dir: Path, schema_dir: Path) -> bool:
460
+ """*report*'s findings, most severe first, then their count; whether one fails the run."""
461
+ violations = sorted(
462
+ report.violations, key=lambda violation: _SEVERITIES.index(violation.severity.value)
463
+ )
464
+ counts = Counter(violation.severity.value for violation in violations)
465
+ for violation in violations:
466
+ where = _where(Path(violation.file_path), violation.line_number, seeds_dir, schema_dir)
467
+ typer.echo(f"{violation.severity.value} {violation.pattern.value} {where}")
468
+ typer.echo(f" {violation.message}")
469
+ if violation.suggestion:
470
+ typer.echo(f" hint: {violation.suggestion}")
471
+ if not violations:
472
+ typer.echo("no findings")
473
+ return False
474
+ tally = ", ".join(f"{counts[name]} {name}" for name in _SEVERITIES if name in counts)
475
+ typer.echo(f"{len(violations)} finding{_plural(len(violations))}: {tally}")
476
+ return bool(_FAILING & counts.keys())
477
+
478
+
479
+ def _where(path: Path, line: int | None, seeds_dir: Path, schema_dir: Path) -> str:
480
+ """A seed by its path among the seeds, a schema file by its path in the schema tree,
481
+ then its line; a directory is named alone."""
482
+ shown = str(path)
483
+ if path.is_relative_to(seeds_dir):
484
+ shown = str(path.relative_to(seeds_dir))
485
+ elif path.is_relative_to(schema_dir):
486
+ shown = str(Path(schema_dir.name) / path.relative_to(schema_dir))
487
+ if path.is_dir() or not line:
488
+ return shown
489
+ return f"{shown}:{line}"
490
+
491
+
492
+ def _plural(count: int) -> str:
493
+ return "" if count == 1 else "s"