feat(cli): add a bar shorthand for the pv-style command

pip install progressbar2 now also puts a three-keystroke bar command
on the path, the same progressbar.__main__:main entry point, so
pipelines read tar cf - src/ | bar --bytes --rate > backup.tar. The
README, CLI reference, and the readme/cli example docstring teach it,
and a packaging test pins both console scripts to the same entry
point.

Author: wolph

README.md

@@ -315,16 +315,18 @@ Errors, timeouts, pools, and the decorator form are covered in the
 
 ## Replace pv on the command line
 
-Installing the package also installs a `progressbar` command, a Python
-implementation of the classic Unix `pv`: it copies input to output and
-draws the transfer on stderr, so it drops into pipelines:
+Installing the package also installs a `progressbar` command and its
+`bar` shorthand, a Python implementation of the classic Unix `pv`: it
+copies input to output and draws the transfer on stderr, so it drops
+into pipelines:
 
 ```sh
 # File to file, with percentage, timer, ETA, rate and byte count:
 progressbar --progress --timer --eta --rate --bytes data.bin -o copy.bin
 
-# In a pipeline, data on stdout and progress on stderr:
-tar cf - src/ | progressbar --bytes --rate > backup.tar
+# In a pipeline, data on stdout and progress on stderr. `bar` is the
+# same command with three keystrokes:
+tar cf - src/ | bar --bytes --rate > backup.tar
 ```
 
 ![the progressbar command copying a file with percentage, timer, ETA, rate and byte count displays](https://raw.githubusercontent.com/wolph/python-progressbar/develop/docs/_static/demos/readme-cli.svg)

docs/examples/readme/cli.py

@@ -1,11 +1,12 @@
 """The `progressbar` command is a `pv` replacement for pipes and files.
 
-Installing the package puts a `progressbar` executable on the path
-(`python -m progressbar` is the same program), a Python implementation
-of the classic Unix `pv`: it copies input to output while drawing
-transfer progress on stderr. This example drives it in-process, moving
-4 MiB at a rate-limited 2 MiB/s with the percentage, timer, ETA, rate
-and byte-counter displays turned on.
+Installing the package puts a `progressbar` executable on the path,
+with `bar` as its pipeline shorthand (`python -m progressbar` is the
+same program), a Python implementation of the classic Unix `pv`: it
+copies input to output while drawing transfer progress on stderr.
+This example drives it in-process, moving 4 MiB at a rate-limited
+2 MiB/s with the percentage, timer, ETA, rate and byte-counter
+displays turned on.
 """
 
 import pathlib

docs/reference/cli.rst

@@ -3,7 +3,8 @@
 ====================
 
 Installing ``progressbar2`` installs a ``progressbar`` console script
-(:py:func:`progressbar.__main__.main`). It reads from stdin (or one or more
+(:py:func:`progressbar.__main__.main`), plus ``bar`` as a shorthand for
+the same command in pipelines. It reads from stdin (or one or more
 files), writes the same bytes through to stdout (or a file), and draws a
 progress bar on stderr while it does -- a small, Python-native reimplementation
 of the ``pv`` ("pipe viewer") command. Per its own ``--help`` text it is

pyproject.toml

@@ -116,6 +116,8 @@ repository = 'https://github.com/wolph/python-progressbar/'
 
 [project.scripts]
 progressbar = 'progressbar.__main__:main'
+# Shorthand for pipelines: `bar data.bin -o copy.bin`.
+bar = 'progressbar.__main__:main'
 
 [project.optional-dependencies]
 # Optional native iterator accelerator. When installed it is detected and used

tests/test_progressbar_command.py

@@ -1,4 +1,5 @@
 import io
+import pathlib
 
 import pytest
 
@@ -288,3 +289,15 @@ def test_main_empty_file_has_known_size(tmp_path, recorded_bars) -> None:
     main.main([str(file), '-o', str(tmp_path / 'out.bin')])
 
     assert recorded_bars[0].init_kwargs.get('max_value') == 0
+
+
+def test_console_scripts_include_the_bar_shorthand() -> None:
+    # Both the canonical `progressbar` command and its `bar` shorthand
+    # must point at the same entry point: the shorthand exists purely
+    # for shorter pipelines (`bar data.bin -o copy.bin`).
+    pyproject = (
+        pathlib.Path(__file__).parents[1] / 'pyproject.toml'
+    ).read_text(encoding='utf-8')
+
+    assert "progressbar = 'progressbar.__main__:main'" in pyproject
+    assert "bar = 'progressbar.__main__:main'" in pyproject