Provide major version lower and upper bounds on all dependencies

[markcampanelli]

Is your feature request related to a problem? Please describe.
To avoid pvlib breakages when its dependencies release a major version with breaking changes, pvlib should include major version lower and upper bounds on all its dependencies.

Describe the solution you'd like
In the pyproject.toml, instead of

dependencies = [
    'numpy >= 1.17.3',
    'pandas >= 1.3.0',
    ...
]

do

dependencies = [
    'numpy >=1.17.3, <2',
    'pandas >=1.3.0, <2',
    ...
]

Describe alternatives you've considered
Keep living dangerously.

Additional context
This should be done for ALL dependencies (even the optional and testing-related ones). Some dependencies are currently given no range info, so some choices would need to be made, but usually one starts with the full range within the latest major version.

[echedey-ls]

I believe the maintainers are usually updating pvlib to allow using the latest packages when an upcoming release is made. At least that was done with numpy, see #2027

[markcampanelli]

When a major version of a dependency is released and an upper bound isn't already in place, fresh installs can go south before anyone has a chance to update for the breaking changes, because pip aggressively pulls the latest in fresh installs. Big packages like numpy do usually give fair warning, but after, say, numpy 2.0 releases with breaking changes, one probably won't be able to easily install an older version of pvlib-python "out of the box" without pip pulling an incompatible (newer) numpy version.

TBH: I've probably been stung by this more by dev dependencies (like pytest, or even older pip version updates) that all of a sudden stop working one day out of the blue, usually in CI after pushing because my local install hasn't updated likewise.

[kandersolar]

Placing upper bounds on dependency versions is a controversial topic in the python packaging world. The distinction between applications and libraries is relevant when reasoning about how strict to be with dependency specifications. This page goes into quite some detail about the reasons against doing it: https://iscinumpy.dev/post/bound-version-constraints/

For the reasons detailed in that page, I'm of the view that imposing caps for pvlib would create more problems than it would solve.

[AdamRJensen]

For the reasons detailed in that page, I'm of the view that imposing caps for pvlib would create more problems than it would solve.

I'm in agreement with Kevin.

I guess the ideal solution would be to retroactively add upper dependencies when new major versions start breaking code.. but that doesn't seem possible.

[markcampanelli]

I guess all I can say is that I nearly entirely disagree with the arguments put forth in https://iscinumpy.dev/post/bound-version-constraints/

I have seen Python development environments and production builds fail miserably “out of the blue” (and with deadlines looming or blocking critical bug fixes) due to an either laziness or lack of awareness of the importance disciplined SemVer. I would claim that if a project cannot determine if it breaking SemVer, then it has probably gotten too complex or has some other management issue.

The TensorFlow example of a library pinning its dependency libraries to the patch level is not an example of a failure of SemVer, rather it’s an example of the misuse/abuse of SemVer. (I have literally hit this “impossible to build” issue with TensorFlow in my current position, so I do get how maddening that is.) Capping at the next major version is considerably more flexible than the TensorFlow “worst practice”.

More realistic difficulties to take issue with SemVer about are things like when a bug fix causes a breaking change. Because the Python ecosystem is so beautifully rich, a downside is that Python libraries tend to have monster dependency trees, which is where I might be more inclined to direct criticism and suggest dependency parsimony in a library like pvlib.

Since I’m not a maintainer, I’m not going to die on this hill. However, I will say that I’ve seen Python get a reputation as to not being “production worthy” due to a perceived difference in community attitudes about proper “guardrails” and code hygiene.

Closing the issue.

[AdamRJensen]

When a major version of a dependency is released and an upper bound isn't already in place, fresh installs can go south before anyone has a chance to update for the breaking changes, because pip aggressively pulls the latest in fresh installs. Big packages like numpy do usually give fair warning, but after, say, numpy 2.0 releases with breaking changes, one probably won't be able to easily install an older version of pvlib-python "out of the box" without pip pulling an incompatible (newer) numpy version.

Just as pip aggressively pulls in the latest release of Numpy, then it would also pull in the latest release of pvlib (which should be compatible). I guess the incompatible issue arises if you fix your pvlib version and not the versions of the major dependencies such as numpy?

[echedey-ls]

I'd like to add that it may be a good idea to add some "latest" requirements to the test matrix - maybe no requirements at all and let the manager resolve to whatever it thinks suits best. So problems with newer versions can be caught early on.

[markcampanelli]

When a major version of a dependency is released and an upper bound isn't already in place, fresh installs can go south before anyone has a chance to update for the breaking changes, because pip aggressively pulls the latest in fresh installs. Big packages like numpy do usually give fair warning, but after, say, numpy 2.0 releases with breaking changes, one probably won't be able to easily install an older version of pvlib-python "out of the box" without pip pulling an incompatible (newer) numpy version.

Just as pip aggressively pulls in the latest release of Numpy, then it would also pull in the latest release of pvlib (which should be compatible). I guess the incompatible issue arises if you fix your pvlib version and not the versions of the major dependencies such as numpy?

In some (perhaps even the majority of) cases, this would sort itself out as you say. For purposes of, say, computation repeatability, a consumer may very well have pinned pvlib to a specific version. (Although, you might argue here that they would likely have pinned numpy too, but it's hard to know exactly what people will do and why. Indeed, maybe in some use case they didn't even have to import numpy directly.)

I don't mean to oversimplify this hard problem by suggesting that capping at the next breaking major version magically solves/avoids all problems. Rather, it's what I perceive as a best practice for combating dependency hell, which most likely none of us likes to spend our time in (and I certainly have some PTSD over). Problems would still pop up, but hopefully they would be more "contained" when they do. And just to reiterate, I am not proposing the "pin-to-patch-level zealotry" of TensorFlow, which is not appropriate for a library in the Python ecosystem. (My understanding is that in the Golang ecosystem all dependencies are called out as a specific commit/tag, which is quite the incentive to create libraries with very few dependencies. My sense is that makes the Go dependency ecosystem more "flat" and modular, but with correspondingly less code reuse, quite unlike the scientific Python ecosystem.)

I view the dependency ranges in a pyproject.toml as contract for the package so that for example, even in 5 years, the user should be able to dust off their old jupyter notebook pinned at pvlib v0.9.3, do pip install . in a fresh virtual environment, and have everything just work.

[kandersolar]

I view the dependency ranges in a pyproject.toml as contract for the package so that for example, even in 5 years, the user should be able to dust off their old jupyter notebook pinned at pvlib v0.9.3, do pip install . in a fresh virtual environment, and have everything just work.

This is certainly a worthy ideal, but it conflicts with another worthy ideal: not unnecessarily tying the hands of users. Providing strict upper bounds on our dependencies (plus our indirect dependencies, since we can't trust our dependencies to always use upper bounds either) would make pvlib a "bad neighbor" in deployments where (1) it is one of many packages being installed and (2) our upper bounds turned out to be unnecessary, which I suspect is the case for the majority of our dependencies' major releases. Which of these two ideals takes priority is the question of library vs application. Unless we rename the project to pvapp, I think flexibility is the better approach ;)

Besides that, I don't want us taking on the maintenance burden of upper bounds. Maintenance time is precious!

So there are some meaningful negatives regarding pvlib trying to provide long-term environment reproducibility. I also see a much more general and complete alternative for users to achieve that reproducibility: $ pip freeze > requirements.txt. With such a good alternative readily available, I don't think our pyproject.toml should be in the business of trying to keep pvlib installable after half a decade of the ecosystem moving on.

I'd like to add that it may be a good idea to add some "latest" requirements to the test matrix - maybe no requirements at all and let the manager resolve to whatever it thinks suits best. So problems with newer versions can be caught early on.

If I understand correctly, almost all of our test matrix does indeed leave the dependencies unpinned (see here), resulting in the package manager installing the latest versions :)

[echedey-ls]

I'd like to add that it may be a good idea to add some "latest" requirements to the test matrix - maybe no requirements at all and let the manager resolve to whatever it thinks suits best. So problems with newer versions can be caught early on.

If I understand correctly, almost all of our test matrix does indeed leave the dependencies unpinned (see here), resulting in the package manager installing the latest versions :)

Aha! That's right @kandersolar , I misinterpreted the role of the requirements files under ci/

[markcampanelli]

With breaking-changes numpy 2.0.0 now released (cf. #2026):

python -m pip install pvlib==0.10.4
python -c "import pvlib"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/pvlib/__init__.py", line 3, in <module>
    from pvlib import (  # noqa: F401
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/pvlib/ivtools/__init__.py", line 7, in <module>
    from pvlib.ivtools import sde, sdm, utils  # noqa: F401
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/pvlib/ivtools/sdm.py", line 15, in <module>
    from pvlib.pvsystem import calcparams_pvsyst, singlediode, v_from_i
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/pvlib/pvsystem.py", line 22, in <module>
    from pvlib import (atmosphere, iam, inverter, irradiance,
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/pvlib/singlediode.py", line 61, in <module>
    NsVbi=np.Inf, breakdown_factor=0., breakdown_voltage=-5.5,
          ^^^^^^
  File "/home/campy/Documents/Employment/IMS/solar/PVfit/venv/pvlib_0p10p4/lib/python3.11/site-packages/numpy/__init__.py", line 397, in __getattr__
    raise AttributeError(
AttributeError: `np.Inf` was removed in the NumPy 2.0 release. Use `np.inf` instead.. Did you mean: 'inf'?

[echedey-ls]

@markcampanelli support for Numpy 2.0 was given in v0.10.5. https://pvlib-python.readthedocs.io/en/stable/whatsnew.html#v0-10-5-may-6-2024 , see Bug Fixes section.

[markcampanelli]

Understood. Just putting a finer point on a previously working version install breaking anew. Mark Campanelli LinkedIn <https://www.linkedin.com/in/markcampanelli/> Intelligent Measurement Systems LLC <https://intelligentmeasurementsystems.com> Try PVfit <https://pvfit.app> today!

…

On Mon, Jun 24, 2024 at 08:26 Echedey Luis ***@***.***> wrote: @markcampanelli <https://github.com/markcampanelli> support for Numpy 2.0 was given in v0.10.5. https://pvlib-python.readthedocs.io/en/stable/whatsnew.html#v0-10-5-may-6-2024 , see Bug Fixes section. — Reply to this email directly, view it on GitHub <#2051 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAISX43GMFMK4GJSSOKENILZJAUCVAVCNFSM6AAAAABHSQ2XQSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDCOBWG4YTGNJZGQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[markcampanelli]

This article gives a thorough reasoning of why using upper bounds is not a good idea in the Python ecosystem: https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special

I re-iterate that this 10,000 word explanation goes almost entirely against the simple, rules-based system laid out here that I have employed in production and which has brought complements from my coworkers once they realized the sanity and stability that it brought to our Python processes. An open-source library with many dependencies like pvlib is indeed challenging due to Python’s idiosyncrasies (poor design choices?), and there are always trade offs, but I am fairly convinced that a “not overly restrictive” policy of capping dependencies and Python at the next expected breaking version does significantly more good than harm.