[deprecated-argument] Create the initial documentation

[Pierre-Sassoulas]

Type of Changes

	Type
✓	📜 Docs

Description

Refs #5953

[codecov]

Codecov Report

Merging #8995 (18f4055) into main (fb2faee) will decrease coverage by 0.02%.
Report is 8 commits behind head on main.
The diff coverage is 57.14%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8995      +/-   ##
==========================================
- Coverage   95.76%   95.75%   -0.02%     
==========================================
  Files         173      173              
  Lines       18639    18645       +6     
==========================================
+ Hits        17850    17853       +3     
- Misses        789      792       +3     

Files Changed	Coverage Δ
pylint/testutils/_primer/package_to_lint.py	73.23% <40.00%> (-2.52%)	⬇️
pylint/checkers/base_checker.py	95.04% <100.00%> (+0.04%)	⬆️

[matusvalo]

I think an example is not clear out of blue. I needed to go back to source code documentation in order to understand it. We should put here a link to documentation of parameters and return value (or at least put a link to an example https://github.com/pylint-dev/pylint/blob/main/examples/deprecation_checker.py) or document it right here.

[Pierre-Sassoulas]

I forgot about this example, how about only a link to the example ? I also was not very clear how it should be done. Do we agree that the only way is to create a plugin, there's no configuration that can make deprecate-arguments be raised otherwise, right ?

[jacobtylerwalls]

there's no configuration that can make deprecate-arguments be raised otherwise, right ?

I think I'm missing some context here, what is the reason we can't just have a vanilla example that uses one of the deprecated arguments in stdlib.py?

[Pierre-Sassoulas]

No I thougth the same. But after a 10mn search I found no such example of deprecated arguments in the stdlib (?!). Chatgpt did hallucinate one though :D Also it seems that we only have a base class that permit to create a custom checker and not an actual builtin pylint checker ? (I did not find anything in pylint either). This is what I'm trying to confirm with @matusvalo in fact :)

[jacobtylerwalls]

👀

pylint/pylint/checkers/stdlib.py

Lines 85 to 88 in 9c1c663

	(3, 9, 0): {"random.Random.shuffle": ((1, "random"),)},
	(3, 12, 0): {
	"coroutine.throw": ((1, "value"), (2, "traceback")),
	"shutil.rmtree": ((2, "onerror"),),

[Pierre-Sassoulas]

Weeeell, I just feel silly now.

[Pierre-Sassoulas]

Also, I'm wondering if the custom checker could now be replaced by an option using qname in order to add value in this data structure after the fact ?

[matusvalo]

Now I am not sure whether everything was answered or there is still something waiting for me... :-D

[Pierre-Sassoulas]

Any idea why we can't add values in DEPRECATED_ARGUMENTS via options/configuration instead of creating a custom checker @matusvalo ? Thank you for initially reviewing the PR :)

[matusvalo]

Any idea why we can't add values in DEPRECATED_ARGUMENTS via options/configuration instead of creating a custom checker @matusvalo ?

It depends on the scope I suppose. If the scope is just python I think sure it can be via configuration I suppose. But if you want to have it as generic checker to be used for other projects - e.g. for django the plugin developer needs to specify logic how you get framework version in order to compare it to the configuration.

[Pierre-Sassoulas]

I added an example with int because depending on the version we can have syntax error once the deprecated arguments is removed. But we could add another example using py-version possibly.