Examples

The following examples illustrate both the usage and the utility of reverse_argparse. They build on each other in complexity, so it will make the most sense to start here at the top and work your way down through each in turn.

The Basics

When using a bare-bones argparse.ArgumentParser, reverse_argparse doesn’t really provide much benefit, but it’s instructive to see how straightforward it is to get up and running with it.

example/basic.py

#!/usr/bin/env python3
"""Basic ``reverse_argparse`` functionality."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

from argparse import ArgumentParser

from reverse_argparse import ReverseArgumentParser

# Construct the `ArgumentParser`.
parser = ArgumentParser()
parser.add_argument("--foo")

# Parse the command line arguments.
args = parser.parse_args()

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_effective_command_line_invocation())

Note

The only thing you’re adding to your script to take advantage of reverse_argparse is lines 7 and 19–22.

Running the script, and passing an argument to it, yields the following:

$ python3 ../../example/basic.py --foo bar
The effective command line invocation was:
basic.py --foo bar

Default Values

Let’s now take the prior example and add some complexity to it by adding more arguments, but this time with default values.

example/default_values.py

#!/usr/bin/env python3
"""How ``reverse_argparse`` handles default values."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

from argparse import ArgumentParser

from reverse_argparse import ReverseArgumentParser

# Construct the `ArgumentParser`.
parser = ArgumentParser()
parser.add_argument("--foo")
parser.add_argument("--bar", default="spam")
parser.add_argument("--baz", type=int, default=42)

# Parse the command line arguments.
args = parser.parse_args()

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_effective_command_line_invocation())

Now running the script with the same command line arguments yields:

$ python3 ../../example/default_values.py --foo bar
The effective command line invocation was:
default_values.py --foo bar --bar spam --baz 42

Relative References

We can complicate things further by adding an argument representing a path. Though the user is free to specify a relative path on the command line, this will be translated to an absolute path behind the scenes.

example/relative_references.py

#!/usr/bin/env python3
"""How ``reverse_argparse`` handles relative references."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

import os
from argparse import ArgumentParser

from reverse_argparse import ReverseArgumentParser

# Construct the `ArgumentParser`.
parser = ArgumentParser()
parser.add_argument("--foo")
parser.add_argument("--bar", default="spam")
parser.add_argument("--baz", type=int, default=42)
parser.add_argument("--src", type=os.path.abspath)  # type: ignore[arg-type]

# Parse the command line arguments.
args = parser.parse_args()

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_effective_command_line_invocation())

Now running the script and pointing to a file in your current working directory yields:

$ python3 ../../example/relative_references.py --src bar.txt
The effective command line invocation was:
relative_references.py --bar spam --baz 42 --src /home/docs/checkouts/readthedocs.org/user_builds/reverse-argparse/checkouts/latest/doc/source/bar.txt

Argument Post-Processing

The example above is actually a special case of any general post-processing of arguments that you might like to do after they are initially parsed. Consider an example of normalizing a date/time from whatever the user specifies to a standard format.

example/post_processing.py

#!/usr/bin/env python3
"""How ``reverse_argparse`` handles post-processing of arguments."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

import os
from argparse import ArgumentParser

import dateparser

from reverse_argparse import ReverseArgumentParser

# Construct the `ArgumentParser`.
parser = ArgumentParser()
parser.add_argument("--foo")
parser.add_argument("--bar", default="spam")
parser.add_argument("--baz", type=int, default=42)
parser.add_argument("--src", type=os.path.abspath)  # type: ignore[arg-type]
parser.add_argument("--before")

# Parse the command line arguments.
args = parser.parse_args()
if args.before is not None:
    args.before = dateparser.parse(args.before)

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_effective_command_line_invocation())

Now running the script and specifying a relative date/time yields:

$ python3 ../../example/post_processing.py --before '30 minutes ago'
The effective command line invocation was:
post_processing.py --bar spam --baz 42 --before '2024-05-13 19:00:31.026047'

Pretty-Printing the Effective Command

In all of the above, the effective command line invocation will be printed on a single line. Often this is what you want, as it facilitates easy copying and pasting. However, when your script grows in complexity, you may want to pretty-print the output such that it’s easier to see at a glance what all the different flags and corresponding values are.

example/pretty_printing.py

#!/usr/bin/env python3
"""``reverse_argparse`` pretty-printing functionality."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

import os
from argparse import ArgumentParser

import dateparser

from reverse_argparse import ReverseArgumentParser

# Construct the `ArgumentParser`.
parser = ArgumentParser()
parser.add_argument("--foo")
parser.add_argument("--bar", default="spam")
parser.add_argument("--baz", type=int, default=42)
parser.add_argument("--src", type=os.path.abspath)  # type: ignore[arg-type]
parser.add_argument("--before")

# Parse the command line arguments.
args = parser.parse_args()
if args.before is not None:
    args.before = dateparser.parse(args.before)

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_pretty_command_line_invocation())

Now running the script and specifying a relative date/time yields:

$ python3 ../../example/pretty_printing.py --foo eggs --src file.txt --before 'today'
The effective command line invocation was:
pretty_printing.py \
    --foo eggs \
    --bar spam \
    --baz 42 \
    --src /home/docs/checkouts/readthedocs.org/user_builds/reverse-argparse/checkouts/latest/doc/source/file.txt \
    --before '2024-05-13 19:30:31.523538'

Subparsers

A special case you might be concerned with is that of an argparse.ArgumentParser with multiple subparsers or sub-commands, each of which will have its own arguments, and even potentially nested subparsers. When using get_effective_command_line_invocation(), you won’t notice anything different, but get_pretty_command_line_invocation() shows the subtle difference.

example/subparsers.py

#!/usr/bin/env python3
"""How ``reverse_argparse`` handles subparsers."""

# © 2024 National Technology & Engineering Solutions of Sandia, LLC
# (NTESS).  Under the terms of Contract DE-NA0003525 with NTESS, the
# U.S. Government retains certain rights in this software.

# SPDX-License-Identifier: BSD-3-Clause

import os
from argparse import ArgumentParser

import dateparser

from reverse_argparse import ReverseArgumentParser

parser = ArgumentParser()
subparsers = parser.add_subparsers(title="Subcommands")
foo_parser = subparsers.add_parser("foo")
foo_parser.add_argument("--one")
foo_parser.add_argument("--two", default="spam")
foo_parser.add_argument("--three", type=int, default=42)
bar_parser = subparsers.add_parser("bar")
bar_parser.add_argument(
    "--four",
    type=os.path.abspath,  # type: ignore[arg-type]
)
bar_parser.add_argument("--five")

# Parse the command line arguments.
args = parser.parse_args()
if getattr(args, "five", None) is not None:
    args.five = dateparser.parse(args.five)

# Insert the body of your script here.

# Unparse the arguments to tell the user what they ran.
print("The effective command line invocation was:")
unparser = ReverseArgumentParser(parser, args)
print(unparser.get_pretty_command_line_invocation())

Running this script and using the foo subcommand yields:

$ python3 ../../example/subparsers.py foo --one eggs
The effective command line invocation was:
subparsers.py \
    foo \
        --one eggs \
        --two spam \
        --three 42

Note

The arguments associated with the subparser have been indented by an extra level. If there are subparsers within subparsers, reverse_argparse keeps track of the indentation level while unparsing, so the user can easily see which arguments correspond to which subparser.