Add --collapse-reuse-models option

[koxudaxi]

Fixes: #1443

Summary by CodeRabbit

• New Features

  • Added --collapse-reuse-models CLI option to collapse duplicate models by replacing references instead of creating empty inheritance subclasses when used with --reuse-model.

• Documentation

  • CLI reference, quick reference, and model customization docs updated to list and describe the new --collapse-reuse-models option (index counts and alphabetical listing adjusted).

• Tests

  • Added a test validating collapse behavior when --reuse-model and --collapse-reuse-models are used together.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new CLI/config option --collapse-reuse-models (and corresponding Config/argument/CLI metadata) and threads it through generate()/Parser constructors; parser/base deduplication logic is modified to optionally collapse duplicate models into references. Documentation and tests added for the option.

Changes

Cohort / File(s)	Summary
Documentation docs/cli-reference/index.md, docs/cli-reference/model-customization.md, docs/cli-reference/quick-reference.md	Add --collapse-reuse-models option to CLI docs and alphabetical index; update category count in index.
Public API / Entry src/datamodel_code_generator/__init__.py, src/datamodel_code_generator/__main__.py	Add collapse_reuse_models: bool = False to generate() and Config; propagate value to generate/run calls.
CLI wiring src/datamodel_code_generator/arguments.py, src/datamodel_code_generator/cli_options.py	Register new CLI flag --collapse-reuse-models (store_true) and add CLI_OPTION_META entry.
Parsers (constructors) src/datamodel_code_generator/parser/base.py, src/datamodel_code_generator/parser/graphql.py, src/datamodel_code_generator/parser/jsonschema.py, src/datamodel_code_generator/parser/openapi.py	Add collapse_reuse_models: bool = False parameter to parser constructors and forward to base; store on Parser instance.
Deduplication logic src/datamodel_code_generator/parser/base.py	Modify reuse/duplicate-module consolidation paths (__reuse_model, __create_shared_module_from_duplicates) to collapse duplicates when collapse_reuse_models is enabled (in addition to existing enum-related behavior).
Tests / Fixtures tests/data/expected/main/json/json_collapse_reuse_model.py, tests/main/test_main_json.py	Add expected generated output for collapse behavior and a CLI test test_main_json_collapse_reuse_model exercising --reuse-model --collapse-reuse-models.

Sequence Diagram(s)

sequenceDiagram
    participant User as CLI User
    participant CLI as datamodel-codegen CLI
    participant Gen as generate()
    participant Parser as Parser (JsonSchema/OpenAPI/GraphQL)
    participant Dedupe as Parser.deduplication logic
    participant FS as File output

    User->>CLI: run with --reuse-model --collapse-reuse-models
    CLI->>Gen: build Config (collapse_reuse_models=True) & call generate(...)
    Gen->>Parser: instantiate parser(collapse_reuse_models=True)
    Parser->>Dedupe: parse models -> identify duplicates
    Dedupe-->>Parser: collapse duplicates into canonical refs (when enabled)
    Parser->>Gen: return consolidated model modules
    Gen->>FS: write generated code files
    FS-->>User: output files created

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review focus:
  • src/datamodel_code_generator/parser/base.py — conditional logic for collapsing vs inheriting and reference rewriting.
  • Constructor parameter propagation in graphql.py, jsonschema.py, openapi.py — ensure argument order and forwarding are correct.
  • CLI/Config propagation (__main__.py, __init__.py, arguments.py) to confirm defaults and help text.
  • New test and expected fixture in tests/ for correctness.

Possibly related PRs

• Add --use-generic-base-class option for DRY model config #2726 — Adds a boolean CLI/config flag propagated into Parser.init and threaded through generate/main/arguments (similar parameter propagation changes).
• Add auto-generated CLI reference documentation from test cases #2673 — Modifies CLI option metadata and CLI docs to add a new option; closely related to CLI docs/CLI_OPTION_META edits.

Suggested labels

safe-to-fix

Suggested reviewers

• ilovelinux

Poem

🐰 I hopped through docs and parser trees,
Replaced the pass with gentler ease.
When duplicates once multiplied,
Now references calmly coincide.
A tidy hop — fewer classes, happier keys!

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'Add --collapse-reuse-models option' directly and clearly describes the main change - introduction of a new CLI option for collapsing reused models.
Linked Issues check	✅ Passed	The PR fully addresses issue #1443 by implementing the --collapse-reuse-models option that collapses duplicate models by replacing references instead of creating empty inheritance subclasses, matching the feature request.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the --collapse-reuse-models feature: CLI argument definition, configuration propagation through layers, parser logic updates, documentation, and tests.
Docstring Coverage	✅ Passed	Docstring coverage is 90.91% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/collapse-reuse-models

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c390cec and bc6c057.

📒 Files selected for processing (1)

• src/datamodel_code_generator/parser/base.py

🧰 Additional context used

🧬 Code graph analysis (1)

src/datamodel_code_generator/parser/base.py (1)

src/datamodel_code_generator/model/enum.py (1)

• Enum (39-121)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)

• GitHub Check: py312-isort6 on Ubuntu
• GitHub Check: 3.14 on Ubuntu
• GitHub Check: 3.12 on macOS
• GitHub Check: 3.11 on Windows
• GitHub Check: 3.14 on Windows
• GitHub Check: 3.10 on Windows
• GitHub Check: 3.13 on Ubuntu
• GitHub Check: 3.12 on Windows
• GitHub Check: Analyze (python)
• GitHub Check: benchmarks

🔇 Additional comments (2)

src/datamodel_code_generator/parser/base.py (2)

745-745: LGTM! Clean parameter addition.

The new collapse_reuse_models parameter is properly typed with a sensible default value of False, maintaining backward compatibility. The parameter is correctly stored as an instance variable following the standard pattern used throughout the Parser initialization.

Also applies to: 912-912

---

1577-1579: LGTM! Consistent cross-module collapse logic.

The condition correctly applies the collapse behavior for Tree scope deduplication, checking whether the model is an Enum, whether inheritance is supported by the data model type, or whether collapse_reuse_models is enabled. This is consistent with the Module scope logic at line 1490 and ensures the feature works uniformly across both reuse scopes.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.36%. Comparing base (0906812) to head (bc6c057).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2731   +/-   ##
=======================================
  Coverage   99.36%   99.36%           
=======================================
  Files          83       83           
  Lines       12062    12068    +6     
  Branches     1456     1456           
=======================================
+ Hits        11985    11991    +6     
  Misses         45       45           
  Partials       32       32           

Flag	Coverage Δ
unittests	99.36% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

src/datamodel_code_generator/__main__.py (1)

442-443: Config plumbing for collapse_reuse_models is consistent; consider UX warning

The new Config.collapse_reuse_models field and its propagation into run_generate_from_config()/generate() look consistent with existing flags like collapse_root_models and reuse_model.

You might optionally add a CLI-level warning analogous to the --reuse-scope=tree check (e.g., when collapse_reuse_models is true but reuse_model is false) so users understand when the flag is a no-op.

Also applies to: 747-748

tests/main/test_main_json.py (1)

108-128: New CLI doc test for --collapse-reuse-models is well targeted

The test cleanly exercises --reuse-model + --collapse-reuse-models against duplicate_models.json with a dedicated golden file, and the cli_doc metadata ties into the docs pipeline appropriately.

If you want parity with test_main_json_reuse_model_pydantic2, you could later add a similar Pydantic v2 variant for this option, but it’s not strictly required for this PR.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0906812 and 286f058.

📒 Files selected for processing (13)

• docs/cli-reference/index.md
• docs/cli-reference/model-customization.md
• docs/cli-reference/quick-reference.md
• src/datamodel_code_generator/__init__.py
• src/datamodel_code_generator/__main__.py
• src/datamodel_code_generator/arguments.py
• src/datamodel_code_generator/cli_options.py
• src/datamodel_code_generator/parser/base.py
• src/datamodel_code_generator/parser/graphql.py
• src/datamodel_code_generator/parser/jsonschema.py
• src/datamodel_code_generator/parser/openapi.py
• tests/data/expected/main/json/json_collapse_reuse_model.py
• tests/main/test_main_json.py

🧰 Additional context used

🧬 Code graph analysis (2)

src/datamodel_code_generator/parser/base.py (1)

src/datamodel_code_generator/model/enum.py (1)

• Enum (39-121)

tests/main/test_main_json.py (2)

tests/main/conftest.py (2)

• output_file (98-100)
• run_main_and_assert (244-408)

tests/test_main_kr.py (1)

• output_file (44-46)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: combine coverage
• GitHub Check: benchmarks

🔇 Additional comments (13)

src/datamodel_code_generator/cli_options.py (1)

72-83: New CLI metadata entry is consistent

"--collapse-reuse-models" is correctly added as a model customization option alongside --collapse-root-models; naming and categorization look consistent with existing entries.

src/datamodel_code_generator/parser/graphql.py (1)

167-196: Correctly threads collapse_reuse_models into GraphQL parser

The new collapse_reuse_models parameter is added with a safe default and forwarded to the base Parser in the same slot as collapse_root_models, so existing behavior is preserved while enabling the new feature.

Also applies to: 265-293

docs/cli-reference/model-customization.md (1)

11-12: --collapse-reuse-models documentation is clear and aligned with behavior

The option is listed in the overview table and documented with a concrete example that accurately illustrates collapsing duplicate models when combined with --reuse-model; anchors and cross-references are consistent with the rest of the page.

Also applies to: 1204-1272

docs/cli-reference/index.md (1)

14-17: Index updated consistently for new option

The Model Customization option count and alphabetical “C” section correctly include --collapse-reuse-models with a link to its detailed docs; index structure remains coherent.

Also applies to: 44-45

src/datamodel_code_generator/parser/openapi.py (1)

253-280: OpenAPI parser correctly wires collapse_reuse_models through to base parser

The new collapse_reuse_models flag is added to the constructor with a default and passed through to JsonSchemaParser.__init__, matching the existing pattern around collapse_root_models/skip_root_model and keeping backward compatibility.

Also applies to: 351-378

docs/cli-reference/quick-reference.md (1)

80-81: Quick reference entries for --collapse-reuse-models are accurate

The new option is integrated into both the Model Customization table and the alphabetical index with descriptions that match the main documentation and correct anchor links.

Also applies to: 184-185

src/datamodel_code_generator/arguments.py (1)

172-178: New --collapse-reuse-models flag wiring looks correct

Argument wiring (store_true, default=None, help text, grouping under model customization) is consistent with existing options like --collapse-root-models and will integrate cleanly with Config.merge_args.

src/datamodel_code_generator/__init__.py (1)

455-456: Public generate() API extension is safe and correctly forwarded

Adding collapse_reuse_models as a keyword-only parameter (with a default) keeps the generate() API backward compatible, and the parser construction now forwards it via collapse_reuse_models=collapse_reuse_models, so parsers can honor the new behavior.

Also applies to: 705-707

tests/data/expected/main/json/json_collapse_reuse_model.py (1)

1-23: Golden output correctly reflects collapsed reuse behavior

The expected models (reusing ArmRight for both Arm_Right and Arm_Left, and avoiding empty subclasses) match the intended --collapse-reuse-models semantics and follow existing header/style conventions for golden files.

src/datamodel_code_generator/parser/jsonschema.py (1)

582-583: JsonSchemaParser correctly forwards collapse_reuse_models to the base parser

The new collapse_reuse_models parameter on JsonSchemaParser.__init__ and its forwarding in the super().__init__ call are consistent with the rest of the constructor, and keep existing direct usages of JsonSchemaParser backward compatible.

Also applies to: 679-681

src/datamodel_code_generator/parser/base.py (3)

745-745: LGTM! Clean parameter addition.

The new collapse_reuse_models parameter is well-positioned, properly typed, and has a sensible default that preserves backward compatibility.

---

912-912: LGTM! Proper instance variable storage.

The parameter is correctly stored as an instance variable following the established pattern.

---

1579-1582: LGTM! Consistent implementation for tree-scope reuse.

The logic correctly extends the collapsing behavior to tree-scope reuse (shared modules), maintaining consistency with the single-module reuse implementation. The three-part condition properly handles Enums, non-inheritable types, and user-requested collapsing.

[codspeed-hq]

CodSpeed Performance Report

Merging #2731 will not alter performance

_{Comparing feature/collapse-reuse-models (bc6c057) with main (0906812)}

Summary

✅ 70 untouched
⏩ 10 skipped¹

Footnotes

1. 10 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩