[MAINT]: Decorator to warn about changed parameter names & allow for deprecation period

[echedey-ls]

• Eases addressing Input parameter naming convention - time vs times #2231 (partially covered here) and Change g_poa_effective to effective_irradiance #2235
• I am familiar with the contributing guidelines
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
  • do we want this in the public API (I'd say no)?
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

@AdamRJensen is threatening my mail inbox with issues reports from the parameter renaming in #2231 and #2235 (just kidding). So maybe instead of making breaking changes we can have some deprecation period.

Maybe over-engineering a pattern in each function for each rename is not the best choice (my own idea), but we can work out some decorator to do so.

Here is that decorator, instructions and recommendations on how to use it:

• Introduced and tested a decorator that emits a warning when the old parameter name is used
  • It does NOT modify docs
  • It does NOT check in which version of pvlib to fail automatically, that's left to the test suite
  • For these non-features, I can try to do them if you are sure of what you want.
• Example of edits required in pvlib.solarposition.hour_angle, docs down below.

Wiki?

In addition, I propose adding instructions on how to proceed with renamings in the wiki.

Docs

• pvlib.solarposition.hour_angle:
  • Main latest: https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.solarposition.hour_angle.html
  • This PR: https://pvlib-python--2237.org.readthedocs.build/en/2237/reference/generated/pvlib.solarposition.hour_angle.html
• pvlib.solarposition.sun_rise_set_transit_spa:
  • Main latest: https://pvlib-python.readthedocs.io/en/latest/reference/generated/pvlib.solarposition.sun_rise_set_transit_spa.html
  • This PR: https://pvlib-python--2237.org.readthedocs.build/en/2237/reference/generated/pvlib.solarposition.sun_rise_set_transit_spa.html#pvlib-solarposition-sun-rise-set-transit-spa

[echedey-ls]

First thing is to consider if such a feature is needed/wanted for pvlib, feel free to weight in :)

[cwhanse]

Seems elegant and useful, and easy to remove if it proves troublesome.

[kandersolar]

I am cautiously on board with the decorator :)

[kandersolar]

It would be nice if the docs somehow indicated that times is still allowed, for now. Maybe we should we use deprecated instead of versionchanged during the deprecation period, and versionchanged afterwards?

[AdamRJensen]

I don't see a point to state that it's still allowed. The less work the better so I vote for version changed only. Deprecating is already cumbersome and I'm hesitant to touch that require it

[echedey-ls]

My line of thought was exactly the same of @AdamRJensen 's. However, I did hesitate about the message. It can be changed to something like:

.. versionchanged:: 0.12.0
    Renamed from ``times`` to ``time``. ``times`` was deprecated in ``0.11.2``.

or

.. versionchanged:: 0.11.2
    Renamed from ``times`` to ``time``. ``times`` will be removed in ``0.12.0``.

which explains both things but clutters the docs IMO.

I don't mind changing it thou.

[echedey-ls]

But it's true that in v0.12.0 a follow-up PR to clean up the test that I have pushed now in 65e144b is required

Edit to complete the statement: a PR required that can also be used to clean up what is left and modify docs as needed.

[echedey-ls]

I'd say this is now ready to choose a normalized deprecation/versionchanged directive format and discuss how to proceed in the future removal, or keep the admonitions.

I have a slight preference for what's been done at sun_rise_set_transit_spa, and just remove the parameter deprecated directive in v0.12.

[echedey-ls]

Let me know if new actions are desired in this PR, or if you prefer to split add decorator / address issues in different PRs.

[AdamRJensen]

I think this is awesome!

[kandersolar]

@echedey-ls I hate to ask for more work, but I think we should limit the scope of this PR to only creating the decorator (not applying it to real pvlib functions). Would you mind splitting out the solarposition.py parameter renames into new PR(s)? That will give them better visibility.

It was helpful to see the decorator "in action" on real examples though :)

[echedey-ls]

No problem. It doesn't make much sense to open the other PR now without the decorator on main, so I'll leave that up to you. These branch's commits already have the necessary changes to cherrypick them or just start from scratch, they aren't that many lines.

[kandersolar]

Thanks @echedey-ls!