ENH: cmdline: Use pydoc pager for --help #5344
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The argument for -h/--help/--help-np is wired up with a custom
argparse.Action class, HelpAction. For an interactive call with
--help and a subcommand, this class looks for a corresponding manpage
file and tries to shell out to man(1), falling back to printing the
help string.
This means that for several common install scenarios, output isn't
displayed with a pager, and there is no distinction between --help and
--help-np. Given that the help text of most subcommands probably
exceeds common terminal heights, callers need to either scroll up or
do something like `datalad <subcommand> --help | less`.
Make a pager available in these situations by using pydoc.pager() to
display the --help output. Two notes:
* guarding the use of pydoc.pager() with datalad's is_interactive()
isn't essential because pydoc.pager() avoids using a pager when it
detects a non-interactive environment. However, these interactive
checks aren't identical, so it probably makes sense to honor a
"no" from is_interactive().
* pydoc.pager() will enter the pager even if the number of lines
doesn't exceed the current terminal height. Given the length of
the output for most subcommands, checking this ourselves (and
worrying about platform-specific details) before calling
pydoc.pager() probably isn't worth it.
Codecov Report
@@ Coverage Diff @@
## master #5344 +/- ##
===========================================
+ Coverage 59.64% 89.90% +30.25%
===========================================
Files 129 300 +171
Lines 19045 42058 +23013
===========================================
+ Hits 11360 37813 +26453
+ Misses 7685 4245 -3440
Continue to review full report at Codecov.
|
yarikoptic
reviewed
Jan 20, 2021
|
especially exciting "will increase coverage by 30.25%" ... not sure what happened with coverage in master, but how could I resist this number? ;) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The argument for -h/--help/--help-np is wired up with a custom
argparse.Action class, HelpAction. For an interactive call with
--help and a subcommand, this class looks for a corresponding manpage
file and tries to shell out to man(1), falling back to printing the
help string.
This means that for several common install scenarios, output isn't
displayed with a pager, and there is no distinction between --help and
--help-np. Given that the help text of most subcommands probably
exceeds common terminal heights, callers need to either scroll up or
do something like
datalad <subcommand> --help | less.Make a pager available in these situations by using pydoc.pager() to
display the --help output. Two notes:
guarding the use of pydoc.pager() with datalad's is_interactive()
isn't essential because pydoc.pager() avoids using a pager when it
detects a non-interactive environment. However, these interactive
checks aren't identical, so it probably makes sense to honor a
"no" from is_interactive().
pydoc.pager() will enter the pager even if the number of lines
doesn't exceed the current terminal height. Given the length of
the output for most subcommands, checking this ourselves (and
worrying about platform-specific details) before calling
pydoc.pager() probably isn't worth it.
I've had a draft for this around for a while and thought about it again as I was typing
datalad siblings --help | less. Given the last point in the commit message, I'm not sure if others will think this is a good change. Thoughts?