fauxdata-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/LOG.md

@@ -1,5 +1,14 @@
 # Log
 
+## 2026-04-06 — agent-friendly CLI
+
+- `init`: aggiunto `--description`, `--rows`, `--format`, `--yes`; questionary diventa fallback
+- Tutti i comandi: `epilog` con esempi in `--help`
+- `generate`: aggiunto `--dry-run` (mostra piano senza scrivere)
+- `generate`: output su successo mostra `output_path`, `format`, `rows` come chiave: valore
+- `init`: output su successo aggiunge `schema_path: <file>`
+- Fix venv: ricreato con `uv venv --clear` (cartella rinominata da `real_fake_datasets`)
+
 ## 2026-03-06 — v0.1.3
 
 - Add Python classifiers to pyproject.toml (3.11, 3.12, 3.13, MIT) — fixes pyversions badge

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fauxdata-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: CLI for generating and validating fake datasets
 Project-URL: Homepage, https://aborruso.github.io/fauxdata/
 Project-URL: Repository, https://github.com/aborruso/fauxdata

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fauxdata-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "CLI for generating and validating fake datasets"
 readme = "README.md"
 requires-python = ">=3.11"

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/src/fauxdata/__init__.py

@@ -1,3 +1,3 @@
 """fauxdata - CLI for generating and validating fake datasets."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/src/fauxdata/commands/generate.py

@@ -26,6 +26,7 @@ def run(
     fmt: Optional[str] = None,
     seed: Optional[int] = None,
     validate: bool = False,
+    dry_run: bool = False,
 ):
     """Generate a fake dataset from a YAML schema."""
     schema = load_schema(schema_path)
@@ -37,6 +38,18 @@ def run(
 
     stdout_mode = output_path == "-"
 
+    if dry_run:
+        rprint(Panel(f"[bold cyan]fauxdata generate --dry-run[/bold cyan]  [dim]{schema_path}[/dim]", expand=False))
+        rprint("[yellow]Dry run — no files will be written.[/yellow]\n")
+        rprint(f"  schema:      {schema_path}")
+        rprint(f"  rows:        {n}")
+        rprint(f"  seed:        {rng_seed}")
+        rprint(f"  format:      {output_fmt}")
+        rprint(f"  output_path: {output_path}")
+        rprint(f"  validate:    {validate}")
+        rprint(f"  columns:     {', '.join(c.name for c in schema.columns)}")
+        return
+
     if not stdout_mode:
         rprint(Panel(f"[bold cyan]fauxdata generate[/bold cyan]  [dim]{schema_path}[/dim]", expand=False))
 
@@ -51,7 +64,9 @@ def run(
     _print_schema_table(schema, n, rng_seed)
 
     saved = export_dataset(df, output_path, output_fmt)
-    rprint(f"\n[green]Saved[/green] [bold]{saved}[/bold]  ([dim]{output_fmt}, {n} rows[/dim])")
+    rprint(f"\noutput_path: {saved}")
+    rprint(f"format: {output_fmt}")
+    rprint(f"rows: {n}")
 
     if validate:
         _run_validation(df, schema)

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/src/fauxdata/commands/init.py

@@ -75,8 +75,14 @@ validation:
 """
 
 
-def run(name: str | None = None):
-    """Interactive schema template creator."""
+def run(
+    name: str | None = None,
+    description: str | None = None,
+    rows: str | None = None,
+    fmt: str | None = None,
+    yes: bool = False,
+):
+    """Create a schema template."""
     rprint(Panel("[bold cyan]fauxdata init[/bold cyan] — schema template creator", expand=False))
 
     schema_name = name or questionary.text(
@@ -87,30 +93,37 @@ def run(name: str | None = None):
     if schema_name is None:
         raise typer.Abort()
 
-    description = questionary.text(
-        "Short description:",
-        default=f"{schema_name} dataset",
-    ).ask() or ""
+    desc = description if description is not None else (
+        questionary.text(
+            "Short description:",
+            default=f"{schema_name} dataset",
+        ).ask() or ""
+    )
 
-    rows = questionary.text("Default number of rows:", default="1000").ask() or "1000"
+    n_rows = rows if rows is not None else (
+        questionary.text("Default number of rows:", default="1000").ask() or "1000"
+    )
 
-    fmt = questionary.select(
-        "Default output format:",
-        choices=["csv", "parquet", "json", "jsonl"],
-    ).ask() or "csv"
+    output_fmt = fmt if fmt is not None else (
+        questionary.select(
+            "Default output format:",
+            choices=["csv", "parquet", "json", "jsonl"],
+        ).ask() or "csv"
+    )
 
     output_file = f"{schema_name}.yml"
     out_path = Path(output_file)
 
-    if out_path.exists():
+    if out_path.exists() and not yes:
         overwrite = questionary.confirm(f"{output_file} already exists. Overwrite?", default=False).ask()
         if not overwrite:
             rprint("[yellow]Aborted.[/yellow]")
             raise typer.Exit()
 
-    content = TEMPLATE.format(name=schema_name, description=description, rows=rows, fmt=fmt)
+    content = TEMPLATE.format(name=schema_name, description=desc, rows=n_rows, fmt=output_fmt)
     out_path.write_text(content)
 
     rprint(f"[green]Created[/green] [bold]{output_file}[/bold]")
     rprint("[dim]Edit the schema then run:[/dim]")
     rprint(f"  [cyan]fauxdata generate {output_file} --validate[/cyan]")
+    rprint(f"schema_path: {output_file}")

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/src/fauxdata/main.py

@@ -44,30 +44,60 @@ def main(
         rprint(ctx.get_help())
 
 
-@app.command("init")
+@app.command(
+    "init",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata init --name people\n\n"
+        "  fauxdata init --name orders --rows 500 --format parquet\n\n"
+        "  fauxdata init --name events --description 'clickstream events' --rows 10000 --format jsonl --yes\n"
+    ),
+)
 def init_cmd(
     name: Optional[str] = typer.Option(None, "--name", "-n", help="Schema name"),
+    description: Optional[str] = typer.Option(None, "--description", "-d", help="Short description"),
+    rows: Optional[str] = typer.Option(None, "--rows", "-r", help="Default number of rows (default: 1000)"),
+    fmt: Optional[str] = typer.Option(None, "--format", "-f", help="Output format: csv, parquet, json, jsonl (default: csv)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Overwrite existing file without confirmation"),
 ):
-    """Create a schema template interactively."""
+    """Create a schema template (interactive if flags are omitted)."""
     from fauxdata.commands.init import run
-    run(name=name)
-
-
-@app.command("generate")
+    run(name=name, description=description, rows=rows, fmt=fmt, yes=yes)
+
+
+@app.command(
+    "generate",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata generate people.yml\n\n"
+        "  fauxdata generate people.yml --rows 500 --format csv --out out.csv\n\n"
+        "  fauxdata generate people.yml --seed 42 --validate\n\n"
+        "  fauxdata generate people.yml --out - --format jsonl | jq .\n\n"
+        "  fauxdata generate people.yml --dry-run\n"
+    ),
+)
 def generate_cmd(
     schema: str = typer.Argument(..., help="Path to YAML schema file"),
     rows: Optional[int] = typer.Option(None, "--rows", "-r", help="Number of rows to generate"),
-    out: Optional[str] = typer.Option(None, "--out", "-o", help="Output file path"),
+    out: Optional[str] = typer.Option(None, "--out", "-o", help="Output file path (use - for stdout)"),
     fmt: Optional[str] = typer.Option(None, "--format", "-f", help="Output format: csv, parquet, json, jsonl"),
     seed: Optional[int] = typer.Option(None, "--seed", "-s", help="Random seed for reproducibility"),
     validate: bool = typer.Option(False, "--validate", "-v", help="Run validation after generating"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be generated without writing files"),
 ):
     """Generate a fake dataset from a YAML schema."""
     from fauxdata.commands.generate import run
-    run(schema_path=schema, rows=rows, out=out, fmt=fmt, seed=seed, validate=validate)
+    run(schema_path=schema, rows=rows, out=out, fmt=fmt, seed=seed, validate=validate, dry_run=dry_run)
 
 
-@app.command("validate")
+@app.command(
+    "validate",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata validate people.csv people.yml\n\n"
+        "  fauxdata validate out/orders.parquet schemas/orders.yml\n"
+    ),
+)
 def validate_cmd(
     dataset: str = typer.Argument(..., help="Path to dataset file (csv, parquet, json, jsonl)"),
     schema: str = typer.Argument(..., help="Path to YAML schema file"),
@@ -77,7 +107,14 @@ def validate_cmd(
     run(dataset_path=dataset, schema_path=schema)
 
 
-@app.command("preview")
+@app.command(
+    "preview",
+    epilog=(
+        "Examples:\n\n"
+        "  fauxdata preview people.csv\n\n"
+        "  fauxdata preview people.parquet --rows 20\n"
+    ),
+)
 def preview_cmd(
     dataset: str = typer.Argument(..., help="Path to dataset file"),
     rows: int = typer.Option(10, "--rows", "-r", help="Number of rows to preview"),

fauxdata_cli-0.1.4/tasks/todo.md

@@ -0,0 +1,38 @@
+# Agent-friendly CLI improvements
+
+## Obiettivo
+Applicare i principi per CLI usabili dagli agenti AI.
+
+## Fase 1 — Non-interactive `init`
+
+- [ ] Aggiungere `--description`, `--rows`, `--format`, `--yes` come flag a `init_cmd` in `main.py`
+- [ ] Aggiornare `run()` in `commands/init.py` per accettare questi parametri
+- [ ] Rendere i prompt questionary fallback (solo quando il flag è None)
+- [ ] `--yes` salta la conferma di sovrascrittura
+
+## Fase 2 — Esempi in `--help`
+
+- [ ] Aggiungere `epilog` con esempi a ogni comando in `main.py` (init, generate, validate, preview)
+
+## Fase 3 — `--dry-run` per `generate`
+
+- [ ] Aggiungere flag `--dry-run` a `generate_cmd` in `main.py`
+- [ ] Implementare dry-run in `commands/generate.py`: mostra cosa farebbe senza scrivere file
+
+## Fase 4 — Output strutturato su successo
+
+- [ ] `generate`: output su successo mostra chiave=valore (output_path, format, rows)
+- [ ] `init`: output su successo mostra schema_path
+
+## Domande aperte
+
+- Aggiungere anche `--quiet` / `--json` per output machine-readable?
+- `validate` e `preview` hanno già flag, sufficienti?
+
+## Review
+
+- Tutte e 4 le fasi completate; 79/79 test passano, coverage 82%
+- `init` ora fully non-interactive con `--name --description --rows --format --yes`
+- `generate` ha `--dry-run` e output strutturato chiave: valore
+- Ogni comando ha esempi nel `--help` via `epilog`
+- Venv ricreato con `--clear` (cartella rinominata da `real_fake_datasets`)

{fauxdata_cli-0.1.3 → fauxdata_cli-0.1.4}/uv.lock

@@ -250,7 +250,7 @@ wheels = [
 
 [[package]]
 name = "fauxdata-cli"
-version = "0.1.3"
+version = "0.1.4"
 source = { editable = "." }
 dependencies = [
     { name = "pointblank" },