Replace custom CLI with argparse - #83
Conversation
| ) | ||
|
|
||
| def add_subcommand(name: str, doc: str) -> argparse.ArgumentParser: | ||
| doc = doc.strip() |
There was a problem hiding this comment.
Won't strip only strip the first line? I suggest using inpect.cleandoc instead.
| # Keep the legacy 'help' and 'version' subcommands working as aliases. | ||
| elif args[0] == 'help': | ||
| print( | ||
| "Warning: 'blurb help' is deprecated, use 'blurb --help' instead", |
There was a problem hiding this comment.
Why not warnings.warn(..., DeprecationWarning), that way we can suppress it.
There was a problem hiding this comment.
This is a CLI, not a library, so I don't think we need warnings here.
If you're calling blurb help or blurb version in a script and see the message, change to blurb --help or blurb --version instead of adding suppression handling.
| "Warning: 'blurb help' is deprecated, use 'blurb --help' instead", | ||
| file=sys.stderr, | ||
| ) | ||
| args = [*args[1:2], '--help'] |
There was a problem hiding this comment.
Won't this allow extra arguments after --help?
There was a problem hiding this comment.
argparse will show the help immediately with --help and extra args don't matter, we get the help anyway:
❯ blurb --help
usage: blurb [-h] [-V] subcommand ...
Management tool for CPython Misc/NEWS and Misc/NEWS.d entries.
positional arguments:
subcommand
add Add a blurb (a Misc/NEWS.d/next entry) to the current CPython repo.
export Removes blurb data files, for building release tarballs/installers.
merge Merge all blurbs together into a single Misc/NEWS file.
populate Creates and populates the Misc/NEWS.d directory tree.
release Move all new blurbs to a single blurb file for the release.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
If blurb is run without any arguments, this is equivalent to blurb add.
❯ blurb --help abc
usage: blurb [-h] [-V] subcommand ...
Management tool for CPython Misc/NEWS and Misc/NEWS.d entries.
positional arguments:
subcommand
add Add a blurb (a Misc/NEWS.d/next entry) to the current CPython repo.
export Removes blurb data files, for building release tarballs/installers.
merge Merge all blurbs together into a single Misc/NEWS file.
populate Creates and populates the Misc/NEWS.d directory tree.
release Move all new blurbs to a single blurb file for the release.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
If blurb is run without any arguments, this is equivalent to blurb add.Also fine for a subcommand:
❯ blurb merge --help
usage: blurb merge [-h] [-f] [output]
Merge all blurbs together into a single Misc/NEWS file.
Optional output argument specifies where to write to.
Default is <cpython-root>/Misc/NEWS.
If overwriting, blurb merge will prompt you to make sure it's okay.
To force it to overwrite, use -f.
positional arguments:
output where to write the NEWS file (default: Misc/NEWS)
options:
-h, --help show this help message and exit
-f, --forced overwrite an existing file without prompting
❯ blurb merge --help abc
usage: blurb merge [-h] [-f] [output]
Merge all blurbs together into a single Misc/NEWS file.
Optional output argument specifies where to write to.
Default is <cpython-root>/Misc/NEWS.
If overwriting, blurb merge will prompt you to make sure it's okay.
To force it to overwrite, use -f.
positional arguments:
output where to write the NEWS file (default: Misc/NEWS)
options:
-h, --help show this help message and exit
-f, --forced overwrite an existing file without prompting|
|
||
|
|
||
|
|
||
| ### blurb help |
There was a problem hiding this comment.
I'd suggest keeping at least a little note pointing to --help.
|
When this lands I think it'll be time for a release, we haven't had any for quite some time (and, to be honest that "in in" is bugging me now ;-). I'm happy to take care of it then. |
hugovk
left a comment
hugovk
left a comment
There was a problem hiding this comment.
When this lands I think it'll be time for a release, we haven't had any for quite some time (and, to be honest that "in in" is bugging me now ;-). I'm happy to take care of it then.
Yes, I think it's time, go for it!
https://github.com/python/blurb/blob/main/CHANGELOG.md shows 2.1.0 and 2.2.0 but neither has been released yet, so they need merging as 2.1.0.
And https://github.com/python/blurb/blob/main/.github/release.yml needs to update dependabot to dependabot[bot].
| # Keep the legacy 'help' and 'version' subcommands working as aliases. | ||
| elif args[0] == 'help': | ||
| print( | ||
| "Warning: 'blurb help' is deprecated, use 'blurb --help' instead", |
There was a problem hiding this comment.
This is a CLI, not a library, so I don't think we need warnings here.
If you're calling blurb help or blurb version in a script and see the message, change to blurb --help or blurb --version instead of adding suppression handling.
| "Warning: 'blurb help' is deprecated, use 'blurb --help' instead", | ||
| file=sys.stderr, | ||
| ) | ||
| args = [*args[1:2], '--help'] |
There was a problem hiding this comment.
argparse will show the help immediately with --help and extra args don't matter, we get the help anyway:
❯ blurb --help
usage: blurb [-h] [-V] subcommand ...
Management tool for CPython Misc/NEWS and Misc/NEWS.d entries.
positional arguments:
subcommand
add Add a blurb (a Misc/NEWS.d/next entry) to the current CPython repo.
export Removes blurb data files, for building release tarballs/installers.
merge Merge all blurbs together into a single Misc/NEWS file.
populate Creates and populates the Misc/NEWS.d directory tree.
release Move all new blurbs to a single blurb file for the release.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
If blurb is run without any arguments, this is equivalent to blurb add.
❯ blurb --help abc
usage: blurb [-h] [-V] subcommand ...
Management tool for CPython Misc/NEWS and Misc/NEWS.d entries.
positional arguments:
subcommand
add Add a blurb (a Misc/NEWS.d/next entry) to the current CPython repo.
export Removes blurb data files, for building release tarballs/installers.
merge Merge all blurbs together into a single Misc/NEWS file.
populate Creates and populates the Misc/NEWS.d directory tree.
release Move all new blurbs to a single blurb file for the release.
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
If blurb is run without any arguments, this is equivalent to blurb add.Also fine for a subcommand:
❯ blurb merge --help
usage: blurb merge [-h] [-f] [output]
Merge all blurbs together into a single Misc/NEWS file.
Optional output argument specifies where to write to.
Default is <cpython-root>/Misc/NEWS.
If overwriting, blurb merge will prompt you to make sure it's okay.
To force it to overwrite, use -f.
positional arguments:
output where to write the NEWS file (default: Misc/NEWS)
options:
-h, --help show this help message and exit
-f, --forced overwrite an existing file without prompting
❯ blurb merge --help abc
usage: blurb merge [-h] [-f] [output]
Merge all blurbs together into a single Misc/NEWS file.
Optional output argument specifies where to write to.
Default is <cpython-root>/Misc/NEWS.
If overwriting, blurb merge will prompt you to make sure it's okay.
To force it to overwrite, use -f.
positional arguments:
output where to write the NEWS file (default: Misc/NEWS)
options:
-h, --help show this help message and exit
-f, --forced overwrite an existing file without prompting2 participants
There's a lot of custom code for the CLI handling, which we can replace with argparse.
This saves us about 150 lines of code, and we get colour help, plus I've added backticks in some help messages for "code" formatting as well.
Right now, blurb has both subcommand and option versions of help and version:
This PR deprecates the subcommands in favour of the more ususal options.