Parser Python
argparse — Parser for command-line options, arguments and …
New in version 3. 2.
Source code: Lib/
The argparse module makes it easy to write user-friendly command-line
interfaces. The program defines what arguments it requires, and argparse
will figure out how to parse those out of The argparse
module also automatically generates help and usage messages and issues errors
when users give the program invalid arguments.
Example¶
The following code is a Python program that takes a list of integers and
produces either the sum or the max:
import argparse
parser = gumentParser(description=’Process some integers. ‘)
d_argument(‘integers’, metavar=’N’, type=int, nargs=’+’,
help=’an integer for the accumulator’)
d_argument(‘–sum’, dest=’accumulate’, action=’store_const’,
const=sum, default=max,
help=’sum the integers (default: find the max)’)
args = rse_args()
print(cumulate(tegers))
Assuming the Python code above is saved into a file called, it can
be run at the command line and provides useful help messages:
$ python -h
usage: [-h] [–sum] N [N… ]
Process some integers.
positional arguments:
N an integer for the accumulator
options:
-h, –help show this help message and exit
–sum sum the integers (default: find the max)
When run with the appropriate arguments, it prints either the sum or the max of
the command-line integers:
$ python 1 2 3 4
4
$ python 1 2 3 4 –sum
10
If invalid arguments are passed in, it will issue an error:
$ python a b c
error: argument N: invalid int value: ‘a’
The following sections walk you through this example.
Creating a parser¶
The first step in using the argparse is creating an
ArgumentParser object:
>>> parser = gumentParser(description=’Process some integers. ‘)
The ArgumentParser object will hold all the information necessary to
parse the command line into Python data types.
Adding arguments¶
Filling an ArgumentParser with information about program arguments is
done by making calls to the add_argument() method.
Generally, these calls tell the ArgumentParser how to take the strings
on the command line and turn them into objects. This information is stored and
used when parse_args() is called. For example:
>>> d_argument(‘integers’, metavar=’N’, type=int, nargs=’+’,… help=’an integer for the accumulator’)
>>> d_argument(‘–sum’, dest=’accumulate’, action=’store_const’,… const=sum, default=max,… help=’sum the integers (default: find the max)’)
Later, calling parse_args() will return an object with
two attributes, integers and accumulate. The integers attribute
will be a list of one or more ints, and the accumulate attribute will be
either the sum() function, if –sum was specified at the command line,
or the max() function if it was not.
Parsing arguments¶
ArgumentParser parses arguments through the
parse_args() 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 Namespace object will be built up from
attributes parsed out of the command line:
>>> rse_args([‘–sum’, ‘7’, ‘-1′, ’42’])
Namespace(accumulate=
In a script, parse_args() will typically be called with no
arguments, and the ArgumentParser will automatically determine the
command-line arguments from
ArgumentParser objects¶
class gumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], Formatter, prefix_chars=’-‘, fromfile_prefix_chars=None, argument_default=None, conflict_handler=’error’, add_help=True, allow_abbrev=True, exit_on_error=True)¶
Create a new ArgumentParser object. All parameters should be passed
as keyword arguments. Each parameter has its own more detailed description
below, but in short they are:
prog – The name of the program (default: [0])
usage – The string describing the program usage (default: generated from
arguments added to parser)
description – Text to display before the argument help (default: none)
epilog – Text to display after the argument help (default: none)
parents – A list of ArgumentParser objects whose arguments should
also be included
formatter_class – A class for customizing the help output
prefix_chars – The set of characters that prefix optional arguments
(default: ‘-‘)
fromfile_prefix_chars – The set of characters that prefix files from
which additional arguments should be read (default: None)
argument_default – The global default value for arguments
(default: None)
conflict_handler – The strategy for resolving conflicting optionals
(usually unnecessary)
add_help – Add a -h/–help option to the parser (default: True)
allow_abbrev – Allows long options to be abbreviated if the
abbreviation is unambiguous. (default: True)
exit_on_error – Determines whether or not ArgumentParser exits with
error info when an error occurs. (default: True)
Changed in version 3. 5: allow_abbrev parameter was added.
Changed in version 3. 8: In previous versions, allow_abbrev also disabled grouping of short
flags such as -vv to mean -v -v.
Changed in version 3. 9: exit_on_error parameter was added.
The following sections describe how each of these are used.
prog¶
By default, ArgumentParser objects use [0] 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
with the following code:
parser = gumentParser()
d_argument(‘–foo’, help=’foo help’)
The help for this program will display as the program name
(regardless of where the program was invoked from):
$ python –help
usage: [-h] [–foo FOO]
–foo FOO foo help
$ cd..
$ python subdir/ –help
To change this default behavior, another value can be supplied using the
prog= argument to ArgumentParser:
>>> parser = gumentParser(prog=’myprogram’)
>>> int_help()
usage: myprogram [-h]
Note that the program name, whether determined from [0] or from the
prog= argument, is available to help messages using the%(prog)s format
specifier.
>>> d_argument(‘–foo’, help=’foo of the%(prog)s program’)
usage: myprogram [-h] [–foo FOO]
–foo FOO foo of the myprogram program
usage¶
By default, ArgumentParser calculates the usage message from the
arguments it contains:
>>> parser = gumentParser(prog=’PROG’)
>>> d_argument(‘–foo’, nargs=’? ‘, help=’foo help’)
>>> d_argument(‘bar’, nargs=’+’, help=’bar help’)
usage: PROG [-h] [–foo [FOO]] bar [bar… ]
bar bar help
–foo [FOO] foo help
The default message can be overridden with the usage= keyword argument:
>>> parser = gumentParser(prog=’PROG’, usage=’%(prog)s [options]’)
usage: PROG [options]
The%(prog)s format specifier is available to fill in the program name in
your usage messages.
description¶
Most calls to the ArgumentParser constructor will use the
description= 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:
>>> parser = gumentParser(description=’A foo that bars’)
usage: [-h]
A foo that bars
By default, the description will be line-wrapped so that it fits within the
given space. To change this behavior, see the formatter_class argument.
epilog¶
Some programs like to display additional description of the program after the
description of the arguments. Such text can be specified using the epilog=
argument to ArgumentParser:
>>> parser = gumentParser(… description=’A foo that bars’,… epilog=”And that’s how you’d foo a bar”)
And that’s how you’d foo a bar
As with the description argument, the epilog= text is by default
line-wrapped, but this behavior can be adjusted with the formatter_class
argument to ArgumentParser.
parents¶
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 parents= argument to ArgumentParser
can be used. The parents= argument takes a list of ArgumentParser
objects, collects all the positional and optional actions from them, and adds
these actions to the ArgumentParser object being constructed:
>>> parent_parser = gumentParser(add_help=False)
>>> d_argument(‘–parent’, type=int)
>>> foo_parser = gumentParser(parents=[parent_parser])
>>> d_argument(‘foo’)
>>> rse_args([‘–parent’, ‘2’, ‘XXX’])
Namespace(foo=’XXX’, parent=2)
>>> bar_parser = gumentParser(parents=[parent_parser])
>>> d_argument(‘–bar’)
>>> rse_args([‘–bar’, ‘YYY’])
Namespace(bar=’YYY’, parent=None)
Note that most parent parsers will specify add_help=False. Otherwise, the
ArgumentParser will see two -h/–help options (one in the parent
and one in the child) and raise an error.
Note
You must fully initialize the parsers before passing them via parents=.
If you change the parent parsers after the child parser, those changes will
not be reflected in the child.
formatter_class¶
ArgumentParser objects allow the help formatting to be customized by
specifying an alternate formatting class. Currently, there are four such
classes:
class argparse. RawDescriptionHelpFormatter¶
class argparse. RawTextHelpFormatter¶
class gumentDefaultsHelpFormatter¶
class tavarTypeHelpFormatter¶
RawDescriptionHelpFormatter and RawTextHelpFormatter give
more control over how textual descriptions are displayed.
By default, ArgumentParser objects line-wrap the description and
epilog texts in command-line help messages:
>>> parser = gumentParser(… prog=’PROG’,… description=”’this description… was indented weird… but that is okay”’,… epilog=”’… likewise for this epilog whose whitespace will… be cleaned up and whose words will be wrapped… across a couple lines”’)
usage: PROG [-h]
this description was indented weird but that is okay
likewise for this epilog whose whitespace will be cleaned up and whose words
will be wrapped across a couple lines
Passing RawDescriptionHelpFormatter as formatter_class=
indicates that description and epilog are already correctly formatted and
should not be line-wrapped:
>>> parser = gumentParser(… formatter_class=argparse. RawDescriptionHelpFormatter,… (”’\… Please do not mess up this text!… ——————————–… I have indented it… exactly the way… I want it… ”’))
Please do not mess up this text!
——————————–
I have indented it
exactly the way
I want it
RawTextHelpFormatter 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.
ArgumentDefaultsHelpFormatter automatically adds information about
default values to each of the argument help messages:
>>> parser = gumentParser(… gumentDefaultsHelpFormatter)
>>> d_argument(‘–foo’, type=int, default=42, help=’FOO! ‘)
>>> d_argument(‘bar’, nargs=’*’, default=[1, 2, 3], help=’BAR! ‘)
usage: PROG [-h] [–foo FOO] [bar… ]
bar BAR! (default: [1, 2, 3])
–foo FOO FOO! (default: 42)
MetavarTypeHelpFormatter uses the name of the type argument for each
argument as the display name for its values (rather than using the dest
as the regular formatter does):
>>> parser = gumentParser(… tavarTypeHelpFormatter)
>>> d_argument(‘–foo’, type=int)
>>> d_argument(‘bar’, type=float)
usage: PROG [-h] [–foo int] float
float
–foo int
prefix_chars¶
Most command-line options will use – as the prefix, e. g. -f/–foo.
Parsers that need to support different or additional prefix
characters, e. for options
like +f or /foo, may specify them using the prefix_chars= argument
to the ArgumentParser constructor:
>>> parser = gumentParser(prog=’PROG’, prefix_chars=’-+’)
>>> d_argument(‘+f’)
>>> d_argument(‘++bar’)
>>> rse_args(‘+f X ++bar Y'())
Namespace(bar=’Y’, f=’X’)
The prefix_chars= argument defaults to ‘-‘. Supplying a set of
characters that does not include – will cause -f/–foo options to be
disallowed.
fromfile_prefix_chars¶
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 fromfile_prefix_chars= argument is given to the
ArgumentParser 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:
>>> with open(”, ‘w’) as fp:… (‘-f\nbar’)
>>> parser = gumentParser(fromfile_prefix_chars=’@’)
>>> d_argument(‘-f’)
>>> rse_args([‘-f’, ‘foo’, ”])
Namespace(f=’bar’)
Arguments read from a file must by default be one per line (but see also
convert_arg_line_to_args()) 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 [‘-f’, ‘foo’, ”]
is considered equivalent to the expression [‘-f’, ‘foo’, ‘-f’, ‘bar’].
The fromfile_prefix_chars= argument defaults to None, meaning that
arguments will never be treated as file references.
argument_default¶
Generally, argument defaults are specified either by passing a default to
add_argument() or by calling the
set_defaults() 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
argument_default= keyword argument to ArgumentParser. For example,
to globally suppress attribute creation on parse_args()
calls, we supply argument_default=SUPPRESS:
>>> parser = gumentParser(PPRESS)
>>> d_argument(‘–foo’)
>>> d_argument(‘bar’, nargs=’? ‘)
>>> rse_args([‘–foo’, ‘1’, ‘BAR’])
Namespace(bar=’BAR’, foo=’1′)
>>> rse_args([])
Namespace()
allow_abbrev¶
Normally, when you pass an argument list to the
parse_args() method of an ArgumentParser,
it recognizes abbreviations of long options.
This feature can be disabled by setting allow_abbrev to False:
>>> parser = gumentParser(prog=’PROG’, allow_abbrev=False)
>>> d_argument(‘–foobar’, action=’store_true’)
>>> d_argument(‘–foonley’, action=’store_false’)
>>> rse_args([‘–foon’])
usage: PROG [-h] [–foobar] [–foonley]
PROG: error: unrecognized arguments: –foon
New in version 3. 5.
conflict_handler¶
ArgumentParser objects do not allow two actions with the same option
string. By default, ArgumentParser objects raise an exception if an
attempt is made to create an argument with an option string that is already in
use:
>>> d_argument(‘-f’, ‘–foo’, help=’old foo help’)
>>> d_argument(‘–foo’, help=’new foo help’)
Traceback (most recent call last):..
ArgumentError: argument –foo: conflicting option string(s): –foo
Sometimes (e. when using parents) it may be useful to simply override any
older arguments with the same option string. To get this behavior, the value
‘resolve’ can be supplied to the conflict_handler= argument of
ArgumentParser:
>>> parser = gumentParser(prog=’PROG’, conflict_handler=’resolve’)
usage: PROG [-h] [-f FOO] [–foo FOO]
-f FOO old foo help
–foo FOO new foo help
Note that ArgumentParser objects only remove an action if all of its
option strings are overridden. So, in the example above, the old -f/–foo
action is retained as the -f action, because only the –foo option
string was overridden.
add_help¶
By default, ArgumentParser objects add an option which simply displays
the parser’s help message. For example, consider a file named
containing the following code:
If -h or –help is supplied at the command line, the ArgumentParser
help will be printed:
Occasionally, it may be useful to disable the addition of this help option.
This can be achieved by passing False as the add_help= argument to
>>> parser = gumentParser(prog=’PROG’, add_help=False)
>>> d_argument(‘–foo’, help=’foo help’)
usage: PROG [–foo FOO]
The help option is typically -h/–help. The exception to this is
if the prefix_chars= is specified and does not include -, in
which case -h and –help are not valid options. In
this case, the first character in prefix_chars is used to prefix
the help options:
>>> parser = gumentParser(prog=’PROG’, prefix_chars=’+/’)
usage: PROG [+h]
+h, ++help show this help message and exit
exit_on_error¶
Normally, when you pass an invalid argument list to the parse_args()
method of an ArgumentParser, it will exit with error info.
If the user would like to catch errors manually, the feature can be enabled by setting
exit_on_error to False:
>>> parser = gumentParser(exit_on_error=False)
>>> d_argument(‘–integers’, type=int)
_StoreAction(option_strings=[‘–integers’], dest=’integers’, nargs=None, const=None, default=None, type=
>>> try:… rse_args(‘–integers a'())… except gumentError:… print(‘Catching an argumentError’)…
Catching an argumentError
New in version 3. 9.
The add_argument() method¶
d_argument(name or flags… [, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])¶
Define how a single command-line argument should be parsed. Each parameter
has its own more detailed description below, but in short they are:
name or flags – Either a name or a list of option strings, e. foo
or -f, –foo.
action – The basic type of action to be taken when this argument is
encountered at the command line.
nargs – The number of command-line arguments that should be consumed.
const – A constant value required by some action and nargs selections.
default – The value produced if the argument is absent from the
command line and if it is absent from the namespace object.
type – The type to which the command-line argument should be converted.
choices – A container of the allowable values for the argument.
required – Whether or not the command-line option may be omitted
(optionals only).
help – A brief description of what the argument does.
metavar – A name for the argument in usage messages.
dest – The name of the attribute to be added to the object returned by
parse_args().
name or flags¶
The add_argument() method must know whether an optional
argument, like -f or –foo, or a positional argument, like a list of
filenames, is expected. The first arguments passed to
add_argument() must therefore be either a series of
flags, or a simple argument name. For example, an optional argument could
be created like:
>>> d_argument(‘-f’, ‘–foo’)
while a positional argument could be created like:
>>> d_argument(‘bar’)
When parse_args() is called, optional arguments will be
identified by the – prefix, and the remaining arguments will be assumed to
be positional:
>>> rse_args([‘BAR’])
Namespace(bar=’BAR’, foo=None)
>>> rse_args([‘BAR’, ‘–foo’, ‘FOO’])
Namespace(bar=’BAR’, foo=’FOO’)
>>> rse_args([‘–foo’, ‘FOO’])
usage: PROG [-h] [-f FOO] bar
PROG: error: the following arguments are required: bar
action¶
ArgumentParser 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
parse_args(). The action keyword argument specifies
how the command-line arguments should be handled. The supplied actions are:
‘store’ – This just stores the argument’s value. This is the default
action. For example:
>>> parser = gumentParser()
>>> rse_args(‘–foo 1′())
Namespace(foo=’1’)
‘store_const’ – This stores the value specified by the const keyword
argument. The ‘store_const’ action is most commonly used with
optional arguments that specify some sort of flag. For example:
>>> d_argument(‘–foo’, action=’store_const’, const=42)
>>> rse_args([‘–foo’])
Namespace(foo=42)
‘store_true’ and ‘store_false’ – These are special cases of
‘store_const’ used for storing the values True and False
respectively. In addition, they create default values of False and
True respectively. For example:
>>> d_argument(‘–foo’, action=’store_true’)
>>> d_argument(‘–bar’, action=’store_false’)
>>> d_argument(‘–baz’, action=’store_false’)
>>> rse_args(‘–foo –bar'())
Namespace(foo=True, bar=False, baz=True)
‘append’ – 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:
>>> d_argument(‘–foo’, action=’append’)
>>> rse_args(‘–foo 1 –foo 2′())
Namespace(foo=[‘1’, ‘2’])
‘append_const’ – This stores a list, and appends the value specified by
the const keyword argument to the list. (Note that the const keyword
argument defaults to None. ) The ‘append_const’ action is typically
useful when multiple arguments need to store constants to the same list. For
example:
>>> d_argument(‘–str’, dest=’types’, action=’append_const’, const=str)
>>> d_argument(‘–int’, dest=’types’, action=’append_const’, const=int)
>>> rse_args(‘–str –int'())
Namespace(types=[
‘count’ – This counts the number of times a keyword argument occurs. For
example, this is useful for increasing verbosity levels:
>>> d_argument(‘–verbose’, ‘-v’, action=’count’, default=0)
>>> rse_args([‘-vvv’])
Namespace(verbose=3)
Note, the default will be None unless explicitly set to 0.
‘help’ – 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 ArgumentParser for details of how the
output is created.
‘version’ – This expects a version= keyword argument in the
add_argument() call, and prints version information
and exits when invoked:
>>> import argparse
>>> d_argument(‘–version’, action=’version’, version=’%(prog)s 2. 0′)
>>> rse_args([‘–version’])
PROG 2. 0
‘extend’ – This stores a list, and extends each argument value to the
list.
>>> d_argument(“–foo”, action=”extend”, nargs=”+”, type=str)
>>> rse_args([“–foo”, “f1”, “–foo”, “f2”, “f3”, “f4”])
Namespace(foo=[‘f1’, ‘f2’, ‘f3’, ‘f4’])
New in version 3. 8.
You may also specify an arbitrary action by passing an Action subclass or
other object that implements the same interface. The BooleanOptionalAction
is available in argparse and adds support for boolean actions such as
–foo and –no-foo:
>>> d_argument(‘–foo’, oleanOptionalAction)
>>> rse_args([‘–no-foo’])
Namespace(foo=False)
The recommended way to create a custom action is to extend Action,
overriding the __call__ method and optionally the __init__ and
format_usage methods.
An example of a custom action:
>>> class FooAction():… def __init__(self, option_strings, dest, nargs=None, **kwargs):… if nargs is not None:… raise ValueError(“nargs not allowed”)… super(). __init__(option_strings, dest, **kwargs)… def __call__(self, parser, namespace, values, option_string=None):… print(‘%r%r%r’% (namespace, values, option_string))… setattr(namespace,, values)…
>>> d_argument(‘–foo’, action=FooAction)
>>> d_argument(‘bar’, action=FooAction)
>>> args = rse_args(‘1 –foo 2′())
Namespace(bar=None, foo=None) ‘1’ None
Namespace(bar=’1′, foo=None) ‘2’ ‘–foo’
>>> args
Namespace(bar=’1′, foo=’2′)
For more details, see Action.
nargs¶
ArgumentParser objects usually associate a single command-line argument with a
single action to be taken. The nargs keyword argument associates a
different number of command-line arguments with a single action. The supported
values are:
N (an integer). N arguments from the command line will be gathered
together into a list. For example:
>>> d_argument(‘–foo’, nargs=2)
>>> d_argument(‘bar’, nargs=1)
>>> rse_args(‘c –foo a b'())
Namespace(bar=[‘c’], foo=[‘a’, ‘b’])
Note that nargs=1 produces a list of one item. This is different from
the default, in which the item is produced by itself.
‘? ‘. 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
default 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 const will be produced. Some
examples to illustrate this:
>>> d_argument(‘–foo’, nargs=’? ‘, const=’c’, default=’d’)
>>> d_argument(‘bar’, nargs=’? ‘, default=’d’)
>>> rse_args([‘XX’, ‘–foo’, ‘YY’])
Namespace(bar=’XX’, foo=’YY’)
>>> rse_args([‘XX’, ‘–foo’])
Namespace(bar=’XX’, foo=’c’)
Namespace(bar=’d’, foo=’d’)
One of the more common uses of nargs=’? ‘ is to allow optional input and
output files:
>>> d_argument(‘infile’, nargs=’? ‘, leType(‘r’),… )
>>> d_argument(‘outfile’, nargs=’? ‘, leType(‘w’),… )
>>> rse_args([”, ”])
Namespace(infile=<_io. TextIOWrapper name='' encoding='UTF-8'>,
outfile=<_io. TextIOWrapper name='' encoding='UTF-8'>)
Namespace(infile=<_io. TextIOWrapper name='
outfile=<_io. TextIOWrapper name='
‘*’. 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 nargs=’*’, but multiple optional arguments with nargs=’*’ is
possible. For example:
>>> d_argument(‘–foo’, nargs=’*’)
>>> d_argument(‘–bar’, nargs=’*’)
>>> d_argument(‘baz’, nargs=’*’)
>>> rse_args(‘a b –foo x y –bar 1 2′())
Namespace(bar=[‘1’, ‘2’], baz=[‘a’, ‘b’], foo=[‘x’, ‘y’])
‘+’. Just like ‘*’, 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:
>>> d_argument(‘foo’, nargs=’+’)
>>> rse_args([‘a’, ‘b’])
Namespace(foo=[‘a’, ‘b’])
usage: PROG [-h] foo [foo… ]
PROG: error: the following arguments are required: foo
If the nargs keyword argument is not provided, the number of arguments consumed
is determined by the action. Generally this means a single command-line argument
will be consumed and a single item (not a list) will be produced.
const¶
The const argument of add_argument() is used to hold
constant values that are not read from the command line but are required for
the various ArgumentParser actions. The two most common uses of it are:
When add_argument() is called with
action=’store_const’ or action=’append_const’. These actions add the
const value to one of the attributes of the object returned by
parse_args(). See the action description for examples.
When add_argument() is called with option strings
(like -f or –foo) and nargs=’? ‘. 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 const will be assumed instead.
See the nargs description for examples.
With the ‘store_const’ and ‘append_const’ actions, the const
keyword argument must be given. For other actions, it defaults to None.
default¶
All optional arguments and some positional arguments may be omitted at the
command line. The default keyword argument of
add_argument(), whose value defaults to None,
specifies what value should be used if the command-line argument is not present.
For optional arguments, the default value is used when the option string
was not present at the command line:
>>> d_argument(‘–foo’, default=42)
>>> rse_args([‘–foo’, ‘2’])
Namespace(foo=’2′)
If the target namespace already has an attribute set, the action default
will not over write it:
>>> rse_args([], mespace(foo=101))
Namespace(foo=101)
If the default value is a string, the parser parses the value as if it
were a command-line argument. In particular, the parser applies any type
conversion argument, if provided, before setting the attribute on the
Namespace return value. Otherwise, the parser uses the value as is:
>>> d_argument(‘–length’, default=’10’, type=int)
>>> d_argument(‘–width’, default=10. 5, type=int)
>>> rse_args()
Namespace(length=10, width=10. 5)
For positional arguments with nargs equal to? or *, the default value
is used when no command-line argument was present:
>>> d_argument(‘foo’, nargs=’? ‘, default=42)
>>> rse_args([‘a’])
Namespace(foo=’a’)
Providing PPRESS causes no attribute to be added if the
command-line argument was not present:
>>> d_argument(‘–foo’, PPRESS)
>>> rse_args([‘–foo’, ‘1’])
type¶
By default, the parser reads command-line arguments in as simple
strings. However, quite often the command-line string should instead be
interpreted as another type, such as a float or int. The
type keyword for add_argument() allows any
necessary type-checking and type conversions to be performed.
If the type keyword is used with the default keyword, the type converter
is only applied if the default is a string.
The argument to type can be any callable that accepts a single string.
If the function raises ArgumentTypeError, TypeError, or
ValueError, the exception is caught and a nicely formatted error
message is displayed. No other exception types are handled.
Common built-in types and functions can be used as type converters:
import pathlib
d_argument(‘count’, type=int)
d_argument(‘distance’, type=float)
d_argument(‘street’, type=ascii)
d_argument(‘code_point’, type=ord)
d_argument(‘source_file’, type=open)
d_argument(‘dest_file’, leType(‘w’, encoding=’latin-1′))
d_argument(‘datapath’, )
User defined functions can be used as well:
>>> def hyphenated(string):… return ‘-‘([word[:4] for word in sefold()()])…
>>> _ = d_argument(‘short_title’, type=hyphenated)
>>> rse_args([‘”The Tale of Two Cities”‘])
Namespace(short_title='”the-tale-of-two-citi’)
The bool() function is not recommended as a type converter. All it does
is convert empty strings to False and non-empty strings to True.
This is usually not what is desired.
In general, the type keyword is a convenience that should only be used for
simple conversions that can only raise one of the three supported exceptions.
Anything with more interesting error-handling or resource management should be
done downstream after the arguments are parsed.
For example, JSON or YAML conversions have complex error cases that require
better reporting than can be given by the type keyword. A
JSONDecodeError would not be well formatted and a
FileNotFound exception would not be handled at all.
Even FileType has its limitations for use with the type
keyword. If one argument uses FileType and then a subsequent argument fails,
an error is reported but the file is not automatically closed. In this case, it
would be better to wait until after the parser has run and then use the
with-statement to manage the files.
For type checkers that simply check against a fixed set of values, consider
using the choices keyword instead.
choices¶
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 add_argument(). 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:
>>> parser = gumentParser(prog=”)
>>> d_argument(‘move’, choices=[‘rock’, ‘paper’, ‘scissors’])
>>> rse_args([‘rock’])
Namespace(move=’rock’)
>>> rse_args([‘fire’])
usage: [-h] {rock, paper, scissors}
error: argument move: invalid choice: ‘fire’ (choose from ‘rock’,
‘paper’, ‘scissors’)
Note that inclusion in the choices container is checked after any type
conversions have been performed, so the type of the objects in the choices
container should match the type specified:
>>> d_argument(‘door’, type=int, choices=range(1, 4))
>>> print(rse_args([‘3’]))
Namespace(door=3)
>>> rse_args([‘4’])
usage: [-h] {1, 2, 3}
error: argument door: invalid choice: 4 (choose from 1, 2, 3)
Any container can be passed as the choices value, so list objects,
set objects, and custom containers are all supported.
Use of is not recommended because it is difficult to
control its appearance in usage, help, and error messages.
Formatted choices overrides the default metavar which is normally derived
from dest. This is usually what you want because the user never sees the
dest parameter. If this display isn’t desirable (perhaps because there are
many choices), just specify an explicit metavar.
required¶
In general, the argparse module assumes that flags like -f and —
parser — Access Python parse trees — Python 3.7.12 …
The parser module provides an interface to Python’s internal parser and
byte-code compiler. The primary purpose for this interface is to allow Python
code to edit the parse tree of a Python expression and create executable code
from this. This is better than trying to parse and modify an arbitrary Python
code fragment as a string because parsing is performed in a manner identical to
the code forming the application. It is also faster.
Note
From Python 2. 5 onward, it’s much more convenient to cut in at the Abstract
Syntax Tree (AST) generation and compilation stage, using the ast
module.
There are a few things to note about this module which are important to making
use of the data structures created. This is not a tutorial on editing the parse
trees for Python code, but some examples of using the parser module are
presented.
Most importantly, a good understanding of the Python grammar processed by the
internal parser is required. For full information on the language syntax, refer
to The Python Language Reference. The parser
itself is created from a grammar specification defined in the file
Grammar/Grammar in the standard Python distribution. The parse trees
stored in the ST objects created by this module are the actual output from the
internal parser when created by the expr() or suite() functions,
described below. The ST objects created by sequence2st() faithfully
simulate those structures. Be aware that the values of the sequences which are
considered “correct” will vary from one version of Python to another as the
formal grammar for the language is revised. However, transporting code from one
Python version to another as source text will always allow correct parse trees
to be created in the target version, with the only restriction being that
migrating to an older version of the interpreter will not support more recent
language constructs. The parse trees are not typically compatible from one
version to another, though source code has usually been forward-compatible within
a major release series.
Each element of the sequences returned by st2list() or st2tuple()
has a simple form. Sequences representing non-terminal elements in the grammar
always have a length greater than one. The first element is an integer which
identifies a production in the grammar. These integers are given symbolic names
in the C header file Include/graminit. h and the Python module
symbol. Each additional element of the sequence represents a component
of the production as recognized in the input string: these are always sequences
which have the same form as the parent. An important aspect of this structure
which should be noted is that keywords used to identify the parent node type,
such as the keyword if in an if_stmt, are included in the
node tree without any special treatment. For example, the if keyword
is represented by the tuple (1, ‘if’), where 1 is the numeric value
associated with all NAME tokens, including variable and function names
defined by the user. In an alternate form returned when line number information
is requested, the same token might be represented as (1, ‘if’, 12), where
the 12 represents the line number at which the terminal symbol was found.
Terminal elements are represented in much the same way, but without any child
elements and the addition of the source text which was identified. The example
of the if keyword above is representative. The various types of
terminal symbols are defined in the C header file Include/token. h and
the Python module token.
The ST objects are not required to support the functionality of this module,
but are provided for three purposes: to allow an application to amortize the
cost of processing complex parse trees, to provide a parse tree representation
which conserves memory space when compared to the Python list or tuple
representation, and to ease the creation of additional modules in C which
manipulate parse trees. A simple “wrapper” class may be created in Python to
hide the use of ST objects.
The parser module defines functions for a few distinct purposes. The
most important purposes are to create ST objects and to convert ST objects to
other representations such as parse trees and compiled code objects, but there
are also functions which serve to query the type of parse tree represented by an
ST object.
See also
Module symbolUseful constants representing internal nodes of the parse tree.
Module tokenUseful constants representing leaf nodes of the parse tree and functions for
testing node values.
Creating ST Objects¶
ST objects may be created from source code or from a parse tree. When creating
an ST object from source, different functions are used to create the ‘eval’
and ‘exec’ forms.
(source)¶
The expr() function parses the parameter source as if it were an input
to compile(source, ”, ‘eval’). If the parse succeeds, an ST object
is created to hold the internal parse tree representation, otherwise an
appropriate exception is raised.
The suite() function parses the parameter source as if it were an input
to compile(source, ”, ‘exec’). If the parse succeeds, an ST object
quence2st(sequence)¶
This function accepts a parse tree represented as a sequence and builds an
internal representation if possible. If it can validate that the tree conforms
to the Python grammar and all nodes are valid node types in the host version of
Python, an ST object is created from the internal representation and returned
to the called. If there is a problem creating the internal representation, or
if the tree cannot be validated, a ParserError exception is raised. An
ST object created this way should not be assumed to compile correctly; normal
exceptions raised by compilation may still be initiated when the ST object is
passed to compilest(). This may indicate problems not related to syntax
(such as a MemoryError exception), but may also be due to constructs such
as the result of parsing del f(0), which escapes the Python parser but is
checked by the bytecode compiler.
Sequences representing terminal tokens may be represented as either two-element
lists of the form (1, ‘name’) or as three-element lists of the form (1,
‘name’, 56). If the third element is present, it is assumed to be a valid
line number. The line number may be specified for any subset of the terminal
symbols in the input tree.
parser. tuple2st(sequence)¶
This is the same function as sequence2st(). This entry point is
maintained for backward compatibility.
Converting ST Objects¶
ST objects, regardless of the input used to create them, may be converted to
parse trees represented as list- or tuple- trees, or may be compiled into
executable code objects. Parse trees may be extracted with or without line
numbering information.
2list(st, line_info=False, col_info=False)¶
This function accepts an ST object from the caller in st and returns a
Python list representing the equivalent parse tree. The resulting list
representation can be used for inspection or the creation of a new parse tree in
list form. This function does not fail so long as memory is available to build
the list representation. If the parse tree will only be used for inspection,
st2tuple() should be used instead to reduce memory consumption and
fragmentation. When the list representation is required, this function is
significantly faster than retrieving a tuple representation and converting that
to nested lists.
If line_info is true, line number information will be included for all
terminal tokens as a third element of the list representing the token. Note
that the line number provided specifies the line on which the token ends.
This information is omitted if the flag is false or omitted.
2tuple(st, line_info=False, col_info=False)¶
Python tuple representing the equivalent parse tree. Other than returning a
tuple instead of a list, this function is identical to st2list().
terminal tokens as a third element of the list representing the token. This
information is omitted if the flag is false or omitted.
mpilest(st, filename=’
The Python byte compiler can be invoked on an ST object to produce code objects
which can be used as part of a call to the built-in exec() or eval()
functions. This function provides the interface to the compiler, passing the
internal parse tree from st to the parser, using the source file name
specified by the filename parameter. The default value supplied for filename
indicates that the source was an ST object.
Compiling an ST object may result in exceptions related to compilation; an
example would be a SyntaxError caused by the parse tree for del f(0):
this statement is considered legal within the formal grammar for Python but is
not a legal language construct. The SyntaxError raised for this
condition is actually generated by the Python byte-compiler normally, which is
why it can be raised at this point by the parser module. Most causes of
compilation failure can be diagnosed programmatically by inspection of the parse
tree.
Queries on ST Objects¶
Two functions are provided which allow an application to determine if an ST was
created as an expression or a suite. Neither of these functions can be used to
determine if an ST was created from source code via expr() or
suite() or from a parse tree via sequence2st().
(st)¶
When st represents an ‘eval’ form, this function returns True, otherwise
it returns False. This is useful, since code objects normally cannot be queried
for this information using existing built-in functions. Note that the code
objects created by compilest() cannot be queried like this either, and
are identical to those created by the built-in compile() function.
suite(st)¶
This function mirrors isexpr() in that it reports whether an ST object
represents an ‘exec’ form, commonly known as a “suite. ” It is not safe to
assume that this function is equivalent to not isexpr(st), as additional
syntactic fragments may be supported in the future.
Exceptions and Error Handling¶
The parser module defines a single exception, but may also pass other built-in
exceptions from other portions of the Python runtime environment. See each
function for information about the exceptions it can raise.
exception rserError¶
Exception raised when a failure occurs within the parser module. This is
generally produced for validation failures rather than the built-in
SyntaxError raised during normal parsing. The exception argument is
either a string describing the reason of the failure or a tuple containing a
sequence causing the failure from a parse tree passed to sequence2st()
and an explanatory string. Calls to sequence2st() need to be able to
handle either type of exception, while calls to other functions in the module
will only need to be aware of the simple string values.
Note that the functions compilest(), expr(), and suite() may
raise exceptions which are normally raised by the parsing and compilation
process. These include the built in exceptions MemoryError,
OverflowError, SyntaxError, and SystemError. In these
cases, these exceptions carry all the meaning normally associated with them.
Refer to the descriptions of each function for detailed information.
ST Objects¶
Ordered and equality comparisons are supported between ST objects. Pickling of
ST objects (using the pickle module) is also supported.
¶
The type of the objects returned by expr(), suite() and
sequence2st().
ST objects have the following methods:
mpile(filename=’
Same as compilest(st, filename).
()¶
Same as isexpr(st).
suite()¶
Same as issuite(st).
(line_info=False, col_info=False)¶
Same as st2list(st, line_info, col_info).
tuple(line_info=False, col_info=False)¶
Same as st2tuple(st, line_info, col_info).
Example: Emulation of compile()¶
While many useful operations may take place between parsing and bytecode
generation, the simplest operation is to do nothing. For this purpose, using
the parser module to produce an intermediate data structure is equivalent
to the code
>>> code = compile(‘a + 5’, ”, ‘eval’)
>>> a = 5
>>> eval(code)
10
The equivalent operation using the parser module is somewhat longer, and
allows the intermediate internal parse tree to be retained as an ST object:
>>> import parser
>>> st = (‘a + 5’)
>>> code = mpile(”)
An application which needs both ST and code objects can package this code into
readily available functions:
import parser
def load_suite(source_string):
st = (source_string)
return st, mpile()
def load_expression(source_string):
return st, mpile()
Python Parser | Working of Python Parse with different Examples
Introduction to Python Parser
In this article, parsing is defined as the processing of a piece of python program and converting these codes into machine language. In general, we can say parse is a command for dividing the given program code into a small piece of code for analyzing the correct syntax. In Python, there is a built-in module called parse which provides an interface between the Python internal parser and compiler, where this module allows the python program to edit the small fragments of code and create the executable program from this edited parse tree of python code. In Python, there is another module known as argparse to parse command-line options.
Working of Python Parse with Examples
In this article, Python parser is mainly used for converting data in the required format, this conversion process is known as parsing. As in many different applications data obtained can have different data formats and these formats might not be suitable to the particular application and here comes the use of parser that means parsing is necessary for such situations. Therefore, parsing is generally defined as the conversion of data with one format to some other format is known as parsing. In parser consists of two parts lexer and a parser and in some cases only parsers are used.
Python parsing is done using various ways such as the use of parser module, parsing using regular expressions, parsing using some string methods such as split() and strip(), parsing using pandas such as reading CSV file to text by using, etc. There is also a concept of argument parsing which means in Python, we have a module named argparse which is used for parsing data with one or more arguments from the terminal or command-line. There are other different modules when working with argument parsings such as getopt, sys, and argparse modules. Now let us below the demonstration for Python parser. In Python, the parser can also be created using few tools such as parser generators and there is a library known as parser combinators that are used for creating parsers.
Now let us see in the below example of how the parser module is used for parsing the given expressions.
Example #1
Code:
import parser
print(“Program to demonstrate parser module in Python”)
print(“\n”)
exp = “5 + 8”
print(“The given expression for parsing is as follows:”)
print(exp)
print(“Parsing of given expression results as: “)
st = (exp)
print(st)
print(“The parsed object is converted to the code object”)
code = mpile()
print(code)
print(“The evaluated result of the given expression is as follows:”)
res = eval(code)
print(res)
Output:
In the above program, we first need to import the parser module, and then we have declared expression to calculate, and to parse this expression we have to use a () function. Then we can evaluate the given expression using eval() function.
In Python, sometimes we get data that consists of date-time format which would be in CSV format or text format. So to parse such formats in proper date-time formats Python provides parse_dates() function. Suppose we have a CSV file that contains data and the data time details are separated with a comma which makes it difficult for reading therefore for such cases we use parse_dates() but before that, we have to import pandas as this function is provided by pandas.
In Python, we can also parse command-line options and arguments using an argparse module which is very user friendly for the command-line interface. Suppose we have Unix commands to execute through python command-line interface such as ls which list all the directories in the current drive and it will take many different arguments also therefore to create such command-line interface we use an argparse module in Python. Therefore, to create a command-line interface in Python we need to do the following; firstly, we have to import an argparse module, then we create an object for holding arguments using ArgumentParser() through the argparse module, later we can add arguments the ArgumentParser() object that will be created and we can run any commands in Python command line. Note as running any commands is not free other than the help command. So here is a small piece of code for how to write the python code to create a command line interface using an argparse module.
import argparse
Now we have created an object using ArgumentParser() and then we can parse the arguments using rse_args() function.
parser = gumentParser()
rse_args()
To add the arguments we can use add_argument() along with passing the argument to this function such as d_argument(“ ls ”). So let us see a small example below.
Example #2
d_argument(“ls”)
args = rse_args()
print()
So in the above program, we can see the screenshot of the output as we cannot use any other commands so it will give an error but when we have an argparse module then we can run the commands in python shell as follows:
$ python –help
usage: [-h] echo
Positional Arguments:
echo
Optional Arguments:
-h, –helpshow this help message and exit
$ python Educba
Educba
Conclusion
In this article, we conclude that Python provides a parsing concept. In this article, we saw that the parsing process is very simple which in general is the process of parting the large string of one type of format for converting this format to another required format is known as parsing. This is done in many different ways in Python using python string methods such as split() or strip(), using python pandas for converting CSV files to text format. In this, we saw that we can even use a parser module for using it as a command-line interface where we can run the commands easily using the argparse module in Python. In the above, we saw how to use argparse and how can we run the commands in Python terminal.
Recommended Articles
This is a guide to Python Parser. Here we also discuss the introduction and working of python parser along with different examples and its code implementation. You may also have a look at the following articles to learn more –
Python Timezone
Python NameError
Python OS Module
Python Event Loop
Frequently Asked Questions about parser python
What is a parser in Python?
The parser module provides an interface to Python’s internal parser and byte-code compiler. The primary purpose for this interface is to allow Python code to edit the parse tree of a Python expression and create executable code from this.Sep 6, 2021
What does parse () do in Python?
In this article, parsing is defined as the processing of a piece of python program and converting these codes into machine language. In general, we can say parse is a command for dividing the given program code into a small piece of code for analyzing the correct syntax.
What kind of parser does Python use?
Debugging generated parsers As the generated C parser is the one used by Python, this means that if something goes wrong when adding some new rules to the grammar you cannot correctly compile and execute Python anymore.
