Add deprecation warning for Pydantic v2 without --use-annotated

[koxudaxi]

Fixes: #2313

Summary by CodeRabbit

• New Features

  • Added deprecation warning when using Pydantic v2 without the --use-annotated flag.
  • Added --no-use-annotated CLI option.
  • Enhanced --use-annotated CLI option to accept explicit true/false values.

• Documentation

  • Cleaned up typing customization documentation.

• Tests

  • Added test coverage for deprecation warning behavior.

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

[coderabbitai]

Warning

Rate limit exceeded

@koxudaxi has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 12 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 4ecea24 and c71802b.

⛔ Files ignored due to path filters (1)

• docs/llms-full.txt is excluded by none and included by none

📒 Files selected for processing (6)

• docs/cli-reference/typing-customization.md
• pyproject.toml
• src/datamodel_code_generator/__main__.py
• src/datamodel_code_generator/arguments.py
• src/datamodel_code_generator/cli_options.py
• tests/main/test_main_general.py

📝 Walkthrough

Walkthrough

This PR adds a deprecation warning system for Pydantic v2 users who don't explicitly set --use-annotated. It converts the --use-annotated flag from a boolean to an optional boolean action, documents the new --no-use-annotated alias, suppresses the related deprecation warning in pytest, and adds test coverage for the new behavior.

Changes

Cohort / File(s)	Summary
Documentation updates docs/cli-reference/typing-customization.md	Removed cross-reference links to "Python Version Compatibility" from two sections.
Deprecation warning system src/datamodel_code_generator/__main__.py	Added conditional block to emit DeprecationWarning when Pydantic v2 models are used without explicit --use-annotated or --no-use-annotated flag.
CLI argument refactoring src/datamodel_code_generator/arguments.py, src/datamodel_code_generator/cli_options.py	Changed --use-annotated from store_true action to BooleanOptionalAction to support three states (true/false/unspecified); added --no-use-annotated as documented CLI option with extended help text.
Configuration & test infrastructure pyproject.toml	Added pytest filterwarnings rule to suppress the new Pydantic v2 deprecation warning during test runs.
Test coverage tests/main/test_main_general.py	Added four new test functions (test_use_annotated_deprecation_warning_pydantic_v2, test_use_annotated_no_warning_with_flag, test_use_annotated_no_warning_with_no_flag, test_use_annotated_no_warning_pydantic_v1) to verify deprecation warning emission and suppression behaviors.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• docs: add cross-links between CLI reference and usage documentation pages #2678: Modifies docs/cli-reference/typing-customization.md cross-reference links (complementary to the documentation removal in this PR).

Suggested labels

breaking-change-analyzed

Poem

🐰 Hops with glee at warnings clear,
For Pydantic v2 growing near!
With flags and bools now three in state,
Annotated futures look so great!
Tests confirm what users seek—
Deprecation made less bleak! ✨

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 title accurately describes the main change—adding a deprecation warning for Pydantic v2 without the --use-annotated flag.
Linked Issues check	✅ Passed	The PR addresses issue #2313 by adding a deprecation warning to guide users toward using --use-annotated with Pydantic v2, supporting the broader goal of moving away from constrained-type function calls.
Out of Scope Changes check	✅ Passed	All changes are directly related to the deprecation warning feature and its supporting infrastructure; no unrelated modifications detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

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-2914.datamodel-code-generator.pages.dev

[codspeed-hq]

CodSpeed Performance Report

Merging #2914 will degrade performance by 15.38%

_{Comparing feature/use-annotated-deprecation-warning (c71802b) with main (69c51fd)}

⚠️ 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 regressions
⏩ 98 skipped¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Benchmarks breakdown

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	WallTime	test_perf_kubernetes_style_pydantic_v2	2.2 s	2.6 s	-15.31%
❌	WallTime	test_perf_deep_nested	5.3 s	6 s	-13.14%
❌	WallTime	test_perf_graphql_style_pydantic_v2	714.1 ms	828.7 ms	-13.83%
❌	WallTime	test_perf_large_models_pydantic_v2	3.1 s	3.7 s	-15.38%
❌	WallTime	test_perf_complex_refs	1.7 s	2 s	-14.47%
❌	WallTime	test_perf_all_options_enabled	5.8 s	6.8 s	-13.59%
❌	WallTime	test_perf_aws_style_openapi_pydantic_v2	1.7 s	1.9 s	-12.78%
❌	WallTime	test_perf_openapi_large	2.5 s	2.9 s	-13.39%
❌	WallTime	test_perf_multiple_files_input	3.2 s	3.7 s	-13.68%
❌	WallTime	test_perf_duplicate_names	849.8 ms	998.9 ms	-14.92%
❌	WallTime	test_perf_stripe_style_pydantic_v2	1.7 s	2 s	-13.73%

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b5a361d) to head (c71802b).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #2914   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           93        93           
  Lines        16841     16865   +24     
  Branches      1951      1952    +1     
=========================================
+ Hits         16841     16865   +24     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

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 adds a deprecation warning but does not change any actual behavior. The warning is emitted when using Pydantic v2 without explicitly specifying --use-annotated or --no-use-annotated, but the generated code output remains exactly the same. The default value (use_annotated=False) is unchanged - only a warning is added to inform users that the default will change in a future version. The change to use BooleanOptionalAction for --use-annotated is backward compatible since --use-annotated still works as before, and --no-use-annotated is simply a new option that allows users to explicitly opt out. No existing workflows, generated code, templates, or API behavior are affected.

---

This analysis was performed by Claude Code Action

[github-actions]

🎉 Released in 0.52.1

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