"Contributing" doc to suggest running flake8 locally

[ramaroesilva]

Is your feature request related to a problem? Please describe.
I find myself depending on pvlib GitHub CI to see if my pull request complies with flake8 (and having to iterate with additional commits and pushes).

Describe the solution you'd like
Would be nice to find in the Contributing doc a recommendation to test code flake8-wise locally before pushing it online (+ instructions on how to do it).

Additional context
Don't know if there are any other structural tests that would make sense (and be easy to implement) locally.

[IoannisSifnaios]

I think there are many ways one can do this (maybe this is why there is no "official" recommendation?). Not sure which Python editor you are using, but both Spyder and VS Code (probably others too) can give you real-time warnings on flake8 mistakes.

[cwhanse]

At a command line prompt: flake8 clearsky.py for example.

[adriesse]

Are there any global flake8 settings on github that the local flake8 might not know about?

[ramaroesilva]

I once had to develop a package using ECMWF's cookie-cutter conda package and it set up an internal routine that code could only be commited locally if all code passed flake8 tests.

This would be a more fluid contributor experience. But being pragmatic, I can work out some basic suggestions for now and maybe later such an integration can be considered.

[markcampanelli]

I think a git commit hook is a local option too: https://flake8.pycqa.org/en/latest/user/using-hooks.html

[ramaroesilva]

I think a git commit hook is a local option too: https://flake8.pycqa.org/en/latest/user/using-hooks.html

Yes, I was talking about a git commit hook! Just don't know how (nor if it is easy) to implement.

[echedey-ls]

@ramaroesilva 's concern is extremely valid IMO.

Are there any global flake8 settings on github that the local flake8 might not know about?

And to address @adriesse 's point, yes, I guess you were kind of aware of the small config we have set up in the workflow file:

https://github.com/pvlib/pvlib-python/blob/770bcd1200ca16f330cb268242812343b673e28b/.github/workflows/flake8.yml#L22C1-L27C17

1. On one hand, we can do the same as is currently being executed in the action: (works straight forward in Linux & Windows PowerShell) git diff upstream/main HEAD -- "*.py" | flake8 --exclude pvlib/version.py --ignore E201,E241,E226,W503,W504 --max-line-length 79 --diff. This approach has the downside of, for example, not checking if an import is no longer required. Because it only checks on the diff. If anything is non-flake8-compliant outside of the diff, flake8 won't detect it. This binds us to use a somewhat old version of flake8 v5.0.4 - 2022-08-03 (latest is v7.3.0 – 2025-06-20). To me, this is a minor issue, that deserves being fixed.
2. On the other hand, my suggestion is to flake8-fix all the codebase manually and just require running flake8 with whatever arguments make it be typed and run fast enough (flake8 pvlib tests --exclude ... --ignore ... --max-line-length 79). This covers the previous downside.
3. So here comes another proposal, add its configuration either in .flake8 or pyproject.toml files (with the appropriate plugin for it to read the latter). That way, typing flake8 ...directories... is just enough.

To automatically do those checks, there is no way to enforce it in Git local workflow, not even by default. It is an opt-in feature. It's up to code contributors to set up their hook. Good enough for us people that work with the code with some frequency. It wouldn't fully substitute the GitHub Action.

I'll always advocate for fixing current non-diff lines being ignored. That being said, I suggest no. 3. in pyproject.toml. It would need us to add two dependencies to pvlib[test] (or a new group [lint]). Right now, documenting exactly the lengthy command seems an unnecessary effort and a source of confusion and errors.

Yes, I was talking about a git commit hook! Just don't know how (nor if it is easy) to implement.

Yes, it is very easy. A quasi-random note on it: I do currently configure my pre-commit locally and later add just an action that runs it, with whatever hooks are defined in there (for new projects where I get to do what I like). It also allows to check and format, many file types with a simple and concise syntax.

[ramaroesilva]

If anything is non-flake8-compliant outside of the diff, flake8 won't detect it. This binds us to use a somewhat old version of flake8 v5.0.4 - 2022-08-03 (latest is v7.3.0 – 2025-06-20). To me, this is a minor issue, that deserves being fixed.

What is the current context related to the need to use an old flake8 version?

[echedey-ls]

If anything is non-flake8-compliant outside of the diff, flake8 won't detect it. This binds us to use a somewhat old version of flake8 v5.0.4 - 2022-08-03 (latest is v7.3.0 – 2025-06-20). To me, this is a minor issue, that deserves being fixed.

What is the current context related to the need to use an old flake8 version?

It's the latest version to support the --diff feature: it's input is a git diff via stdin. It was removed on v6.0.0.

I don't know when it was first set up since it's external to the repo, but the history about linting pvlib code goes back to Stickler CI, a service that ran a linter (don't know which one) against the codebase and reported just those related to the pull request. I guess it was well after development started. It was shut down in 2023 and here in pvlib flake8 was adopted as a substitute, in an attempt to get a linter working 1:1 ASAP.

Ref.:

• https://github.com/pvlib/pvlib-python/commits/main/.github/workflows/flake8.yml
• Python Flake8 linter workflow to replace stickler-ci #1786
• stickler-ci is shutting down #1722
• Kind of related: Add lint checks to CI (without Stickler CI) #776
• I wasn't able to find any issue/PR/discussion regarding when Stickler CI was set up for the first time