FM / library

/usr/share/doc/python2-docs/html/library/

/usr/share/doc/python2-docs/html/library

Name	Size	Mode	Actions
2to3.html	59507	0644	edit dl rm
abc.html	25826	0644	edit dl rm
aepack.html	14164	0644	edit dl rm
aetools.html	16389	0644	edit dl rm
aetypes.html	21021	0644	edit dl rm
aifc.html	25064	0644	edit dl rm
al.html	18672	0644	edit dl rm
allos.html	35297	0644	edit dl rm
anydbm.html	18124	0644	edit dl rm
archiving.html	10078	0644	edit dl rm
argparse.html	263616	0644	edit dl rm
array.html	31855	0644	edit dl rm
ast.html	38167	0644	edit dl rm
asynchat.html	33930	0644	edit dl rm
asyncore.html	40631	0644	edit dl rm
atexit.html	18455	0644	edit dl rm
audioop.html	34252	0644	edit dl rm
autogil.html	8733	0644	edit dl rm
base64.html	21862	0644	edit dl rm
basehttpserver.html	37441	0644	edit dl rm
bastion.html	11798	0644	edit dl rm
bdb.html	41395	0644	edit dl rm
binascii.html	22997	0644	edit dl rm
binhex.html	11309	0644	edit dl rm
bisect.html	24666	0644	edit dl rm
bsddb.html	28589	0644	edit dl rm
bz2.html	29048	0644	edit dl rm
calendar.html	41762	0644	edit dl rm
carbon.html	51998	0644	edit dl rm
cd.html	30033	0644	edit dl rm
cgi.html	55922	0644	edit dl rm
cgihttpserver.html	14026	0644	edit dl rm
cgitb.html	12263	0644	edit dl rm
chunk.html	15899	0644	edit dl rm
cmath.html	28365	0644	edit dl rm
cmd.html	29042	0644	edit dl rm
code.html	26959	0644	edit dl rm
codecs.html	118258	0644	edit dl rm
codeop.html	15898	0644	edit dl rm
collections.html	147647	0644	edit dl rm
colorpicker.html	8035	0644	edit dl rm
colorsys.html	11919	0644	edit dl rm
commands.html	15516	0644	edit dl rm
compileall.html	18621	0644	edit dl rm
compiler.html	75897	0644	edit dl rm
configparser.html	67751	0644	edit dl rm
constants.html	13979	0644	edit dl rm
contextlib.html	22777	0644	edit dl rm
cookie.html	41854	0644	edit dl rm
cookielib.html	91032	0644	edit dl rm
copy.html	13004	0644	edit dl rm
copy_reg.html	14691	0644	edit dl rm
crypt.html	10647	0644	edit dl rm
crypto.html	7761	0644	edit dl rm
csv.html	76456	0644	edit dl rm
ctypes.html	264575	0644	edit dl rm
curses.ascii.html	24873	0644	edit dl rm
curses.html	167501	0644	edit dl rm
curses.panel.html	15824	0644	edit dl rm
custominterp.html	8026	0644	edit dl rm
datatypes.html	18015	0644	edit dl rm
datetime.html	253438	0644	edit dl rm
dbhash.html	16825	0644	edit dl rm
dbm.html	13507	0644	edit dl rm
debug.html	10703	0644	edit dl rm
decimal.html	222315	0644	edit dl rm
development.html	14828	0644	edit dl rm
difflib.html	91975	0644	edit dl rm
dircache.html	12299	0644	edit dl rm
dis.html	84156	0644	edit dl rm
distribution.html	7679	0644	edit dl rm
distutils.html	10152	0644	edit dl rm
dl.html	17668	0644	edit dl rm
doctest.html	185883	0644	edit dl rm
docxmlrpcserver.html	17573	0644	edit dl rm
dumbdbm.html	15549	0644	edit dl rm
dummy_thread.html	10065	0644	edit dl rm
dummy_threading.html	8934	0644	edit dl rm
easydialogs.html	33124	0644	edit dl rm
email-examples.html	47424	0644	edit dl rm
email.charset.html	29424	0644	edit dl rm
email.encoders.html	12847	0644	edit dl rm
email.errors.html	17952	0644	edit dl rm
email.generator.html	23141	0644	edit dl rm
email.header.html	29108	0644	edit dl rm
email.html	55722	0644	edit dl rm
email.iterators.html	12623	0644	edit dl rm
email.message.html	70189	0644	edit dl rm
email.mime.html	31655	0644	edit dl rm
email.parser.html	35142	0644	edit dl rm
email.utils.html	27076	0644	edit dl rm
ensurepip.html	18327	0644	edit dl rm
errno.html	40246	0644	edit dl rm
exceptions.html	63693	0644	edit dl rm
fcntl.html	26245	0644	edit dl rm
filecmp.html	23997	0644	edit dl rm
fileformats.html	9653	0644	edit dl rm
fileinput.html	27071	0644	edit dl rm
filesys.html	10866	0644	edit dl rm
fl.html	56525	0644	edit dl rm
fm.html	13009	0644	edit dl rm
fnmatch.html	16258	0644	edit dl rm
formatter.html	37371	0644	edit dl rm
fpectl.html	16879	0644	edit dl rm
fpformat.html	11455	0644	edit dl rm
fractions.html	24888	0644	edit dl rm
framework.html	36934	0644	edit dl rm
frameworks.html	7551	0644	edit dl rm
ftplib.html	49577	0644	edit dl rm
functions.html	205640	0644	edit dl rm
functools.html	29645	0644	edit dl rm
future_builtins.html	14477	0644	edit dl rm
gc.html	28423	0644	edit dl rm
gdbm.html	17805	0644	edit dl rm
gensuitemodule.html	12574	0644	edit dl rm
getopt.html	25280	0644	edit dl rm
getpass.html	11426	0644	edit dl rm
gettext.html	84971	0644	edit dl rm
gl.html	24342	0644	edit dl rm
glob.html	14430	0644	edit dl rm
grp.html	11316	0644	edit dl rm
gzip.html	20576	0644	edit dl rm
hashlib.html	25467	0644	edit dl rm
heapq.html	34890	0644	edit dl rm
hmac.html	14374	0644	edit dl rm
hotshot.html	20147	0644	edit dl rm
htmllib.html	27682	0644	edit dl rm
htmlparser.html	42433	0644	edit dl rm
httplib.html	70932	0644	edit dl rm
i18n.html	10047	0644	edit dl rm
ic.html	18654	0644	edit dl rm
idle.html	42148	0644	edit dl rm
imageop.html	16099	0644	edit dl rm
imaplib.html	58515	0644	edit dl rm
imgfile.html	12732	0644	edit dl rm
imghdr.html	12238	0644	edit dl rm
imp.html	37603	0644	edit dl rm
importlib.html	8926	0644	edit dl rm
imputil.html	33563	0644	edit dl rm
index.html	79088	0644	edit dl rm
inspect.html	56823	0644	edit dl rm
internet.html	26138	0644	edit dl rm
intro.html	9353	0644	edit dl rm
io.html	113701	0644	edit dl rm
ipc.html	16598	0644	edit dl rm
itertools.html	125397	0644	edit dl rm
jpeg.html	13757	0644	edit dl rm
json.html	73678	0644	edit dl rm
keyword.html	8210	0644	edit dl rm
language.html	11687	0644	edit dl rm
linecache.html	11416	0644	edit dl rm
locale.html	61576	0644	edit dl rm
logging.config.html	80045	0644	edit dl rm
logging.handlers.html	80194	0644	edit dl rm
logging.html	110254	0644	edit dl rm
mac.html	23376	0644	edit dl rm
macos.html	16129	0644	edit dl rm
macosa.html	14080	0644	edit dl rm
macostools.html	16898	0644	edit dl rm
macpath.html	8386	0644	edit dl rm
mailbox.html	171121	0644	edit dl rm
mailcap.html	14132	0644	edit dl rm
markup.html	19862	0644	edit dl rm
marshal.html	19456	0644	edit dl rm
math.html	44015	0644	edit dl rm
md5.html	15123	0644	edit dl rm
mhlib.html	24123	0644	edit dl rm
mimetools.html	21206	0644	edit dl rm
mimetypes.html	30634	0644	edit dl rm
mimewriter.html	16078	0644	edit dl rm
mimify.html	15279	0644	edit dl rm
miniaeframe.html	13109	0644	edit dl rm
misc.html	7236	0644	edit dl rm
mm.html	9570	0644	edit dl rm
mmap.html	30832	0644	edit dl rm
modulefinder.html	18096	0644	edit dl rm
modules.html	9017	0644	edit dl rm
msilib.html	57853	0644	edit dl rm
msvcrt.html	21232	0644	edit dl rm
multifile.html	26256	0644	edit dl rm
multiprocessing.html	414535	0644	edit dl rm
mutex.html	12147	0644	edit dl rm
netdata.html	18379	0644	edit dl rm
netrc.html	14021	0644	edit dl rm
new.html	13177	0644	edit dl rm
nis.html	11502	0644	edit dl rm
nntplib.html	45689	0644	edit dl rm
numbers.html	40636	0644	edit dl rm
numeric.html	14292	0644	edit dl rm
operator.html	93622	0644	edit dl rm
optparse.html	250109	0644	edit dl rm
os.html	240195	0644	edit dl rm
os.path.html	43402	0644	edit dl rm
ossaudiodev.html	45594	0644	edit dl rm
othergui.html	9403	0644	edit dl rm
parser.html	42558	0644	edit dl rm
pdb.html	38603	0644	edit dl rm
persistence.html	15676	0644	edit dl rm
pickle.html	109684	0644	edit dl rm
pickletools.html	11475	0644	edit dl rm
pipes.html	19685	0644	edit dl rm
pkgutil.html	27367	0644	edit dl rm
platform.html	31599	0644	edit dl rm
plistlib.html	18344	0644	edit dl rm
popen2.html	27601	0644	edit dl rm
poplib.html	24320	0644	edit dl rm
posix.html	16626	0644	edit dl rm
posixfile.html	21387	0644	edit dl rm
pprint.html	32207	0644	edit dl rm
profile.html	72788	0644	edit dl rm
pty.html	10195	0644	edit dl rm
pwd.html	12388	0644	edit dl rm
pyclbr.html	15812	0644	edit dl rm
pydoc.html	13650	0644	edit dl rm
pyexpat.html	80886	0644	edit dl rm
python.html	12854	0644	edit dl rm
py_compile.html	11932	0644	edit dl rm
queue.html	26856	0644	edit dl rm
quopri.html	12739	0644	edit dl rm
random.html	42722	0644	edit dl rm
re.html	155985	0644	edit dl rm
readline.html	37383	0644	edit dl rm
repr.html	21778	0644	edit dl rm
resource.html	28286	0644	edit dl rm
restricted.html	12366	0644	edit dl rm
rexec.html	40566	0644	edit dl rm
rfc822.html	46408	0644	edit dl rm
rlcompleter.html	14460	0644	edit dl rm
robotparser.html	13403	0644	edit dl rm
runpy.html	21925	0644	edit dl rm
sched.html	19878	0644	edit dl rm
scrolledtext.html	9728	0644	edit dl rm
select.html	44090	0644	edit dl rm
sets.html	40151	0644	edit dl rm
sgi.html	10371	0644	edit dl rm
sgmllib.html	34464	0644	edit dl rm
sha.html	13062	0644	edit dl rm
shelve.html	29955	0644	edit dl rm
shlex.html	35033	0644	edit dl rm
shutil.html	45454	0644	edit dl rm
signal.html	34023	0644	edit dl rm
simplehttpserver.html	20351	0644	edit dl rm
simplexmlrpcserver.html	37794	0644	edit dl rm
site.html	26887	0644	edit dl rm
smtpd.html	13587	0644	edit dl rm
smtplib.html	47054	0644	edit dl rm
sndhdr.html	10993	0644	edit dl rm
socket.html	116414	0644	edit dl rm
socketserver.html	76430	0644	edit dl rm
someos.html	16472	0644	edit dl rm
spwd.html	11163	0644	edit dl rm
sqlite3.html	150014	0644	edit dl rm
ssl.html	202453	0644	edit dl rm
stat.html	34597	0644	edit dl rm
statvfs.html	11326	0644	edit dl rm
stdtypes.html	298144	0644	edit dl rm
string.html	120219	0644	edit dl rm
stringio.html	20061	0644	edit dl rm
stringprep.html	17729	0644	edit dl rm
strings.html	15905	0644	edit dl rm
struct.html	44896	0644	edit dl rm
subprocess.html	110447	0644	edit dl rm
sun.html	7253	0644	edit dl rm
sunau.html	30011	0644	edit dl rm
sunaudio.html	19236	0644	edit dl rm
symbol.html	8140	0644	edit dl rm
symtable.html	25871	0644	edit dl rm
sys.html	110996	0644	edit dl rm
sysconfig.html	26299	0644	edit dl rm
syslog.html	19737	0644	edit dl rm
tabnanny.html	11393	0644	edit dl rm
tarfile.html	88728	0644	edit dl rm
telnetlib.html	27782	0644	edit dl rm
tempfile.html	31903	0644	edit dl rm
termios.html	17309	0644	edit dl rm
test.html	57030	0644	edit dl rm
textwrap.html	30135	0644	edit dl rm
thread.html	21486	0644	edit dl rm
threading.html	86655	0644	edit dl rm
time.html	63798	0644	edit dl rm
timeit.html	40529	0644	edit dl rm
tix.html	50582	0644	edit dl rm
tk.html	26568	0644	edit dl rm
tkinter.html	84316	0644	edit dl rm
token.html	20999	0644	edit dl rm
tokenize.html	20607	0644	edit dl rm
trace.html	28668	0644	edit dl rm
traceback.html	40900	0644	edit dl rm
ttk.html	108515	0644	edit dl rm
tty.html	9753	0644	edit dl rm
turtle.html	230483	0644	edit dl rm
types.html	29833	0644	edit dl rm
undoc.html	24680	0644	edit dl rm
unicodedata.html	20186	0644	edit dl rm
unittest.html	225021	0644	edit dl rm
unix.html	11223	0644	edit dl rm
urllib.html	68266	0644	edit dl rm
urllib2.html	113380	0644	edit dl rm
urlparse.html	43474	0644	edit dl rm
user.html	12707	0644	edit dl rm
userdict.html	32069	0644	edit dl rm
uu.html	11810	0644	edit dl rm
uuid.html	30137	0644	edit dl rm
warnings.html	50950	0644	edit dl rm
wave.html	24894	0644	edit dl rm
weakref.html	38808	0644	edit dl rm
webbrowser.html	26565	0644	edit dl rm
whichdb.html	9499	0644	edit dl rm
windows.html	9817	0644	edit dl rm
winsound.html	20466	0644	edit dl rm
wsgiref.html	88384	0644	edit dl rm
xdrlib.html	33018	0644	edit dl rm
xml.dom.html	97877	0644	edit dl rm
xml.dom.minidom.html	43230	0644	edit dl rm
xml.dom.pulldom.html	13835	0644	edit dl rm
xml.etree.elementtree.html	111804	0644	edit dl rm
xml.html	18007	0644	edit dl rm
xml.sax.handler.html	41877	0644	edit dl rm
xml.sax.html	23458	0644	edit dl rm
xml.sax.reader.html	44802	0644	edit dl rm
xml.sax.utils.html	16087	0644	edit dl rm
xmlrpclib.html	69191	0644	edit dl rm
zipfile.html	62227	0644	edit dl rm
zipimport.html	22769	0644	edit dl rm
zlib.html	31230	0644	edit dl rm
_winreg.html	64631	0644	edit dl rm
__builtin__.html	11069	0644	edit dl rm
__future__.html	14688	0644	edit dl rm
__main__.html	7512	0644	edit dl rm

Edit: /usr/share/doc/python2-docs/html/library/argparse.html (263616B)

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <title>15.4. argparse — Parser for command-line options, arguments and sub-commands &#8212; Python 2.7.16 documentation</title>
 <link rel="stylesheet" href="../_static/classic.css" type="text/css" />
 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
 <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
 <script type="text/javascript" src="../_static/jquery.js"></script>
 <script type="text/javascript" src="../_static/underscore.js"></script>
 <script type="text/javascript" src="../_static/doctools.js"></script>
 <script type="text/javascript" src="../_static/sidebar.js"></script>
 <link rel="search" type="application/opensearchdescription+xml"
 title="Search within Python 2.7.16 documentation"
 href="../_static/opensearch.xml"/>
 <link rel="author" title="About these documents" href="../about.html" />
 <link rel="index" title="Index" href="../genindex.html" />
 <link rel="search" title="Search" href="../search.html" />
 <link rel="copyright" title="Copyright" href="../copyright.html" />
 <link rel="next" title="15.5. optparse — Parser for command line options" href="optparse.html" />
 <link rel="prev" title="15.3. time — Time access and conversions" href="time.html" />
 <link rel="shortcut icon" type="image/png" href="../_static/py.png" />
 <link rel="canonical" href="https://docs.python.org/2/library/argparse.html" />
 <script type="text/javascript" src="../_static/copybutton.js"></script>

</head><body> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 accesskey="I">index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="optparse.html" title="15.5. optparse — Parser for command line options"
 accesskey="N">next</a> |</li>
 <li class="right" >
 <a href="time.html" title="15.3. time — Time access and conversions"
 accesskey="P">previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li>
 <a href="../index.html">Python 2.7.16 documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">15. Generic Operating System Services</a> &#187;</li> 
 </ul>
 </div>

<div class="document">
 <div class="documentwrapper">
 <div class="bodywrapper">
 <div class="body" role="main">
 
 <div class="section" id="module-argparse">
<h1>15.4. <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> — Parser for command-line options, arguments and sub-commands<a class="headerlink" href="#module-argparse" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
New in version 2.7.
</div>
Source code: <a class="reference external" href="https://github.com/python/cpython/tree/2.7/Lib/argparse.py">Lib/argparse.py</a>
<hr class="docutils" />
<div class="sidebar">
Tutorial
This page contains the API reference information. For a more gentle
introduction to Python command-line parsing, have a look at the
<a class="reference internal" href="../howto/argparse.html#id1">argparse tutorial</a>.
</div>
The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a>
will figure out how to parse those out of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate">sys.argv</code></a>. The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a>
module also automatically generates help and usage messages and issues errors
when users give the program invalid arguments.
<div class="section" id="example">
<h2>15.4.1. Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
The following code is a Python program that takes a list of integers and
produces either the sum or the max:
<div class="highlight-default notranslate"><div class="highlight"><pre>import argparse

parser = argparse.ArgumentParser(description=&#39;Process some integers.&#39;)
parser.add_argument(&#39;integers&#39;, metavar=&#39;N&#39;, type=int, nargs=&#39;+&#39;,
 help=&#39;an integer for the accumulator&#39;)
parser.add_argument(&#39;--sum&#39;, dest=&#39;accumulate&#39;, action=&#39;store_const&#39;,
 const=sum, default=max,
 help=&#39;sum the integers (default: find the max)&#39;)

args = parser.parse_args()
print args.accumulate(args.integers)
</pre></div>
</div>
Assuming the Python code above is saved into a file called <code class="docutils literal notranslate">prog.py</code>, it can
be run at the command line and provides useful help messages:
<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py -h
usage: prog.py [-h] [--sum] N [N ...]

Process some integers.

positional arguments:
 N an integer for the accumulator

optional arguments:
 -h, --help show this help message and exit
 --sum sum the integers (default: find the max)
</pre></div>
</div>
When run with the appropriate arguments, it prints either the sum or the max of
the command-line integers:
<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py 1 2 3 4
4

$ python prog.py 1 2 3 4 --sum
10
</pre></div>
</div>
If invalid arguments are passed in, it will issue an error:
<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python prog.py a b c
usage: prog.py [-h] [--sum] N [N ...]
prog.py: error: argument N: invalid int value: &#39;a&#39;
</pre></div>
</div>
The following sections walk you through this example.
<div class="section" id="creating-a-parser">
<h3>15.4.1.1. Creating a parser<a class="headerlink" href="#creating-a-parser" title="Permalink to this headline">¶</a></h3>
The first step in using the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> is creating an
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> object:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(description=&#39;Process some integers.&#39;)
</pre></div>
</div>
The <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> object will hold all the information necessary to
parse the command line into Python data types.
</div>
<div class="section" id="adding-arguments">
<h3>15.4.1.2. Adding arguments<a class="headerlink" href="#adding-arguments" title="Permalink to this headline">¶</a></h3>
Filling an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> with information about program arguments is
done by making calls to the <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> method.
Generally, these calls tell the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> how to take the strings
on the command line and turn them into objects. This information is stored and
used when <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> is called. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.add_argument(&#39;integers&#39;, metavar=&#39;N&#39;, type=int, nargs=&#39;+&#39;,
... help=&#39;an integer for the accumulator&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--sum&#39;, dest=&#39;accumulate&#39;, action=&#39;store_const&#39;,
... const=sum, default=max,
... help=&#39;sum the integers (default: find the max)&#39;)
</pre></div>
</div>
Later, calling <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> will return an object with
two attributes, <code class="docutils literal notranslate">integers</code> and <code class="docutils literal notranslate">accumulate</code>. The <code class="docutils literal notranslate">integers</code> attribute
will be a list of one or more ints, and the <code class="docutils literal notranslate">accumulate</code> attribute will be
either the <a class="reference internal" href="functions.html#sum" title="sum"><code class="xref py py-func docutils literal notranslate">sum()</code></a> function, if <code class="docutils literal notranslate">--sum</code> was specified at the command line,
or the <a class="reference internal" href="functions.html#max" title="max"><code class="xref py py-func docutils literal notranslate">max()</code></a> function if it was not.
</div>
<div class="section" id="parsing-arguments">
<h3>15.4.1.3. Parsing arguments<a class="headerlink" href="#parsing-arguments" title="Permalink to this headline">¶</a></h3>
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> parses arguments through the
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method. This will inspect the command line,
convert each argument to the appropriate type and then invoke the appropriate action.
In most cases, this means a simple <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> object will be built up from
attributes parsed out of the command line:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.parse_args([&#39;--sum&#39;, &#39;7&#39;, &#39;-1&#39;, &#39;42&#39;])
Namespace(accumulate=&lt;built-in function sum&gt;, integers=[7, -1, 42])
</pre></div>
</div>
In a script, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> will typically be called with no
arguments, and the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> will automatically determine the
command-line arguments from <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate">sys.argv</code></a>.
</div>
</div>
<div class="section" id="argumentparser-objects">
<h2>15.4.2. ArgumentParser objects<a class="headerlink" href="#argumentparser-objects" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="argparse.ArgumentParser">
class <code class="descclassname">argparse.</code><code class="descname">ArgumentParser</code>(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=argparse.HelpFormatter, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)<a class="headerlink" href="#argparse.ArgumentParser" title="Permalink to this definition">¶</a></dt>
<dd>Create a new <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> object. All parameters should be passed
as keyword arguments. Each parameter has its own more detailed description
below, but in short they are:
<ul class="simple">
<li><a class="reference internal" href="#prog">prog</a> - The name of the program (default: <code class="docutils literal notranslate">sys.argv[0]</code>)</li>
<li><a class="reference internal" href="#usage">usage</a> - The string describing the program usage (default: generated from
arguments added to parser)</li>
<li><a class="reference internal" href="#description">description</a> - Text to display before the argument help (default: none)</li>
<li><a class="reference internal" href="#epilog">epilog</a> - Text to display after the argument help (default: none)</li>
<li><a class="reference internal" href="#parents">parents</a> - A list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects whose arguments should
also be included</li>
<li><a class="reference internal" href="#formatter-class">formatter_class</a> - A class for customizing the help output</li>
<li><a class="reference internal" href="#prefix-chars">prefix_chars</a> - The set of characters that prefix optional arguments
(default: ‘-‘)</li>
<li><a class="reference internal" href="#fromfile-prefix-chars">fromfile_prefix_chars</a> - The set of characters that prefix files from
which additional arguments should be read (default: <code class="docutils literal notranslate">None</code>)</li>
<li><a class="reference internal" href="#argument-default">argument_default</a> - The global default value for arguments
(default: <code class="docutils literal notranslate">None</code>)</li>
<li><a class="reference internal" href="#conflict-handler">conflict_handler</a> - The strategy for resolving conflicting optionals
(usually unnecessary)</li>
<li><a class="reference internal" href="#add-help">add_help</a> - Add a <code class="docutils literal notranslate">-h/--help</code> option to the parser (default: <code class="docutils literal notranslate">True</code>)</li>
</ul>
</dd></dl>

The following sections describe how each of these are used.
<div class="section" id="prog">
<h3>15.4.2.1. prog<a class="headerlink" href="#prog" title="Permalink to this headline">¶</a></h3>
By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects use <code class="docutils literal notranslate">sys.argv[0]</code> to determine
how to display the name of the program in help messages. This default is almost
always desirable because it will make the help messages match how the program was
invoked on the command line. For example, consider a file named
<code class="docutils literal notranslate">myprogram.py</code> with the following code:
<div class="highlight-default notranslate"><div class="highlight"><pre>import argparse
parser = argparse.ArgumentParser()
parser.add_argument(&#39;--foo&#39;, help=&#39;foo help&#39;)
args = parser.parse_args()
</pre></div>
</div>
The help for this program will display <code class="docutils literal notranslate">myprogram.py</code> as the program name
(regardless of where the program was invoked from):
<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help show this help message and exit
 --foo FOO foo help
$ cd ..
$ python subdir/myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help show this help message and exit
 --foo FOO foo help
</pre></div>
</div>
To change this default behavior, another value can be supplied using the
<code class="docutils literal notranslate">prog=</code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;myprogram&#39;)
&gt;&gt;&gt; parser.print_help()
usage: myprogram [-h]

optional arguments:
 -h, --help show this help message and exit
</pre></div>
</div>
Note that the program name, whether determined from <code class="docutils literal notranslate">sys.argv[0]</code> or from the
<code class="docutils literal notranslate">prog=</code> argument, is available to help messages using the <code class="docutils literal notranslate">%(prog)s</code> format
specifier.
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;myprogram&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, help=&#39;foo of the %(prog)s program&#39;)
&gt;&gt;&gt; parser.print_help()
usage: myprogram [-h] [--foo FOO]

optional arguments:
 -h, --help show this help message and exit
 --foo FOO foo of the myprogram program
</pre></div>
</div>
</div>
<div class="section" id="usage">
<h3>15.4.2.2. usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3>
By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> calculates the usage message from the
arguments it contains:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=&#39;?&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;+&#39;, help=&#39;bar help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h] [--foo [FOO]] bar [bar ...]

positional arguments:
 bar bar help

optional arguments:
 -h, --help show this help message and exit
 --foo [FOO] foo help
</pre></div>
</div>
The default message can be overridden with the <code class="docutils literal notranslate">usage=</code> keyword argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, usage=&#39;%(prog)s [options]&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=&#39;?&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;+&#39;, help=&#39;bar help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [options]

positional arguments:
 bar bar help

optional arguments:
 -h, --help show this help message and exit
 --foo [FOO] foo help
</pre></div>
</div>
The <code class="docutils literal notranslate">%(prog)s</code> format specifier is available to fill in the program name in
your usage messages.
</div>
<div class="section" id="description">
<h3>15.4.2.3. description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3>
Most calls to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> constructor will use the
<code class="docutils literal notranslate">description=</code> keyword argument. This argument gives a brief description of
what the program does and how it works. In help messages, the description is
displayed between the command-line usage string and the help messages for the
various arguments:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(description=&#39;A foo that bars&#39;)
&gt;&gt;&gt; parser.print_help()
usage: argparse.py [-h]

A foo that bars

optional arguments:
 -h, --help show this help message and exit
</pre></div>
</div>
By default, the description will be line-wrapped so that it fits within the
given space. To change this behavior, see the <a class="reference internal" href="#formatter-class">formatter_class</a> argument.
</div>
<div class="section" id="epilog">
<h3>15.4.2.4. epilog<a class="headerlink" href="#epilog" title="Permalink to this headline">¶</a></h3>
Some programs like to display additional description of the program after the
description of the arguments. Such text can be specified using the <code class="docutils literal notranslate">epilog=</code>
argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(
... description=&#39;A foo that bars&#39;,
... epilog=&quot;And that&#39;s how you&#39;d foo a bar&quot;)
&gt;&gt;&gt; parser.print_help()
usage: argparse.py [-h]

A foo that bars

optional arguments:
 -h, --help show this help message and exit

And that&#39;s how you&#39;d foo a bar
</pre></div>
</div>
As with the <a class="reference internal" href="#description">description</a> argument, the <code class="docutils literal notranslate">epilog=</code> text is by default
line-wrapped, but this behavior can be adjusted with the <a class="reference internal" href="#formatter-class">formatter_class</a>
argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>.
</div>
<div class="section" id="parents">
<h3>15.4.2.5. parents<a class="headerlink" href="#parents" title="Permalink to this headline">¶</a></h3>
Sometimes, several parsers share a common set of arguments. Rather than
repeating the definitions of these arguments, a single parser with all the
shared arguments and passed to <code class="docutils literal notranslate">parents=</code> argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>
can be used. The <code class="docutils literal notranslate">parents=</code> argument takes a list of <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>
objects, collects all the positional and optional actions from them, and adds
these actions to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> object being constructed:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parent_parser = argparse.ArgumentParser(add_help=False)
&gt;&gt;&gt; parent_parser.add_argument(&#39;--parent&#39;, type=int)

&gt;&gt;&gt; foo_parser = argparse.ArgumentParser(parents=[parent_parser])
&gt;&gt;&gt; foo_parser.add_argument(&#39;foo&#39;)
&gt;&gt;&gt; foo_parser.parse_args([&#39;--parent&#39;, &#39;2&#39;, &#39;XXX&#39;])
Namespace(foo=&#39;XXX&#39;, parent=2)

&gt;&gt;&gt; bar_parser = argparse.ArgumentParser(parents=[parent_parser])
&gt;&gt;&gt; bar_parser.add_argument(&#39;--bar&#39;)
&gt;&gt;&gt; bar_parser.parse_args([&#39;--bar&#39;, &#39;YYY&#39;])
Namespace(bar=&#39;YYY&#39;, parent=None)
</pre></div>
</div>
Note that most parent parsers will specify <code class="docutils literal notranslate">add_help=False</code>. Otherwise, the
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> will see two <code class="docutils literal notranslate">-h/--help</code> options (one in the parent
and one in the child) and raise an error.
<div class="admonition note">
Note
You must fully initialize the parsers before passing them via <code class="docutils literal notranslate">parents=</code>.
If you change the parent parsers after the child parser, those changes will
not be reflected in the child.
</div>
</div>
<div class="section" id="formatter-class">
<h3>15.4.2.6. formatter_class<a class="headerlink" href="#formatter-class" title="Permalink to this headline">¶</a></h3>
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects allow the help formatting to be customized by
specifying an alternate formatting class. Currently, there are three such
classes:
<dl class="class">
<dt id="argparse.RawDescriptionHelpFormatter">
class <code class="descclassname">argparse.</code><code class="descname">RawDescriptionHelpFormatter</code><a class="headerlink" href="#argparse.RawDescriptionHelpFormatter" title="Permalink to this definition">¶</a></dt>
<dt id="argparse.RawTextHelpFormatter">
class <code class="descclassname">argparse.</code><code class="descname">RawTextHelpFormatter</code><a class="headerlink" href="#argparse.RawTextHelpFormatter" title="Permalink to this definition">¶</a></dt>
<dt id="argparse.ArgumentDefaultsHelpFormatter">
class <code class="descclassname">argparse.</code><code class="descname">ArgumentDefaultsHelpFormatter</code><a class="headerlink" href="#argparse.ArgumentDefaultsHelpFormatter" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

The first two allow more control over how textual descriptions are displayed,
while the last automatically adds information about argument default values.
By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects line-wrap the <a class="reference internal" href="#description">description</a> and
<a class="reference internal" href="#epilog">epilog</a> texts in command-line help messages:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(
... prog=&#39;PROG&#39;,
... description=&#39;&#39;&#39;this description
... was indented weird
... but that is okay&#39;&#39;&#39;,
... epilog=&#39;&#39;&#39;
... likewise for this epilog whose whitespace will
... be cleaned up and whose words will be wrapped
... across a couple lines&#39;&#39;&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h]

this description was indented weird but that is okay

optional arguments:
 -h, --help show this help message and exit

likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
</pre></div>
</div>
Passing <a class="reference internal" href="#argparse.RawDescriptionHelpFormatter" title="argparse.RawDescriptionHelpFormatter"><code class="xref py py-class docutils literal notranslate">RawDescriptionHelpFormatter</code></a> as <code class="docutils literal notranslate">formatter_class=</code>
indicates that <a class="reference internal" href="#description">description</a> and <a class="reference internal" href="#epilog">epilog</a> are already correctly formatted and
should not be line-wrapped:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(
... prog=&#39;PROG&#39;,
... formatter_class=argparse.RawDescriptionHelpFormatter,
... description=textwrap.dedent(&#39;&#39;&#39;\
... Please do not mess up this text!
... --------------------------------
... I have indented it
... exactly the way
... I want it
... &#39;&#39;&#39;))
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h]

Please do not mess up this text!
--------------------------------
 I have indented it
 exactly the way
 I want it

optional arguments:
 -h, --help show this help message and exit
</pre></div>
</div>
<a class="reference internal" href="#argparse.RawTextHelpFormatter" title="argparse.RawTextHelpFormatter"><code class="xref py py-class docutils literal notranslate">RawTextHelpFormatter</code></a> maintains whitespace for all sorts of help text,
including argument descriptions. However, multiple new lines are replaced with
one. If you wish to preserve multiple blank lines, add spaces between the
newlines.
The other formatter class available, <a class="reference internal" href="#argparse.ArgumentDefaultsHelpFormatter" title="argparse.ArgumentDefaultsHelpFormatter"><code class="xref py py-class docutils literal notranslate">ArgumentDefaultsHelpFormatter</code></a>,
will add information about the default value of each of the arguments:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(
... prog=&#39;PROG&#39;,
... formatter_class=argparse.ArgumentDefaultsHelpFormatter)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, type=int, default=42, help=&#39;FOO!&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;*&#39;, default=[1, 2, 3], help=&#39;BAR!&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h] [--foo FOO] [bar [bar ...]]

positional arguments:
 bar BAR! (default: [1, 2, 3])

optional arguments:
 -h, --help show this help message and exit
 --foo FOO FOO! (default: 42)
</pre></div>
</div>
</div>
<div class="section" id="prefix-chars">
<h3>15.4.2.7. prefix_chars<a class="headerlink" href="#prefix-chars" title="Permalink to this headline">¶</a></h3>
Most command-line options will use <code class="docutils literal notranslate">-</code> as the prefix, e.g. <code class="docutils literal notranslate">-f/--foo</code>.
Parsers that need to support different or additional prefix
characters, e.g. for options
like <code class="docutils literal notranslate">+f</code> or <code class="docutils literal notranslate">/foo</code>, may specify them using the <code class="docutils literal notranslate">prefix_chars=</code> argument
to the ArgumentParser constructor:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, prefix_chars=&#39;-+&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;+f&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;++bar&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;+f X ++bar Y&#39;.split())
Namespace(bar=&#39;Y&#39;, f=&#39;X&#39;)
</pre></div>
</div>
The <code class="docutils literal notranslate">prefix_chars=</code> argument defaults to <code class="docutils literal notranslate">'-'</code>. Supplying a set of
characters that does not include <code class="docutils literal notranslate">-</code> will cause <code class="docutils literal notranslate">-f/--foo</code> options to be
disallowed.
</div>
<div class="section" id="fromfile-prefix-chars">
<h3>15.4.2.8. fromfile_prefix_chars<a class="headerlink" href="#fromfile-prefix-chars" title="Permalink to this headline">¶</a></h3>
Sometimes, for example when dealing with a particularly long argument lists, it
may make sense to keep the list of arguments in a file rather than typing it out
at the command line. If the <code class="docutils literal notranslate">fromfile_prefix_chars=</code> argument is given to the
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> constructor, then arguments that start with any of the
specified characters will be treated as files, and will be replaced by the
arguments they contain. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; with open(&#39;args.txt&#39;, &#39;w&#39;) as fp:
... fp.write(&#39;-f\nbar&#39;)
&gt;&gt;&gt; parser = argparse.ArgumentParser(fromfile_prefix_chars=&#39;@&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-f&#39;, &#39;foo&#39;, &#39;@args.txt&#39;])
Namespace(f=&#39;bar&#39;)
</pre></div>
</div>
Arguments read from a file must by default be one per line (but see also
<a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate">convert_arg_line_to_args()</code></a>) and are treated as if they
were in the same place as the original file referencing argument on the command
line. So in the example above, the expression <code class="docutils literal notranslate">['-f', 'foo', '&#64;args.txt']</code>
is considered equivalent to the expression <code class="docutils literal notranslate">['-f', 'foo', '-f', 'bar']</code>.
The <code class="docutils literal notranslate">fromfile_prefix_chars=</code> argument defaults to <code class="docutils literal notranslate">None</code>, meaning that
arguments will never be treated as file references.
</div>
<div class="section" id="argument-default">
<h3>15.4.2.9. argument_default<a class="headerlink" href="#argument-default" title="Permalink to this headline">¶</a></h3>
Generally, argument defaults are specified either by passing a default to
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> or by calling the
<a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate">set_defaults()</code></a> methods with a specific set of name-value
pairs. Sometimes however, it may be useful to specify a single parser-wide
default for arguments. This can be accomplished by passing the
<code class="docutils literal notranslate">argument_default=</code> keyword argument to <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>. For example,
to globally suppress attribute creation on <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>
calls, we supply <code class="docutils literal notranslate">argument_default=SUPPRESS</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;?&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;1&#39;, &#39;BAR&#39;])
Namespace(bar=&#39;BAR&#39;, foo=&#39;1&#39;)
&gt;&gt;&gt; parser.parse_args([])
Namespace()
</pre></div>
</div>
</div>
<div class="section" id="conflict-handler">
<h3>15.4.2.10. conflict_handler<a class="headerlink" href="#conflict-handler" title="Permalink to this headline">¶</a></h3>
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects do not allow two actions with the same option
string. By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects raise an exception if an
attempt is made to create an argument with an option string that is already in
use:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;, &#39;--foo&#39;, help=&#39;old foo help&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, help=&#39;new foo help&#39;)
Traceback (most recent call last):
 ..
ArgumentError: argument --foo: conflicting option string(s): --foo
</pre></div>
</div>
Sometimes (e.g. when using <a class="reference internal" href="#parents">parents</a>) it may be useful to simply override any
older arguments with the same option string. To get this behavior, the value
<code class="docutils literal notranslate">'resolve'</code> can be supplied to the <code class="docutils literal notranslate">conflict_handler=</code> argument of
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, conflict_handler=&#39;resolve&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;, &#39;--foo&#39;, help=&#39;old foo help&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, help=&#39;new foo help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h] [-f FOO] [--foo FOO]

optional arguments:
 -h, --help show this help message and exit
 -f FOO old foo help
 --foo FOO new foo help
</pre></div>
</div>
Note that <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects only remove an action if all of its
option strings are overridden. So, in the example above, the old <code class="docutils literal notranslate">-f/--foo</code>
action is retained as the <code class="docutils literal notranslate">-f</code> action, because only the <code class="docutils literal notranslate">--foo</code> option
string was overridden.
</div>
<div class="section" id="add-help">
<h3>15.4.2.11. add_help<a class="headerlink" href="#add-help" title="Permalink to this headline">¶</a></h3>
By default, ArgumentParser objects add an option which simply displays
the parser’s help message. For example, consider a file named
<code class="docutils literal notranslate">myprogram.py</code> containing the following code:
<div class="highlight-default notranslate"><div class="highlight"><pre>import argparse
parser = argparse.ArgumentParser()
parser.add_argument(&#39;--foo&#39;, help=&#39;foo help&#39;)
args = parser.parse_args()
</pre></div>
</div>
If <code class="docutils literal notranslate">-h</code> or <code class="docutils literal notranslate">--help</code> is supplied at the command line, the ArgumentParser
help will be printed:
<div class="highlight-shell-session notranslate"><div class="highlight"><pre>$ python myprogram.py --help
usage: myprogram.py [-h] [--foo FOO]

optional arguments:
 -h, --help show this help message and exit
 --foo FOO foo help
</pre></div>
</div>
Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing <code class="docutils literal notranslate">False</code> as the <code class="docutils literal notranslate">add_help=</code> argument to
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, add_help=False)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [--foo FOO]

optional arguments:
 --foo FOO foo help
</pre></div>
</div>
The help option is typically <code class="docutils literal notranslate">-h/--help</code>. The exception to this is
if the <code class="docutils literal notranslate">prefix_chars=</code> is specified and does not include <code class="docutils literal notranslate">-</code>, in
which case <code class="docutils literal notranslate">-h</code> and <code class="docutils literal notranslate">--help</code> are not valid options. In
this case, the first character in <code class="docutils literal notranslate">prefix_chars</code> is used to prefix
the help options:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, prefix_chars=&#39;+/&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [+h]

optional arguments:
 +h, ++help show this help message and exit
</pre></div>
</div>
</div>
</div>
<div class="section" id="the-add-argument-method">
<h2>15.4.3. The add_argument() method<a class="headerlink" href="#the-add-argument-method" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="argparse.ArgumentParser.add_argument">
<code class="descclassname">ArgumentParser.</code><code class="descname">add_argument</code>(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])<a class="headerlink" href="#argparse.ArgumentParser.add_argument" title="Permalink to this definition">¶</a></dt>
<dd>Define how a single command-line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are:
<ul class="simple">
<li><a class="reference internal" href="#name-or-flags">name or flags</a> - Either a name or a list of option strings, e.g. <code class="docutils literal notranslate">foo</code>
or <code class="docutils literal notranslate">-f, --foo</code>.</li>
<li><a class="reference internal" href="#action">action</a> - The basic type of action to be taken when this argument is
encountered at the command line.</li>
<li><a class="reference internal" href="#nargs">nargs</a> - The number of command-line arguments that should be consumed.</li>
<li><a class="reference internal" href="#const">const</a> - A constant value required by some <a class="reference internal" href="#action">action</a> and <a class="reference internal" href="#nargs">nargs</a> selections.</li>
<li><a class="reference internal" href="#default">default</a> - The value produced if the argument is absent from the
command line.</li>
<li><a class="reference internal" href="#type">type</a> - The type to which the command-line argument should be converted.</li>
<li><a class="reference internal" href="#choices">choices</a> - A container of the allowable values for the argument.</li>
<li><a class="reference internal" href="#required">required</a> - Whether or not the command-line option may be omitted
(optionals only).</li>
<li><a class="reference internal" href="#help">help</a> - A brief description of what the argument does.</li>
<li><a class="reference internal" href="#metavar">metavar</a> - A name for the argument in usage messages.</li>
<li><a class="reference internal" href="#dest">dest</a> - The name of the attribute to be added to the object returned by
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>.</li>
</ul>
</dd></dl>

The following sections describe how each of these are used.
<div class="section" id="name-or-flags">
<h3>15.4.3.1. name or flags<a class="headerlink" href="#name-or-flags" title="Permalink to this headline">¶</a></h3>
The <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> method must know whether an optional
argument, like <code class="docutils literal notranslate">-f</code> or <code class="docutils literal notranslate">--foo</code>, or a positional argument, like a list of
filenames, is expected. The first arguments passed to
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> must therefore be either a series of
flags, or a simple argument name. For example, an optional argument could
be created like:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;, &#39;--foo&#39;)
</pre></div>
</div>
while a positional argument could be created like:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;)
</pre></div>
</div>
When <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> is called, optional arguments will be
identified by the <code class="docutils literal notranslate">-</code> prefix, and the remaining arguments will be assumed to
be positional:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;, &#39;--foo&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;BAR&#39;])
Namespace(bar=&#39;BAR&#39;, foo=None)
&gt;&gt;&gt; parser.parse_args([&#39;BAR&#39;, &#39;--foo&#39;, &#39;FOO&#39;])
Namespace(bar=&#39;BAR&#39;, foo=&#39;FOO&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;FOO&#39;])
usage: PROG [-h] [-f FOO] bar
PROG: error: too few arguments
</pre></div>
</div>
</div>
<div class="section" id="action">
<h3>15.4.3.2. action<a class="headerlink" href="#action" title="Permalink to this headline">¶</a></h3>
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects associate command-line arguments with actions. These
actions can do just about anything with the command-line arguments associated with
them, though most actions simply add an attribute to the object returned by
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>. The <code class="docutils literal notranslate">action</code> keyword argument specifies
how the command-line arguments should be handled. The supplied actions are:
<ul>
<li><code class="docutils literal notranslate">'store'</code> - This just stores the argument’s value. This is the default
action. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;--foo 1&#39;.split())
Namespace(foo=&#39;1&#39;)
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'store_const'</code> - This stores the value specified by the <a class="reference internal" href="#const">const</a> keyword
argument. The <code class="docutils literal notranslate">'store_const'</code> action is most commonly used with
optional arguments that specify some sort of flag. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;store_const&#39;, const=42)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;])
Namespace(foo=42)
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'store_true'</code> and <code class="docutils literal notranslate">'store_false'</code> - These are special cases of
<code class="docutils literal notranslate">'store_const'</code> using for storing the values <code class="docutils literal notranslate">True</code> and <code class="docutils literal notranslate">False</code>
respectively. In addition, they create default values of <code class="docutils literal notranslate">False</code> and <code class="docutils literal notranslate">True</code>
respectively. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--bar&#39;, action=&#39;store_false&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--baz&#39;, action=&#39;store_false&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;--foo --bar&#39;.split())
Namespace(bar=False, baz=True, foo=True)
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'append'</code> - This stores a list, and appends each argument value to the
list. This is useful to allow an option to be specified multiple times.
Example usage:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;append&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;--foo 1 --foo 2&#39;.split())
Namespace(foo=[&#39;1&#39;, &#39;2&#39;])
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'append_const'</code> - This stores a list, and appends the value specified by
the <a class="reference internal" href="#const">const</a> keyword argument to the list. (Note that the <a class="reference internal" href="#const">const</a> keyword
argument defaults to <code class="docutils literal notranslate">None</code>.) The <code class="docutils literal notranslate">'append_const'</code> action is typically
useful when multiple arguments need to store constants to the same list. For
example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--str&#39;, dest=&#39;types&#39;, action=&#39;append_const&#39;, const=str)
&gt;&gt;&gt; parser.add_argument(&#39;--int&#39;, dest=&#39;types&#39;, action=&#39;append_const&#39;, const=int)
&gt;&gt;&gt; parser.parse_args(&#39;--str --int&#39;.split())
Namespace(types=[&lt;type &#39;str&#39;&gt;, &lt;type &#39;int&#39;&gt;])
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'count'</code> - This counts the number of times a keyword argument occurs. For
example, this is useful for increasing verbosity levels:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--verbose&#39;, &#39;-v&#39;, action=&#39;count&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-vvv&#39;])
Namespace(verbose=3)
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'help'</code> - This prints a complete help message for all the options in the
current parser and then exits. By default a help action is automatically
added to the parser. See <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> for details of how the
output is created.
</li>
<li><code class="docutils literal notranslate">'version'</code> - This expects a <code class="docutils literal notranslate">version=</code> keyword argument in the
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> call, and prints version information
and exits when invoked:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; import argparse
&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--version&#39;, action=&#39;version&#39;, version=&#39;%(prog)s 2.0&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;--version&#39;])
PROG 2.0
</pre></div>
</div>
</li>
</ul>
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The recommended way to do
this is to extend <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate">Action</code></a>, overriding the <code class="docutils literal notranslate">__call__</code> method
and optionally the <code class="docutils literal notranslate">__init__</code> method.
An example of a custom action:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; class FooAction(argparse.Action):
... def __init__(self, option_strings, dest, nargs=None, **kwargs):
... if nargs is not None:
... raise ValueError(&quot;nargs not allowed&quot;)
... super(FooAction, self).__init__(option_strings, dest, **kwargs)
... def __call__(self, parser, namespace, values, option_string=None):
... print &#39;%r %r %r&#39; % (namespace, values, option_string)
... setattr(namespace, self.dest, values)
...
&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=FooAction)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, action=FooAction)
&gt;&gt;&gt; args = parser.parse_args(&#39;1 --foo 2&#39;.split())
Namespace(bar=None, foo=None) &#39;1&#39; None
Namespace(bar=&#39;1&#39;, foo=None) &#39;2&#39; &#39;--foo&#39;
&gt;&gt;&gt; args
Namespace(bar=&#39;1&#39;, foo=&#39;2&#39;)
</pre></div>
</div>
For more details, see <a class="reference internal" href="#argparse.Action" title="argparse.Action"><code class="xref py py-class docutils literal notranslate">Action</code></a>.
</div>
<div class="section" id="nargs">
<h3>15.4.3.3. nargs<a class="headerlink" href="#nargs" title="Permalink to this headline">¶</a></h3>
ArgumentParser objects usually associate a single command-line argument with a
single action to be taken. The <code class="docutils literal notranslate">nargs</code> keyword argument associates a
different number of command-line arguments with a single action. The supported
values are:
<ul>
<li><code class="docutils literal notranslate">N</code> (an integer). <code class="docutils literal notranslate">N</code> arguments from the command line will be gathered
together into a list. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=2)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=1)
&gt;&gt;&gt; parser.parse_args(&#39;c --foo a b&#39;.split())
Namespace(bar=[&#39;c&#39;], foo=[&#39;a&#39;, &#39;b&#39;])
</pre></div>
</div>
Note that <code class="docutils literal notranslate">nargs=1</code> produces a list of one item. This is different from
the default, in which the item is produced by itself.
</li>
<li><code class="docutils literal notranslate">'?'</code>. One argument will be consumed from the command line if possible, and
produced as a single item. If no command-line argument is present, the value from
<a class="reference internal" href="#default">default</a> will be produced. Note that for optional arguments, there is an
additional case - the option string is present but not followed by a
command-line argument. In this case the value from <a class="reference internal" href="#const">const</a> will be produced. Some
examples to illustrate this:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=&#39;?&#39;, const=&#39;c&#39;, default=&#39;d&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;?&#39;, default=&#39;d&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;XX&#39;, &#39;--foo&#39;, &#39;YY&#39;])
Namespace(bar=&#39;XX&#39;, foo=&#39;YY&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;XX&#39;, &#39;--foo&#39;])
Namespace(bar=&#39;XX&#39;, foo=&#39;c&#39;)
&gt;&gt;&gt; parser.parse_args([])
Namespace(bar=&#39;d&#39;, foo=&#39;d&#39;)
</pre></div>
</div>
One of the more common uses of <code class="docutils literal notranslate">nargs='?'</code> is to allow optional input and
output files:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;infile&#39;, nargs=&#39;?&#39;, type=argparse.FileType(&#39;r&#39;),
... default=sys.stdin)
&gt;&gt;&gt; parser.add_argument(&#39;outfile&#39;, nargs=&#39;?&#39;, type=argparse.FileType(&#39;w&#39;),
... default=sys.stdout)
&gt;&gt;&gt; parser.parse_args([&#39;input.txt&#39;, &#39;output.txt&#39;])
Namespace(infile=&lt;open file &#39;input.txt&#39;, mode &#39;r&#39; at 0x...&gt;,
 outfile=&lt;open file &#39;output.txt&#39;, mode &#39;w&#39; at 0x...&gt;)
&gt;&gt;&gt; parser.parse_args([])
Namespace(infile=&lt;open file &#39;&lt;stdin&gt;&#39;, mode &#39;r&#39; at 0x...&gt;,
 outfile=&lt;open file &#39;&lt;stdout&gt;&#39;, mode &#39;w&#39; at 0x...&gt;)
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'*'</code>. All command-line arguments present are gathered into a list. Note that
it generally doesn’t make much sense to have more than one positional argument
with <code class="docutils literal notranslate">nargs='*'</code>, but multiple optional arguments with <code class="docutils literal notranslate">nargs='*'</code> is
possible. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=&#39;*&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--bar&#39;, nargs=&#39;*&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;baz&#39;, nargs=&#39;*&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;a b --foo x y --bar 1 2&#39;.split())
Namespace(bar=[&#39;1&#39;, &#39;2&#39;], baz=[&#39;a&#39;, &#39;b&#39;], foo=[&#39;x&#39;, &#39;y&#39;])
</pre></div>
</div>
</li>
<li><code class="docutils literal notranslate">'+'</code>. Just like <code class="docutils literal notranslate">'*'</code>, all command-line args present are gathered into a
list. Additionally, an error message will be generated if there wasn’t at
least one command-line argument present. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, nargs=&#39;+&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;a&#39;, &#39;b&#39;])
Namespace(foo=[&#39;a&#39;, &#39;b&#39;])
&gt;&gt;&gt; parser.parse_args([])
usage: PROG [-h] foo [foo ...]
PROG: error: too few arguments
</pre></div>
</div>
</li>
</ul>
<ul id="argparse-remainder">
<li><code class="docutils literal notranslate">argparse.REMAINDER</code>. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
to other command line utilities:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;command&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;args&#39;, nargs=argparse.REMAINDER)
&gt;&gt;&gt; print parser.parse_args(&#39;--foo B cmd --arg1 XX ZZ&#39;.split())
Namespace(args=[&#39;--arg1&#39;, &#39;XX&#39;, &#39;ZZ&#39;], command=&#39;cmd&#39;, foo=&#39;B&#39;)
</pre></div>
</div>
</li>
</ul>
If the <code class="docutils literal notranslate">nargs</code> keyword argument is not provided, the number of arguments consumed
is determined by the <a class="reference internal" href="#action">action</a>. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
</div>
<div class="section" id="const">
<h3>15.4.3.4. const<a class="headerlink" href="#const" title="Permalink to this headline">¶</a></h3>
The <code class="docutils literal notranslate">const</code> argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> is used to hold
constant values that are not read from the command line but are required for
the various <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> actions. The two most common uses of it are:
<ul class="simple">
<li>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> is called with
<code class="docutils literal notranslate">action='store_const'</code> or <code class="docutils literal notranslate">action='append_const'</code>. These actions add the
<code class="docutils literal notranslate">const</code> value to one of the attributes of the object returned by
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>. See the <a class="reference internal" href="#action">action</a> description for examples.</li>
<li>When <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> is called with option strings
(like <code class="docutils literal notranslate">-f</code> or <code class="docutils literal notranslate">--foo</code>) and <code class="docutils literal notranslate">nargs='?'</code>. This creates an optional
argument that can be followed by zero or one command-line arguments.
When parsing the command line, if the option string is encountered with no
command-line argument following it, the value of <code class="docutils literal notranslate">const</code> will be assumed instead.
See the <a class="reference internal" href="#nargs">nargs</a> description for examples.</li>
</ul>
With the <code class="docutils literal notranslate">'store_const'</code> and <code class="docutils literal notranslate">'append_const'</code> actions, the <code class="docutils literal notranslate">const</code>
keyword argument must be given. For other actions, it defaults to <code class="docutils literal notranslate">None</code>.
</div>
<div class="section" id="default">
<h3>15.4.3.5. default<a class="headerlink" href="#default" title="Permalink to this headline">¶</a></h3>
All optional arguments and some positional arguments may be omitted at the
command line. The <code class="docutils literal notranslate">default</code> keyword argument of
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>, whose value defaults to <code class="docutils literal notranslate">None</code>,
specifies what value should be used if the command-line argument is not present.
For optional arguments, the <code class="docutils literal notranslate">default</code> value is used when the option string
was not present at the command line:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, default=42)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;2&#39;])
Namespace(foo=&#39;2&#39;)
&gt;&gt;&gt; parser.parse_args([])
Namespace(foo=42)
</pre></div>
</div>
If the <code class="docutils literal notranslate">default</code> value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any <a class="reference internal" href="#type">type</a>
conversion argument, if provided, before setting the attribute on the
<a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> return value. Otherwise, the parser uses the value as is:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--length&#39;, default=&#39;10&#39;, type=int)
&gt;&gt;&gt; parser.add_argument(&#39;--width&#39;, default=10.5, type=int)
&gt;&gt;&gt; parser.parse_args()
Namespace(length=10, width=10.5)
</pre></div>
</div>
For positional arguments with <a class="reference internal" href="#nargs">nargs</a> equal to <code class="docutils literal notranslate">?</code> or <code class="docutils literal notranslate">*</code>, the <code class="docutils literal notranslate">default</code> value
is used when no command-line argument was present:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, nargs=&#39;?&#39;, default=42)
&gt;&gt;&gt; parser.parse_args([&#39;a&#39;])
Namespace(foo=&#39;a&#39;)
&gt;&gt;&gt; parser.parse_args([])
Namespace(foo=42)
</pre></div>
</div>
Providing <code class="docutils literal notranslate">default=argparse.SUPPRESS</code> causes no attribute to be added if the
command-line argument was not present.:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, default=argparse.SUPPRESS)
&gt;&gt;&gt; parser.parse_args([])
Namespace()
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;1&#39;])
Namespace(foo=&#39;1&#39;)
</pre></div>
</div>
</div>
<div class="section" id="type">
<h3>15.4.3.6. type<a class="headerlink" href="#type" title="Permalink to this headline">¶</a></h3>
By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> objects read command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, like a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal notranslate">float</code></a> or <a class="reference internal" href="functions.html#int" title="int"><code class="xref py py-class docutils literal notranslate">int</code></a>. The
<code class="docutils literal notranslate">type</code> keyword argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> allows any
necessary type-checking and type conversions to be performed. Common built-in
types and functions can be used directly as the value of the <code class="docutils literal notranslate">type</code> argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, type=int)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, type=file)
&gt;&gt;&gt; parser.parse_args(&#39;2 temp.txt&#39;.split())
Namespace(bar=&lt;open file &#39;temp.txt&#39;, mode &#39;r&#39; at 0x...&gt;, foo=2)
</pre></div>
</div>
See the section on the <a class="reference internal" href="#default">default</a> keyword argument for information on when the
<code class="docutils literal notranslate">type</code> argument is applied to default arguments.
To ease the use of various types of files, the argparse module provides the
factory FileType which takes the <code class="docutils literal notranslate">mode=</code> and <code class="docutils literal notranslate">bufsize=</code> arguments of the
<code class="docutils literal notranslate">file</code> object. For example, <code class="docutils literal notranslate">FileType('w')</code> can be used to create a
writable file:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, type=argparse.FileType(&#39;w&#39;))
&gt;&gt;&gt; parser.parse_args([&#39;out.txt&#39;])
Namespace(bar=&lt;open file &#39;out.txt&#39;, mode &#39;w&#39; at 0x...&gt;)
</pre></div>
</div>
<code class="docutils literal notranslate">type=</code> can take any callable that takes a single string argument and returns
the converted value:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; def perfect_square(string):
... value = int(string)
... sqrt = math.sqrt(value)
... if sqrt != int(sqrt):
... msg = &quot;%r is not a perfect square&quot; % string
... raise argparse.ArgumentTypeError(msg)
... return value
...
&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, type=perfect_square)
&gt;&gt;&gt; parser.parse_args([&#39;9&#39;])
Namespace(foo=9)
&gt;&gt;&gt; parser.parse_args([&#39;7&#39;])
usage: PROG [-h] foo
PROG: error: argument foo: &#39;7&#39; is not a perfect square
</pre></div>
</div>
The <a class="reference internal" href="#choices">choices</a> keyword argument may be more convenient for type checkers that
simply check against a range of values:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, type=int, choices=xrange(5, 10))
&gt;&gt;&gt; parser.parse_args([&#39;7&#39;])
Namespace(foo=7)
&gt;&gt;&gt; parser.parse_args([&#39;11&#39;])
usage: PROG [-h] {5,6,7,8,9}
PROG: error: argument foo: invalid choice: 11 (choose from 5, 6, 7, 8, 9)
</pre></div>
</div>
See the <a class="reference internal" href="#choices">choices</a> section for more details.
</div>
<div class="section" id="choices">
<h3>15.4.3.7. choices<a class="headerlink" href="#choices" title="Permalink to this headline">¶</a></h3>
Some command-line arguments should be selected from a restricted set of values.
These can be handled by passing a container object as the choices keyword
argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>. When the command line is
parsed, argument values will be checked, and an error message will be displayed
if the argument was not one of the acceptable values:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;game.py&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;move&#39;, choices=[&#39;rock&#39;, &#39;paper&#39;, &#39;scissors&#39;])
&gt;&gt;&gt; parser.parse_args([&#39;rock&#39;])
Namespace(move=&#39;rock&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;fire&#39;])
usage: game.py [-h] {rock,paper,scissors}
game.py: error: argument move: invalid choice: &#39;fire&#39; (choose from &#39;rock&#39;,
&#39;paper&#39;, &#39;scissors&#39;)
</pre></div>
</div>
Note that inclusion in the choices container is checked after any <a class="reference internal" href="#type">type</a>
conversions have been performed, so the type of the objects in the choices
container should match the <a class="reference internal" href="#type">type</a> specified:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;doors.py&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;door&#39;, type=int, choices=range(1, 4))
&gt;&gt;&gt; print(parser.parse_args([&#39;3&#39;]))
Namespace(door=3)
&gt;&gt;&gt; parser.parse_args([&#39;4&#39;])
usage: doors.py [-h] {1,2,3}
doors.py: error: argument door: invalid choice: 4 (choose from 1, 2, 3)
</pre></div>
</div>
Any object that supports the <code class="docutils literal notranslate">in</code> operator can be passed as the choices
value, so <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal notranslate">dict</code></a> objects, <a class="reference internal" href="stdtypes.html#set" title="set"><code class="xref py py-class docutils literal notranslate">set</code></a> objects, custom containers,
etc. are all supported.
</div>
<div class="section" id="required">
<h3>15.4.3.8. required<a class="headerlink" href="#required" title="Permalink to this headline">¶</a></h3>
In general, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> module assumes that flags like <code class="docutils literal notranslate">-f</code> and <code class="docutils literal notranslate">--bar</code>
indicate optional arguments, which can always be omitted at the command line.
To make an option required, <code class="docutils literal notranslate">True</code> can be specified for the <code class="docutils literal notranslate">required=</code>
keyword argument to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, required=True)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;BAR&#39;])
Namespace(foo=&#39;BAR&#39;)
&gt;&gt;&gt; parser.parse_args([])
usage: argparse.py [-h] [--foo FOO]
argparse.py: error: option --foo is required
</pre></div>
</div>
As the example shows, if an option is marked as <code class="docutils literal notranslate">required</code>,
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> will report an error if that option is not
present at the command line.
<div class="admonition note">
Note
Required options are generally considered bad form because users expect
options to be optional, and thus they should be avoided when possible.
</div>
</div>
<div class="section" id="help">
<h3>15.4.3.9. help<a class="headerlink" href="#help" title="Permalink to this headline">¶</a></h3>
The <code class="docutils literal notranslate">help</code> value is a string containing a brief description of the argument.
When a user requests help (usually by using <code class="docutils literal notranslate">-h</code> or <code class="docutils literal notranslate">--help</code> at the
command line), these <code class="docutils literal notranslate">help</code> descriptions will be displayed with each
argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;frobble&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;,
... help=&#39;foo the bars before frobbling&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;+&#39;,
... help=&#39;one of the bars to be frobbled&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-h&#39;])
usage: frobble [-h] [--foo] bar [bar ...]

positional arguments:
 bar one of the bars to be frobbled

optional arguments:
 -h, --help show this help message and exit
 --foo foo the bars before frobbling
</pre></div>
</div>
The <code class="docutils literal notranslate">help</code> strings can include various format specifiers to avoid repetition
of things like the program name or the argument <a class="reference internal" href="#default">default</a>. The available
specifiers include the program name, <code class="docutils literal notranslate">%(prog)s</code> and most keyword arguments to
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>, e.g. <code class="docutils literal notranslate">%(default)s</code>, <code class="docutils literal notranslate">%(type)s</code>, etc.:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;frobble&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;?&#39;, type=int, default=42,
... help=&#39;the bar to %(prog)s (default: %(default)s)&#39;)
&gt;&gt;&gt; parser.print_help()
usage: frobble [-h] [bar]

positional arguments:
 bar the bar to frobble (default: 42)

optional arguments:
 -h, --help show this help message and exit
</pre></div>
</div>
</div>
<div class="section" id="metavar">
<h3>15.4.3.10. metavar<a class="headerlink" href="#metavar" title="Permalink to this headline">¶</a></h3>
When <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> generates help messages, it needs some way to refer
to each expected argument. By default, ArgumentParser objects use the <a class="reference internal" href="#dest">dest</a>
value as the “name” of each object. By default, for positional argument
actions, the <a class="reference internal" href="#dest">dest</a> value is used directly, and for optional argument actions,
the <a class="reference internal" href="#dest">dest</a> value is uppercased. So, a single positional argument with
<code class="docutils literal notranslate">dest='bar'</code> will be referred to as <code class="docutils literal notranslate">bar</code>. A single
optional argument <code class="docutils literal notranslate">--foo</code> that should be followed by a single command-line argument
will be referred to as <code class="docutils literal notranslate">FOO</code>. An example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;X --foo Y&#39;.split())
Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)
&gt;&gt;&gt; parser.print_help()
usage: [-h] [--foo FOO] bar

positional arguments:
 bar

optional arguments:
 -h, --help show this help message and exit
 --foo FOO
</pre></div>
</div>
An alternative name can be specified with <code class="docutils literal notranslate">metavar</code>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, metavar=&#39;YYY&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, metavar=&#39;XXX&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;X --foo Y&#39;.split())
Namespace(bar=&#39;X&#39;, foo=&#39;Y&#39;)
&gt;&gt;&gt; parser.print_help()
usage: [-h] [--foo YYY] XXX

positional arguments:
 XXX

optional arguments:
 -h, --help show this help message and exit
 --foo YYY
</pre></div>
</div>
Note that <code class="docutils literal notranslate">metavar</code> only changes the displayed name - the name of the
attribute on the <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> object is still determined
by the <a class="reference internal" href="#dest">dest</a> value.
Different values of <code class="docutils literal notranslate">nargs</code> may cause the metavar to be used multiple times.
Providing a tuple to <code class="docutils literal notranslate">metavar</code> specifies a different display for each of the
arguments:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-x&#39;, nargs=2)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, nargs=2, metavar=(&#39;bar&#39;, &#39;baz&#39;))
&gt;&gt;&gt; parser.print_help()
usage: PROG [-h] [-x X X] [--foo bar baz]

optional arguments:
 -h, --help show this help message and exit
 -x X X
 --foo bar baz
</pre></div>
</div>
</div>
<div class="section" id="dest">
<h3>15.4.3.11. dest<a class="headerlink" href="#dest" title="Permalink to this headline">¶</a></h3>
Most <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> actions add some value as an attribute of the
object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>. The name of this
attribute is determined by the <code class="docutils literal notranslate">dest</code> keyword argument of
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>. For positional argument actions,
<code class="docutils literal notranslate">dest</code> is normally supplied as the first argument to
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;XXX&#39;])
Namespace(bar=&#39;XXX&#39;)
</pre></div>
</div>
For optional argument actions, the value of <code class="docutils literal notranslate">dest</code> is normally inferred from
the option strings. <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> generates the value of <code class="docutils literal notranslate">dest</code> by
taking the first long option string and stripping away the initial <code class="docutils literal notranslate">--</code>
string. If no long option strings were supplied, <code class="docutils literal notranslate">dest</code> will be derived from
the first short option string by stripping the initial <code class="docutils literal notranslate">-</code> character. Any
internal <code class="docutils literal notranslate">-</code> characters will be converted to <code class="docutils literal notranslate">_</code> characters to make sure
the string is a valid attribute name. The examples below illustrate this
behavior:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;-f&#39;, &#39;--foo-bar&#39;, &#39;--foo&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-x&#39;, &#39;-y&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;-f 1 -x 2&#39;.split())
Namespace(foo_bar=&#39;1&#39;, x=&#39;2&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;--foo 1 -y 2&#39;.split())
Namespace(foo_bar=&#39;1&#39;, x=&#39;2&#39;)
</pre></div>
</div>
<code class="docutils literal notranslate">dest</code> allows a custom attribute name to be provided:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, dest=&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;--foo XXX&#39;.split())
Namespace(bar=&#39;XXX&#39;)
</pre></div>
</div>
</div>
<div class="section" id="action-classes">
<h3>15.4.3.12. Action classes<a class="headerlink" href="#action-classes" title="Permalink to this headline">¶</a></h3>
Action classes implement the Action API, a callable which returns a callable
which processes arguments from the command-line. Any object which follows this
API may be passed as the <code class="docutils literal notranslate">action</code> parameter to <code class="xref py py-meth docutils literal notranslate">add_argument()</code>.
<dl class="class">
<dt id="argparse.Action">
class <code class="descclassname">argparse.</code><code class="descname">Action</code>(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)<a class="headerlink" href="#argparse.Action" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

Action objects are used by an ArgumentParser to represent the information needed
to parse a single argument from one or more strings from the command line. The
Action class must accept the two positional arguments plus any keyword arguments
passed to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">ArgumentParser.add_argument()</code></a> except for the <code class="docutils literal notranslate">action</code> itself.
Instances of Action (or return value of any callable to the <code class="docutils literal notranslate">action</code>
parameter) should have attributes “dest”, “option_strings”, “default”, “type”,
“required”, “help”, etc. defined. The easiest way to ensure these attributes
are defined is to call <code class="docutils literal notranslate">Action.__init__</code>.
Action instances should be callable, so subclasses must override the
<code class="docutils literal notranslate">__call__</code> method, which should accept four parameters:
<ul class="simple">
<li><code class="docutils literal notranslate">parser</code> - The ArgumentParser object which contains this action.</li>
<li><code class="docutils literal notranslate">namespace</code> - The <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> object that will be returned by
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>. Most actions add an attribute to this
object using <a class="reference internal" href="functions.html#setattr" title="setattr"><code class="xref py py-func docutils literal notranslate">setattr()</code></a>.</li>
<li><code class="docutils literal notranslate">values</code> - The associated command-line arguments, with any type conversions
applied. Type conversions are specified with the <a class="reference internal" href="#type">type</a> keyword argument to
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a>.</li>
<li><code class="docutils literal notranslate">option_string</code> - The option string that was used to invoke this action.
The <code class="docutils literal notranslate">option_string</code> argument is optional, and will be absent if the action
is associated with a positional argument.</li>
</ul>
The <code class="docutils literal notranslate">__call__</code> method may perform arbitrary actions, but will typically set
attributes on the <code class="docutils literal notranslate">namespace</code> based on <code class="docutils literal notranslate">dest</code> and <code class="docutils literal notranslate">values</code>.
</div>
</div>
<div class="section" id="the-parse-args-method">
<h2>15.4.4. The parse_args() method<a class="headerlink" href="#the-parse-args-method" title="Permalink to this headline">¶</a></h2>
<dl class="method">
<dt id="argparse.ArgumentParser.parse_args">
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_args</code>(args=None, namespace=None)<a class="headerlink" href="#argparse.ArgumentParser.parse_args" title="Permalink to this definition">¶</a></dt>
<dd>Convert argument strings to objects and assign them as attributes of the
namespace. Return the populated namespace.
Previous calls to <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> determine exactly what objects are
created and how they are assigned. See the documentation for
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> for details.
<ul class="simple">
<li><a class="reference internal" href="#args">args</a> - List of strings to parse. The default is taken from
<a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate">sys.argv</code></a>.</li>
<li><a class="reference internal" href="#namespace">namespace</a> - An object to take the attributes. The default is a new empty
<a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> object.</li>
</ul>
</dd></dl>

<div class="section" id="option-value-syntax">
<h3>15.4.4.1. Option value syntax<a class="headerlink" href="#option-value-syntax" title="Permalink to this headline">¶</a></h3>
The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method supports several ways of
specifying the value of an option (if it takes one). In the simplest case, the
option and its value are passed as two separate arguments:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-x&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-x&#39;, &#39;X&#39;])
Namespace(foo=None, x=&#39;X&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;FOO&#39;])
Namespace(foo=&#39;FOO&#39;, x=None)
</pre></div>
</div>
For long options (options with names longer than a single character), the option
and value can also be passed as a single command-line argument, using <code class="docutils literal notranslate">=</code> to
separate them:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.parse_args([&#39;--foo=FOO&#39;])
Namespace(foo=&#39;FOO&#39;, x=None)
</pre></div>
</div>
For short options (options only one character long), the option and its value
can be concatenated:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.parse_args([&#39;-xX&#39;])
Namespace(foo=None, x=&#39;X&#39;)
</pre></div>
</div>
Several short options can be joined together, using only a single <code class="docutils literal notranslate">-</code> prefix,
as long as only the last option (or none of them) requires a value:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-x&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-y&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-z&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-xyzZ&#39;])
Namespace(x=True, y=True, z=&#39;Z&#39;)
</pre></div>
</div>
</div>
<div class="section" id="invalid-arguments">
<h3>15.4.4.2. Invalid arguments<a class="headerlink" href="#invalid-arguments" title="Permalink to this headline">¶</a></h3>
While parsing the command line, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> checks for a
variety of errors, including ambiguous options, invalid types, invalid options,
wrong number of positional arguments, etc. When it encounters such an error,
it exits and prints the error along with a usage message:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, type=int)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;, nargs=&#39;?&#39;)

&gt;&gt;&gt; # invalid type
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;spam&#39;])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: argument --foo: invalid int value: &#39;spam&#39;

&gt;&gt;&gt; # invalid option
&gt;&gt;&gt; parser.parse_args([&#39;--bar&#39;])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: no such option: --bar

&gt;&gt;&gt; # wrong number of arguments
&gt;&gt;&gt; parser.parse_args([&#39;spam&#39;, &#39;badger&#39;])
usage: PROG [-h] [--foo FOO] [bar]
PROG: error: extra arguments found: badger
</pre></div>
</div>
</div>
<div class="section" id="arguments-containing">
<h3>15.4.4.3. Arguments containing <code class="docutils literal notranslate">-</code><a class="headerlink" href="#arguments-containing" title="Permalink to this headline">¶</a></h3>
The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method attempts to give errors whenever
the user has clearly made a mistake, but some situations are inherently
ambiguous. For example, the command-line argument <code class="docutils literal notranslate">-1</code> could either be an
attempt to specify an option or an attempt to provide a positional argument.
The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method is cautious here: positional
arguments may only begin with <code class="docutils literal notranslate">-</code> if they look like negative numbers and
there are no options in the parser that look like negative numbers:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-x&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, nargs=&#39;?&#39;)

&gt;&gt;&gt; # no negative number options, so -1 is a positional argument
&gt;&gt;&gt; parser.parse_args([&#39;-x&#39;, &#39;-1&#39;])
Namespace(foo=None, x=&#39;-1&#39;)

&gt;&gt;&gt; # no negative number options, so -1 and -5 are positional arguments
&gt;&gt;&gt; parser.parse_args([&#39;-x&#39;, &#39;-1&#39;, &#39;-5&#39;])
Namespace(foo=&#39;-5&#39;, x=&#39;-1&#39;)

&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-1&#39;, dest=&#39;one&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, nargs=&#39;?&#39;)

&gt;&gt;&gt; # negative number options present, so -1 is an option
&gt;&gt;&gt; parser.parse_args([&#39;-1&#39;, &#39;X&#39;])
Namespace(foo=None, one=&#39;X&#39;)

&gt;&gt;&gt; # negative number options present, so -2 is an option
&gt;&gt;&gt; parser.parse_args([&#39;-2&#39;])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: no such option: -2

&gt;&gt;&gt; # negative number options present, so both -1s are options
&gt;&gt;&gt; parser.parse_args([&#39;-1&#39;, &#39;-1&#39;])
usage: PROG [-h] [-1 ONE] [foo]
PROG: error: argument -1: expected one argument
</pre></div>
</div>
If you have positional arguments that must begin with <code class="docutils literal notranslate">-</code> and don’t look
like negative numbers, you can insert the pseudo-argument <code class="docutils literal notranslate">'--'</code> which tells
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> that everything after that is a positional
argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.parse_args([&#39;--&#39;, &#39;-f&#39;])
Namespace(foo=&#39;-f&#39;, one=None)
</pre></div>
</div>
</div>
<div class="section" id="argument-abbreviations-prefix-matching">
<h3>15.4.4.4. Argument abbreviations (prefix matching)<a class="headerlink" href="#argument-abbreviations-prefix-matching" title="Permalink to this headline">¶</a></h3>
The <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> method allows long options to be
abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches
a unique option):
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-bacon&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;-badger&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;-bac MMM&#39;.split())
Namespace(bacon=&#39;MMM&#39;, badger=None)
&gt;&gt;&gt; parser.parse_args(&#39;-bad WOOD&#39;.split())
Namespace(bacon=None, badger=&#39;WOOD&#39;)
&gt;&gt;&gt; parser.parse_args(&#39;-ba BA&#39;.split())
usage: PROG [-h] [-bacon BACON] [-badger BADGER]
PROG: error: ambiguous option: -ba could match -badger, -bacon
</pre></div>
</div>
An error is produced for arguments that could produce more than one options.
</div>
<div class="section" id="beyond-sys-argv">
<h3>15.4.4.5. Beyond <code class="docutils literal notranslate">sys.argv</code><a class="headerlink" href="#beyond-sys-argv" title="Permalink to this headline">¶</a></h3>
Sometimes it may be useful to have an ArgumentParser parse arguments other than those
of <a class="reference internal" href="sys.html#sys.argv" title="sys.argv"><code class="xref py py-data docutils literal notranslate">sys.argv</code></a>. This can be accomplished by passing a list of strings to
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>. This is useful for testing at the
interactive prompt:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(
... &#39;integers&#39;, metavar=&#39;int&#39;, type=int, choices=xrange(10),
... nargs=&#39;+&#39;, help=&#39;an integer in the range 0..9&#39;)
&gt;&gt;&gt; parser.add_argument(
... &#39;--sum&#39;, dest=&#39;accumulate&#39;, action=&#39;store_const&#39;, const=sum,
... default=max, help=&#39;sum the integers (default: find the max)&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;1&#39;, &#39;2&#39;, &#39;3&#39;, &#39;4&#39;])
Namespace(accumulate=&lt;built-in function max&gt;, integers=[1, 2, 3, 4])
&gt;&gt;&gt; parser.parse_args([&#39;1&#39;, &#39;2&#39;, &#39;3&#39;, &#39;4&#39;, &#39;--sum&#39;])
Namespace(accumulate=&lt;built-in function sum&gt;, integers=[1, 2, 3, 4])
</pre></div>
</div>
</div>
<div class="section" id="the-namespace-object">
<h3>15.4.4.6. The Namespace object<a class="headerlink" href="#the-namespace-object" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="argparse.Namespace">
class <code class="descclassname">argparse.</code><code class="descname">Namespace</code><a class="headerlink" href="#argparse.Namespace" title="Permalink to this definition">¶</a></dt>
<dd>Simple class used by default by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> to create
an object holding attributes and return it.
</dd></dl>

This class is deliberately simple, just an <a class="reference internal" href="functions.html#object" title="object"><code class="xref py py-class docutils literal notranslate">object</code></a> subclass with a
readable string representation. If you prefer to have dict-like view of the
attributes, you can use the standard Python idiom, <a class="reference internal" href="functions.html#vars" title="vars"><code class="xref py py-func docutils literal notranslate">vars()</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; args = parser.parse_args([&#39;--foo&#39;, &#39;BAR&#39;])
&gt;&gt;&gt; vars(args)
{&#39;foo&#39;: &#39;BAR&#39;}
</pre></div>
</div>
It may also be useful to have an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> assign attributes to an
already existing object, rather than a new <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> object. This can
be achieved by specifying the <code class="docutils literal notranslate">namespace=</code> keyword argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; class C(object):
... pass
...
&gt;&gt;&gt; c = C()
&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;)
&gt;&gt;&gt; parser.parse_args(args=[&#39;--foo&#39;, &#39;BAR&#39;], namespace=c)
&gt;&gt;&gt; c.foo
&#39;BAR&#39;
</pre></div>
</div>
</div>
</div>
<div class="section" id="other-utilities">
<h2>15.4.5. Other utilities<a class="headerlink" href="#other-utilities" title="Permalink to this headline">¶</a></h2>
<div class="section" id="sub-commands">
<h3>15.4.5.1. Sub-commands<a class="headerlink" href="#sub-commands" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.add_subparsers">
<code class="descclassname">ArgumentParser.</code><code class="descname">add_subparsers</code>([title][, description][, prog][, parser_class][, action][, option_string][, dest][, help][, metavar])<a class="headerlink" href="#argparse.ArgumentParser.add_subparsers" title="Permalink to this definition">¶</a></dt>
<dd>Many programs split up their functionality into a number of sub-commands,
for example, the <code class="docutils literal notranslate">svn</code> program can invoke sub-commands like <code class="docutils literal notranslate">svn
checkout</code>, <code class="docutils literal notranslate">svn update</code>, and <code class="docutils literal notranslate">svn commit</code>. Splitting up functionality
this way can be a particularly good idea when a program performs several
different functions which require different kinds of command-line arguments.
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> supports the creation of such sub-commands with the
<a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> method. The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> method is normally
called with no arguments and returns a special action object. This object
has a single method, <code class="xref py py-meth docutils literal notranslate">add_parser()</code>, which takes a
command name and any <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> constructor arguments, and
returns an <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> object that can be modified as usual.
Description of parameters:
<ul class="simple">
<li>title - title for the sub-parser group in help output; by default
“subcommands” if description is provided, otherwise uses title for
positional arguments</li>
<li>description - description for the sub-parser group in help output, by
default <code class="docutils literal notranslate">None</code></li>
<li>prog - usage information that will be displayed with sub-command help,
by default the name of the program and any positional arguments before the
subparser argument</li>
<li>parser_class - class which will be used to create sub-parser instances, by
default the class of the current parser (e.g. ArgumentParser)</li>
<li><a class="reference internal" href="#action">action</a> - the basic type of action to be taken when this argument is
encountered at the command line</li>
<li><a class="reference internal" href="#dest">dest</a> - name of the attribute under which sub-command name will be
stored; by default <code class="docutils literal notranslate">None</code> and no value is stored</li>
<li><a class="reference internal" href="#help">help</a> - help for sub-parser group in help output, by default <code class="docutils literal notranslate">None</code></li>
<li><a class="reference internal" href="#metavar">metavar</a> - string presenting available sub-commands in help; by default it
is <code class="docutils literal notranslate">None</code> and presents sub-commands in form {cmd1, cmd2, ..}</li>
</ul>
Some example usage:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; # create the top-level parser
&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; subparsers = parser.add_subparsers(help=&#39;sub-command help&#39;)
&gt;&gt;&gt;
&gt;&gt;&gt; # create the parser for the &quot;a&quot; command
&gt;&gt;&gt; parser_a = subparsers.add_parser(&#39;a&#39;, help=&#39;a help&#39;)
&gt;&gt;&gt; parser_a.add_argument(&#39;bar&#39;, type=int, help=&#39;bar help&#39;)
&gt;&gt;&gt;
&gt;&gt;&gt; # create the parser for the &quot;b&quot; command
&gt;&gt;&gt; parser_b = subparsers.add_parser(&#39;b&#39;, help=&#39;b help&#39;)
&gt;&gt;&gt; parser_b.add_argument(&#39;--baz&#39;, choices=&#39;XYZ&#39;, help=&#39;baz help&#39;)
&gt;&gt;&gt;
&gt;&gt;&gt; # parse some argument lists
&gt;&gt;&gt; parser.parse_args([&#39;a&#39;, &#39;12&#39;])
Namespace(bar=12, foo=False)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;b&#39;, &#39;--baz&#39;, &#39;Z&#39;])
Namespace(baz=&#39;Z&#39;, foo=True)
</pre></div>
</div>
Note that the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> will only contain
attributes for the main parser and the subparser that was selected by the
command line (and not any other subparsers). So in the example above, when
the <code class="docutils literal notranslate">a</code> command is specified, only the <code class="docutils literal notranslate">foo</code> and <code class="docutils literal notranslate">bar</code> attributes are
present, and when the <code class="docutils literal notranslate">b</code> command is specified, only the <code class="docutils literal notranslate">foo</code> and
<code class="docutils literal notranslate">baz</code> attributes are present.
Similarly, when a help message is requested from a subparser, only the help
for that particular parser will be printed. The help message will not
include parent parser or sibling parser messages. (A help message for each
subparser command, however, can be given by supplying the <code class="docutils literal notranslate">help=</code> argument
to <code class="xref py py-meth docutils literal notranslate">add_parser()</code> as above.)
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser.parse_args([&#39;--help&#39;])
usage: PROG [-h] [--foo] {a,b} ...

positional arguments:
 {a,b} sub-command help
 a a help
 b b help

optional arguments:
 -h, --help show this help message and exit
 --foo foo help

&gt;&gt;&gt; parser.parse_args([&#39;a&#39;, &#39;--help&#39;])
usage: PROG a [-h] bar

positional arguments:
 bar bar help

optional arguments:
 -h, --help show this help message and exit

&gt;&gt;&gt; parser.parse_args([&#39;b&#39;, &#39;--help&#39;])
usage: PROG b [-h] [--baz {X,Y,Z}]

optional arguments:
 -h, --help show this help message and exit
 --baz {X,Y,Z} baz help
</pre></div>
</div>
The <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> method also supports <code class="docutils literal notranslate">title</code> and <code class="docutils literal notranslate">description</code>
keyword arguments. When either is present, the subparser’s commands will
appear in their own group in the help output. For example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; subparsers = parser.add_subparsers(title=&#39;subcommands&#39;,
... description=&#39;valid subcommands&#39;,
... help=&#39;additional help&#39;)
&gt;&gt;&gt; subparsers.add_parser(&#39;foo&#39;)
&gt;&gt;&gt; subparsers.add_parser(&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;-h&#39;])
usage: [-h] {foo,bar} ...

optional arguments:
 -h, --help show this help message and exit

subcommands:
 valid subcommands

{foo,bar} additional help
</pre></div>
</div>
One particularly effective way of handling sub-commands is to combine the use
of the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> method with calls to <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate">set_defaults()</code></a> so
that each subparser knows which Python function it should execute. For
example:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; # sub-command functions
&gt;&gt;&gt; def foo(args):
... print args.x * args.y
...
&gt;&gt;&gt; def bar(args):
... print &#39;((%s))&#39; % args.z
...
&gt;&gt;&gt; # create the top-level parser
&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; subparsers = parser.add_subparsers()
&gt;&gt;&gt;
&gt;&gt;&gt; # create the parser for the &quot;foo&quot; command
&gt;&gt;&gt; parser_foo = subparsers.add_parser(&#39;foo&#39;)
&gt;&gt;&gt; parser_foo.add_argument(&#39;-x&#39;, type=int, default=1)
&gt;&gt;&gt; parser_foo.add_argument(&#39;y&#39;, type=float)
&gt;&gt;&gt; parser_foo.set_defaults(func=foo)
&gt;&gt;&gt;
&gt;&gt;&gt; # create the parser for the &quot;bar&quot; command
&gt;&gt;&gt; parser_bar = subparsers.add_parser(&#39;bar&#39;)
&gt;&gt;&gt; parser_bar.add_argument(&#39;z&#39;)
&gt;&gt;&gt; parser_bar.set_defaults(func=bar)
&gt;&gt;&gt;
&gt;&gt;&gt; # parse the args and call whatever function was selected
&gt;&gt;&gt; args = parser.parse_args(&#39;foo 1 -x 2&#39;.split())
&gt;&gt;&gt; args.func(args)
2.0
&gt;&gt;&gt;
&gt;&gt;&gt; # parse the args and call whatever function was selected
&gt;&gt;&gt; args = parser.parse_args(&#39;bar XYZYX&#39;.split())
&gt;&gt;&gt; args.func(args)
((XYZYX))
</pre></div>
</div>
This way, you can let <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> do the job of calling the
appropriate function after argument parsing is complete. Associating
functions with actions like this is typically the easiest way to handle the
different actions for each of your subparsers. However, if it is necessary
to check the name of the subparser that was invoked, the <code class="docutils literal notranslate">dest</code> keyword
argument to the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> call will work:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; subparsers = parser.add_subparsers(dest=&#39;subparser_name&#39;)
&gt;&gt;&gt; subparser1 = subparsers.add_parser(&#39;1&#39;)
&gt;&gt;&gt; subparser1.add_argument(&#39;-x&#39;)
&gt;&gt;&gt; subparser2 = subparsers.add_parser(&#39;2&#39;)
&gt;&gt;&gt; subparser2.add_argument(&#39;y&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;2&#39;, &#39;frobble&#39;])
Namespace(subparser_name=&#39;2&#39;, y=&#39;frobble&#39;)
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="filetype-objects">
<h3>15.4.5.2. FileType objects<a class="headerlink" href="#filetype-objects" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="argparse.FileType">
class <code class="descclassname">argparse.</code><code class="descname">FileType</code>(mode='r', bufsize=None)<a class="headerlink" href="#argparse.FileType" title="Permalink to this definition">¶</a></dt>
<dd>The <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate">FileType</code></a> factory creates objects that can be passed to the type
argument of <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">ArgumentParser.add_argument()</code></a>. Arguments that have
<a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate">FileType</code></a> objects as their type will open command-line arguments as files
with the requested modes and buffer sizes:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--output&#39;, type=argparse.FileType(&#39;wb&#39;, 0))
&gt;&gt;&gt; parser.parse_args([&#39;--output&#39;, &#39;out&#39;])
Namespace(output=&lt;open file &#39;out&#39;, mode &#39;wb&#39; at 0x...&gt;)
</pre></div>
</div>
FileType objects understand the pseudo-argument <code class="docutils literal notranslate">'-'</code> and automatically
convert this into <code class="docutils literal notranslate">sys.stdin</code> for readable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate">FileType</code></a> objects and
<code class="docutils literal notranslate">sys.stdout</code> for writable <a class="reference internal" href="#argparse.FileType" title="argparse.FileType"><code class="xref py py-class docutils literal notranslate">FileType</code></a> objects:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;infile&#39;, type=argparse.FileType(&#39;r&#39;))
&gt;&gt;&gt; parser.parse_args([&#39;-&#39;])
Namespace(infile=&lt;open file &#39;&lt;stdin&gt;&#39;, mode &#39;r&#39; at 0x...&gt;)
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="argument-groups">
<h3>15.4.5.3. Argument groups<a class="headerlink" href="#argument-groups" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.add_argument_group">
<code class="descclassname">ArgumentParser.</code><code class="descname">add_argument_group</code>(title=None, description=None)<a class="headerlink" href="#argparse.ArgumentParser.add_argument_group" title="Permalink to this definition">¶</a></dt>
<dd>By default, <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> groups command-line arguments into
“positional arguments” and “optional arguments” when displaying help
messages. When there is a better conceptual grouping of arguments than this
default one, appropriate groups can be created using the
<a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate">add_argument_group()</code></a> method:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, add_help=False)
&gt;&gt;&gt; group = parser.add_argument_group(&#39;group&#39;)
&gt;&gt;&gt; group.add_argument(&#39;--foo&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; group.add_argument(&#39;bar&#39;, help=&#39;bar help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [--foo FOO] bar

group:
 bar bar help
 --foo FOO foo help
</pre></div>
</div>
The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate">add_argument_group()</code></a> method returns an argument group object which
has an <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> method just like a regular
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>. When an argument is added to the group, the parser
treats it just like a normal argument, but displays the argument in a
separate group for help messages. The <a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate">add_argument_group()</code></a> method
accepts title and description arguments which can be used to
customize this display:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;, add_help=False)
&gt;&gt;&gt; group1 = parser.add_argument_group(&#39;group1&#39;, &#39;group1 description&#39;)
&gt;&gt;&gt; group1.add_argument(&#39;foo&#39;, help=&#39;foo help&#39;)
&gt;&gt;&gt; group2 = parser.add_argument_group(&#39;group2&#39;, &#39;group2 description&#39;)
&gt;&gt;&gt; group2.add_argument(&#39;--bar&#39;, help=&#39;bar help&#39;)
&gt;&gt;&gt; parser.print_help()
usage: PROG [--bar BAR] foo

group1:
 group1 description

foo foo help

group2:
 group2 description

--bar BAR bar help
</pre></div>
</div>
Note that any arguments not in your user-defined groups will end up back
in the usual “positional arguments” and “optional arguments” sections.
</dd></dl>

</div>
<div class="section" id="mutual-exclusion">
<h3>15.4.5.4. Mutual exclusion<a class="headerlink" href="#mutual-exclusion" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.add_mutually_exclusive_group">
<code class="descclassname">ArgumentParser.</code><code class="descname">add_mutually_exclusive_group</code>(required=False)<a class="headerlink" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="Permalink to this definition">¶</a></dt>
<dd>Create a mutually exclusive group. <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> will make sure that only
one of the arguments in the mutually exclusive group was present on the
command line:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; group = parser.add_mutually_exclusive_group()
&gt;&gt;&gt; group.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; group.add_argument(&#39;--bar&#39;, action=&#39;store_false&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;])
Namespace(bar=True, foo=True)
&gt;&gt;&gt; parser.parse_args([&#39;--bar&#39;])
Namespace(bar=False, foo=False)
&gt;&gt;&gt; parser.parse_args([&#39;--foo&#39;, &#39;--bar&#39;])
usage: PROG [-h] [--foo | --bar]
PROG: error: argument --bar: not allowed with argument --foo
</pre></div>
</div>
The <a class="reference internal" href="#argparse.ArgumentParser.add_mutually_exclusive_group" title="argparse.ArgumentParser.add_mutually_exclusive_group"><code class="xref py py-meth docutils literal notranslate">add_mutually_exclusive_group()</code></a> method also accepts a required
argument, to indicate that at least one of the mutually exclusive arguments
is required:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser(prog=&#39;PROG&#39;)
&gt;&gt;&gt; group = parser.add_mutually_exclusive_group(required=True)
&gt;&gt;&gt; group.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; group.add_argument(&#39;--bar&#39;, action=&#39;store_false&#39;)
&gt;&gt;&gt; parser.parse_args([])
usage: PROG [-h] (--foo | --bar)
PROG: error: one of the arguments --foo --bar is required
</pre></div>
</div>
Note that currently mutually exclusive argument groups do not support the
title and description arguments of
<a class="reference internal" href="#argparse.ArgumentParser.add_argument_group" title="argparse.ArgumentParser.add_argument_group"><code class="xref py py-meth docutils literal notranslate">add_argument_group()</code></a>.
</dd></dl>

</div>
<div class="section" id="parser-defaults">
<h3>15.4.5.5. Parser defaults<a class="headerlink" href="#parser-defaults" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.set_defaults">
<code class="descclassname">ArgumentParser.</code><code class="descname">set_defaults</code>(**kwargs)<a class="headerlink" href="#argparse.ArgumentParser.set_defaults" title="Permalink to this definition">¶</a></dt>
<dd>Most of the time, the attributes of the object returned by <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a>
will be fully determined by inspecting the command-line arguments and the argument
actions. <a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate">set_defaults()</code></a> allows some additional
attributes that are determined without any inspection of the command line to
be added:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;foo&#39;, type=int)
&gt;&gt;&gt; parser.set_defaults(bar=42, baz=&#39;badger&#39;)
&gt;&gt;&gt; parser.parse_args([&#39;736&#39;])
Namespace(bar=42, baz=&#39;badger&#39;, foo=736)
</pre></div>
</div>
Note that parser-level defaults always override argument-level defaults:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, default=&#39;bar&#39;)
&gt;&gt;&gt; parser.set_defaults(foo=&#39;spam&#39;)
&gt;&gt;&gt; parser.parse_args([])
Namespace(foo=&#39;spam&#39;)
</pre></div>
</div>
Parser-level defaults can be particularly useful when working with multiple
parsers. See the <a class="reference internal" href="#argparse.ArgumentParser.add_subparsers" title="argparse.ArgumentParser.add_subparsers"><code class="xref py py-meth docutils literal notranslate">add_subparsers()</code></a> method for an
example of this type.
</dd></dl>

<dl class="method">
<dt id="argparse.ArgumentParser.get_default">
<code class="descclassname">ArgumentParser.</code><code class="descname">get_default</code>(dest)<a class="headerlink" href="#argparse.ArgumentParser.get_default" title="Permalink to this definition">¶</a></dt>
<dd>Get the default value for a namespace attribute, as set by either
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">add_argument()</code></a> or by
<a class="reference internal" href="#argparse.ArgumentParser.set_defaults" title="argparse.ArgumentParser.set_defaults"><code class="xref py py-meth docutils literal notranslate">set_defaults()</code></a>:
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, default=&#39;badger&#39;)
&gt;&gt;&gt; parser.get_default(&#39;foo&#39;)
&#39;badger&#39;
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="printing-help">
<h3>15.4.5.6. Printing help<a class="headerlink" href="#printing-help" title="Permalink to this headline">¶</a></h3>
In most typical applications, <a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> will take
care of formatting and printing any usage or error messages. However, several
formatting methods are available:
<dl class="method">
<dt id="argparse.ArgumentParser.print_usage">
<code class="descclassname">ArgumentParser.</code><code class="descname">print_usage</code>(file=None)<a class="headerlink" href="#argparse.ArgumentParser.print_usage" title="Permalink to this definition">¶</a></dt>
<dd>Print a brief description of how the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> should be
invoked on the command line. If file is <code class="docutils literal notranslate">None</code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate">sys.stdout</code></a> is
assumed.
</dd></dl>

<dl class="method">
<dt id="argparse.ArgumentParser.print_help">
<code class="descclassname">ArgumentParser.</code><code class="descname">print_help</code>(file=None)<a class="headerlink" href="#argparse.ArgumentParser.print_help" title="Permalink to this definition">¶</a></dt>
<dd>Print a help message, including the program usage and information about the
arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>. If file is
<code class="docutils literal notranslate">None</code>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate">sys.stdout</code></a> is assumed.
</dd></dl>

There are also variants of these methods that simply return a string instead of
printing it:
<dl class="method">
<dt id="argparse.ArgumentParser.format_usage">
<code class="descclassname">ArgumentParser.</code><code class="descname">format_usage</code>()<a class="headerlink" href="#argparse.ArgumentParser.format_usage" title="Permalink to this definition">¶</a></dt>
<dd>Return a string containing a brief description of how the
<a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> should be invoked on the command line.
</dd></dl>

<dl class="method">
<dt id="argparse.ArgumentParser.format_help">
<code class="descclassname">ArgumentParser.</code><code class="descname">format_help</code>()<a class="headerlink" href="#argparse.ArgumentParser.format_help" title="Permalink to this definition">¶</a></dt>
<dd>Return a string containing a help message, including the program usage and
information about the arguments registered with the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a>.
</dd></dl>

</div>
<div class="section" id="partial-parsing">
<h3>15.4.5.7. Partial parsing<a class="headerlink" href="#partial-parsing" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.parse_known_args">
<code class="descclassname">ArgumentParser.</code><code class="descname">parse_known_args</code>(args=None, namespace=None)<a class="headerlink" href="#argparse.ArgumentParser.parse_known_args" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

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
<a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate">parse_known_args()</code></a> method can be useful. It works much like
<a class="reference internal" href="#argparse.ArgumentParser.parse_args" title="argparse.ArgumentParser.parse_args"><code class="xref py py-meth docutils literal notranslate">parse_args()</code></a> 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.
<div class="highlight-default notranslate"><div class="highlight"><pre>&gt;&gt;&gt; parser = argparse.ArgumentParser()
&gt;&gt;&gt; parser.add_argument(&#39;--foo&#39;, action=&#39;store_true&#39;)
&gt;&gt;&gt; parser.add_argument(&#39;bar&#39;)
&gt;&gt;&gt; parser.parse_known_args([&#39;--foo&#39;, &#39;--badger&#39;, &#39;BAR&#39;, &#39;spam&#39;])
(Namespace(bar=&#39;BAR&#39;, foo=True), [&#39;--badger&#39;, &#39;spam&#39;])
</pre></div>
</div>
<div class="admonition warning">
Warning
<a class="reference internal" href="#prefix-matching">Prefix matching</a> rules apply to
<code class="xref py py-meth docutils literal notranslate">parse_known_args()</code>. The parser may consume an option even if it’s just
a prefix of one of its known options, instead of leaving it in the remaining
arguments list.
</div>
</div>
<div class="section" id="customizing-file-parsing">
<h3>15.4.5.8. Customizing file parsing<a class="headerlink" href="#customizing-file-parsing" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.convert_arg_line_to_args">
<code class="descclassname">ArgumentParser.</code><code class="descname">convert_arg_line_to_args</code>(arg_line)<a class="headerlink" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="Permalink to this definition">¶</a></dt>
<dd>Arguments that are read from a file (see the fromfile_prefix_chars
keyword argument to the <a class="reference internal" href="#argparse.ArgumentParser" title="argparse.ArgumentParser"><code class="xref py py-class docutils literal notranslate">ArgumentParser</code></a> constructor) are read one
argument per line. <a class="reference internal" href="#argparse.ArgumentParser.convert_arg_line_to_args" title="argparse.ArgumentParser.convert_arg_line_to_args"><code class="xref py py-meth docutils literal notranslate">convert_arg_line_to_args()</code></a> can be overridden for
fancier reading.
This method takes a single argument arg_line which is a string read from
the argument file. It returns a list of arguments parsed from this string.
The method is called once per line read from the argument file, in order.
A useful override of this method is one that treats each space-separated word
as an argument:
<div class="highlight-default notranslate"><div class="highlight"><pre>def convert_arg_line_to_args(self, arg_line):
 return arg_line.split()
</pre></div>
</div>
</dd></dl>

</div>
<div class="section" id="exiting-methods">
<h3>15.4.5.9. Exiting methods<a class="headerlink" href="#exiting-methods" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="argparse.ArgumentParser.exit">
<code class="descclassname">ArgumentParser.</code><code class="descname">exit</code>(status=0, message=None)<a class="headerlink" href="#argparse.ArgumentParser.exit" title="Permalink to this definition">¶</a></dt>
<dd>This method terminates the program, exiting with the specified status
and, if given, it prints a message before that.
</dd></dl>

<dl class="method">
<dt id="argparse.ArgumentParser.error">
<code class="descclassname">ArgumentParser.</code><code class="descname">error</code>(message)<a class="headerlink" href="#argparse.ArgumentParser.error" title="Permalink to this definition">¶</a></dt>
<dd>This method prints a usage message including the message to the
standard error and terminates the program with a status code of 2.
</dd></dl>

</div>
</div>
<div class="section" id="upgrading-optparse-code">
<h2>15.4.6. Upgrading optparse code<a class="headerlink" href="#upgrading-optparse-code" title="Permalink to this headline">¶</a></h2>
Originally, the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> module had attempted to maintain compatibility
with <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate">optparse</code></a>. However, <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate">optparse</code></a> was difficult to extend
transparently, particularly with the changes required to support the new
<code class="docutils literal notranslate">nargs=</code> specifiers and better usage messages. When most everything in
<a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate">optparse</code></a> had either been copy-pasted over or monkey-patched, it no
longer seemed practical to try to maintain the backwards compatibility.
The <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> module improves on the standard library <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate">optparse</code></a>
module in a number of ways including:
<ul class="simple">
<li>Handling positional arguments.</li>
<li>Supporting sub-commands.</li>
<li>Allowing alternative option prefixes like <code class="docutils literal notranslate">+</code> and <code class="docutils literal notranslate">/</code>.</li>
<li>Handling zero-or-more and one-or-more style arguments.</li>
<li>Producing more informative usage messages.</li>
<li>Providing a much simpler interface for custom <code class="docutils literal notranslate">type</code> and <code class="docutils literal notranslate">action</code>.</li>
</ul>
A partial upgrade path from <a class="reference internal" href="optparse.html#module-optparse" title="optparse: Command-line option parsing library. (deprecated)"><code class="xref py py-mod docutils literal notranslate">optparse</code></a> to <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a>:
<ul class="simple">
<li>Replace all <a class="reference internal" href="optparse.html#optparse.OptionParser.add_option" title="optparse.OptionParser.add_option"><code class="xref py py-meth docutils literal notranslate">optparse.OptionParser.add_option()</code></a> calls with
<a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">ArgumentParser.add_argument()</code></a> calls.</li>
<li>Replace <code class="docutils literal notranslate">(options, args) = parser.parse_args()</code> with <code class="docutils literal notranslate">args =
parser.parse_args()</code> and add additional <a class="reference internal" href="#argparse.ArgumentParser.add_argument" title="argparse.ArgumentParser.add_argument"><code class="xref py py-meth docutils literal notranslate">ArgumentParser.add_argument()</code></a>
calls for the positional arguments. Keep in mind that what was previously
called <code class="docutils literal notranslate">options</code>, now in the <a class="reference internal" href="#module-argparse" title="argparse: Command-line option and argument parsing library."><code class="xref py py-mod docutils literal notranslate">argparse</code></a> context is called <code class="docutils literal notranslate">args</code>.</li>
<li>Replace <a class="reference internal" href="optparse.html#optparse.OptionParser.disable_interspersed_args" title="optparse.OptionParser.disable_interspersed_args"><code class="xref py py-meth docutils literal notranslate">optparse.OptionParser.disable_interspersed_args()</code></a>
by setting <code class="docutils literal notranslate">nargs</code> of a positional argument to <a class="reference internal" href="#argparse-remainder">argparse.REMAINDER</a>, or
use <a class="reference internal" href="#argparse.ArgumentParser.parse_known_args" title="argparse.ArgumentParser.parse_known_args"><code class="xref py py-meth docutils literal notranslate">parse_known_args()</code></a> to collect unparsed argument
strings in a separate list.</li>
<li>Replace callback actions and the <code class="docutils literal notranslate">callback_*</code> keyword arguments with
<code class="docutils literal notranslate">type</code> or <code class="docutils literal notranslate">action</code> arguments.</li>
<li>Replace string names for <code class="docutils literal notranslate">type</code> keyword arguments with the corresponding
type objects (e.g. int, float, complex, etc).</li>
<li>Replace <code class="xref py py-class docutils literal notranslate">optparse.Values</code> with <a class="reference internal" href="#argparse.Namespace" title="argparse.Namespace"><code class="xref py py-class docutils literal notranslate">Namespace</code></a> and
<code class="xref py py-exc docutils literal notranslate">optparse.OptionError</code> and <code class="xref py py-exc docutils literal notranslate">optparse.OptionValueError</code> with
<code class="xref py py-exc docutils literal notranslate">ArgumentError</code>.</li>
<li>Replace strings with implicit arguments such as <code class="docutils literal notranslate">%default</code> or <code class="docutils literal notranslate">%prog</code> with
the standard Python syntax to use dictionaries to format strings, that is,
<code class="docutils literal notranslate">%(default)s</code> and <code class="docutils literal notranslate">%(prog)s</code>.</li>
<li>Replace the OptionParser constructor <code class="docutils literal notranslate">version</code> argument with a call to
<code class="docutils literal notranslate">parser.add_argument('--version', action='version', version='&lt;the version&gt;')</code>.</li>
</ul>
</div>
</div>

</div>
 </div>
 </div>
 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
 <div class="sphinxsidebarwrapper">
 <h3><a href="../contents.html">Table Of Contents</a></h3>
 <ul>
<li><a class="reference internal" href="#">15.4. <code class="docutils literal notranslate">argparse</code> — Parser for command-line options, arguments and sub-commands</a><ul>
<li><a class="reference internal" href="#example">15.4.1. Example</a><ul>
<li><a class="reference internal" href="#creating-a-parser">15.4.1.1. Creating a parser</a></li>
<li><a class="reference internal" href="#adding-arguments">15.4.1.2. Adding arguments</a></li>
<li><a class="reference internal" href="#parsing-arguments">15.4.1.3. Parsing arguments</a></li>
</ul>
</li>
<li><a class="reference internal" href="#argumentparser-objects">15.4.2. ArgumentParser objects</a><ul>
<li><a class="reference internal" href="#prog">15.4.2.1. prog</a></li>
<li><a class="reference internal" href="#usage">15.4.2.2. usage</a></li>
<li><a class="reference internal" href="#description">15.4.2.3. description</a></li>
<li><a class="reference internal" href="#epilog">15.4.2.4. epilog</a></li>
<li><a class="reference internal" href="#parents">15.4.2.5. parents</a></li>
<li><a class="reference internal" href="#formatter-class">15.4.2.6. formatter_class</a></li>
<li><a class="reference internal" href="#prefix-chars">15.4.2.7. prefix_chars</a></li>
<li><a class="reference internal" href="#fromfile-prefix-chars">15.4.2.8. fromfile_prefix_chars</a></li>
<li><a class="reference internal" href="#argument-default">15.4.2.9. argument_default</a></li>
<li><a class="reference internal" href="#conflict-handler">15.4.2.10. conflict_handler</a></li>
<li><a class="reference internal" href="#add-help">15.4.2.11. add_help</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-add-argument-method">15.4.3. The add_argument() method</a><ul>
<li><a class="reference internal" href="#name-or-flags">15.4.3.1. name or flags</a></li>
<li><a class="reference internal" href="#action">15.4.3.2. action</a></li>
<li><a class="reference internal" href="#nargs">15.4.3.3. nargs</a></li>
<li><a class="reference internal" href="#const">15.4.3.4. const</a></li>
<li><a class="reference internal" href="#default">15.4.3.5. default</a></li>
<li><a class="reference internal" href="#type">15.4.3.6. type</a></li>
<li><a class="reference internal" href="#choices">15.4.3.7. choices</a></li>
<li><a class="reference internal" href="#required">15.4.3.8. required</a></li>
<li><a class="reference internal" href="#help">15.4.3.9. help</a></li>
<li><a class="reference internal" href="#metavar">15.4.3.10. metavar</a></li>
<li><a class="reference internal" href="#dest">15.4.3.11. dest</a></li>
<li><a class="reference internal" href="#action-classes">15.4.3.12. Action classes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-parse-args-method">15.4.4. The parse_args() method</a><ul>
<li><a class="reference internal" href="#option-value-syntax">15.4.4.1. Option value syntax</a></li>
<li><a class="reference internal" href="#invalid-arguments">15.4.4.2. Invalid arguments</a></li>
<li><a class="reference internal" href="#arguments-containing">15.4.4.3. Arguments containing <code class="docutils literal notranslate">-</code></a></li>
<li><a class="reference internal" href="#argument-abbreviations-prefix-matching">15.4.4.4. Argument abbreviations (prefix matching)</a></li>
<li><a class="reference internal" href="#beyond-sys-argv">15.4.4.5. Beyond <code class="docutils literal notranslate">sys.argv</code></a></li>
<li><a class="reference internal" href="#the-namespace-object">15.4.4.6. The Namespace object</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-utilities">15.4.5. Other utilities</a><ul>
<li><a class="reference internal" href="#sub-commands">15.4.5.1. Sub-commands</a></li>
<li><a class="reference internal" href="#filetype-objects">15.4.5.2. FileType objects</a></li>
<li><a class="reference internal" href="#argument-groups">15.4.5.3. Argument groups</a></li>
<li><a class="reference internal" href="#mutual-exclusion">15.4.5.4. Mutual exclusion</a></li>
<li><a class="reference internal" href="#parser-defaults">15.4.5.5. Parser defaults</a></li>
<li><a class="reference internal" href="#printing-help">15.4.5.6. Printing help</a></li>
<li><a class="reference internal" href="#partial-parsing">15.4.5.7. Partial parsing</a></li>
<li><a class="reference internal" href="#customizing-file-parsing">15.4.5.8. Customizing file parsing</a></li>
<li><a class="reference internal" href="#exiting-methods">15.4.5.9. Exiting methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#upgrading-optparse-code">15.4.6. Upgrading optparse code</a></li>
</ul>
</li>
</ul>

<h4>Previous topic</h4>
 <a href="time.html"
 title="previous chapter">15.3. <code class="docutils literal notranslate">time</code> — Time access and conversions</a>
 <h4>Next topic</h4>
 <a href="optparse.html"
 title="next chapter">15.5. <code class="docutils literal notranslate">optparse</code> — Parser for command line options</a>
 <div role="note" aria-label="source link">
 <h3>This Page</h3>
 <ul class="this-page-menu">
 <li><a href="../_sources/library/argparse.rst.txt"
 rel="nofollow">Show Source</a></li>
 </ul>
 </div>
<div id="searchbox" style="display: none" role="search">
 <h3>Quick search</h3>
 <div class="searchformwrapper">
 <form class="search" action="../search.html" method="get">
 <input type="text" name="q" />
 <input type="submit" value="Go" />
 <input type="hidden" name="check_keywords" value="yes" />
 <input type="hidden" name="area" value="default" />
 </form>
 </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
 </div>
 </div>
 <div class="clearer"></div>
 </div> 
 <div class="related" role="navigation" aria-label="related navigation">
 <h3>Navigation</h3>
 <ul>
 <li class="right" style="margin-right: 10px">
 <a href="../genindex.html" title="General Index"
 >index</a></li>
 <li class="right" >
 <a href="../py-modindex.html" title="Python Module Index"
 >modules</a> |</li>
 <li class="right" >
 <a href="optparse.html" title="15.5. optparse — Parser for command line options"
 >next</a> |</li>
 <li class="right" >
 <a href="time.html" title="15.3. time — Time access and conversions"
 >previous</a> |</li>
 <li><img src="../_static/py.png" alt=""
 style="vertical-align: middle; margin-top: -1px"/></li>
 <li><a href="https://www.python.org/">Python</a> &#187;</li>
 <li>
 <a href="../index.html">Python 2.7.16 documentation</a> &#187;
 </li>

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>
 <li class="nav-item nav-item-2"><a href="allos.html" >15. Generic Operating System Services</a> &#187;</li> 
 </ul>
 </div> 
 <div class="footer">
 &copy; <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation.
 
 The Python Software Foundation is a non-profit corporation.
 <a href="https://www.python.org/psf/donations/">Please donate.</a>
 
 Last updated on Mar 27, 2019.
 <a href="../bugs.html">Found a bug</a>?
 
 Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6.
 </div>

</body>
</html>

cmd: