[blocked by 9611] Add @deprecate_arg decorator

[Eric-Arellano]

Summary

There were many instances where we deprecated arguments, but used warnings.warn() directly rather than a utility from deprecation.py. That is an issue because it means we won't be setting __qiskit_deprecations__ on the function (#9611), which means that the deprecation won't show up in our docs.

This adds the new @deprecate_arg decorator, which allows us to migrate all current argument deprecations.

A benefit of this new decorator is it standardizes how we word the deprecation. Some examples:

Grover.__init__()'s argument quantum_instance is pending deprecation as of Qiskit Terra 0.22.0. It will be marked deprecated in a future release, and then removed in a future release. Instead, use the sampler argument.

ADAM.minimize()'s argument initial_point is deprecated as of Qiskit Terra 0.23.0. It will be removed no earlier than 3 months after the release date. Instead, use the argument x0, which behaves identically.

Setting amp to a complex in the ScalableSymbolicPulse constructor is deprecated as of Qiskit Terra 0.23.0. It will be removed no earlier than 3 months after the release date. Instead, use a float for amp (for the magnitude) and a float for angle.

Details and comments

Why not instead improve @deprecate_arguments (plural)? It's too brittle trying to fit all the metadata about multiple arguments' deprecations into a single decorator, as it requires us to use dictionaries to map the argument to the metadata. For example, we might want to deprecate different arguments at different times (since argument), but that wasn't possible before.

The deprecation will always show up in our documentation. But at runtime, a warning will only happen if the argument was used and the optional predicate function returns True.

For pending deprecations, rather than having a category: Type[DeprecationWarning] argument, we have the more confined pending: bool. As explained in #9601, this is a simpler interface for developers. The downside is we can't support arbitrary types of deprecation warnings, like CustomDeprecationWarning. But I don't see the need for that.

A follow up will tackle @deprecate_function.

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the the following people are requested to review this:

• @Qiskit/terra-core
• @ajavadia
• @enavarro51
• @ikkoham
• @levbishop
• @manoelmarques
• @mtreinish
• @nkanazawa1989
• @t-imamichi
• @woodsp-ibm

[Eric-Arellano]

This PR is too big to review. Going to split it out into a PR that adds @deprecate_arg and @deprecate_func, then a few PRs that apply those to the repo.

(All still blocked by #9611 though.)