Create parameter deprecation annotation

[andersonhc]

This PR creates a new deprecated_parameter(list_of_parameters) annotation

• The parameters on the list are removed before the method is executed
• Legacy code will still execute, have the parameters removed and a warning displayed
• New code will fail linters and type checkers because the deprecated argument won't be on the method signature

Checklist:

• A unit test is covering the code added / modified by this PR

• In case of a new feature, docstrings have been added, with also some documentation in the docs/ folder

• A mention of the change is present in CHANGELOG.md

• This PR is ready to be merged

By submitting this pull request, I confirm that my contribution is made under the terms of the GNU LGPL 3.0 license.

[Lucas-C]

By introducing deprecated_parameter(), we lose the information of the deprecation version.

Could we maybe preserve it by passing it to deprecated_parameter()?

[Lucas-C]

A couple of questions:

• what is the purpose/motivation for this change?
• what is the impact of this change on the pdoc-generated API documentation?

[andersonhc]

A couple of questions:

• what is the purpose/motivation for this change?
• what is the impact of this change on the pdoc-generated API documentation?

I was reviewing the changes to prepare for the next release, and we had 3 new parameters added to fpdf.add_font(). The last parameter previously was uni as a deprecated parameter.
My first idea was to add a *, on the parameter list, to force everything after to be named/kwarg only and don't break in the future if we remove uni, so I just decided to create the annotation to remove uni already from the method signature.
uni has been deprecated for more than 3 years.

The pdoc won't show uni anymore on the method signature.

If you disagree with the change or prefer to postpone it, I have no objections and we can only add the * to restrict positional arguments on the methods for now.

[Lucas-C]

The pdoc won't show uni anymore on the method signature.

OK.

First I thought: "That's a good thing, it would be nice to stop displaying old deprecated parameters in our documention."

But then I wonder: what about recently deprecated parameters?
Wouldn't it be useful for our end-users that they appear in the API documentation?

---

I'm not against this change, we should just carefully consider its impact 🙂

Should we consider using this new deprecated_parameter() in every function where we have deprecated params?
And if so, should this generalization be part of this PR?

[andersonhc]

Should we consider using this new deprecated_parameter() in every function where we have deprecated params? And if so, should this generalization be part of this PR?

My thought was to use deprecated_parameter() as a last resort before the actual removal of the deprecated parameters.

Step 1: Mark the parameter as deprecated on the documentation and emit warnings
Step 2: After a few releases, add the deprecated_parameter() annotation so the parameter is removed from the documentation and linters/IDEs will point it as error
Step 3: Actual removal of the parameter

[Lucas-C]

My thought was to use deprecated_parameter() as a last resort before the actual removal of the deprecated parameters.

Step 1: Mark the parameter as deprecated on the documentation and emit warnings Step 2: After a few releases, add the deprecated_parameter() annotation so the parameter is removed from the documentation and linters/IDEs will point it as error Step 3: Actual removal of the parameter

Sounds good 👍 🙂

Would you mind adding, as part of this PR, a short paragraph to https://py-pdf.github.io/fpdf2/Development.html named Deprecation policy that would keep a trace of what you just wrote, please?

[Lucas-C]

Perfect, thank you @andersonhc 👍