The behavior is not a bug as it is documented. The parse_known_args entry has an example something like yours with interleaved known and unknowns and all are processed and assigned to the namespace or unknown tuple. I presume that this example intentionally makes this point.

ArgumentParser.parse_known_args(args=None, namespace=None)

Sometimes a script may only parse a few of the command-line arguments, passing the remaining arguments on to another script or program. In these cases, the parse_known_args() method can be useful. It works much like parse_args() except that it does not produce an error when extra arguments are present. Instead, it returns a two item tuple containing the populated namespace and the list of remaining argument strings.

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='store_true')
>>> parser.add_argument('bar')
>>> parser.parse_known_args(['--foo', '--badger', 'BAR', 'spam'])
(Namespace(bar='BAR', foo=True), ['--badger', 'spam'])

Perhaps you are implicitly making a feature request, but I do not know argparse well enough to know if what you want is already possible or not.

Ooh, I misread the example, which indeed makes this behavior clear. Thank you for the explanation! The text of the documentation only talks about “remaining arguments”, making it seem that it means “the rest after some point” and not “any unknown ones anywhere”.

Argparse actually supports what I want it to do, using argparse.ArgumentParser.add_argument("unknown_args", nargs=argparse.REMAINDER) as the last positional parameter, but the argparse.REMAINDER is only obliquely mentioned in the documentation and doesn't seem to be properly documented anywhere. The only downside I see is that it makes the unknown-args argument show up in the help, but that can be solved by adding help=argparse.SUPPRESS.

In that case, I guess I'm making a documentation improvement request. :-) My suggested change would be amendment of the last sentence as follows: “Instead, it skips over any unknown arguments in the command line, only parsing the known ones, and returns a two item tuple containing the populated namespace and the list of skipped argument strings.”

Perhaps I would also add another paragraph as follows:
“Note that parsing the skipped arguments in a later pass may produce unexpected results. If the --badger argument in the example below is supposed to be taking a parameter, it would get spam as the parameter instead of BAR, which was already consumed by parse_known_args().”

And maybe also the following:
“If you want to parse known arguments from the start of the argument list and stop at the first unknown one, you can add an unknown_args positional parameter using argparse.ArgumentParser.add_argument("unknown_args", nargs=argparse.REMAINDER, help=argparse.SUPPRESS) and using parse_args() instead of this function.”

Can you create a pull request?

Yes, I'll get to it in a few days.

Documentation for REMAINDER has intentionally been removed, since its use has been somewhat buggy. It is still allowed, but we aren't encouraging its use.

Note that parse_args also uses parse_known_args, only it raises an error when the 'extra' list is not empty.

In any case, parsing tries to handle all strings, putting ones it does not recognize in the namespace under the "UNRECOGNIZED" dest. It does not have a 'short-circuit' option, which would stop parsing the rest. One hallmark of argparse parsing is it tries to handle arguments, at least the optionals, in what ever order the end user provides.

Besides REMAINDER, '--' can act to short-circuit this regular parsing.