Source code: Lib/abc.py
This module provides the infrastructure for defining abstract base classes (ABCs) in Python, as outlined in PEP 3119; see the PEP for why this was added to Python. (See also PEP 3141 and the numbers module regarding a type hierarchy for numbers based on ABCs.)
The collections module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition, the collections.abc submodule has some ABCs that can be used to test whether a class or instance provides a particular interface, for example, if it is hashable or if it is a mapping.
This module provides the metaclass ABCMeta for defining ABCs and a helper class ABC to alternatively define ABCs through inheritance:
A helper class that has ABCMeta as its metaclass. With this class, an abstract base class can be created by simply deriving from ABC avoiding sometimes confusing metaclass usage, for example:
Note that the type of ABC is still ABCMeta, therefore inheriting from ABC requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts. One may also define an abstract base class by passing the metaclass keyword and using ABCMeta directly, for example:
New in version 3.4.
Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as “virtual subclasses” – these and their descendants will be considered subclasses of the registering ABC by the built-in issubclass() function, but the registering ABC won’t show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via super()). 1
Classes created with a metaclass of ABCMeta have the following method:
Register subclass as a “virtual subclass” of this ABC. For example:
Changed in version 3.3: Returns the registered subclass, to allow usage as a class decorator.
Changed in version 3.4: To detect calls to register(), you can use the get_cache_token() function.
You can also override this method in an abstract base class:
(Must be defined as a class method.)
Check whether subclass is considered a subclass of this ABC. This means that you can customize the behavior of issubclass further without the need to call register() on every class you want to consider a subclass of the ABC. (This class method is called from the __subclasscheck__() method of the ABC.)
This method should return True, False or NotImplemented. If it returns True, the subclass is considered a subclass of this ABC. If it returns False, the subclass is not considered a subclass of this ABC, even if it would normally be one. If it returns NotImplemented, the subclass check is continued with the usual mechanism.
For a demonstration of these concepts, look at this example ABC definition:
The ABC MyIterable defines the standard iterable method, __iter__(), as an abstract method. The implementation given here can still be called from subclasses. The get_iterator() method is also part of the MyIterable abstract base class, but it does not have to be overridden in non-abstract derived classes.
The __subclasshook__() class method defined here says that any class that has an __iter__() method in its __dict__ (or in that of one of its base classes, accessed via the __mro__ list) is considered a MyIterable too.
Finally, the last line makes Foo a virtual subclass of MyIterable, even though it does not define an __iter__() method (it uses the old-style iterable protocol, defined in terms of __len__() and __getitem__()). Note that this will not make get_iterator available as a method of Foo, so it is provided separately.
The abc module also provides the following decorator:
A decorator indicating abstract methods.
Using this decorator requires that the class’s metaclass is ABCMeta or is derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms. abstractmethod() may be used to declare abstract methods for properties and descriptors.
Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are not supported. The abstractmethod() only affects subclasses derived using regular inheritance; “virtual subclasses” registered with the ABC’s register() method are not affected.
When abstractmethod() is applied in combination with other method descriptors, it should be applied as the innermost decorator, as shown in the following usage examples:
In order to correctly interoperate with the abstract base class machinery, the descriptor must identify itself as abstract using __isabstractmethod__. In general, this attribute should be True if any of the methods used to compose the descriptor are abstract. For example, Python’s built-in property does the equivalent of:
Note
Unlike Java abstract methods, these abstract methods may have an implementation. This implementation can be called via the super() mechanism from the class that overrides it. This could be useful as an end-point for a super-call in a framework that uses cooperative multiple-inheritance.
The abc module also supports the following legacy decorators:
New in version 3.2.
Deprecated since version 3.3: It is now possible to use classmethod with abstractmethod(), making this decorator redundant.
A subclass of the built-in classmethod(), indicating an abstract classmethod. Otherwise it is similar to abstractmethod().
This special case is deprecated, as the classmethod() decorator is now correctly identified as abstract when applied to an abstract method:
New in version 3.2.
Deprecated since version 3.3: It is now possible to use staticmethod with abstractmethod(), making this decorator redundant.
A subclass of the built-in staticmethod(), indicating an abstract staticmethod. Otherwise it is similar to abstractmethod().
This special case is deprecated, as the staticmethod() decorator is now correctly identified as abstract when applied to an abstract method:
Deprecated since version 3.3: It is now possible to use property, property.getter(), property.setter() and property.deleter() with abstractmethod(), making this decorator redundant.
A subclass of the built-in property(), indicating an abstract property.
This special case is deprecated, as the property() decorator is now correctly identified as abstract when applied to an abstract method:
The above example defines a read-only property; you can also define a read-write abstract property by appropriately marking one or more of the underlying methods as abstract:
If only some components are abstract, only those components need to be updated to create a concrete property in a subclass:
The abc module also provides the following functions:
Returns the current abstract base class cache token.
The token is an opaque object (that supports equality testing) identifying the current version of the abstract base class cache for virtual subclasses. The token changes with every call to ABCMeta.register() on any ABC.
New in version 3.4.
C++ programmers should note that Python’s virtual base class concept is not the same as C++’s.


A helper class that has ABCMeta as its metaclass. With this class, an abstract base class can be created by simply deriving from ABC avoiding sometimes confusing metaclass usage, for example:
Note that the type of ABC is still ABCMeta, therefore inheriting from ABC requires the usual precautions regarding metaclass usage, as multiple inheritance may lead to metaclass conflicts. One may also define an abstract base class by passing the metaclass keyword and using ABCMeta directly, for example:
New in version 3.4.


Metaclass for defining Abstract Base Classes (ABCs).
Use this metaclass to create an ABC. An ABC can be subclassed directly, and then acts as a mix-in class. You can also register unrelated concrete classes (even built-in classes) and unrelated ABCs as “virtual subclasses” – these and their descendants will be considered subclasses of the registering ABC by the built-in issubclass() function, but the registering ABC won’t show up in their MRO (Method Resolution Order) nor will method implementations defined by the registering ABC be callable (not even via super()). 1
Classes created with a metaclass of ABCMeta have the following method:
Register subclass as a “virtual subclass” of this ABC. For example:
Changed in version 3.3: Returns the registered subclass, to allow usage as a class decorator.
Changed in version 3.4: To detect calls to register(), you can use the get_cache_token() function.
You can also override this method in an abstract base class:
(Must be defined as a class method.)
Check whether subclass is considered a subclass of this ABC. This means that you can customize the behavior of issubclass further without the need to call register() on every class you want to consider a subclass of the ABC. (This class method is called from the __subclasscheck__() method of the ABC.)
This method should return True, False or NotImplemented. If it returns True, the subclass is considered a subclass of this ABC. If it returns False, the subclass is not considered a subclass of this ABC, even if it would normally be one. If it returns NotImplemented, the subclass check is continued with the usual mechanism.
For a demonstration of these concepts, look at this example ABC definition:
The ABC MyIterable defines the standard iterable method, __iter__(), as an abstract method. The implementation given here can still be called from subclasses. The get_iterator() method is also part of the MyIterable abstract base class, but it does not have to be overridden in non-abstract derived classes.
The __subclasshook__() class method defined here says that any class that has an __iter__() method in its __dict__ (or in that of one of its base classes, accessed via the __mro__ list) is considered a MyIterable too.
Finally, the last line makes Foo a virtual subclass of MyIterable, even though it does not define an __iter__() method (it uses the old-style iterable protocol, defined in terms of __len__() and __getitem__()). Note that this will not make get_iterator available as a method of Foo, so it is provided separately.


Register subclass as a “virtual subclass” of this ABC. For example:
Changed in version 3.3: Returns the registered subclass, to allow usage as a class decorator.
Changed in version 3.4: To detect calls to register(), you can use the get_cache_token() function.


(Must be defined as a class method.)
Check whether subclass is considered a subclass of this ABC. This means that you can customize the behavior of issubclass further without the need to call register() on every class you want to consider a subclass of the ABC. (This class method is called from the __subclasscheck__() method of the ABC.)
This method should return True, False or NotImplemented. If it returns True, the subclass is considered a subclass of this ABC. If it returns False, the subclass is not considered a subclass of this ABC, even if it would normally be one. If it returns NotImplemented, the subclass check is continued with the usual mechanism.


New in version 3.2.
Deprecated since version 3.3: It is now possible to use classmethod with abstractmethod(), making this decorator redundant.
A subclass of the built-in classmethod(), indicating an abstract classmethod. Otherwise it is similar to abstractmethod().
This special case is deprecated, as the classmethod() decorator is now correctly identified as abstract when applied to an abstract method:


A decorator indicating abstract methods.
Using this decorator requires that the class’s metaclass is ABCMeta or is derived from it. A class that has a metaclass derived from ABCMeta cannot be instantiated unless all of its abstract methods and properties are overridden. The abstract methods can be called using any of the normal ‘super’ call mechanisms. abstractmethod() may be used to declare abstract methods for properties and descriptors.
Dynamically adding abstract methods to a class, or attempting to modify the abstraction status of a method or class once it is created, are not supported. The abstractmethod() only affects subclasses derived using regular inheritance; “virtual subclasses” registered with the ABC’s register() method are not affected.
When abstractmethod() is applied in combination with other method descriptors, it should be applied as the innermost decorator, as shown in the following usage examples:
In order to correctly interoperate with the abstract base class machinery, the descriptor must identify itself as abstract using __isabstractmethod__. In general, this attribute should be True if any of the methods used to compose the descriptor are abstract. For example, Python’s built-in property does the equivalent of:
Note
Unlike Java abstract methods, these abstract methods may have an implementation. This implementation can be called via the super() mechanism from the class that overrides it. This could be useful as an end-point for a super-call in a framework that uses cooperative multiple-inheritance.


Deprecated since version 3.3: It is now possible to use property, property.getter(), property.setter() and property.deleter() with abstractmethod(), making this decorator redundant.
A subclass of the built-in property(), indicating an abstract property.
This special case is deprecated, as the property() decorator is now correctly identified as abstract when applied to an abstract method:
The above example defines a read-only property; you can also define a read-write abstract property by appropriately marking one or more of the underlying methods as abstract:
If only some components are abstract, only those components need to be updated to create a concrete property in a subclass:


New in version 3.2.
Deprecated since version 3.3: It is now possible to use staticmethod with abstractmethod(), making this decorator redundant.
A subclass of the built-in staticmethod(), indicating an abstract staticmethod. Otherwise it is similar to abstractmethod().
This special case is deprecated, as the staticmethod() decorator is now correctly identified as abstract when applied to an abstract method:


Returns the current abstract base class cache token.
The token is an opaque object (that supports equality testing) identifying the current version of the abstract base class cache for virtual subclasses. The token changes with every call to ABCMeta.register() on any ABC.
New in version 3.4.


Return the absolute value of a number. The argument may be an integer, a floating point number, or an object implementing __abs__(). If the argument is a complex number, its magnitude is returned.


Source code: Lib/aifc.py
This module provides support for reading and writing AIFF and AIFF-C files. AIFF is Audio Interchange File Format, a format for storing digital audio samples in a file. AIFF-C is a newer version of the format that includes the ability to compress the audio data.
Audio files have a number of parameters that describe the audio data. The sampling rate or frame rate is the number of times per second the sound is sampled. The number of channels indicate if the audio is mono, stereo, or quadro. Each frame consists of one sample per channel. The sample size is the size in bytes of each sample. Thus a frame consists of nchannels * samplesize bytes, and a second’s worth of audio consists of nchannels * samplesize * framerate bytes.
For example, CD quality audio has a sample size of two bytes (16 bits), uses two channels (stereo) and has a frame rate of 44,100 frames/second. This gives a frame size of 4 bytes (2*2), and a second’s worth occupies 2*2*44100 bytes (176,400 bytes).
Module aifc defines the following function:
Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a string naming a file or a file object. mode must be 'r' or 'rb' when the file must be opened for reading, or 'w' or 'wb' when the file must be opened for writing. If omitted, file.mode is used if it exists, otherwise 'rb' is used. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use writeframesraw() and setnframes(). The open() function may be used in a with statement. When the with block completes, the close() method is called.
Changed in version 3.4: Support for the with statement was added.
Objects returned by open() when a file is opened for reading have the following methods:
Return the number of audio channels (1 for mono, 2 for stereo).
Return the size in bytes of individual samples.
Return the sampling rate (number of audio frames per second).
Return the number of audio frames in the file.
Return a bytes array of length 4 describing the type of compression used in the audio file. For AIFF files, the returned value is b'NONE'.
Return a bytes array convertible to a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is b'not compressed'.
Returns a namedtuple() (nchannels, sampwidth,
framerate, nframes, comptype, compname), equivalent to output of the get*() methods.
Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string).
Return the tuple as described in getmarkers() for the mark with the given id.
Read and return the next nframes frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels.
Rewind the read pointer. The next readframes() will start from the beginning.
Seek to the specified frame number.
Return the current frame number.
Close the AIFF file. After calling this method, the object can no longer be used.
Objects returned by open() when a file is opened for writing have all the above methods, except for readframes() and setpos(). In addition the following methods exist. The get*() methods can only be called after the corresponding set*() methods have been called. Before the first writeframes() or writeframesraw(), all parameters except for the number of frames must be filled in.
Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.
Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.
Specify the number of channels in the audio file.
Specify the size in bytes of audio samples.
Specify the sampling frequency in frames per second.
Specify the number of frames that are to be written to the audio file. If this parameter is not set, or not set correctly, the file needs to support seeking.
Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type as a bytes array, the type parameter should be a bytes array of length 4. Currently the following compression types are supported: b'NONE', b'ULAW', b'ALAW', b'G722'.
Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a getparams() call as argument to setparams().
Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before close().
Return the current write position in the output file. Useful in combination with setmark().
Write data to the output file. This method can only be called after the audio file parameters have been set.
Changed in version 3.4: Any bytes-like object is now accepted.
Like writeframes(), except that the header of the audio file is not updated.
Changed in version 3.4: Any bytes-like object is now accepted.
Close the AIFF file. The header of the file is updated to reflect the actual size of the audio data. After calling this method, the object can no longer be used.


Create an AIFF-C file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.


Create an AIFF file. The default is that an AIFF-C file is created, unless the name of the file ends in '.aiff' in which case the default is an AIFF file.


Close the AIFF file. After calling this method, the object can no longer be used.


Return a bytes array convertible to a human-readable description of the type of compression used in the audio file. For AIFF files, the returned value is b'not compressed'.


Return a bytes array of length 4 describing the type of compression used in the audio file. For AIFF files, the returned value is b'NONE'.


Return the sampling rate (number of audio frames per second).


Return the tuple as described in getmarkers() for the mark with the given id.


Return a list of markers in the audio file. A marker consists of a tuple of three elements. The first is the mark ID (an integer), the second is the mark position in frames from the beginning of the data (an integer), the third is the name of the mark (a string).


Return the number of audio channels (1 for mono, 2 for stereo).


Return the number of audio frames in the file.


Returns a namedtuple() (nchannels, sampwidth,
framerate, nframes, comptype, compname), equivalent to output of the get*() methods.


Return the size in bytes of individual samples.


Read and return the next nframes frames from the audio file. The returned data is a string containing for each frame the uncompressed samples of all channels.


Rewind the read pointer. The next readframes() will start from the beginning.


Specify the compression type. If not specified, the audio data will not be compressed. In AIFF files, compression is not possible. The name parameter should be a human-readable description of the compression type as a bytes array, the type parameter should be a bytes array of length 4. Currently the following compression types are supported: b'NONE', b'ULAW', b'ALAW', b'G722'.


Specify the sampling frequency in frames per second.


Add a mark with the given id (larger than 0), and the given name at the given position. This method can be called at any time before close().


Specify the number of channels in the audio file.


Specify the number of frames that are to be written to the audio file. If this parameter is not set, or not set correctly, the file needs to support seeking.


Set all the above parameters at once. The argument is a tuple consisting of the various parameters. This means that it is possible to use the result of a getparams() call as argument to setparams().


Specify the size in bytes of audio samples.


Write data to the output file. This method can only be called after the audio file parameters have been set.
Changed in version 3.4: Any bytes-like object is now accepted.


Like writeframes(), except that the header of the audio file is not updated.
Changed in version 3.4: Any bytes-like object is now accepted.


Open an AIFF or AIFF-C file and return an object instance with methods that are described below. The argument file is either a string naming a file or a file object. mode must be 'r' or 'rb' when the file must be opened for reading, or 'w' or 'wb' when the file must be opened for writing. If omitted, file.mode is used if it exists, otherwise 'rb' is used. When used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use writeframesraw() and setnframes(). The open() function may be used in a with statement. When the with block completes, the close() method is called.
Changed in version 3.4: Support for the with statement was added.


Return True if all elements of the iterable are true (or if the iterable is empty). Equivalent to:


Return True if any element of the iterable is true. If the iterable is empty, return False. Equivalent to:


New in version 3.2.
Source code: Lib/argparse.py
Tutorial
This page contains the API reference information. For a more gentle introduction to Python command-line parsing, have a look at the argparse tutorial.
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 sys.argv. The argparse module also automatically generates help and usage messages and issues errors when users give the program invalid arguments.
The following code is a Python program that takes a list of integers and produces either the sum or the max:
Assuming the Python code above is saved into a file called prog.py, it can be run at the command line and provides useful help messages:
When run with the appropriate arguments, it prints either the sum or the max of the command-line integers:
If invalid arguments are passed in, it will issue an error:
The following sections walk you through this example.
The first step in using the argparse is creating an ArgumentParser object:
The ArgumentParser object will hold all the information necessary to parse the command line into Python data types.
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:
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.
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:
In a script, parse_args() will typically be called with no arguments, and the ArgumentParser will automatically determine the command-line arguments from sys.argv.
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:
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.
By default, ArgumentParser objects use sys.argv[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 myprogram.py with the following code:
The help for this program will display myprogram.py as the program name (regardless of where the program was invoked from):
To change this default behavior, another value can be supplied using the prog= argument to ArgumentParser:
Note that the program name, whether determined from sys.argv[0] or from the prog= argument, is available to help messages using the %(prog)s format specifier.
By default, ArgumentParser calculates the usage message from the arguments it contains:
The default message can be overridden with the usage= keyword argument:
The %(prog)s format specifier is available to fill in the program name in your usage messages.
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:
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.
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:
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.
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:
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.
ArgumentParser objects allow the help formatting to be customized by specifying an alternate formatting class. Currently, there are four such classes:
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:
Passing RawDescriptionHelpFormatter as formatter_class= indicates that description and epilog are already correctly formatted and should not be line-wrapped:
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:
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):
Most command-line options will use - as the prefix, e.g. -f/--foo. Parsers that need to support different or additional prefix characters, e.g. for options like +f or /foo, may specify them using the prefix_chars= argument to the ArgumentParser constructor:
The prefix_chars= argument defaults to '-'. Supplying a set of characters that does not include - will cause -f/--foo options to be disallowed.
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:
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', '@args.txt'] 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.
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:
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:
New in version 3.5.
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:
Sometimes (e.g. 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:
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.
By default, ArgumentParser objects add an option which simply displays the parser’s help message. For example, consider a file named myprogram.py 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 ArgumentParser:
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:
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:
New in version 3.9.
Define how a single command-line argument should be parsed. Each parameter has its own more detailed description below, but in short they are:
The following sections describe how each of these are used.
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:
while a positional argument could be created like:
When parse_args() is called, optional arguments will be identified by the - prefix, and the remaining arguments will be assumed to be positional:
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:
'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:
'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:
'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:
'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:
'count' - This counts the number of times a keyword argument occurs. For example, this is useful for increasing verbosity levels:
Note, the default will be None unless explicitly set to 0.
'version' - This expects a version= keyword argument in the add_argument() call, and prints version information and exits when invoked:
'extend' - This stores a list, and extends each argument value to the list. Example usage:
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:
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:
For more details, see Action.
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:
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:
One of the more common uses of nargs='?' is to allow optional input and output files:
'*'. 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:
'+'. 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:
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.
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:
With the 'store_const' and 'append_const' actions, the const keyword argument must be given. For other actions, it defaults to None.
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:
If the target namespace already has an attribute set, the action default will not over write it:
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:
For positional arguments with nargs equal to ? or *, the default value is used when no command-line argument was present:
Providing default=argparse.SUPPRESS causes no attribute to be added if the command-line argument was not present:
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:
User defined functions can be used as well:
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. An 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.
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:
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:
Any container can be passed as the choices value, so list objects, set objects, and custom containers are all supported.
Use of enum.Enum 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.
In general, the argparse module assumes that flags like -f and --bar indicate optional arguments, which can always be omitted at the command line. To make an option required, True can be specified for the required= keyword argument to add_argument():
As the example shows, if an option is marked as required, parse_args() will report an error if that option is not present at the command line.
Note
Required options are generally considered bad form because users expect options to be optional, and thus they should be avoided when possible.
The help value is a string containing a brief description of the argument. When a user requests help (usually by using -h or --help at the command line), these help descriptions will be displayed with each argument:
The help strings can include various format specifiers to avoid repetition of things like the program name or the argument default. The available specifiers include the program name, %(prog)s and most keyword arguments to add_argument(), e.g. %(default)s, %(type)s, etc.:
As the help string supports %-formatting, if you want a literal % to appear in the help string, you must escape it as %%.
argparse supports silencing the help entry for certain options, by setting the help value to argparse.SUPPRESS:
When ArgumentParser generates help messages, it needs some way to refer to each expected argument. By default, ArgumentParser objects use the dest value as the “name” of each object. By default, for positional argument actions, the dest value is used directly, and for optional argument actions, the dest value is uppercased. So, a single positional argument with dest='bar' will be referred to as bar. A single optional argument --foo that should be followed by a single command-line argument will be referred to as FOO. An example:
An alternative name can be specified with metavar:
Note that metavar only changes the displayed name - the name of the attribute on the parse_args() object is still determined by the dest value.
Different values of nargs may cause the metavar to be used multiple times. Providing a tuple to metavar specifies a different display for each of the arguments:
Most ArgumentParser actions add some value as an attribute of the object returned by parse_args(). The name of this attribute is determined by the dest keyword argument of add_argument(). For positional argument actions, dest is normally supplied as the first argument to add_argument():
For optional argument actions, the value of dest is normally inferred from the option strings. ArgumentParser generates the value of dest by taking the first long option string and stripping away the initial -- string. If no long option strings were supplied, dest will be derived from the first short option string by stripping the initial - character. Any internal - characters will be converted to _ characters to make sure the string is a valid attribute name. The examples below illustrate this behavior:
dest allows a custom attribute name to be provided:
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 action parameter to add_argument().
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 ArgumentParser.add_argument() except for the action itself.
Instances of Action (or return value of any callable to the action 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 Action.__init__.
Action instances should be callable, so subclasses must override the __call__ method, which should accept four parameters:
The __call__ method may perform arbitrary actions, but will typically set attributes on the namespace based on dest and values.
Action subclasses can define a format_usage method that takes no argument and return a string which will be used when printing the usage of the program. If such method is not provided, a sensible default will be used.
Convert argument strings to objects and assign them as attributes of the namespace. Return the populated namespace.
Previous calls to add_argument() determine exactly what objects are created and how they are assigned. See the documentation for add_argument() for details.
The parse_args() 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:
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 = to separate them:
For short options (options only one character long), the option and its value can be concatenated:
Several short options can be joined together, using only a single - prefix, as long as only the last option (or none of them) requires a value:
While parsing the command line, parse_args() 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:
The parse_args() 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 -1 could either be an attempt to specify an option or an attempt to provide a positional argument. The parse_args() method is cautious here: positional arguments may only begin with - if they look like negative numbers and there are no options in the parser that look like negative numbers:
If you have positional arguments that must begin with - and don’t look like negative numbers, you can insert the pseudo-argument '--' which tells parse_args() that everything after that is a positional argument:
The parse_args() method by default allows long options to be abbreviated to a prefix, if the abbreviation is unambiguous (the prefix matches a unique option):
An error is produced for arguments that could produce more than one options. This feature can be disabled by setting allow_abbrev to False.
Sometimes it may be useful to have an ArgumentParser parse arguments other than those of sys.argv. This can be accomplished by passing a list of strings to parse_args(). This is useful for testing at the interactive prompt:
Simple class used by default by parse_args() to create an object holding attributes and return it.
This class is deliberately simple, just an object subclass with a readable string representation. If you prefer to have dict-like view of the attributes, you can use the standard Python idiom, vars():
It may also be useful to have an ArgumentParser assign attributes to an already existing object, rather than a new Namespace object. This can be achieved by specifying the namespace= keyword argument:
Many programs split up their functionality into a number of sub-commands, for example, the svn program can invoke sub-commands like svn
checkout, svn update, and svn commit. 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. ArgumentParser supports the creation of such sub-commands with the add_subparsers() method. The add_subparsers() method is normally called with no arguments and returns a special action object. This object has a single method, add_parser(), which takes a command name and any ArgumentParser constructor arguments, and returns an ArgumentParser object that can be modified as usual.
Description of parameters:
Some example usage:
Note that the object returned by parse_args() 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 a command is specified, only the foo and bar attributes are present, and when the b command is specified, only the foo and baz 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 help= argument to add_parser() as above.)
The add_subparsers() method also supports title and description keyword arguments. When either is present, the subparser’s commands will appear in their own group in the help output. For example:
Furthermore, add_parser supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for checkout:
One particularly effective way of handling sub-commands is to combine the use of the add_subparsers() method with calls to set_defaults() so that each subparser knows which Python function it should execute. For example:
This way, you can let parse_args() 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 dest keyword argument to the add_subparsers() call will work:
Changed in version 3.7: New required keyword argument.
The FileType factory creates objects that can be passed to the type argument of ArgumentParser.add_argument(). Arguments that have FileType objects as their type will open command-line arguments as files with the requested modes, buffer sizes, encodings and error handling (see the open() function for more details):
FileType objects understand the pseudo-argument '-' and automatically convert this into sys.stdin for readable FileType objects and sys.stdout for writable FileType objects:
New in version 3.4: The encodings and errors keyword arguments.
By default, ArgumentParser 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 add_argument_group() method:
The add_argument_group() method returns an argument group object which has an add_argument() method just like a regular ArgumentParser. 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 add_argument_group() method accepts title and description arguments which can be used to customize this display:
Note that any arguments not in your user-defined groups will end up back in the usual “positional arguments” and “optional arguments” sections.
Create a mutually exclusive group. argparse will make sure that only one of the arguments in the mutually exclusive group was present on the command line:
The add_mutually_exclusive_group() method also accepts a required argument, to indicate that at least one of the mutually exclusive arguments is required:
Note that currently mutually exclusive argument groups do not support the title and description arguments of add_argument_group().
Most of the time, the attributes of the object returned by parse_args() will be fully determined by inspecting the command-line arguments and the argument actions. set_defaults() allows some additional attributes that are determined without any inspection of the command line to be added:
Note that parser-level defaults always override argument-level defaults:
Parser-level defaults can be particularly useful when working with multiple parsers. See the add_subparsers() method for an example of this type.
Get the default value for a namespace attribute, as set by either add_argument() or by set_defaults():
In most typical applications, parse_args() will take care of formatting and printing any usage or error messages. However, several formatting methods are available:
Print a brief description of how the ArgumentParser should be invoked on the command line. If file is None, sys.stdout is assumed.
Print a help message, including the program usage and information about the arguments registered with the ArgumentParser. If file is None, sys.stdout is assumed.
There are also variants of these methods that simply return a string instead of printing it:
Return a string containing a brief description of how the ArgumentParser should be invoked on the command line.
Return a string containing a help message, including the program usage and information about the arguments registered with the ArgumentParser.
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 parse_known_args() method can be useful. It works much like parse_args() 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.
Warning
Prefix matching rules apply to parse_known_args(). 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.
Arguments that are read from a file (see the fromfile_prefix_chars keyword argument to the ArgumentParser constructor) are read one argument per line. convert_arg_line_to_args() 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. The following example demonstrates how to do this:
This method terminates the program, exiting with the specified status and, if given, it prints a message before that. The user can override this method to handle these steps differently:
This method prints a usage message including the message to the standard error and terminates the program with a status code of 2.
A number of Unix commands allow the user to intermix optional arguments with positional arguments. The parse_intermixed_args() and parse_known_intermixed_args() methods support this parsing style.
These parsers do not support all the argparse features, and will raise exceptions if unsupported features are used. In particular, subparsers, argparse.REMAINDER, and mutually exclusive groups that include both optionals and positionals are not supported.
The following example shows the difference between parse_known_args() and parse_intermixed_args(): the former returns ['2',
'3'] as unparsed arguments, while the latter collects all the positionals into rest.
parse_known_intermixed_args() returns a two item tuple containing the populated namespace and the list of remaining argument strings. parse_intermixed_args() raises an error if there are any remaining unparsed argument strings.
New in version 3.7.
Originally, the argparse module had attempted to maintain compatibility with optparse. However, optparse was difficult to extend transparently, particularly with the changes required to support the new nargs= specifiers and better usage messages. When most everything in optparse had either been copy-pasted over or monkey-patched, it no longer seemed practical to try to maintain the backwards compatibility.
The argparse module improves on the standard library optparse module in a number of ways including:
A partial upgrade path from optparse to argparse:


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:
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.


Define how a single command-line argument should be parsed. Each parameter has its own more detailed description below, but in short they are:


By default, ArgumentParser 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 add_argument_group() method:
The add_argument_group() method returns an argument group object which has an add_argument() method just like a regular ArgumentParser. 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 add_argument_group() method accepts title and description arguments which can be used to customize this display:
Note that any arguments not in your user-defined groups will end up back in the usual “positional arguments” and “optional arguments” sections.


Create a mutually exclusive group. argparse will make sure that only one of the arguments in the mutually exclusive group was present on the command line:
The add_mutually_exclusive_group() method also accepts a required argument, to indicate that at least one of the mutually exclusive arguments is required:
Note that currently mutually exclusive argument groups do not support the title and description arguments of add_argument_group().


Many programs split up their functionality into a number of sub-commands, for example, the svn program can invoke sub-commands like svn
checkout, svn update, and svn commit. 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. ArgumentParser supports the creation of such sub-commands with the add_subparsers() method. The add_subparsers() method is normally called with no arguments and returns a special action object. This object has a single method, add_parser(), which takes a command name and any ArgumentParser constructor arguments, and returns an ArgumentParser object that can be modified as usual.
Description of parameters:
Some example usage:
Note that the object returned by parse_args() 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 a command is specified, only the foo and bar attributes are present, and when the b command is specified, only the foo and baz 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 help= argument to add_parser() as above.)
The add_subparsers() method also supports title and description keyword arguments. When either is present, the subparser’s commands will appear in their own group in the help output. For example:
Furthermore, add_parser supports an additional aliases argument, which allows multiple strings to refer to the same subparser. This example, like svn, aliases co as a shorthand for checkout:
One particularly effective way of handling sub-commands is to combine the use of the add_subparsers() method with calls to set_defaults() so that each subparser knows which Python function it should execute. For example:
This way, you can let parse_args() 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 dest keyword argument to the add_subparsers() call will work:
Changed in version 3.7: New required keyword argument.


Arguments that are read from a file (see the fromfile_prefix_chars keyword argument to the ArgumentParser constructor) are read one argument per line. convert_arg_line_to_args() 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. The following example demonstrates how to do this:


This method prints a usage message including the message to the standard error and terminates the program with a status code of 2.


This method terminates the program, exiting with the specified status and, if given, it prints a message before that. The user can override this method to handle these steps differently:


Return a string containing a help message, including the program usage and information about the arguments registered with the ArgumentParser.


Return a string containing a brief description of how the ArgumentParser should be invoked on the command line.


Get the default value for a namespace attribute, as set by either add_argument() or by set_defaults():


Convert argument strings to objects and assign them as attributes of the namespace. Return the populated namespace.
Previous calls to add_argument() determine exactly what objects are created and how they are assigned. See the documentation for add_argument() for details.


Print a help message, including the program usage and information about the arguments registered with the ArgumentParser. If file is None, sys.stdout is assumed.


Print a brief description of how the ArgumentParser should be invoked on the command line. If file is None, sys.stdout is assumed.


Most of the time, the attributes of the object returned by parse_args() will be fully determined by inspecting the command-line arguments and the argument actions. set_defaults() allows some additional attributes that are determined without any inspection of the command line to be added:
Note that parser-level defaults always override argument-level defaults:
Parser-level defaults can be particularly useful when working with multiple parsers. See the add_subparsers() method for an example of this type.


The FileType factory creates objects that can be passed to the type argument of ArgumentParser.add_argument(). Arguments that have FileType objects as their type will open command-line arguments as files with the requested modes, buffer sizes, encodings and error handling (see the open() function for more details):
FileType objects understand the pseudo-argument '-' and automatically convert this into sys.stdin for readable FileType objects and sys.stdout for writable FileType objects:
New in version 3.4: The encodings and errors keyword arguments.


Simple class used by default by parse_args() to create an object holding attributes and return it.


The base class for those built-in exceptions that are raised for various arithmetic errors: OverflowError, ZeroDivisionError, FloatingPointError.


This module defines an object type which can compactly represent an array of basic values: characters, integers, floating point numbers. Arrays are sequence types and behave very much like lists, except that the type of objects stored in them is constrained. The type is specified at object creation time by using a type code, which is a single character. The following type codes are defined:
Type code
C Type
Python Type
Minimum size in bytes
Notes
'b'
signed char
int
1
'B'
unsigned char
int
1
'u'
wchar_t
Unicode character
2
(1)
'h'
signed short
int
2
'H'
unsigned short
int
2
'i'
signed int
int
2
'I'
unsigned int
int
2
'l'
signed long
int
4
'L'
unsigned long
int
4
'q'
signed long long
int
8
'Q'
unsigned long long
int
8
'f'
float
float
4
'd'
double
float
8
Notes:
It can be 16 bits or 32 bits depending on the platform.
Changed in version 3.9: array('u') now uses wchar_t as C type instead of deprecated Py_UNICODE. This change doesn’t affect to its behavior because Py_UNICODE is alias of wchar_t since Python 3.3.
Deprecated since version 3.3, will be removed in version 4.0.
The actual representation of values is determined by the machine architecture (strictly speaking, by the C implementation). The actual size can be accessed through the itemsize attribute.
The module defines the following type:
A new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a list, a bytes-like object, or iterable over elements of the appropriate type.
If given a list or string, the initializer is passed to the new array’s fromlist(), frombytes(), or fromunicode() method (see below) to add initial items to the array. Otherwise, the iterable initializer is passed to the extend() method.
Raises an auditing event array.__new__ with arguments typecode, initializer.
A string with all available type codes.
Array objects support the ordinary sequence operations of indexing, slicing, concatenation, and multiplication. When using slice assignment, the assigned value must be an array object with the same type code; in all other cases, TypeError is raised. Array objects also implement the buffer interface, and may be used wherever bytes-like objects are supported.
The following data items and methods are also supported:
The typecode character used to create the array.
The length in bytes of one array item in the internal representation.
Append a new item with value x to the end of the array.
Return a tuple (address, length) giving the current memory address and the length in elements of the buffer used to hold array’s contents. The size of the memory buffer in bytes can be computed as array.buffer_info()[1] *
array.itemsize. This is occasionally useful when working with low-level (and inherently unsafe) I/O interfaces that require memory addresses, such as certain ioctl() operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it.
Note
When using array objects from code written in C or C++ (the only way to effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is documented in Buffer Protocol.
“Byteswap” all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, RuntimeError is raised. It is useful when reading data from a file written on a machine with a different byte order.
Return the number of occurrences of x in the array.
Append items from iterable to the end of the array. If iterable is another array, it must have exactly the same type code; if not, TypeError will be raised. If iterable is not an array, it must be iterable and its elements must be the right type to be appended to the array.
Appends items from the string, interpreting the string as an array of machine values (as if it had been read from a file using the fromfile() method).
New in version 3.2: fromstring() is renamed to frombytes() for clarity.
Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array.
Append items from the list. This is equivalent to for x in list:
a.append(x) except that if there is a type error, the array is unchanged.
Extends this array with data from the given unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.frombytes(unicodestring.encode(enc)) to append Unicode data to an array of some other type.
Return the smallest i such that i is the index of the first occurrence of x in the array.
Insert a new item with value x in the array before position i. Negative values are treated as being relative to the end of the array.
Removes the item with the index i from the array and returns it. The optional argument defaults to -1, so that by default the last item is removed and returned.
Remove the first occurrence of x from the array.
Reverse the order of the items in the array.
Convert the array to an array of machine values and return the bytes representation (the same sequence of bytes that would be written to a file by the tofile() method.)
New in version 3.2: tostring() is renamed to tobytes() for clarity.
Write all items (as machine values) to the file object f.
Convert the array to an ordinary list with the same items.
Convert the array to a unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.tobytes().decode(enc) to obtain a unicode string from an array of some other type.
When an array object is printed or converted to a string, it is represented as array(typecode, initializer). The initializer is omitted if the array is empty, otherwise it is a string if the typecode is 'u', otherwise it is a list of numbers. The string is guaranteed to be able to be converted back to an array with the same type and value using eval(), so long as the array class has been imported using from array import array. Examples:
See also
Packing and unpacking of heterogeneous binary data.
Packing and unpacking of External Data Representation (XDR) data as used in some remote procedure call systems.
The Numeric Python extension (NumPy) defines another array type; see http://www.numpy.org/ for further information about Numerical Python.


A new array whose items are restricted by typecode, and initialized from the optional initializer value, which must be a list, a bytes-like object, or iterable over elements of the appropriate type.
If given a list or string, the initializer is passed to the new array’s fromlist(), frombytes(), or fromunicode() method (see below) to add initial items to the array. Otherwise, the iterable initializer is passed to the extend() method.
Raises an auditing event array.__new__ with arguments typecode, initializer.


Append a new item with value x to the end of the array.


Return a tuple (address, length) giving the current memory address and the length in elements of the buffer used to hold array’s contents. The size of the memory buffer in bytes can be computed as array.buffer_info()[1] *
array.itemsize. This is occasionally useful when working with low-level (and inherently unsafe) I/O interfaces that require memory addresses, such as certain ioctl() operations. The returned numbers are valid as long as the array exists and no length-changing operations are applied to it.
Note
When using array objects from code written in C or C++ (the only way to effectively make use of this information), it makes more sense to use the buffer interface supported by array objects. This method is maintained for backward compatibility and should be avoided in new code. The buffer interface is documented in Buffer Protocol.


“Byteswap” all items of the array. This is only supported for values which are 1, 2, 4, or 8 bytes in size; for other types of values, RuntimeError is raised. It is useful when reading data from a file written on a machine with a different byte order.


Return the number of occurrences of x in the array.


Append items from iterable to the end of the array. If iterable is another array, it must have exactly the same type code; if not, TypeError will be raised. If iterable is not an array, it must be iterable and its elements must be the right type to be appended to the array.


Appends items from the string, interpreting the string as an array of machine values (as if it had been read from a file using the fromfile() method).
New in version 3.2: fromstring() is renamed to frombytes() for clarity.


Read n items (as machine values) from the file object f and append them to the end of the array. If less than n items are available, EOFError is raised, but the items that were available are still inserted into the array.


Append items from the list. This is equivalent to for x in list:
a.append(x) except that if there is a type error, the array is unchanged.


Extends this array with data from the given unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.frombytes(unicodestring.encode(enc)) to append Unicode data to an array of some other type.


Return the smallest i such that i is the index of the first occurrence of x in the array.


Insert a new item with value x in the array before position i. Negative values are treated as being relative to the end of the array.


The length in bytes of one array item in the internal representation.


Removes the item with the index i from the array and returns it. The optional argument defaults to -1, so that by default the last item is removed and returned.


Remove the first occurrence of x from the array.


Reverse the order of the items in the array.


Convert the array to an array of machine values and return the bytes representation (the same sequence of bytes that would be written to a file by the tofile() method.)
New in version 3.2: tostring() is renamed to tobytes() for clarity.


Write all items (as machine values) to the file object f.


Convert the array to an ordinary list with the same items.


Convert the array to a unicode string. The array must be a type 'u' array; otherwise a ValueError is raised. Use array.tobytes().decode(enc) to obtain a unicode string from an array of some other type.


The typecode character used to create the array.


As repr(), return a string containing a printable representation of an object, but escape the non-ASCII characters in the string returned by repr() using \x, \u or \U escapes. This generates a string similar to that returned by repr() in Python 2.


Source code: Lib/ast.py
The ast module helps Python applications to process trees of the Python abstract syntax grammar. The abstract syntax itself might change with each Python release; this module helps to find out programmatically what the current grammar looks like.
An abstract syntax tree can be generated by passing ast.PyCF_ONLY_AST as a flag to the compile() built-in function, or using the parse() helper provided in this module. The result will be a tree of objects whose classes all inherit from ast.AST. An abstract syntax tree can be compiled into a Python code object using the built-in compile() function.
The abstract grammar is currently defined as follows:
This is the base of all AST node classes. The actual node classes are derived from the Parser/Python.asdl file, which is reproduced below. They are defined in the _ast C module and re-exported in ast.
There is one class defined for each left-hand side symbol in the abstract grammar (for example, ast.stmt or ast.expr). In addition, there is one class defined for each constructor on the right-hand side; these classes inherit from the classes for the left-hand side trees. For example, ast.BinOp inherits from ast.expr. For production rules with alternatives (aka “sums”), the left-hand side class is abstract: only instances of specific constructor nodes are ever created.
Each concrete class has an attribute _fields which gives the names of all child nodes.
Each instance of a concrete class has one attribute for each child node, of the type as defined in the grammar. For example, ast.BinOp instances have an attribute left of type ast.expr.
If these attributes are marked as optional in the grammar (using a question mark), the value might be None. If the attributes can have zero-or-more values (marked with an asterisk), the values are represented as Python lists. All possible attributes must be present and have valid values when compiling an AST with compile().
Instances of ast.expr and ast.stmt subclasses have lineno, col_offset, lineno, and col_offset attributes. The lineno and end_lineno are the first and last line numbers of source text span (1-indexed so the first line is line 1) and the col_offset and end_col_offset are the corresponding UTF-8 byte offsets of the first and last tokens that generated the node. The UTF-8 offset is recorded because the parser uses UTF-8 internally.
Note that the end positions are not required by the compiler and are therefore optional. The end offset is after the last symbol, for example one can get the source segment of a one-line expression node using source_line[node.col_offset : node.end_col_offset].
The constructor of a class ast.T parses its arguments as follows:
For example, to create and populate an ast.UnaryOp node, you could use
or the more compact
Changed in version 3.8: Class ast.Constant is now used for all constants.
Changed in version 3.9: Simple indices are represented by their value, extended slices are represented as tuples.
Deprecated since version 3.8: Old classes ast.Num, ast.Str, ast.Bytes, ast.NameConstant and ast.Ellipsis are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.
Deprecated since version 3.9: Old classes ast.Index and ast.ExtSlice are still available, but they will be removed in future Python releases. In the meantime, instantiating them will return an instance of a different class.
Note
The descriptions of the specific node classes displayed here were initially adapted from the fantastic Green Tree Snakes project and all its contributors.
A constant value. The value attribute of the Constant literal contains the Python object it represents. The values represented can be simple types such as a number, string or None, but also immutable container types (tuples and frozensets) if all of their elements are constant.
Node representing a single formatting field in an f-string. If the string contains a single formatting field and nothing else the node can be isolated otherwise it appears in JoinedStr.
conversion is an integer:
An f-string, comprising a series of FormattedValue and Constant nodes.
A list or tuple. elts holds a list of nodes representing the elements. ctx is Store if the container is an assignment target (i.e. (x,y)=something), and Load otherwise.
A set. elts holds a list of nodes representing the set’s elements.
A dictionary. keys and values hold lists of nodes representing the keys and the values respectively, in matching order (what would be returned when calling dictionary.keys() and dictionary.values()).
When doing dictionary unpacking using dictionary literals the expression to be expanded goes in the values list, with a None at the corresponding position in keys.
A variable name. id holds the name as a string, and ctx is one of the following types.
Variable references can be used to load the value of a variable, to assign a new value to it, or to delete it. Variable references are given a context to distinguish these cases.
A *var variable reference. value holds the variable, typically a Name node. This type must be used when building a Call node with *args.
When an expression, such as a function call, appears as a statement by itself with its return value not used or stored, it is wrapped in this container. value holds one of the other nodes in this section, a Constant, a Name, a Lambda, a Yield or YieldFrom node.
A unary operation. op is the operator, and operand any expression node.
Unary operator tokens. Not is the not keyword, Invert is the ~ operator.
A binary operation (like addition or division). op is the operator, and left and right are any expression nodes.
Binary operator tokens.
A boolean operation, ‘or’ or ‘and’. op is Or or And. values are the values involved. Consecutive operations with the same operator, such as a or b or c, are collapsed into one node with several values.
This doesn’t include not, which is a UnaryOp.
Boolean operator tokens.
A comparison of two or more values. left is the first value in the comparison, ops the list of operators, and comparators the list of values after the first element in the comparison.
Comparison operator tokens.
A function call. func is the function, which will often be a Name or Attribute object. Of the arguments:
When creating a Call node, args and keywords are required, but they can be empty lists. starargs and kwargs are optional.
A keyword argument to a function call or class definition. arg is a raw string of the parameter name, value is a node to pass in.
An expression such as a if b else c. Each field holds a single node, so in the following example, all three are Name nodes.
Attribute access, e.g. d.keys. value is a node, typically a Name. attr is a bare string giving the name of the attribute, and ctx is Load, Store or Del according to how the attribute is acted on.
A named expression. This AST node is produced by the assignment expressions operator (also known as the walrus operator). As opposed to the Assign node in which the first argument can be multiple nodes, in this case both target and value must be single nodes.
A subscript, such as l[1]. value is the subscripted object (usually sequence or mapping). slice is an index, slice or key. It can be a Tuple and contain a Slice. ctx is Load, Store or Del according to the action performed with the subscript.
Regular slicing (on the form lower:upper or lower:upper:step). Can occur only inside the slice field of Subscript, either directly or as an element of Tuple.
List and set comprehensions, generator expressions, and dictionary comprehensions. elt (or key and value) is a single node representing the part that will be evaluated for each item.
generators is a list of comprehension nodes.
One for clause in a comprehension. target is the reference to use for each element - typically a Name or Tuple node. iter is the object to iterate over. ifs is a list of test expressions: each for clause can have multiple ifs.
is_async indicates a comprehension is asynchronous (using an async for instead of for). The value is an integer (0 or 1).
An assignment. targets is a list of nodes, and value is a single node.
Multiple nodes in targets represents assigning the same value to each. Unpacking is represented by putting a Tuple or List within targets.
type_comment is an optional string with the type annotation as a comment.
An assignment with a type annotation. target is a single node and can be a Name, a Attribute or a Subscript. annotation is the annotation, such as a Constant or Name node. value is a single optional node. simple is a boolean integer set to True for a Name node in target that do not appear in between parenthesis and are hence pure names and not expressions.
Augmented assignment, such as a += 1. In the following example, target is a Name node for x (with the Store context), op is Add, and value is a Constant with value for 1.
The target attribute connot be of class Tuple or List, unlike the targets of Assign.
A raise statement. exc is the exception object to be raised, normally a Call or Name, or None for a standalone raise. cause is the optional part for y in raise x from y.
An assertion. test holds the condition, such as a Compare node. msg holds the failure message.
Represents a del statement. targets is a list of nodes, such as Name, Attribute or Subscript nodes.
A pass statement.
Other statements which are only applicable inside functions or loops are described in other sections.
An import statement. names is a list of alias nodes.
Represents from x import y. module is a raw string of the ‘from’ name, without any leading dots, or None for statements such as from . import foo. level is an integer holding the level of the relative import (0 means absolute import).
Both parameters are raw strings of the names. asname can be None if the regular name is to be used.
Note
Optional clauses such as else are stored as an empty list if they’re not present.
An if statement. test holds a single node, such as a Compare node. body and orelse each hold a list of nodes.
elif clauses don’t have a special representation in the AST, but rather appear as extra If nodes within the orelse section of the previous one.
A for loop. target holds the variable(s) the loop assigns to, as a single Name, Tuple or List node. iter holds the item to be looped over, again as a single node. body and orelse contain lists of nodes to execute. Those in orelse are executed if the loop finishes normally, rather than via a break statement.
type_comment is an optional string with the type annotation as a comment.
A while loop. test holds the condition, such as a Compare node.
The break and continue statements.
try blocks. All attributes are list of nodes to execute, except for handlers, which is a list of ExceptHandler nodes.
A single except clause. type is the exception type it will match, typically a Name node (or None for a catch-all except: clause). name is a raw string for the name to hold the exception, or None if the clause doesn’t have as foo. body is a list of nodes.
A with block. items is a list of withitem nodes representing the context managers, and body is the indented block inside the context.
type_comment is an optional string with the type annotation as a comment.
A single context manager in a with block. context_expr is the context manager, often a Call node. optional_vars is a Name, Tuple or List for the as foo part, or None if that isn’t used.
A function definition.
type_comment is an optional string with the type annotation as a comment.
lambda is a minimal function definition that can be used inside an expression. Unlike FunctionDef, body holds a single node.
The arguments for a function.
A single argument in a list. arg is a raw string of the argument name, annotation is its annotation, such as a Str or Name node.
type_comment is an optional string with the type annotation as a comment
A return statement.
A yield or yield from expression. Because these are expressions, they must be wrapped in a Expr node if the value sent back is not used.
global and nonlocal statements. names is a list of raw strings.
A class definition.
An async def function definition. Has the same fields as FunctionDef.
An await expression. value is what it waits for. Only valid in the body of an AsyncFunctionDef.
async for loops and async with context managers. They have the same fields as For and With, respectively. Only valid in the body of an AsyncFunctionDef.
Note
When a string is parsed by ast.parse(), operator nodes (subclasses of ast.operator, ast.unaryop, ast.cmpop, ast.boolop and ast.expr_context) on the returned tree will be singletons. Changes to one will be reflected in all other occurrences of the same value (e.g. ast.Add).
Apart from the node classes, the ast module defines these utility functions and classes for traversing abstract syntax trees:
Parse the source into an AST node. Equivalent to compile(source,
filename, mode, ast.PyCF_ONLY_AST).
If type_comments=True is given, the parser is modified to check and return type comments as specified by PEP 484 and PEP 526. This is equivalent to adding ast.PyCF_TYPE_COMMENTS to the flags passed to compile(). This will report syntax errors for misplaced type comments. Without this flag, type comments will be ignored, and the type_comment field on selected AST nodes will always be None. In addition, the locations of # type:
ignore comments will be returned as the type_ignores attribute of Module (otherwise it is always an empty list).
In addition, if mode is 'func_type', the input syntax is modified to correspond to PEP 484 “signature type comments”, e.g. (str, int) -> List[str].
Also, setting feature_version to a tuple (major, minor) will attempt to parse using that Python version’s grammar. Currently major must equal to 3. For example, setting feature_version=(3, 4) will allow the use of async and await as variable names. The lowest supported version is (3, 4); the highest is sys.version_info[0:2].
Warning
It is possible to crash the Python interpreter with a sufficiently large/complex string due to stack depth limitations in Python’s AST compiler.
Changed in version 3.8: Added type_comments, mode='func_type' and feature_version.
Unparse an ast.AST object and generate a string with code that would produce an equivalent ast.AST object if parsed back with ast.parse().
Warning
The produced code string will not necessarily be equal to the original code that generated the ast.AST object (without any compiler optimizations, such as constant tuples/frozensets).
Warning
Trying to unparse a highly complex expression would result with RecursionError.
New in version 3.9.
Safely evaluate an expression node or a string containing a Python literal or container display. The string or node provided may only consist of the following Python literal structures: strings, bytes, numbers, tuples, lists, dicts, sets, booleans, and None.
This can be used for safely evaluating strings containing Python values from untrusted sources without the need to parse the values oneself. It is not capable of evaluating arbitrarily complex expressions, for example involving operators or indexing.
Warning
It is possible to crash the Python interpreter with a sufficiently large/complex string due to stack depth limitations in Python’s AST compiler.
Changed in version 3.2: Now allows bytes and set literals.
Changed in version 3.9: Now supports creating empty sets with 'set()'.
Return the docstring of the given node (which must be a FunctionDef, AsyncFunctionDef, ClassDef, or Module node), or None if it has no docstring. If clean is true, clean up the docstring’s indentation with inspect.cleandoc().
Changed in version 3.5: AsyncFunctionDef is now supported.
Get source code segment of the source that generated node. If some location information (lineno, end_lineno, col_offset, or end_col_offset) is missing, return None.
If padded is True, the first line of a multi-line statement will be padded with spaces to match its original position.
New in version 3.8.
When you compile a node tree with compile(), the compiler expects lineno and col_offset attributes for every node that supports them. This is rather tedious to fill in for generated nodes, so this helper adds these attributes recursively where not already set, by setting them to the values of the parent node. It works recursively starting at node.
Increment the line number and end line number of each node in the tree starting at node by n. This is useful to “move code” to a different location in a file.
Copy source location (lineno, col_offset, end_lineno, and end_col_offset) from old_node to new_node if possible, and return new_node.
Yield a tuple of (fieldname, value) for each field in node._fields that is present on node.
Yield all direct child nodes of node, that is, all fields that are nodes and all items of fields that are lists of nodes.
Recursively yield all descendant nodes in the tree starting at node (including node itself), in no specified order. This is useful if you only want to modify nodes in place and don’t care about the context.
A node visitor base class that walks the abstract syntax tree and calls a visitor function for every node found. This function may return a value which is forwarded by the visit() method.
This class is meant to be subclassed, with the subclass adding visitor methods.
Visit a node. The default implementation calls the method called self.visit_classname where classname is the name of the node class, or generic_visit() if that method doesn’t exist.
This visitor calls visit() on all children of the node.
Note that child nodes of nodes that have a custom visitor method won’t be visited unless the visitor calls generic_visit() or visits them itself.
Don’t use the NodeVisitor if you want to apply changes to nodes during traversal. For this a special visitor exists (NodeTransformer) that allows modifications.
Deprecated since version 3.8: Methods visit_Num(), visit_Str(), visit_Bytes(), visit_NameConstant() and visit_Ellipsis() are deprecated now and will not be called in future Python versions. Add the visit_Constant() method to handle all constant nodes.
A NodeVisitor subclass that walks the abstract syntax tree and allows modification of nodes.
The NodeTransformer will walk the AST and use the return value of the visitor methods to replace or remove the old node. If the return value of the visitor method is None, the node will be removed from its location, otherwise it is replaced with the return value. The return value may be the original node in which case no replacement takes place.
Here is an example transformer that rewrites all occurrences of name lookups (foo) to data['foo']:
Keep in mind that if the node you’re operating on has child nodes you must either transform the child nodes yourself or call the generic_visit() method for the node first.
For nodes that were part of a collection of statements (that applies to all statement nodes), the visitor may also return a list of nodes rather than just a single node.
If NodeTransformer introduces new nodes (that weren’t part of original tree) without giving them location information (such as lineno), fix_missing_locations() should be called with the new sub-tree to recalculate the location information:
Usually you use the transformer like this:
Return a formatted dump of the tree in node. This is mainly useful for debugging purposes. If annotate_fields is true (by default), the returned string will show the names and the values for fields. If annotate_fields is false, the result string will be more compact by omitting unambiguous field names. Attributes such as line numbers and column offsets are not dumped by default. If this is wanted, include_attributes can be set to true.
If indent is a non-negative integer or string, then the tree will be pretty-printed with that indent level. An indent level of 0, negative, or "" will only insert newlines. None (the default) selects the single line representation. Using a positive integer indent indents that many spaces per level. If indent is a string (such as "\t"), that string is used to indent each level.
Changed in version 3.9: Added the indent option.
The following flags may be passed to compile() in order to change effects on the compilation of a program:
Enables support for top-level await, async for, async with and async comprehensions.
New in version 3.8.
Generates and returns an abstract syntax tree instead of returning a compiled code object.
Enables support for PEP 484 and PEP 526 style type comments (# type: <type>, # type: ignore <stuff>).
New in version 3.8.
New in version 3.9.
The ast module can be executed as a script from the command line. It is as simple as:
The following options are accepted:
Show the help message and exit.
Specify what kind of code must be compiled, like the mode argument in parse().
Don’t parse type comments.
Include attributes such as line numbers and column offsets.
Indentation of nodes in AST (number of spaces).
If infile is specified its contents are parsed to AST and dumped to stdout. Otherwise, the content is read from stdin.
See also
Green Tree Snakes, an external documentation resource, has good details on working with Python ASTs.
ASTTokens annotates Python ASTs with the positions of tokens and text in the source code that generated them. This is helpful for tools that make source code transformations.
leoAst.py unifies the token-based and parse-tree-based views of python programs by inserting two-way links between tokens and ast nodes.
LibCST parses code as a Concrete Syntax Tree that looks like an ast tree and keeps all formatting details. It’s useful for building automated refactoring (codemod) applications and linters.
Parso is a Python parser that supports error recovery and round-trip parsing for different Python versions (in multiple Python versions). Parso is also able to list multiple syntax errors in your python file.


Both parameters are raw strings of the names. asname can be None if the regular name is to be used.


An assignment with a type annotation. target is a single node and can be a Name, a Attribute or a Subscript. annotation is the annotation, such as a Constant or Name node. value is a single optional node. simple is a boolean integer set to True for a Name node in target that do not appear in between parenthesis and are hence pure names and not expressions.