DOC: flake8-per-pr for windows users

[h-vetinari]

This was vaguely inspired by #23658, and by me finding out that windows has a built-in kinda-sorta-grep called findstr.

I've already started using it, and it's proven very useful. However, windows CLI tools are horrible, horribly documented, and just generally have terrible syntax. The command was built together from (approximately):

• https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/for#BKMK_examples
• https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/findstr
• https://ss64.com/nt/for.html
• https://blogs.msdn.microsoft.com/oldnewthing/20120731-00/?p=7003
• https://stackoverflow.com/questions/8844868/what-are-the-undocumented-features-and-limitations-of-the-windows-findstr-comman

Some general notes for someone wanting to embark on a similar path:

• use findstr /?
• piping is easy (normally), with |
• the /f in for is a flag for determining what's being iterated over, while %i is the variable
• to execute a function in the "set" of the for, it must be in single quotes
• inside those single quotes, the pipe must be "escaped" with ^.
• order of flags matters
• findstr has... suboptimal... regex mechanics.

Nevertheless, there could be an even better version (that makes sure we're only checking .py files), that I didn't put in this PR, because I fear it will exceed the line length that's rendered without being cut off:

for /f %i in ('git diff upstream/master --name-only ^| findstr /r "pandas/.*\.py"') do flake8 %i

[TomAugspurger]

I'd be curious to hear your thoughts on #23616.

If we recommend using pre-commit hooks (after verifying that hey work on all platforms) we could remove this doc section entirely.

[jbrockmendel]

Possibly a silly question: why not just do this in python? Being a cross-platform scripting language and all...

[h-vetinari]

Possibly a silly question: why not just do this in python? Being a cross-platform scripting language and all...

Point taken. If/once there is a larger validation script for the user-side of a PR (before pushing), then obviously this isn't necessary.

It was more because the docs mentioned "this can't be done on windows", and I decided to see if that was true. ;-)

As a one-liner (without an additional script file to call), I do find it neat though (or at least as neat as the ugly syntax allows)...

[h-vetinari]

Will not bother to restart the already-strained CI (at least Travis) with another restart due to a flaky hypothesis test that clearly cannot be caused by a change in the docs... :)

[gfyoung]

@h-vetinari : FYI, instead of pushing commits to trigger entirely new builds, just ping one of us. We can restart individual builds for you.

I like these doc changes. I would also advocate for a Python-based validation script, but this is a good step in the right direction. I actually have one myself (for more general purpose), if anyone is interested.

[codecov]

Codecov Report

Merging #23707 into master will decrease coverage by <.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #23707      +/-   ##
==========================================
- Coverage   92.24%   92.24%   -0.01%     
==========================================
  Files         161      161              
  Lines       51339    51336       -3     
==========================================
- Hits        47360    47357       -3     
  Misses       3979     3979

Flag	Coverage Δ
#multiple	90.64% <ø> (-0.01%)	⬇️
#single	42.34% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/io/formats/format.py	97.88% <0%> (-0.01%)	⬇️
pandas/core/series.py	93.68% <0%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e413c49...2d5752e. Read the comment docs.

[h-vetinari]

@gfyoung

@h-vetinari : FYI, instead of pushing commits to trigger entirely new builds, just ping one of us. We can restart individual builds for you.

I know, but:

• often there's no-one around
• I'm impatient (also auto-cancel seems to be finally working reliably again)
• and most importantly, I feel I'm already pinging y'all too much (e.g. judging from the number of pings that go unanswered for >1 week; this is not a criticism, but a reality of OSS).

Would it be possible to grant "restart-CI" rights (without going into merge-rights and somesuch)?

[gfyoung]

often there's no-one around

I'm impatient (also auto-cancel seems to be finally working reliably again)

Sorry, not sure if can't help you on those 😉 . Time is a relatively limited resource for all of us, but also keep in mind that continually restarting the builds doesn't always work out if the builds already start, which can slow down everyone else's builds, which ultimately can then affect how quickly we can get to all of the PR's and issues that we have.

Would it be possible to grant "restart-CI" rights (without going into merge-rights and somesuch)?

Not for individual builds unfortunately.

[TomAugspurger]

Thanks!