Skip to content

Commit

Permalink
doc: add warning about Python argparse in flux-jobs(1)
Browse files Browse the repository at this point in the history
Problem: There's a quirk in the Python argparse implementation that
causes a required option argument that has a leading dash to be
ignored when a space between long option and its argument is used
instead of an equals. This is common with the `flux jobs --since`
option because relative FSD is allowed so `-1h`, `-30m`, etc are
expected option arguments. This can be very confusing to users who
may not have an inkling of what's going on.

Add a note in the flux-jobs(1) man page regarding this quirk in hopes
users will see and become aware of it. Suggest that `=` always be used
between `--since` and its argument to avoid the problem.
  • Loading branch information
grondo committed Sep 15, 2024
1 parent a75a4d9 commit d9905ae
Showing 1 changed file with 9 additions and 0 deletions.
9 changes: 9 additions & 0 deletions doc/man1/flux-jobs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,15 @@ OPTIONS
"last Monday", etc. It is assumed to be an error if a timestamp in
the future is supplied.

.. note::
Due to a quirk in the Python argument parsing implementation,
it is suggested to always use ``=`` between the :option:`--since`
option and its argument, e.g. ``--since=-1d`` rather than ``--since
-1d``. In the second case Python mistakenly considers the option
argument an unknown option and will raise an error about a missing
argument to :option:`--since`.


.. option:: -f, --filter=STATE|RESULT

List jobs with specific job state or result. Multiple states or
Expand Down

0 comments on commit d9905ae

Please sign in to comment.