Build a command-line script
A Python script needs named inputs, flags, validation, and generated usage text.
Python · Module
argparse
argparse builds command-line interfaces from declared arguments and options. It parses input into a Namespace and automatically provides help, usage, and invalid-input errors.
- Since
- 3.2
How it works
Create an ArgumentParser, declare positional arguments and options with add_argument(), then call parse_args() to convert command-line strings into a namespace. The parser also supplies help and usage output and reports invalid input.
Syntax
argparse.ArgumentParser(...); parser.add_argument(...); parser.parse_args(args=None, namespace=None)Parameters
| Name | Type | Description |
|---|---|---|
**kwargs | various keyword arguments | Optional parser configuration such as description, formatter behavior, and argument-handling policy. |
name_or_flags | str | One or more names or option strings defining an argument, such as name, -n, or --name. |
**kwargs | various keyword arguments | Configuration for an argument, including action, type, default, required, help, and dest. |
args | sequence of str | An optional sequence of command-line strings; when omitted, parse_args() reads sys.argv. |
Returns
parse_args() returns a Namespace whose attributes contain the parsed argument values; parser operations also generate help, usage, or errors as appropriate.
Key points
- The module is the standard-library building block for defining command-line interfaces.
- A parser can generate user-facing usage information without manually formatting a help screen.
- Most argparse programs begin by constructing an ArgumentParser instance.
- Use add_argument() repeatedly to describe each accepted command-line input.
- One API supports required positionals, value-bearing options, and boolean switches.
- By default, parsing uses the process command line exposed through sys.argv.
Common mistakes
- Help is automatically available through -h and --help unless the parser configuration changes it.
Example: Parse a positional argument and flag
import argparse
parser = argparse.ArgumentParser(description="Greet someone")
parser.add_argument("name", help="person to greet")
parser.add_argument("--shout", action="store_true", help="uppercase output")
args = parser.parse_args()
message = f"Hello, {args.name}!"
print(message.upper() if args.shout else message)Defines a required positional name and an optional boolean flag, then parses command-line input into attributes on the returned namespace.
When to use it
Implement subcommands
A utility exposes several operations under one executable.
Convert and validate options
A program needs typed values such as integers or paths from shell input.
Interview questions
QWhat are the core responsibilities of ArgumentParser?
ArgumentParser stores the command-line interface definition. add_argument() declares positional arguments, value-taking options, or boolean flags; parse_args() processes the command line and returns a Namespace.
Follow-up: How would you validate a typed option? Pass a callable such as int through the type parameter, causing the parsed value to be converted or an error to be reported.
QHow do positional arguments differ from options?
A positional argument is identified by its name and is normally required. An optional argument is introduced with option strings such as --shout and can be configured with action="store_true" for an on/off flag.
Follow-up: How can an option have a short and long spelling? Supply both option strings, for example parser.add_argument("-v", "--verbose", action="store_true").
QWhat does parse_args() return and how are values accessed?
parse_args() reads the program's command-line arguments, converts configured values, and assigns them to attributes on a returned Namespace. The attribute name normally comes from the argument declaration unless dest is specified.
Follow-up: How can a parser process a supplied argument list instead of sys.argv? Pass that list to parse_args(args); omitting it makes the parser use the command line.
Related
argparse.ArgumentParserArgumentParser.add_argument()ArgumentParser.parse_args()Namespaceargparse tutorial