Rework pip command line look & feel #533
Conversation
* Remove module-singleton baseparser.parser object. A parser instance is created in pip.main() and passed as the first argument to each command. Each command can access the main parser from self.main_parser. * Remove all global command instances. Commands are instantiated on demand in pip.main(). Deferred command module imports were removed. * Factor option handling out of pip.main() and into pip.parseopts() * The list of available commands is now part of the parser's description and comes before all other options. 'Pip help' is more targeted at showing the options of a command instead of all available commands. * Move command specific options under a 'Command Options' OptionGroup * Move general options under a 'General Options' OptionGroup Conflicts: pip/__init__.py
* Add the notion of long and short help messages. If option.help is a tuple, its first element should be a short help message, suitable for display on the command line. The second element should be a paragraph of text describing the option in greater detail more suitable for a man page. * Group package index options under a 'Package Index Options' option group. * Reword help messages with regard to clarity and brevity * Rearrange option order (flags first) * Make metavars shorter and lowercased * Un-capitalize help messages * Fix help messages inconsistencies
|
Hm, that's a lod of code churn to just fix the help output. I'm -1 doing such an invasive modification. You, @carljm? |
|
A friendly help information helps a lot. |
|
@jezdez most of the churn comes from #463, which reworks the option and command handling in pip. It is invasive, as most refactorings are, but I believe it is well worth it - has pip seen even a day of refactoring in its development history? It's probably a normal developer reaction, but pip's code makes me feel uneasy :) While the look of the cli is hardly the most important part of pip, it just feels unpolished in comparison to other package managers (cabal and gem to name a few). Some attention to detail is all that's needed. This is all strictly imho. Please, take no offense. Pip is such an important tool for all pythonists and this is just my humble attempt at making it more awesome. |
|
I would like to look over it more carefully. I'm not a priori -1 just due to the amount of changes, if it's a real improvement both in the clarity and organization of the code and in the actual help output. I agree with @gvalkov that help output matters, and that some parts of pip are in need of refactoring; I don't want to rule out the possibility of ever doing that refactoring. But I need to look at this more closely to ensure that there really is a significant and worthwhile improvement. |
* develop: (84 commits) Update changelog. Updated basecommand.py such that writing to the log file doesn't fail. If permission is denied for writing in the specified log file the message will be written to a temporary one. Update AUTHORS and changelog for git submodules. remove "git submodule foreach" call for backwards compatibility; expect errors in pip install because old versions of git write senseless things to stderr fix python2.5 syntax error test submodule support make sure sitecustomize.py doesn't grow in the FastTestPipEnvironment not expecting errors in these tests. let them pass errors. fix pypa#533 . quite and recursive on submodule checkout fix on git repo. if a repo contains submodules, checkout submodules reset_env option to add a patch to sitecustomize.py dist_in_usersite explicitly returns False usersite installs should ignore version conflicts with site Add changelog entry for build-dir fix. Bump dev version. Remove backwards-compatibility shims for Python 2.4. Mock out getcwd. don't allow --user installs in no-global virtualenvs Re-added try/except around src_prefix Append documentation about comment line in requirements file format pypa#564 ...
|
I can't help but feel that I've wasted my time on this - it was a reasonable refactoring :( |
|
Looks like this was closed accidentally by a mistaken issue number reference in a different commit. |
|
@carljm I think it's github's fault. this pull request id should not be 533 |
|
+1 for the patch: while I can't comment on the patch itself, I really like this new form of help output |
|
It's been quite a while since I proposed these changes, so the branch is currently unmergeable. I could update it once more if there was a reasonable chance of getting it in. |
|
I like the idea that someone is worried about the CLI experience. My initial visual reaction to the diff was positive. When I started looking in detail, I realized it would take a bit of time to sort out what's what, and I've just been too busy working other issues to give it that time. |
lock
bot
added
the
auto-locked
This is more of a request for comments with code attached, rather than an actual pull request (I have my doubts about it too).
This patch changes the look of the command line interface from this to this, assuming a terminal width of 100 characters. It's much more compact and somewhat more consistent.
This patch also introduces a distinction between long and short help messages. If you pass a tuple as the help argument to
add_option, the first element is what the help formatter will use. The second argument could be a more detailed paragraph of text that can be used in a man page or some other kind of reference.This patch is based on top of #463.