pydantic-fixturegen 1.0.0__tar.gz → 1.1.0__tar.gz

pydantic_fixturegen-1.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: pydantic-fixturegen
+Version: 1.1.0
+Summary: Deterministic fixture generator for Pydantic models.
+Project-URL: Homepage, https://github.com/casper-kristiansson/pydantic-fixturegen
+Project-URL: Documentation, https://github.com/casper-kristiansson/pydantic-fixturegen
+Project-URL: Repository, https://github.com/casper-kristiansson/pydantic-fixturegen
+Author: Fixturegen Developers
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.10
+Requires-Dist: faker>=24.0.0
+Requires-Dist: pluggy>=1.5.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
+Requires-Dist: typer>=0.12.3
+Provides-Extra: all
+Requires-Dist: hypothesis>=6.100.0; extra == 'all'
+Requires-Dist: orjson>=3.10.0; extra == 'all'
+Requires-Dist: rstr>=3.2.0; extra == 'all'
+Requires-Dist: watchfiles>=0.22.0; extra == 'all'
+Provides-Extra: all-dev
+Requires-Dist: hypothesis>=6.100.0; extra == 'all-dev'
+Requires-Dist: mypy>=1.11; extra == 'all-dev'
+Requires-Dist: orjson>=3.10.0; extra == 'all-dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'all-dev'
+Requires-Dist: pytest>=8.3; extra == 'all-dev'
+Requires-Dist: rstr>=3.2.0; extra == 'all-dev'
+Requires-Dist: ruff>=0.6.5; extra == 'all-dev'
+Requires-Dist: watchfiles>=0.22.0; extra == 'all-dev'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Provides-Extra: docs
+Provides-Extra: hypothesis
+Requires-Dist: hypothesis>=6.100.0; extra == 'hypothesis'
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6.5; extra == 'lint'
+Provides-Extra: orjson
+Requires-Dist: orjson>=3.10.0; extra == 'orjson'
+Provides-Extra: regex
+Requires-Dist: rstr>=3.2.0; extra == 'regex'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=5.0; extra == 'test'
+Requires-Dist: pytest>=8.3; extra == 'test'
+Provides-Extra: watch
+Requires-Dist: watchfiles>=0.22.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# pydantic-fixturegen: deterministic Pydantic fixtures, JSON generator, secure sandbox
+
+> Pydantic v2 deterministic fixtures, pytest fixtures, JSON generator, secure sandboxed CLI with Pluggy providers.
+
+[![PyPI version](https://img.shields.io/pypi/v/pydantic-fixturegen.svg "PyPI")](https://pypi.org/project/pydantic-fixturegen/)
+![Python versions](https://img.shields.io/pypi/pyversions/pydantic-fixturegen.svg "Python 3.10–3.13")
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg "MIT License")
+
+Generate deterministic Pydantic v2 data, pytest fixtures, and JSON quickly with a safe, task-focused CLI built for modern testing workflows.
+
+## Why
+
+<a id="why"></a>
+<a id="features"></a>
+
+- You keep tests reproducible with cascaded seeds across `random`, Faker, and optional NumPy.
+- You run untrusted models inside a safe-import sandbox with network, filesystem, and memory guards.
+- You drive JSON, pytest fixtures, schemas, and explanations from the CLI or Python helpers.
+- You extend generation with Pluggy providers and preset bundles without forking core code.
+
+You also stay observant while you work: every command can emit structured logs, diff artifacts against disk, and surface sandbox warnings so you catch regressions before they land.
+
+## Install
+
+```bash
+pip install pydantic-fixturegen
+# Extras: orjson, regex, hypothesis, watch
+pip install 'pydantic-fixturegen[all]'
+```
+
+Other flows → [docs/install.md](./docs/install.md)
+
+## Quick start
+
+<a id="quickstart"></a>
+
+1. Create a small Pydantic v2 model file.
+2. List models: `pfg list ./models.py`
+3. Generate JSON: `pfg gen json ./models.py --include models.User --n 2 --indent 2 --out ./out/User`
+4. Generate fixtures: `pfg gen fixtures ./models.py --out tests/fixtures/test_user.py --cases 3`
+   Full steps → [docs/quickstart.md](./docs/quickstart.md)
+
+JSON, fixtures, and schema commands all share flags like `--include`, `--exclude`, `--seed`, `--preset`, and `--watch`, so once you learn one flow you can handle the rest without re-reading the help pages.
+
+## Basics
+
+### Core usage (top 5)
+
+<a id="cli"></a>
+
+```bash
+pfg list <path>
+pfg gen json <target> [--n --jsonl --indent --out]
+pfg gen fixtures <target> [--style --scope --cases --out]
+pfg gen schema <target> --out <file>
+pfg doctor <target>
+```
+
+- `pfg list` discovers models with AST or safe-import; add `--ast` when you must avoid imports.
+- `pfg gen json` emits JSON or JSONL; scale with `--n`, `--jsonl`, `--shard-size`, and `--freeze-seeds`.
+- `pfg gen fixtures` writes pytest modules; tune `--style`, `--scope`, `--cases`, and `--return-type`.
+- `pfg gen schema` dumps JSON Schema atomically; point `--out` at a file or directory template.
+- `pfg doctor` audits coverage and sandbox warnings; fail builds with `--fail-on-gaps`.
+
+All commands → [docs/cli.md](./docs/cli.md)
+
+### Basic configuration
+
+<a id="configuration-precedence"></a>
+
+| key                   | type               | default | purpose       |
+| --------------------- | ------------------ | ------- | ------------- |
+| seed                  | int \| str \| null | null    | Global seed   |
+| locale                | str                | en_US   | Faker locale  |
+| union_policy          | enum               | first   | Union branch  |
+| enum_policy           | enum               | first   | Enum choice   |
+| json.indent           | int                | 2       | Pretty JSON   |
+| json.orjson           | bool               | false   | Fast JSON     |
+| emitters.pytest.style | enum               | functions | Fixture style |
+| emitters.pytest.scope | enum               | function | Fixture scope |
+
+```toml
+[tool.pydantic_fixturegen]
+seed = 42
+[tool.pydantic_fixturegen.json]
+indent = 2
+```
+
+Full matrix and precedence → [docs/configuration.md](./docs/configuration.md)
+
+### Common tasks
+
+- Freeze seeds for CI determinism → [docs/seeds.md](./docs/seeds.md)
+- Use watch mode → [docs/quickstart.md#watch-mode](./docs/quickstart.md#watch-mode)
+- Templated output paths → [docs/output-paths.md](./docs/output-paths.md)
+- Provider customization → [docs/providers.md](./docs/providers.md)
+- Capture explain trees or JSON diagnostics for review → [docs/explain.md](./docs/explain.md)
+
+## Documentation
+
+<a id="next-steps"></a>
+<a id="architecture"></a>
+<a id="comparison"></a>
+
+[Index](./docs/index.md) · [Quickstart](./docs/quickstart.md) · [Cookbook](./docs/cookbook.md) · [Configuration](./docs/configuration.md) · [CLI](./docs/cli.md) · [Concepts](./docs/concepts.md) · [Features](./docs/features.md) · [Security](./docs/security.md) · [Architecture](./docs/architecture.md) · [Troubleshooting](./docs/troubleshooting.md) · [Alternatives](./docs/alternatives.md)
+
+## Community
+
+<a id="community"></a>
+
+Open issues for bugs or ideas, start Discussions for design questions, and follow the security policy when you disclose sandbox bypasses.
+
+## License
+
+<a id="license"></a>
+
+MIT. See `LICENSE`.

pydantic_fixturegen-1.1.0/README.md

@@ -0,0 +1,117 @@
+# pydantic-fixturegen: deterministic Pydantic fixtures, JSON generator, secure sandbox
+
+> Pydantic v2 deterministic fixtures, pytest fixtures, JSON generator, secure sandboxed CLI with Pluggy providers.
+
+[![PyPI version](https://img.shields.io/pypi/v/pydantic-fixturegen.svg "PyPI")](https://pypi.org/project/pydantic-fixturegen/)
+![Python versions](https://img.shields.io/pypi/pyversions/pydantic-fixturegen.svg "Python 3.10–3.13")
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg "MIT License")
+
+Generate deterministic Pydantic v2 data, pytest fixtures, and JSON quickly with a safe, task-focused CLI built for modern testing workflows.
+
+## Why
+
+<a id="why"></a>
+<a id="features"></a>
+
+- You keep tests reproducible with cascaded seeds across `random`, Faker, and optional NumPy.
+- You run untrusted models inside a safe-import sandbox with network, filesystem, and memory guards.
+- You drive JSON, pytest fixtures, schemas, and explanations from the CLI or Python helpers.
+- You extend generation with Pluggy providers and preset bundles without forking core code.
+
+You also stay observant while you work: every command can emit structured logs, diff artifacts against disk, and surface sandbox warnings so you catch regressions before they land.
+
+## Install
+
+```bash
+pip install pydantic-fixturegen
+# Extras: orjson, regex, hypothesis, watch
+pip install 'pydantic-fixturegen[all]'
+```
+
+Other flows → [docs/install.md](./docs/install.md)
+
+## Quick start
+
+<a id="quickstart"></a>
+
+1. Create a small Pydantic v2 model file.
+2. List models: `pfg list ./models.py`
+3. Generate JSON: `pfg gen json ./models.py --include models.User --n 2 --indent 2 --out ./out/User`
+4. Generate fixtures: `pfg gen fixtures ./models.py --out tests/fixtures/test_user.py --cases 3`
+   Full steps → [docs/quickstart.md](./docs/quickstart.md)
+
+JSON, fixtures, and schema commands all share flags like `--include`, `--exclude`, `--seed`, `--preset`, and `--watch`, so once you learn one flow you can handle the rest without re-reading the help pages.
+
+## Basics
+
+### Core usage (top 5)
+
+<a id="cli"></a>
+
+```bash
+pfg list <path>
+pfg gen json <target> [--n --jsonl --indent --out]
+pfg gen fixtures <target> [--style --scope --cases --out]
+pfg gen schema <target> --out <file>
+pfg doctor <target>
+```
+
+- `pfg list` discovers models with AST or safe-import; add `--ast` when you must avoid imports.
+- `pfg gen json` emits JSON or JSONL; scale with `--n`, `--jsonl`, `--shard-size`, and `--freeze-seeds`.
+- `pfg gen fixtures` writes pytest modules; tune `--style`, `--scope`, `--cases`, and `--return-type`.
+- `pfg gen schema` dumps JSON Schema atomically; point `--out` at a file or directory template.
+- `pfg doctor` audits coverage and sandbox warnings; fail builds with `--fail-on-gaps`.
+
+All commands → [docs/cli.md](./docs/cli.md)
+
+### Basic configuration
+
+<a id="configuration-precedence"></a>
+
+| key                   | type               | default | purpose       |
+| --------------------- | ------------------ | ------- | ------------- |
+| seed                  | int \| str \| null | null    | Global seed   |
+| locale                | str                | en_US   | Faker locale  |
+| union_policy          | enum               | first   | Union branch  |
+| enum_policy           | enum               | first   | Enum choice   |
+| json.indent           | int                | 2       | Pretty JSON   |
+| json.orjson           | bool               | false   | Fast JSON     |
+| emitters.pytest.style | enum               | functions | Fixture style |
+| emitters.pytest.scope | enum               | function | Fixture scope |
+
+```toml
+[tool.pydantic_fixturegen]
+seed = 42
+[tool.pydantic_fixturegen.json]
+indent = 2
+```
+
+Full matrix and precedence → [docs/configuration.md](./docs/configuration.md)
+
+### Common tasks
+
+- Freeze seeds for CI determinism → [docs/seeds.md](./docs/seeds.md)
+- Use watch mode → [docs/quickstart.md#watch-mode](./docs/quickstart.md#watch-mode)
+- Templated output paths → [docs/output-paths.md](./docs/output-paths.md)
+- Provider customization → [docs/providers.md](./docs/providers.md)
+- Capture explain trees or JSON diagnostics for review → [docs/explain.md](./docs/explain.md)
+
+## Documentation
+
+<a id="next-steps"></a>
+<a id="architecture"></a>
+<a id="comparison"></a>
+
+[Index](./docs/index.md) · [Quickstart](./docs/quickstart.md) · [Cookbook](./docs/cookbook.md) · [Configuration](./docs/configuration.md) · [CLI](./docs/cli.md) · [Concepts](./docs/concepts.md) · [Features](./docs/features.md) · [Security](./docs/security.md) · [Architecture](./docs/architecture.md) · [Troubleshooting](./docs/troubleshooting.md) · [Alternatives](./docs/alternatives.md)
+
+## Community
+
+<a id="community"></a>
+
+Open issues for bugs or ideas, start Discussions for design questions, and follow the security policy when you disclose sandbox bypasses.
+
+## License
+
+<a id="license"></a>
+
+MIT. See `LICENSE`.

pydantic_fixturegen-1.1.0/docs/alternatives.md

@@ -0,0 +1,13 @@
+# Alternatives: choose the right fixture tool
+
+> Compare pydantic-fixturegen with common approaches so you can justify the switch.
+
+| Tooling                     | Determinism                                        | Plugin model                           | Sandboxing            | CLI coverage                          | Best fit                                                |
+| --------------------------- | -------------------------------------------------- | --------------------------------------- | --------------------- | ------------------------------------- | ------------------------------------------------------- |
+| **pydantic-fixturegen**     | Strong: cascaded seeds across `random`/Faker/NumPy | Pluggy hooks (`pfg_register_providers`, `pfg_modify_strategy`, `pfg_emit_artifact`) | Yes (network, FS jail, caps) | Broad (`list`, `gen`, `diff`, `check`, `doctor`, `explain`) | Teams needing deterministic Pydantic fixtures and JSON artifacts |
+| Hand-written fixtures       | Manual discipline required                         | None                                    | None                  | None                                  | Small codebases with few models                         |
+| `factory_boy`               | Optional seeding                                   | Class-based factories                   | None                  | N/A                                   | ORM-backed object factories                             |
+| `hypothesis.extra.pydantic` | Generative, not fixed by default                   | Strategy composition                    | None                  | N/A                                   | Property-based exploration                              |
+| Custom scripts              | Depends on implementation                          | Ad hoc                                  | Rare                  | Rare                                  | One-off data dumps without reusable tooling             |
+
+When you need deterministic JSON/JSONL, pytest fixtures, and schema artefacts with a secure sandbox, pydantic-fixturegen keeps everything in one CLI. Use other tools when you prioritise interactive data exploration over reproducibility.

pydantic_fixturegen-1.1.0/docs/api.md

@@ -0,0 +1,96 @@
+# Python API: call generators from code
+
+> Use the same engine as the CLI while staying inside Python workflows.
+
+Import helpers directly:
+
+```python
+from pydantic_fixturegen.api import (
+    generate_json,
+    generate_fixtures,
+    generate_schema,
+    JsonGenerationResult,
+    FixturesGenerationResult,
+    SchemaGenerationResult,
+)
+```
+
+## `generate_json`
+
+```python
+result: JsonGenerationResult = generate_json(
+    "./models.py",
+    out="artifacts/{model}/sample-{case_index}.json",
+    count=3,
+    jsonl=True,
+    indent=0,
+    use_orjson=True,
+    shard_size=1000,
+    include=["app.models.User"],
+    seed=42,
+    preset="boundary",
+    freeze_seeds=True,
+    freeze_seeds_file=".pfg-seeds.json",
+)
+```
+
+- Parameters mirror `pfg gen json`.
+- `out` accepts the same templated placeholders as the CLI.
+- `freeze_seeds` and `freeze_seeds_file` manage deterministic per-model seeds.
+- The result exposes `paths`, `base_output`, the selected `model`, a `ConfigSnapshot`, and any warnings.
+
+## `generate_fixtures`
+
+```python
+fixtures: FixturesGenerationResult = generate_fixtures(
+    "./models.py",
+    out="tests/fixtures/{model}_fixtures.py",
+    style="factory",
+    scope="session",
+    cases=5,
+    return_type="dict",
+    seed=42,
+    p_none=0.2,
+    include=["app.models.User"],
+    preset="boundary-max",
+)
+```
+
+- Mirrors `pfg gen fixtures` options.
+- Returns the path that was written (or `None` when skipped), resolved `style`, `scope`, `return_type`, and `cases`.
+- Inspect `fixtures.metadata` for banner details such as digest and version.
+
+## `generate_schema`
+
+```python
+schema: SchemaGenerationResult = generate_schema(
+    "./models.py",
+    out="schema/{model}.json",
+    indent=2,
+    include=["app.models.User", "app.models.Address"],
+)
+```
+
+- Writes JSON Schema files atomically.
+- The result lists discovered `models`, shared config, and warnings.
+
+## Using the results
+
+Each result dataclass includes:
+
+- `paths` or `path` — filesystem locations written to disk.
+- `base_output` — the original template base path for reference.
+- `config` — `ConfigSnapshot` capturing seed, include/exclude patterns, and time anchor.
+- `warnings` — tuple of warning identifiers surfaced during generation.
+- `constraint_summary` (where applicable) — per-field constraint reports when constraints fail.
+- `delegated` — indicates whether generation was handled by a plugin.
+
+Because results are dataclasses, you can serialize them to JSON easily:
+
+```python
+from dataclasses import asdict
+
+summary = asdict(fixtures)
+```
+
+Use these helpers inside build steps, pre-commit hooks, or custom orchestration without shelling out to the CLI. Pair them with [logging](./logging.md) if you need structured telemetry from embedded runs.

pydantic_fixturegen-1.1.0/docs/architecture.md

@@ -0,0 +1,42 @@
+# Architecture: how the pipeline fits together
+
+> Understand the stages that turn Pydantic models into deterministic artifacts.
+
+```text
+Models
+  ↓
+Discovery (AST ⟷ Safe-Import Sandbox)
+  ↓
+Strategies (policies + presets + plugins)
+  ↓
+ProviderRegistry (built-ins + pfg_register_providers)
+  ↓
+Instance Builder (deterministic seeds)
+  ↓
+Emitters (JSON | Fixtures | Schema, atomic IO)
+  ↓
+Artifacts with metadata (seed/version/digest)
+```
+
+## Stage breakdown
+
+- **Discovery**: Collects model metadata using AST, sandboxed imports, or hybrid mode. Emits warnings when imports misbehave.
+- **Strategies**: `StrategyBuilder` summarises field constraints, applies presets, and calls plugin hooks to adjust strategy objects.
+- **Provider registry**: Supplies concrete value generators. Plugins can register additional providers or override defaults.
+- **Instance builder**: Cascades deterministic seeds across Faker and optional NumPy, respecting `p_none`, enum, and union policies.
+- **Emitters**: Write JSON/JSONL, pytest fixtures, and schema files atomically, templating output paths as needed.
+- **Metadata**: Banners and logs record seed, generator version, digests, style, scope, and constraint summaries.
+
+## Plugin touchpoints
+
+- `pfg_register_providers` — add or replace providers before strategies run.
+- `pfg_modify_strategy` — tweak per-field strategies after defaults are created.
+- `pfg_emit_artifact` — intercept artifact writing; return `True` to skip the built-in emitter.
+
+## Observability
+
+- Structured logging (`--log-json`) mirrors each stage with stable event names.
+- `pfg doctor` reports coverage metrics and sandbox issues after discovery and strategy building.
+- Diff/check commands reuse the same pipeline to ensure comparisons match real generation.
+
+For extension guidance, continue to [providers](./providers.md), [strategies](./strategies.md), or [emitters](./emitters.md).

pydantic_fixturegen-1.1.0/docs/cli.md

@@ -0,0 +1,160 @@
+# CLI: drive generation from commands
+
+> Learn every command, flag, and default so you can script generation with confidence.
+
+## Global options
+
+```bash
+pfg --verbose       # repeat -v to increase verbosity (info → debug)
+pfg --quiet         # repeat -q to reduce output (info → warning → error → silent)
+pfg --log-json      # emit structured JSON logs; combine with jq for CI parsing
+```
+
+You can append `-- --help` after any proxy command to view native Typer help because `pfg` forwards arguments to sub-apps.
+
+## `pfg list`
+
+```bash
+pfg list ./models.py --include pkg.User --public-only
+```
+
+- Lists fully-qualified model names discovered via AST and safe-import by default.
+- Use `--ast` to disable imports, `--hybrid` to combine AST with sandbox inspection, or `--timeout` / `--memory-limit-mb` to tune sandbox guards.
+- `--json-errors` prints machine-readable payloads with error code `20`.
+
+## `pfg gen`
+
+`gen` hosts multiple subcommands. Inspect them with `pfg gen -- --help`.
+
+### `pfg gen json`
+
+```bash
+pfg gen json ./models.py \
+  --out ./out/users.json \
+  --include pkg.User \
+  --n 10 \
+  --jsonl \
+  --indent 0 \
+  --orjson \
+  --shard-size 1000 \
+  --seed 42 \
+  --freeze-seeds \
+  --preset boundary
+```
+
+- `--out` is required and supports templates (`{model}`, `{case_index}`, `{timestamp}`).
+- Control volume with `--n` (records) and `--shard-size` (records per file).
+- Switch encoding with `--jsonl`, `--indent`, `--orjson/--no-orjson`.
+- Determinism helpers: `--seed`, `--freeze-seeds`, `--freeze-seeds-file`, `--preset`.
+- Observability: `--json-errors`, `--watch`, `--watch-debounce`, `--now`.
+
+### `pfg gen fixtures`
+
+```bash
+pfg gen fixtures ./models.py \
+  --out tests/fixtures/test_models.py \
+  --style factory \
+  --scope module \
+  --cases 3 \
+  --return-type dict \
+  --p-none 0.2 \
+  --seed 42
+```
+
+- `--out` is required and can use templates.
+- `--style` controls structure (`functions`, `factory`, `class`).
+- `--scope` sets fixture scope; `--cases` parametrises templates.
+- `--return-type` chooses between returning the model or its dict representation.
+- Determinism flags mirror `gen json`.
+
+### `pfg gen schema`
+
+```bash
+pfg gen schema ./models.py --out ./schema --include pkg.User
+```
+
+- Requires `--out` and writes JSON Schema files atomically.
+- Combine with `--include`/`--exclude`, `--json-errors`, `--watch`, and `--now`.
+
+### `pfg gen explain`
+
+```bash
+pfg gen explain ./models.py --tree --max-depth 2 --include pkg.User
+```
+
+- `--tree` prints ASCII strategy diagrams.
+- `--json` emits structured data suitable for tooling.
+- Limit depth with `--max-depth`, filter models with `--include`/`--exclude`.
+- Use `--json-errors` for machine-readable failures.
+
+## `pfg diff`
+
+```bash
+pfg diff ./models.py \
+  --json-out out/users.json \
+  --fixtures-out tests/fixtures/test_models.py \
+  --schema-out schema \
+  --show-diff
+```
+
+- Regenerates artifacts in-memory and compares them with existing files.
+- Writes JSON summaries when you pass output paths.
+- `--show-diff` streams unified diffs to stdout.
+- Determinism helpers: `--seed`, `--freeze-seeds`.
+
+## `pfg check`
+
+```bash
+pfg check ./models.py --json-errors --fixtures-out /tmp/fixtures.py
+```
+
+- Validates configuration, discovery, and emitter destinations without writing artifacts.
+- Mirrors `diff` output flags, including `--json-out`, `--fixtures-out`, and `--schema-out`.
+- Use it in CI to block invalid configs before generation.
+
+## `pfg init`
+
+```bash
+pfg init \
+  --pyproject-path pyproject.toml \
+  --yaml \
+  --yaml-path config/pydantic-fixturegen.yaml \
+  --seed 42 \
+  --union-policy weighted \
+  --enum-policy random \
+  --json-indent 2 \
+  --pytest-style functions \
+  --pytest-scope module
+```
+
+- Scaffolds configuration files and optional fixture directories.
+- Accepts `--no-pyproject` if you only want YAML.
+- Adds `.gitkeep` inside `tests/fixtures/` unless you pass `--no-fixtures-dir`.
+
+## `pfg doctor`
+
+```bash
+pfg doctor ./models.py --fail-on-gaps 0 --json-errors
+```
+
+- Audits coverage gaps (fields without providers), risky imports, and sandbox findings.
+- Use `--fail-on-gaps` to turn warnings into non-zero exits.
+- Combine with `--include`/`--exclude` to focus on specific models.
+
+## `pfg schema`
+
+```bash
+pfg schema config --out schema/config.schema.json
+```
+
+- Dumps JSON Schemas describing configuration or model outputs.
+- The `config` subcommand wraps the schema bundled under `pydantic_fixturegen/schemas/config.schema.json`.
+
+## Tips for scripting
+
+- Append `--json-errors` anywhere you need machine-readable results; check exit codes for CI gating.
+- Use `--now` when you want reproducible “current time” values in generated data.
+- `--preset boundary` or `--preset boundary-max` applies opinionated strategies; combine with explicit overrides to fine-tune probability.
+- When piping commands, pass `--` before flags for subcommands to avoid Typer proxy conflicts.
+
+Continue to [output paths](./output-paths.md) for templating and [logging](./logging.md) for structured events that pair with automation.

pydantic_fixturegen-1.1.0/docs/concepts.md

@@ -0,0 +1,36 @@
+# Concepts: why pydantic-fixturegen exists
+
+> Ground yourself in the principles behind deterministic fixture generation.
+
+## Deterministic by design
+
+- Seeds cascade across Python `random`, Faker, and optional NumPy RNGs.
+- Freeze files (`.pfg-seeds.json`) store per-model seeds so regeneration stays identical everywhere.
+- Metadata banners capture seed, version, and digest to prove provenance.
+
+## Sandbox-first safety
+
+- Untrusted models run inside a safe-import sandbox that blocks network calls, jails filesystem writes, and caps memory.
+- Exit code `40` signals timeouts; diagnostics flag risky imports.
+- Discovery supports AST-only mode when you cannot run user code at all.
+
+## CLI-first workflow
+
+- `pfg` wraps every task: list models, generate JSON, emit fixtures, diff outputs, check configs, explain strategies, and run doctors.
+- Commands share consistent flag names (`--include`, `--exclude`, `--seed`, `--preset`) to reduce context switching.
+- Watch mode (`[watch]` extra) keeps artifacts in sync during development.
+
+## Extensibility with Pluggy
+
+- Provider registry accepts new generators via `pfg_register_providers`.
+- Strategies can be adjusted per-field through `pfg_modify_strategy`.
+- Emitters can be replaced or augmented with `pfg_emit_artifact`.
+- Entry points allow third-party packages to ship plugins without forking.
+
+## Atomic, auditable output
+
+- Emitters write to temp files and rename into place, eliminating partial artifacts.
+- JSON and schema content uses sorted keys and trailing newlines for clean diffs.
+- Fixture modules store digest metadata and align with formatters like Ruff/Black.
+
+Keep these concepts in mind as you explore the [quickstart](./quickstart.md), dive into [configuration](./configuration.md), or extend the system via [providers](./providers.md).