Python parse_known_args Consumes Child Options: Define the Forwarding Boundary

A Python wrapper can lose a child command's option even when it uses parse_known_args. The method separates arguments the current parser recognizes from the remainder; it does not establish ownership between two command-line programs. Start by deciding which tokens belong to the wrapper and which belong to the child. Then choose parsing rules that preserve that boundary.

There are two different failure modes. A long option can be interpreted as an abbreviation of a wrapper option. Separately, an exact wrapper option can be recognized after an unknown token. Disabling abbreviation addresses the first problem. It does not make parsing stop at the first unknown argument.

Reproduce abbreviation without launching a child

Pass an explicit argument list so the test is independent of a shell and your current process arguments. This complete example registers only --output and gives the parser --out. With the default abbreviation behavior, the wrapper consumes both the option and its value. With abbreviation disabled, both remain available for forwarding.

import argparse

for abbreviate in (True, False):
    parser = argparse.ArgumentParser(allow_abbrev=abbreviate)
    parser.add_argument("--output")
    known, rest = parser.parse_known_args(["--out", "child.txt"])
    if abbreviate:
        assert known.output == "child.txt" and rest == []
    else:
        assert known.output is None
        assert rest == ["--out", "child.txt"]
    exact, rest = parser.parse_known_args(["--output", "wrapper.txt"])
    assert exact.output == "wrapper.txt" and rest == []
print("abbreviation disabled; exact options still recognized")

The exact spelling remains recognized in both cases. A child option named exactly --output still collides with this wrapper's option. If several registered long options share a prefix, an abbreviated token can also be ambiguous and produce a parser error. Do not treat an error as a guarantee that every unrecognized option will be returned unchanged.

The Python documentation explicitly warns that prefix matching applies during partial parsing. The test illustrates that contract; it does not establish the behavior of a different parser library. Keep allow_abbrev=False when abbreviations are undesirable, but still design an ownership rule.

An unknown token is not a stop instruction

A wrapper might assume that everything after a command name or unrecognized token belongs to the child. That is a separate command-line grammar. parse_known_args can still collect a known option later in the list. The following example uses an append action to make both recognized occurrences visible.

import argparse

parser = argparse.ArgumentParser(allow_abbrev=False)
parser.add_argument("--foo", action="append")
known, rest = parser.parse_known_args(["--foo", "a", "STOP", "--foo", "b"])
assert known.foo == ["a", "b"]
assert rest == ["STOP"]
print(known.foo, rest)

Here STOP is merely an unknown positional token. It does not transfer ownership of the remaining input. Disabling abbreviations changes nothing because both occurrences use the exact registered option name. This matters for wrappers around tools whose options overlap with the wrapper's options.

Do not fix this by deleting every token that resembles a wrapper option from the remainder. Option values can contain spaces, start with a dash, or equal a command name. A handwritten scan must understand the grammar to distinguish those cases. Instead, make the contract explicit before either parser processes the other's input.

Reserve a separator and split the original list first

One simple contract is wrapper [wrapper options] -- [child arguments]. Reserve the first standalone -- as the separator. Wrapper values cannot be a standalone separator under this contract; use another representation or a separate API if that value must be supported. Split the original list before calling parse_args on the wrapper portion.

import argparse

parser = argparse.ArgumentParser(allow_abbrev=False)
parser.add_argument("--output", required=True)

def separate(argv):
    try:
        boundary = argv.index("--")
    except ValueError:
        raise ValueError("expected wrapper options -- child arguments")
    return parser.parse_args(argv[:boundary]), argv[boundary + 1:]

argv = ["--output", "wrapper.txt", "--", "--output", "child.txt",
        "space in one argument", "--", "literal-tail"]
known, child = separate(argv)
assert known.output == "wrapper.txt"
assert child == ["--output", "child.txt", "space in one argument",
                 "--", "literal-tail"]
try:
    separate(["--output", "wrapper.txt"])
except ValueError:
    pass
else:
    raise AssertionError("missing separator was accepted")
print("child arguments preserved as a list; nothing executed")

The first separator is consumed by the wrapper contract. A later separator is preserved for the child. An argument containing spaces remains one list element. No quoting or shell reconstruction is necessary to test this boundary. This example deliberately does not launch a subprocess or choose an executable.

If production code later starts a program, use the supported subprocess API with an argument list, a separately selected executable, and the default non-shell behavior. Review executable selection, untrusted option values, working directory, cancellation, and exit handling for that integration. A correct list boundary alone is not validation of what the child is allowed to do.

Keep positionals and short flags in the contract

A standalone -- passed directly to a parser generally marks the end of option parsing for that parser; it is not a universal child-routing protocol. Positional definitions influence what the parser consumes. Splitting before parsing avoids asking the wrapper parser to interpret the child's positionals or short flags at all.

Subparsers and a remainder positional can be appropriate for a different grammar. They require their own tests for option placement and conflicts. Likewise, allow_abbrev=False is about long-option abbreviations; it is not a blanket prohibition on grouped short flags. Avoid promising lossless forwarding for a CLI whose actual grammar you have not tested.

Before changing a wrapper, test exact-name collisions, prefixes, missing separators, empty child lists, child separators, and arguments containing spaces. Decide whether an empty child list is valid before accepting it; the example permits it. Run the fixture with the deployed Python version and inspect the resulting list before any real execution. The examples were checked on macOS with CPython 3.11, 3.13, and 3.14; shell behavior and a real child program were outside the test.