Merge pull request #2351 from Dzhud/add-help-examples

Add usage examples to --help output

Author: sirosen

changelog.d/1142.feature.md

@@ -0,0 +1,4 @@
+Add usage examples to the ``--help`` output for ``pip-compile`` and
+``pip-sync`` commands.
+
+-- by {user}`Dzhud`

piptools/scripts/compile.py

@@ -74,11 +74,29 @@ def _determine_linesep(
     }[strategy]
 
 
-@click.command(
-    name="pip-compile",
-    context_settings={"help_option_names": options.help_option_names},
-)
+COMPILE_EPILOG = """\b
+Examples:
+\b
+    Compile requirements.in to requirements.txt:
+    $ pip-compile
+\b
+    Upgrade all packages to their latest versions:
+    $ pip-compile --upgrade
+\b
+    Upgrade specific packages:
+    $ pip-compile -P django -P requests
+\b
+    Include package hashes for extra security:
+    $ pip-compile --generate-hashes
+\b
+    Compile with optional extras:
+    $ pip-compile --extra dev pyproject.toml
+"""
+
+
+@click.command(name="pip-compile")
 @click.pass_context
+@options.help_option(epilog=COMPILE_EPILOG)
 @options.version
 @options.color
 @options.verbose

piptools/scripts/options.py

@@ -9,6 +9,8 @@
 from piptools.locations import CACHE_DIR, DEFAULT_CONFIG_FILE_NAMES
 from piptools.utils import UNSAFE_PACKAGES, override_defaults_from_config_file
 
+_FC = _t.TypeVar("_FC", bound="_t.Callable[..., _t.Any] | click.Command")
+
 BuildTargetT = _t.Literal["sdist", "wheel", "editable"]
 ALL_BUILD_TARGETS: tuple[BuildTargetT, ...] = (
     "editable",
@@ -17,6 +19,34 @@
 )
 
 
+def help_option(*, epilog: str | None = None) -> _t.Callable[[_FC], _FC]:
+    """A variant of the built-in click ``--help`` option, customized for pip-tools.
+
+    Unlike ``click.help_option``, this decorator accepts its own ``epilog`` text which
+    is printed *without indentation* after help text.
+    """
+
+    def show_help(ctx: click.Context, param: click.Parameter, value: bool) -> None:
+        """Callback that print the help page on ``<stdout>`` and exits."""
+        if value and not ctx.resilient_parsing:
+            click.echo(ctx.get_help(), color=ctx.color)
+            if epilog is not None:
+                formatter = ctx.make_formatter()
+                formatter.write_text(epilog)
+                click.echo("\n" + formatter.getvalue().rstrip("\n"), color=ctx.color)
+            ctx.exit()
+
+    return click.option(  # type: ignore[return-value]
+        "-h",
+        "--help",
+        help="Show this message and exit.",
+        callback=show_help,
+        is_eager=True,
+        expose_value=False,
+        is_flag=True,
+    )
+
+
 def _get_default_option(option_name: str) -> _t.Any:
     """
     Get default value of the pip's option (including option from pip.conf)
@@ -27,8 +57,6 @@ def _get_default_option(option_name: str) -> _t.Any:
     return getattr(default_values, option_name)
 
 
-help_option_names = ("-h", "--help")
-
 # The options used by pip-compile and pip-sync are presented in no specific order.
 
 version = click.version_option(package_name="pip-tools")

piptools/scripts/sync.py

@@ -30,10 +30,25 @@
 
 DEFAULT_REQUIREMENTS_FILE = "requirements.txt"
 
-
-@click.command(
-    name="pip-sync", context_settings={"help_option_names": options.help_option_names}
-)
+SYNC_EPILOG = """\b
+Examples:
+\b
+    Synchronize environment with requirements.txt:
+    $ pip-sync
+\b
+    Synchronize with multiple requirements files:
+    $ pip-sync requirements.txt dev.txt
+\b
+    Preview what would be installed or uninstalled:
+    $ pip-sync --dry-run
+\b
+    Ask for confirmation before making changes:
+    $ pip-sync --ask
+"""
+
+
+@click.command(name="pip-sync")
+@options.help_option(epilog=SYNC_EPILOG)
 @options.version
 @options.ask
 @options.dry_run

tests/test_cli_compile.py

@@ -527,6 +527,27 @@ def test_run_as_module_compile():
     assert b"Compile requirements.txt from source files" in result.stdout
 
 
+def test_compile_help_opt_supports_short_and_long_flag(runner):
+    shortflag_result = runner.invoke(cli, ["-h"])
+    longflag_result = runner.invoke(cli, ["--help"])
+    assert shortflag_result.exit_code == 0
+    assert longflag_result.exit_code == 0
+
+    assert shortflag_result.stdout.startswith("Usage:")
+    assert longflag_result.stdout.startswith("Usage:")
+    assert shortflag_result.stdout == longflag_result.stdout
+
+
+def test_compile_help_opt_shows_examples_section(runner):
+    result = runner.invoke(cli, ["-h"])
+    assert result.exit_code == 0
+    assert result.stdout.startswith("Usage:")
+
+    # not only should there be an `Examples` section in the output, but it should have
+    # no preceding whitespace where it is shown
+    assert "\nExamples:\n" in result.stdout
+
+
 def test_editable_package(pip_conf, runner):
     """piptools can compile an editable"""
     fake_package_dir = os.path.join(PACKAGES_PATH, "small_fake_with_deps")

tests/test_cli_sync.py

@@ -33,6 +33,27 @@ def test_run_as_module_sync():
     assert b"Synchronize virtual environment with" in result.stdout
 
 
+def test_sync_help_opt_supports_short_and_long_flag(runner):
+    shortflag_result = runner.invoke(cli, ["-h"])
+    longflag_result = runner.invoke(cli, ["--help"])
+    assert shortflag_result.exit_code == 0
+    assert longflag_result.exit_code == 0
+
+    assert shortflag_result.stdout.startswith("Usage:")
+    assert longflag_result.stdout.startswith("Usage:")
+    assert shortflag_result.stdout == longflag_result.stdout
+
+
+def test_sync_help_opt_shows_examples_section(runner):
+    result = runner.invoke(cli, ["-h"])
+    assert result.exit_code == 0
+    assert result.stdout.startswith("Usage:")
+
+    # not only should there be an `Examples` section in the output, but it should have
+    # no preceding whitespace where it is shown
+    assert "\nExamples:\n" in result.stdout
+
+
 @mock.patch("piptools.sync.run")
 def test_quiet_option(run, runner):
     """sync command can be run with `--quiet` or `-q` flag."""