fix(#507): warn when CLI defaults conflict with TOML

[KyleKing]

Fixes #507

Adds a user-warning when plugins have argument defaults that conflict with the new TOML config

> uv tool install . --editable --force --with="mdformat-mkdocs[recommended]==4.1.1"
> mdformat --version
/Users/kyleking/.local/share/uv/tools/mdformat/lib/python3.13/site-packages/mdformat_mkdocs/__init__.py:0: UserWarning: The `default` (False) for ['--align-semantic-breaks-in-lists'] from the 'mkdocs' plugin, will always override any value configured in TOML. The only supported CLI defaults are `None` or `argparse.SUPPRESS`. To resolve, consider refactoring to `.add_argument(..., default=None)` 
/Users/kyleking/.local/share/uv/tools/mdformat/lib/python3.13/site-packages/mdformat_mkdocs/__init__.py:0: UserWarning: The `default` (False) for ['--ignore-missing-references'] from the 'mkdocs' plugin, will always override any value configured in TOML. The only supported CLI defaults are `None` or `argparse.SUPPRESS`. To resolve, consider refactoring to `.add_argument(..., default=None)`
mdformat 0.7.22 (mdformat_frontmatter 2.0.8, mdformat-gfm 0.4.1, mdformat_simple_breaks 0.0.1, mdformat_tables 1.0.0, mdformat_mkdocs 4.1.1, mdformat_footnote 0.1.1, mdformat_wikilink 0.2.0, mdformat-config 0.2.1, mdformat-web 0.2.0, mdformat-beautysh 0.1.1, mdformat-ruff 0.1.3)

Edit: the example STDERR above was updated to reflect the implementation changes

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (6b47904) to head (19a503e).
Report is 4 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #512   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           15        15           
  Lines          966       970    +4     
  Branches       170       171    +1     
=========================================
+ Hits           966       970    +4     

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

[hukkin]

Let's use DeprecationWarning to avoid the visibility issue mentioned here #507 (comment)

[KyleKing]

The risk with a deprecation warning is that developers may never see it because the test code needs to exercise run() or the plugin author needs to modify the warning level, which when tested with my prior release of mdformat-mkdocs wouldn't have been visible to me

I think a UserWarning might be appropriate because ultimately users will be the ones experiencing unexpected behavior. The impact should be small because only plugins that have migrated to the new groups and have arguments with defaults will need to make any changes. For examples mdformat-tables=1.0.0 won't error and I don't see other examples on GitHub: https://github.com/search?q=add_cli_argument_group+language%3APython+NOT+repo%3Ahukkin%2Fmdformat+NOT+repo%3Ajamesquilty%2Fmdformat+NOT+repo%3Aantazoey%2Fmdformat+NOT+repo%3Ajamesquilty%2Fmdformat-tables+NOT+repo%3Ahukkin%2Fmdformat-tables+NOT+repo%3AKyleKing%2Fmdformat&type=code&l=Python

[hukkin]

Besides potential unexpected behavior, the user is also the one experiencing the annoying warning message. But unlike the developer, the user cannot do anything about it. There can be plugins that decide not to read from the configuration file, and options where TOML configuration makes no sense. Mdformat would show a warning to users, though working exactly as intended.

If it's later decided that a hard error here is better, a DeprecationWarning is more accurate at signaling future removal.

So I'd say let's keep the DeprecationWarning. That, to my knowledge, is visible by default in pytest and unittest. I encourage plugin developers to test with mdformat._cli.run.

[KyleKing]

Thanks for the feedback!

[hukkin]

Besides potential unexpected behavior, the user is also the one experiencing the annoying warning message. But unlike the developer, the user cannot do anything about it. There can be plugins that decide not to read from the configuration file, and options where TOML configuration makes no sense. Mdformat would show a warning to users, though working exactly as intended.

If it's later decided that a hard error here is better, a DeprecationWarning is more accurate at signaling future removal.

So I'd say let's keep the DeprecationWarning. That, to my knowledge, is visible by default in pytest and unittest. I encourage plugin developers to test with mdformat._cli.run.

[hukkin]

Merged, thank you! 🎉