Deprecate modelchain.get_orientation

[RDaxini]

• Related discussion Fix typos in ModelChain error messages #2492
• I am familiar with the contributing guidelines
• Tests added
• 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.

See discussion in related #2492

Original test test_bad_get_orientation(): only checked whether a value error was raised, the new test (with what I think is a clearer name) checks not only whether a value error is raised but also whether the error string matches

[RDaxini]

I could also add tests to check whether the correct values are returned according to the strategy provided, is this necessary?
For example:

def test_get_orientation_flat():
    surface_tilt, surface_azimuth = modelchain.get_orientation('flat')
    assert surface_tilt == 0
    assert surface_azimuth == 180

[cwhanse]

tests to check whether the correct values are returned

Optional IMO. I'm actually wondering why modelchain.py has this function. It was added in 2016 in the initial modelchain build and hasn't been used since in the ModelChain methods. There's a PVSystem.get_orientation method but that looks like just casting to a dict.

[RDaxini]

@cwhanse fair observation, are you proposing we deprecate and remove the function entirely?

[wholmgren]

Yes get rid of it!

[echedey-ls]

LGTM :)
Just a comment and a formatting preference down below.

[kandersolar]

Suggested change

	* Deprecate :py:func:`~pvlib.modelchain.get_orientation`. Removal scheduled for
	``v0.14.0``. (:pull:`2691`)
	* Deprecate :py:func:`~pvlib.modelchain.get_orientation`. (:pull:`2691`)

In case v0.14.0 turns out to be in the next few releases, I think it is better to not mention a version number.

However, I notice that generally I seem to be the only one advocating for not mentioning specific versions regarding deprecation removals. Maybe it's time to discuss and adopt an actual policy here? In the meantime, feel free to overrule me!

[RDaxini]

In case v0.14.0 turns out to be in the next few releases, I think it is better to not mention a version number.

Hmm that's a fair point, I confess I had not thought much about that. I think I am on board with your suggestion. If no-one objects in the next day or two, I'll commit your suggestion.

Maybe it's time to discuss and adopt an actual policy here?

+1

[kandersolar]

Suggested change

removal="0.14",

[kandersolar]

Suggested change

	since="0.13",
	since="0.13.1",

[kandersolar]

To add to @echedey-ls's point above, the usual practice would be to wait to remove the tests until we remove the functionality. For the deprecation period, we would usually retain the tests, just slightly modified so that the function calls are inside with pytest.warns(pvlibDeprecationWarning, match="..."): blocks to (1) ensure the deprecation warning is working as expected and (2) prevent that warning from escaping into the test suite's logging output.

I suggest just for the sake of best practice we should do that here too.