Add file-like pager: click.get_pager_file()

[craigds]

In koordinates/kart we're in need of an output pager, and are already using click.

Trouble is, passing a generator to echo_via_pager requires that you're producing output in one place. That's not the case with a reasonably complex command - functions and modules delegating to each other all over the place.

To use echo_via_pager, I essentially had to use some kind of concurrency - async or threads - and have my code feed output to a worker thread which would yield the output from a generator function, which echo_via_pager would consume.

That worked, but then I realised click could just expose the file-like object it's using internally (which is usually a pipe to less).

This PR does that. click.get_pager_file exposes a writable file like object which feeds into a pager. The semantics of click.echo_via_pager haven't changed, but it now uses click.get_pager_file under the hood and merely feeds the generator contents into the file.

[davidism]

Thanks for looking at this, it's definitely an interesting approach. Have you confirmed that this works on Windows? Have you tested it with different pagers on Linux?

[craigds]

Thanks for taking a look.

I've tested both _pipepager and _tempfilepager paths, but only with less and only on MacOS. I'll try with linux builds and with other pagers, and probably I can rope @rcoup into testing on Windows for me...

[craigds]

Extra testing is still TODO, but the new commits are a bit more reviewable, esp if you read them one at a time 👍

[craigds]

On MacOS and Linux (I did it with the python:3.8 docker image) output works as expected with PAGER=cat, PAGER=less, PAGER=more.

[stefreak]

I love this one. It improves the code a lot. What is missing except for a round of conflict resolution? Does it really need extra test or is it covered by test of echo_via_pager?

[craigds]

It needs testing in windows. The little testing I did suggested that it doesn't really work on windows yet. I got stuck trying to set up any kind of dev environment on windows to improve it. If anyone who has a windows setup already could help, that'd be much appreciated

[craigds]

the mypy stuff is also blowing my mind a bit to be honest. I just spent about an hour trying to resolve all the type warnings and haven't yet managed to figure out what to do with things like variables that can hold either a text stream or a bytes stream

[stefreak]

@craigds would you mind if I give this another shot once #2775 has been merged? I rented a Hetzner windows server for development tasks like this and could look into adding tests for windows.

[craigds]

@stefreak yep that'd be awesome. I'll have a go at updating this PR for you

[craigds]

@stefreak I've updated this PR to latest main and it works okay for me on MacOS:

[AndreasBackx]

@stefreak @craigds this might be able make it into 8.2.0. If you rebase this PR on #2775, I'm happy to accept a "stacked PR" like that. It should be possible to get #2775 in 8.2.0, see #2789 for more info. I'm working through all 8.1.8 and 8.2.0 potential PRs right now and updating that issue and a new one as well.