Use shorthand --start and --target for CLI in docs and tests (#324)

Author: stefmolin

.github/workflows/generate-morphs.yml

@@ -65,8 +65,8 @@ jobs:
           DATASET_ARGS=$(python bin/ci.py $DATASET_ALL_CHANGED_FILES)
           echo "Generating morphs for the following datasets: $DATASET_ARGS"
           data-morph \
-               --start-shape $DATASET_ARGS \
-               --target-shape bullseye heart rectangle star slant_up \
+               --start $DATASET_ARGS \
+               --target bullseye heart rectangle star slant_up \
                --workers 0
 
       # If shapes are added or modified in this PR
@@ -79,8 +79,8 @@ jobs:
           SHAPE_ARGS=$(python bin/ci.py $SHAPE_ALL_CHANGED_FILES)
           echo "Generating morphs for the following shapes: $SHAPE_ARGS"
           data-morph \
-               --start-shape music \
-               --target-shape $SHAPE_ARGS \
+               --start music \
+               --target $SHAPE_ARGS \
                --workers 0
 
       # For core code changes, we want to do a couple morphs to see if they still look ok
@@ -89,8 +89,8 @@ jobs:
         if: steps.changed-files-yaml.outputs.dataset_any_changed != 'true' && steps.changed-files-yaml.outputs.shape_any_changed != 'true'
         run: |
           data-morph \
-               --start-shape music \
-               --target-shape bullseye heart star \
+               --start music \
+               --target bullseye heart star \
                --workers 0
 
       - uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08  # v4.6.0

README.md

@@ -98,7 +98,7 @@ Once installed, Data Morph can be used on the command line or as an importable P
 Run `data-morph` on the command line:
 
 ```console
-$ data-morph --start-shape panda --target-shape star
+$ data-morph --start panda --target star
 ```
 
 This produces the animation in the newly-created `morphed_data` directory within your current working directory (shown above). More examples, including how to run multiple transformations in parallel, can be found in the [documentation](https://stefaniemolin.com/data-morph/).

docs/cli.rst

@@ -17,41 +17,41 @@ Examples
 
    .. code-block:: console
 
-    $ data-morph --start-shape panda --target-shape star
+    $ data-morph --start panda --target star
 
 2. Morph the panda shape into all available target shapes distributing the work
    to as many worker processes as possible:
 
    .. code-block:: console
 
-    $ data-morph --start-shape panda --target-shape all --workers 0
+    $ data-morph --start panda --target all --workers 0
 
 3. Morph the cat, dog, and panda shapes into the circle and slant_down shapes:
 
    .. code-block:: console
 
-    $ data-morph --start-shape cat dog panda --target-shape circle slant_down
+    $ data-morph --start cat dog panda --target circle slant_down
 
 4. Morph the dog shape into upward-slanting lines over 50,000 iterations with seed 1:
 
    .. code-block:: console
 
-    $ data-morph --start-shape dog --target-shape slant_up --iterations 50000 --seed 1
+    $ data-morph --start dog --target slant_up --iterations 50000 --seed 1
 
 5. Morph the cat shape into a circle, preserving summary statistics to 3 decimal places:
 
    .. code-block:: console
 
-    $ data-morph --start-shape cat --target-shape circle --decimals 3
+    $ data-morph --start cat --target circle --decimals 3
 
 6. Morph the music shape into a bullseye, specifying the output directory:
 
    .. code-block:: console
 
-    $ data-morph --start-shape music --target-shape bullseye --output-dir path/to/dir
+    $ data-morph --start music --target bullseye --output-dir path/to/dir
 
 7. Morph the sheep shape into vertical lines, slowly easing in and out for the animation:
 
    .. code-block:: console
 
-    $ data-morph --start-shape sheep --target-shape v_lines --ease
+    $ data-morph --start sheep --target v_lines --ease

docs/quickstart.rst

@@ -38,7 +38,7 @@ Run ``data-morph`` on the command line:
 
 .. code:: console
 
-   $ data-morph --start-shape panda --target-shape star
+   $ data-morph --start panda --target star
 
 This produces the following animation in the newly-created ``morphed_data`` directory
 within your current working directory:
@@ -53,7 +53,7 @@ If you don't want the marginal plots (the histograms on the sides), you can use
 
 .. code:: console
 
-   $ data-morph --start-shape panda --target-shape star --classic
+   $ data-morph --start panda --target star --classic
 
 Animations generated in classic mode include only the scatter plot and the summary statistics:
 
@@ -69,7 +69,7 @@ of the initial shape:
 
 .. code:: console
 
-   $ data-morph --start-shape panda --target-shape star --freeze 50 --ease
+   $ data-morph --start panda --target star --freeze 50 --ease
 
 Here is the resulting animation:
 
@@ -88,7 +88,7 @@ the command below:
 
 .. code:: console
 
-   $ data-morph --start-shape music soccer --target-shape heart diamond
+   $ data-morph --start music soccer --target heart diamond
 
 .. tip::
 
@@ -98,7 +98,7 @@ the command below:
 
    .. code:: console
 
-      $ data-morph --start-shape music soccer --target-shape heart diamond --workers 0
+      $ data-morph --start music soccer --target heart diamond --workers 0
 
    If you have the GNU ``parallel`` command on your machine, you can use it to run
    a slightly faster parallelized Data Morph (since it incurs less Python overhead),
@@ -107,7 +107,7 @@ the command below:
    .. code:: console
 
       $ parallel --progress -j0 \
-      >     data-morph --start-shape {1} --target-shape {2} \
+      >     data-morph --start {1} --target {2} \
       >     ::: music soccer ::: heart diamond
 
    Check out the `GNU parallel documentation <https://www.gnu.org/software/parallel/sphinx.html>`_

docs/tutorials/custom-datasets.rst

@@ -99,7 +99,7 @@ Pass the path to the CSV file to use those points as the starting shape:
 
 .. code:: console
 
-   $ data-morph --start-shape path/to/points.csv --target-shape wide_lines --classic
+   $ data-morph --start path/to/points.csv --target wide_lines --classic
 
 Here is an example animation generated from a custom dataset:
 
@@ -132,4 +132,4 @@ If and only if you are given the go ahead:
 
     .. code:: console
 
-       $ data-morph --start-shape path/to/points.csv --target-shape all
+       $ data-morph --start path/to/points.csv --target all

docs/tutorials/shape-creation.rst

@@ -191,7 +191,7 @@ for the ``name`` attribute of your shape class to generate three animations:
 
 .. code:: console
 
-   $ data-morph --start-shape panda music soccer --target-shape <your shape> --workers 3
+   $ data-morph --start panda music soccer --target <your shape> --workers 3
 
 Review the animations. Remember, some shapes will work better on certain datasets,
 and that's fine. However, if your shape only works well on one of the built-in datasets

tests/test_cli.py

@@ -34,7 +34,7 @@ def test_cli_version(capsys):
 def test_cli_bad_shape():
     """Test that invalid target shapes raise a ValueError."""
     with pytest.raises(ValueError, match='No valid target shapes were provided'):
-        cli.main(['--start-shape=dino', '--target-shape=does-not-exist'])
+        cli.main(['--start=dino', '--target=does-not-exist'])
 
 
 @pytest.mark.input_validation
@@ -50,7 +50,7 @@ def test_cli_bad_shape():
 def test_cli_bad_input_decimals(decimals, reason, capsys):
     """Test that invalid input for decimals is handled correctly."""
     with pytest.raises(SystemExit):
-        cli.main(['--start-shape=dino', f'--decimals={decimals}'])
+        cli.main(['--start=dino', f'--decimals={decimals}'])
     assert f'error: argument --decimals: {reason}:' in capsys.readouterr().err
 
 
@@ -66,7 +66,7 @@ def test_cli_bad_input_decimals(decimals, reason, capsys):
 def test_cli_bad_input_floats(field, value, reason, capsys):
     """Test that invalid input for floats is handled correctly."""
     with pytest.raises(SystemExit):
-        cli.main([f'--{field}', value, '--start-shape=dino'])
+        cli.main([f'--{field}', value, '--start=dino'])
     assert f'error: argument --{field}: {reason}' in capsys.readouterr().err
 
 
@@ -76,7 +76,7 @@ def test_cli_bad_input_floats(field, value, reason, capsys):
 def test_cli_bad_input_integers(field, value, capsys):
     """Test that invalid input for integers is handled correctly."""
     with pytest.raises(SystemExit):
-        cli.main(['--start-shape=dino', f'--{field}={value}'])
+        cli.main(['--start=dino', f'--{field}={value}'])
     assert f'error: argument --{field}: invalid int value:' in capsys.readouterr().err
 
 
@@ -88,7 +88,7 @@ def test_cli_bad_input_integers(field, value, capsys):
 def test_cli_bad_input_boolean(field, value, capsys):
     """Test that invalid input for Boolean switches are handled correctly."""
     with pytest.raises(SystemExit):
-        cli.main(['--start-shape=dino', f'--{field}={value}'])
+        cli.main(['--start=dino', f'--{field}={value}'])
     assert (
         f'error: argument --{field}: ignored explicit argument'
         in capsys.readouterr().err
@@ -107,8 +107,8 @@ def test_cli_dataloader(start_shape, scale, mocker):
     load = mocker.patch.object(cli.DataLoader, 'load_dataset', autospec=True)
     _ = mocker.patch.object(cli.DataMorpher, 'morph')
     argv = [
-        f'--start-shape={start_shape}',
-        '--target-shape=circle',
+        f'--start={start_shape}',
+        '--target=circle',
         *bound_args,
     ]
     cli.main([arg for arg in argv if arg])
@@ -145,8 +145,8 @@ def test_cli_one_shape(start_shape, flag, mocker, tmp_path):
     morph_mock = mocker.patch.object(cli.DataMorpher, 'morph', autospec=True)
 
     argv = [
-        f'--start-shape={morph_args["start_shape_name"]}',
-        f'--target-shape={morph_args["target_shape"]}',
+        f'--start={morph_args["start_shape_name"]}',
+        f'--target={morph_args["target_shape"]}',
         f'--iterations={morph_args["iterations"]}',
         f'--decimals={init_args["decimals"]}' if init_args['decimals'] else '',
         f'--seed={init_args["seed"]}',
@@ -220,9 +220,9 @@ def test_cli_multiple_shapes(
     workers = 2
     cli.main(
         [
-            '--start-shape',
+            '--start',
             *start_shape,
-            '--target-shape',
+            '--target',
             *target_shape,
             f'--iterations={iterations}',
             f'--output-dir={tmp_path}',