Document external library import use case for --type-overrides

[koxudaxi]

Summary by CodeRabbit

• Documentation
  • Comprehensively expanded typing customization guide with type override examples and best practices
  • Added detailed guidance for model-level vs field-level override formatting
  • Included practical use cases: GeoJSON, custom datetime, ObjectId, and custom validators
  • Clarified how the generator handles external library type overrides and model-level skipping behavior

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

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation and test coverage enhancements for the --type-overrides CLI option, including detailed guidance on formatting overrides, explanations of model-level behavior, practical use cases with external libraries like geojson_pydantic, and corresponding test implementation and expected output.

Changes

Cohort / File(s)	Summary
Documentation docs/cli-reference/typing-customization.md	Added comprehensive guidance on type-overrides/type-mappings, including formatting conventions (ModelName vs Model.field), model-level override behavior (skips generation and imports from specified package), and common use cases (GeoJSON, custom datetime, ObjectId, validators).
Test Data tests/data/expected/main/type_overrides_external_lib.py	New expected output file defining Pydantic models leveraging geojson_pydantic types: Model with __root__: Any and Place with name, location (Feature), and boundary (FeatureCollection) fields.
Test Implementation tests/main/test_main_general.py	Extended CLI documentation for --type-overrides option and added test_type_overrides_external_lib() test function verifying type-overrides behavior with external library types.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Add --type-overrides option to replace schema types with custom Python types #2758: Implements and tests the --type-overrides CLI feature with parser support and external-library/model-level override tests, directly related to this documentation and test coverage addition.
• Add --input-model-ref-strategy option for controlling type reuse #2850: Handles model-level type overrides that skip generation and import external types (x-python-import), sharing the same override mechanism being documented and tested here.

Suggested labels

breaking-change-analyzed

Poem

🐰 Hoppity-hop, the docs now shine so bright,
With type-overrides explained just right!
External libraries dance with geojson cheer,
Tests validate the magic we hold dear.
From override to import, the path is clear! 🌟

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: documenting an external library import use case for the --type-overrides feature, which is reflected across all three modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

---

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.}

[github-actions]

📚 Docs Preview: https://pr-2893.datamodel-code-generator.pages.dev

[codspeed-hq]

CodSpeed Performance Report

Merging #2893 will not alter performance

_{Comparing docs/type-overrides-external-lib (9137b8a) with main (4f26e46)}

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

Summary

✅ 11 untouched
⏩ 98 skipped¹

Footnotes

1. 98 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. ↩

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

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

2739-2769: Well-structured documentation for external library imports!

The additions clearly document the --type-overrides use case for external libraries like geojson-pydantic, with helpful format tables and practical examples. The note about model-level overrides skipping generation is particularly important for users to understand.

Optional: Fix markdown strong-style formatting

The static analysis tool suggests using underscores instead of asterisks for bold text for consistency. While this is purely stylistic, you might consider:

-**Override Formats:**
+__Override Formats:__

-**Common Use Cases:**
+__Common Use Cases:__

This is completely optional and doesn't affect the rendered output.

📜 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 4f26e46 and 9137b8a.

⛔ Files ignored due to path filters (1)

• tests/data/jsonschema/type_overrides_external_lib.json is excluded by !tests/data/**/*.json and included by none

📒 Files selected for processing (3)

• docs/cli-reference/typing-customization.md
• tests/data/expected/main/type_overrides_external_lib.py
• tests/main/test_main_general.py

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2026-01-02T08:25:19.839Z

Learnt from: koxudaxi
Repo: koxudaxi/datamodel-code-generator PR: 2890
File: tests/data/expected/main/jsonschema/ref_nullable_with_constraint.py:14-15
Timestamp: 2026-01-02T08:25:19.839Z
Learning: The datamodel-code-generator currently generates RootModel subclasses with an explicit `root` field annotation (e.g., `class StringType(RootModel[str]): root: str`). This is existing behavior of the code generator and should not be flagged as an issue introduced by new changes.

Applied to files:

• tests/data/expected/main/type_overrides_external_lib.py

🪛 markdownlint-cli2 (0.18.1)

docs/cli-reference/typing-customization.md

2742-2742: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

---

2742-2742: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

---

2749-2749: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

---

2749-2749: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

---

2768-2768: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

---

2768-2768: Strong style
Expected: underscore; Actual: asterisk

(MD050, strong-style)

⏰ 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). (12)

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

🔇 Additional comments (3)

tests/main/test_main_general.py (2)

675-701: LGTM - Comprehensive documentation metadata.

The cli_doc decorator provides excellent metadata for documentation generation, including the option description, usage example, and related options.

---

722-745: The input schema file tests/data/jsonschema/type_overrides_external_lib.json is already present in the repository. The file is excluded from the sparse checkout view by design (the repository's .git/info/sparse-checkout configuration explicitly excludes tests/data/**/*.json), but it exists in the full git repository. The presence of the golden output file tests/data/expected/main/type_overrides_external_lib.py with the correct expected output confirms the input schema is properly committed and the test is correctly structured.

Likely an incorrect or invalid review comment.

tests/data/expected/main/type_overrides_external_lib.py (1)

1-20: LGTM - Expected output correctly uses external library types.

The generated code properly imports and uses Feature and FeatureCollection from geojson_pydantic, demonstrating the type override functionality. The Place model correctly references these external types instead of generating them locally.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.37%. Comparing base (1d221da) to head (9137b8a).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2893   +/-   ##
=======================================
  Coverage   99.37%   99.37%           
=======================================
  Files          92       92           
  Lines       16152    16196   +44     
  Branches     1906     1915    +9     
=======================================
+ Hits        16051    16095   +44     
  Misses         52       52           
  Partials       49       49           

Flag	Coverage Δ
unittests	99.37% <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.

[github-actions]

Breaking Change Analysis

Result: No breaking changes detected

Reasoning: This PR is purely a documentation enhancement. It adds explanatory text to the --type-overrides documentation section (describing override formats, common use cases like GeoJSON types, and the behavior of model-level overrides) and adds a new test case to demonstrate external library usage. No source code, CLI behavior, default values, templates, or code generation logic was modified. The existing --type-overrides functionality remains unchanged - this PR simply documents it better.

---

This analysis was performed by Claude Code Action

[github-actions]

🎉 Released in 0.52.0

This PR is now available in the latest release. See the release notes for details.