Why does argparse store the value of --retries 3 as a string, and what changes it?

### Everything arrives as text The operating system hands a process its command line as a list of strings. argparse does not guess: with no `type=`, a value is stored exactly as typed, so `--retries 3` gives you `'3'`, and `'3' * 2` is `'33'` rather than `6`. That silent string is behind a large share of the bugs in hand-rolled scripts, because `if args.retries > 0` raises `TypeError` in Python 3 rather than quietly comparing. ### type= is a callable, not a type name The `type=` keyword of `add_argument()` accepts any callable taking one string and returning the value you want stored. `type=int` and `type=float` are the common cases, but `type=pathlib.Path` gives you a path object, `type=str.lower` normalises case, and a function of your own can parse a date, a duration or a key=value pair. Because it is an ordinary callable, argparse calls it once **per value**, which composes with `nargs`: `add_argument("--ids", nargs="*", type=int)` yields a list of integers, not a list of strings and not one integer. ### The rule about defaults, stated precisely argparse applies `type=` to a `default` only when that default is a string. If the argument is missing from the command line and the stored default is still the string you wrote, argparse runs it through the converter, so `default="6800"` with `type=int` produces `6800`. A default that is already a non-string — `6800`, `None`, `[]`, a `Path` — is stored as-is, untouched. The practical guidance is to write the default in its final type (`default=6800`) so no conversion has to happen at all, and to remember that `None` is the default default: without `default=`, an absent optional lands as `None`, and code that does arithmetic on it fails at the first use rather than at parse time. ### choices, and the order of operations `choices=` is a membership test performed **after** the type conversion, on the converted value. So `add_argument("--n", type=int, choices=[1, 2, 6800])` must list integers, not strings; listing `["1"]` would never match. That ordering is also what makes `type=str.lower` with `choices=["fast", "full"]` accept `--mode FULL`: the value is lowered first, then checked. A rejected choice becomes a parse error naming the allowed set, printed with the usage line to standard error, exit status 2. ### Where type= does not apply Actions that consume no value never call the converter. `action="store_true"` and `"store_false"` are the obvious cases; `action="count"` is another. Passing `type=` alongside them is dead configuration at best. The most common mistake in this area is reaching for `type=bool` to build a switch: `bool` is a perfectly valid callable, so argparse accepts it — and then `--force False` stores `True`, because `bool` on a non-empty string is `True` for every string except the empty one. There are two correct answers: `action="store_true"` for a plain on-switch, and `argparse.BooleanOptionalAction` (added in Python 3.9) when you want an explicit off-switch too, which generates `--cache` and `--no-cache` from a single declaration and honours `default=True`. ### Errors raised inside the converter When the callable raises `ValueError` or `TypeError` — as `int("many")` does — argparse turns that into a parse error rather than a traceback, printing `error: argument --retries: invalid int value: 'many'`. That is a deliberate design choice: a user typo should produce a usage message, not a stack trace. It also means the converter's own error text is discarded unless you raise `argparse.ArgumentTypeError`, whose message argparse prints verbatim. ### A checklist for a converter you write yourself Make it a named module-level function so the generated error message reads well (argparse uses the callable's `__name__` in `invalid <name> value`). Make it total: given any string, either return a value or raise. Keep it free of side effects — no file writes, no network — because argparse may call it while building an error message path, and because a converter that mutates state is untestable. Do validate cheap invariants there (a positive count, an ISO date, an existing directory) rather than after `parse_args()`: failing inside the converter gives you argparse's uniform error format and exit status for free, while failing afterwards means you write your own message, your own exit code, and eventually two inconsistent styles in the same tool.