Python Argparse Type List Produces Characters: Use Nargs or Append for Multiple Values

type converts each argument token. list("report.csv") produces characters; it does not tell argparse to consume multiple tokens. Use nargs for one option with several values, or append for repeated options.

Check the failure with a small fixture

A command-line option returns characters instead of a list of file arguments.

import argparse
bad = argparse.ArgumentParser()
bad.add_argument("--files", type=list)
assert bad.parse_args(["--files", "ab.csv"]).files == list("ab.csv")
multiple = argparse.ArgumentParser()
multiple.add_argument("--files", nargs="+", type=str)
assert multiple.parse_args(["--files", "a.csv", "b.csv"]).files == ["a.csv", "b.csv"]
repeated = argparse.ArgumentParser()
repeated.add_argument("--file", action="append", default=None)
assert repeated.parse_args(["--file", "a.csv", "--file", "b.csv"]).file == ["a.csv", "b.csv"]
assert repeated.parse_args([]).file is None

What the result means

The fixture passes token lists directly, so shell quoting does not obscure parser behavior. nargs="+" requires at least one value after an occurrence. append records each occurrence separately. Combining append with nargs can produce a list of lists, so validate the resulting shape against what downstream code accepts.

Choose the correction for your caller

Write the intended command syntax before choosing parser settings. For --files a.csv b.csv, use a multi-value nargs contract. For --file a.csv --file b.csv, use append. A comma-separated value is one token and needs an explicitly documented split rule if you support it; nargs does not interpret commas. Normalize the absent-option case deliberately, for example args.file or [], and preserve filenames containing spaces by keeping them as one shell token.

Limits and the next check

Values beginning with hyphens can be interpreted as options; design and test your CLI syntax for such paths, using an unambiguous path form or argument convention. Do not use eval to parse a user-supplied Python-looking list. This example tests parsing only and does not open any files.

Related: Compare a related data or execution contract.

The embedded Python example was executed as an isolated local script on November 10, 2026 (KST), using Python 3.11.6. It demonstrates the stated boundary; it is not a test of your application or a promise of compatibility with every Python release.