Command line and environment

1. Command line and environment¶
The CPython interpreter scans the command line and the environment for various settings.
CPython implementation detail: Other implementations’ command line schemes may differ. See Alternate Implementations for further resources.
1.1. Command line¶
When invoking Python, you may specify any of these options:
python [-bBdEhiIOPqRsSuvVWx?] [-c command | -m module-name | script | - ] [args]
The most common use case is, of course, a simple invocation of a script:
python myscript.py
1.1.1. Interface options¶
The interpreter interface resembles that of the UNIX shell, but provides some additional methods of invocation:
When called with standard input connected to a tty device, it prompts for commands and executes them until an EOF (an end-of-file character, you can produce that with Ctrl-D on UNIX or Ctrl-Z, Enter on Windows) is read. For more on interactive mode, see Interactive Mode.
When called with a file name argument or with a file as standard input, it reads and executes a script from that file.
When called with a directory name argument, it reads and executes an appropriately named script from that directory.
When called with
-c command
, it executes the Python statement(s) given as command. Here command may contain multiple statements separated by newlines. Leading whitespace is significant in Python statements!When called with
-m module-name
, the given module is located on the Python module path and executed as a script.
In non-interactive mode, the entire input is parsed before it is executed.
An interface option terminates the list of options consumed by the interpreter,
all consecutive arguments will end up in sys.argv
– note that the first
element, subscript zero (sys.argv[0]
), is a string reflecting the program’s
source.
- -c <command>¶
Execute the Python code in command. command can be one or more statements separated by newlines, with significant leading whitespace as in normal module code.
If this option is given, the first element of
sys.argv
will be"-c"
and the current directory will be added to the start ofsys.path
(allowing modules in that directory to be imported as top level modules).Raises an auditing event
cpython.run_command
with argumentcommand
.Changed in version 3.14: command is automatically dedented before execution.
- -m <module-name>¶
Search
sys.path
for the named module and execute its contents as the__main__
module.Since the argument is a module name, you must not give a file extension (
.py
). The module name should be a valid absolute Python module name, but the implementation may not always enforce this (e.g. it may allow you to use a name that includes a hyphen).Package names (including namespace packages) are also permitted. When a package name is supplied instead of a normal module, the interpreter will execute
<pkg>.__main__
as the main module. This behaviour is deliberately similar to the handling of directories and zipfiles that are passed to the interpreter as the script argument.Note
This option cannot be used with built-in modules and extension modules written in C, since they do not have Python module files. However, it can still be used for precompiled modules, even if the original source file is not available.
If this option is given, the first element of
sys.argv
will be the full path to the module file (while the module file is being located, the first element will be set to"-m"
). As with the-c
option, the current directory will be added to the start ofsys.path
.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the current directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.Many standard library modules contain code that is invoked on their execution as a script. An example is the
timeit
module:python -m timeit -s "setup here" "benchmarked code here" python -m timeit -h # for details
Raises an auditing event
cpython.run_module
with argumentmodule-name
.See also
runpy.run_module()
Equivalent functionality directly available to Python code
PEP 338 – Executing modules as scripts
Changed in version 3.1: Supply the package name to run a
__main__
submodule.Changed in version 3.4: namespace packages are also supported
- -
Read commands from standard input (
sys.stdin
). If standard input is a terminal,-i
is implied.If this option is given, the first element of
sys.argv
will be"-"
and the current directory will be added to the start ofsys.path
.Raises an auditing event
cpython.run_stdin
with no arguments.
- <script>
Execute the Python code contained in script, which must be a filesystem path (absolute or relative) referring to either a Python file, a directory containing a
__main__.py
file, or a zipfile containing a__main__.py
file.If this option is given, the first element of
sys.argv
will be the script name as given on the command line.If the script name refers directly to a Python file, the directory containing that file is added to the start of
sys.path
, and the file is executed as the__main__
module.If the script name refers to a directory or zipfile, the script name is added to the start of
sys.path
and the__main__.py
file in that location is executed as the__main__
module.-I
option can be used to run the script in isolated mode wheresys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too.Raises an auditing event
cpython.run_file
with argumentfilename
.See also
runpy.run_path()
Equivalent functionality directly available to Python code
If no interface option is given, -i
is implied, sys.argv[0]
is
an empty string (""
) and the current directory will be added to the
start of sys.path
. Also, tab-completion and history editing is
automatically enabled, if available on your platform (see
Readline configuration).
See also
Changed in version 3.4: Automatic enabling of tab-completion and history editing.
1.1.2. Generic options¶
- -?¶
- -h¶
- --help¶
Print a short description of all command line options and corresponding environment variables and exit.
- --help-env¶
Print a short description of Python-specific environment variables and exit.
Added in version 3.11.
- --help-xoptions¶
Print a description of implementation-specific
-X
options and exit.Added in version 3.11.
- --help-all¶
Print complete usage information and exit.
Added in version 3.11.
1.1.3. Miscellaneous options¶
- -b¶
Issue a warning when converting
bytes
orbytearray
tostr
without specifying encoding or comparingbytes
orbytearray
withstr
orbytes
withint
. Issue an error when the option is given twice (-bb
).
- -B¶
If given, Python won’t try to write
.pyc
files on the import of source modules. See alsoPYTHONDONTWRITEBYTECODE
.
- --check-hash-based-pycs default|always|never¶
Control the validation behavior of hash-based
.pyc
files. See Cached bytecode invalidation. When set todefault
, checked and unchecked hash-based bytecode cache files are validated according to their default semantics. When set toalways
, all hash-based.pyc
files, whether checked or unchecked, are validated against their corresponding source file. When set tonever
, hash-based.pyc
files are not validated against their corresponding source files.The semantics of timestamp-based
.pyc
files are unaffected by this option.
- -d¶
Turn on parser debugging output (for expert only). See also the
PYTHONDEBUG
environment variable.This option requires a debug build of Python, otherwise it’s ignored.
- -E¶
Ignore all
PYTHON*
environment variables, e.g.PYTHONPATH
andPYTHONHOME
, that might be set.
- -i¶
Enter interactive mode after execution.
Using the
-i
option will enter interactive mode in any of the following circumstances:Interactive mode will start even when
sys.stdin
does not appear to be a terminal. ThePYTHONSTARTUP
file is not read.This can be useful to inspect global variables or a stack trace when a script raises an exception. See also
PYTHONINSPECT
.
- -I¶
Run Python in isolated mode. This also implies
-E
,-P
and-s
options.In isolated mode
sys.path
contains neither the script’s directory nor the user’s site-packages directory. AllPYTHON*
environment variables are ignored, too. Further restrictions may be imposed to prevent the user from injecting malicious code.Added in version 3.4.
- -O¶
Remove assert statements and any code conditional on the value of
__debug__
. Augment the filename for compiled (bytecode) files by adding.opt-1
before the.pyc
extension (see PEP 488). See alsoPYTHONOPTIMIZE
.Changed in version 3.5: Modify
.pyc
filenames according to PEP 488.
- -OO¶
Do
-O
and also discard docstrings. Augment the filename for compiled (bytecode) files by adding.opt-2
before the.pyc
extension (see PEP 488).Changed in version 3.5: Modify
.pyc
filenames according to PEP 488.
- -P¶
Don’t prepend a potentially unsafe path to
sys.path
:python -m module
command line: Don’t prepend the current working directory.python script.py
command line: Don’t prepend the script’s directory. If it’s a symbolic link, resolve symbolic links.python -c code
andpython
(REPL) command lines: Don’t prepend an empty string, which means the current working directory.
See also the
PYTHONSAFEPATH
environment variable, and-E
and-I
(isolated) options.Added in version 3.11.
- -q¶
Don’t display the copyright and version messages even in interactive mode.
Added in version 3.2.
- -R¶
Turn on hash randomization. This option only has an effect if the
PYTHONHASHSEED
environment variable is set to anything other thanrandom
, since hash randomization is enabled by default.On previous versions of Python, this option turns on hash randomization, so that the
__hash__()
values of str and bytes objects are “salted” with an unpredictable random value. Although they remain constant within an individual Python process, they are not predictable between repeated invocations of Python.Hash randomization is intended to provide protection against a denial-of-service caused by carefully chosen inputs that exploit the worst case performance of a dict construction, O(n2) complexity. See http://ocert.org/advisories/ocert-2011-003.html for details.
PYTHONHASHSEED
allows you to set a fixed value for the hash seed secret.Added in version 3.2.3.
Changed in version 3.7: The option is no longer ignored.
- -s¶
Don’t add the
user site-packages directory
tosys.path
.See also
PYTHONNOUSERSITE
.See also
PEP 370 – Per user site-packages directory
- -S¶
Disable the import of the module
site
and the site-dependent manipulations ofsys.path
that it entails. Also disable these manipulations ifsite
is explicitly imported later (callsite.main()
if you want them to be triggered).
- -u¶
Force the stdout and stderr streams to be unbuffered. This option has no effect on the stdin stream.
See also
PYTHONUNBUFFERED
.Changed in version 3.7: The text layer of the stdout and stderr streams now is unbuffered.
- -v¶
Print a message each time a module is initialized, showing the place (filename or built-in module) from which it is loaded. When given twice (
-vv
), print a message for each file that is checked for when searching for a module. Also provides information on module cleanup at exit.Changed in version 3.10: The
site
module reports the site-specific paths and.pth
files being processed.See also
PYTHONVERBOSE
.
- -W arg¶
Warning control. Python’s warning machinery by default prints warning messages to
sys.stderr
.The simplest settings apply a particular action unconditionally to all warnings emitted by a process (even those that are otherwise ignored by default):
-Wdefault # Warn once per call location -Werror # Convert to exceptions -Walways # Warn every time -Wall # Same as -Walways -Wmodule # Warn once per calling module -Wonce # Warn once per Python process -Wignore # Never warn
The action names can be abbreviated as desired and the interpreter will resolve them to the appropriate action name. For example,
-Wi
is the same as-Wignore
.The full form of argument is:
action:message:category:module:lineno
Empty fields match all values; trailing empty fields may be omitted. For example
-W ignore::DeprecationWarning
ignores all DeprecationWarning warnings.The action field is as explained above but only applies to warnings that match the remaining fields.
The message field must match the whole warning message; this match is case-insensitive.
The category field matches the warning category (ex:
DeprecationWarning
). This must be a class name; the match test whether the actual warning category of the message is a subclass of the specified warning category.The module field matches the (fully qualified) module name; this match is case-sensitive.
The lineno field matches the line number, where zero matches all line numbers and is thus equivalent to an omitted line number.
Multiple
-W
options can be given; when a warning matches more than one option, the action for the last matching option is performed. Invalid-W
options are ignored (though, a warning message is printed about invalid options when the first warning is issued).Warnings can also be controlled using the
PYTHONWARNINGS
environment variable and from within a Python program using thewarnings
module. For example, thewarnings.filterwarnings()
function can be used to use a regular expression on the warning message.See The Warnings Filter and Describing Warning Filters for more details.
- -x¶
Skip the first line of the source, allowing use of non-Unix forms of
#!cmd
. This is intended for a DOS specific hack only.
- -X¶
Reserved for various implementation-specific options. CPython currently defines the following possible values:
-X faulthandler
to enablefaulthandler
. See alsoPYTHONFAULTHANDLER
.Added in version 3.3.
-X showrefcount
to output the total reference count and number of used memory blocks when the program finishes or after each statement in the interactive interpreter. This only works on debug builds.Added in version 3.4.
-X tracemalloc
to start tracing Python memory allocations using thetracemalloc
module. By default, only the most recent frame is stored in a traceback of a trace. Use-X tracemalloc=NFRAME
to start tracing with a traceback limit of NFRAME frames. Seetracemalloc.start()
andPYTHONTRACEMALLOC
for more information.Added in version 3.4.
-X int_max_str_digits
configures the integer string conversion length limitation. See alsoPYTHONINTMAXSTRDIGITS
.Added in version 3.11.
-X importtime
to show how long each import takes. It shows module name, cumulative time (including nested imports) and self time (excluding nested imports). Note that its output may be broken in multi-threaded application. Typical usage ispython -X importtime -c 'import asyncio'
.-X importtime=2
enables additional output that indicates when an imported module has already been loaded. In such cases, the stringcached
will be printed in both time columns.See also
PYTHONPROFILEIMPORTTIME
.Added in version 3.7.
Changed in version 3.14: Added
-X importtime=2
to also trace imports of loaded modules, and reserved values other than1
and2
for future use.-X dev
: enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. See alsoPYTHONDEVMODE
.Added in version 3.7.
-X utf8
enables the Python UTF-8 Mode.-X utf8=0
explicitly disables Python UTF-8 Mode (even when it would otherwise activate automatically). See alsoPYTHONUTF8
.Added in version 3.7.
-X pycache_prefix=PATH
enables writing.pyc
files to a parallel tree rooted at the given directory instead of to the code tree. See alsoPYTHONPYCACHEPREFIX
.Added in version 3.8.
-X warn_default_encoding
issues aEncodingWarning
when the locale-specific default encoding is used for opening files. See alsoPYTHONWARNDEFAULTENCODING
.Added in version 3.10.
-X no_debug_ranges
disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks. See alsoPYTHONNODEBUGRANGES
.Added in version 3.11.
-X frozen_modules
determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
if this is an installed Python (the normal case). If it’s under development (running from the source tree) then the default isoff
. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
. See alsoPYTHON_FROZEN_MODULES
.Added in version 3.11.
-X perf
enables support for the Linuxperf
profiler. When this option is provided, theperf
profiler will be able to report Python calls. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is “off”. See alsoPYTHONPERFSUPPORT
and Python support for the Linux perf profiler.Added in version 3.12.
-X perf_jit
enables support for the Linuxperf
profiler with DWARF support. When this option is provided, theperf
profiler will be able to report Python calls using DWARF information. This option is only available on some platforms and will do nothing if is not supported on the current system. The default value is “off”. See alsoPYTHON_PERF_JIT_SUPPORT
and Python support for the Linux perf profiler.Added in version 3.13.
-X disable_remote_debug
disables the remote debugging support as described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.This option is only available on some platforms and will do nothing if is not supported on the current system. See also
PYTHON_DISABLE_REMOTE_DEBUG
and PEP 768.Added in version 3.14.
-X cpu_count=n
overridesos.cpu_count()
,os.process_cpu_count()
, andmultiprocessing.cpu_count()
. n must be greater than or equal to 1. This option may be useful for users who need to limit CPU resources of a container system. See alsoPYTHON_CPU_COUNT
. If n isdefault
, nothing is overridden.Added in version 3.13.
-X presite=package.module
specifies a module that should be imported before thesite
module is executed and before the__main__
module exists. Therefore, the imported module isn’t__main__
. This can be used to execute code early during Python initialization. Python needs to be built in debug mode for this option to exist. See alsoPYTHON_PRESITE
.Added in version 3.13.
-X gil=0,1
forces the GIL to be disabled or enabled, respectively. Setting to0
is only available in builds configured with--disable-gil
. See alsoPYTHON_GIL
and Free-threaded CPython.Added in version 3.13.
-X thread_inherit_context=0,1
causesThread
to, by default, use a copy of context of the caller ofThread.start()
when starting. Otherwise, threads will start with an empty context. If unset, the value of this option defaults to1
on free-threaded builds and to0
otherwise. See alsoPYTHON_THREAD_INHERIT_CONTEXT
.Added in version 3.14.
-X context_aware_warnings=0,1
causes thewarnings.catch_warnings
context manager to use aContextVar
to store warnings filter state. If unset, the value of this option defaults to1
on free-threaded builds and to0
otherwise. See alsoPYTHON_CONTEXT_AWARE_WARNINGS
.Added in version 3.14.
-X tlbc=0,1
enables (1, the default) or disables (0) thread-local bytecode in builds configured with--disable-gil
. When disabled, this also disables the specializing interpreter. See alsoPYTHON_TLBC
.Added in version 3.14.
It also allows passing arbitrary values and retrieving them through the
sys._xoptions
dictionary.Added in version 3.2.
Changed in version 3.9: Removed the
-X showalloccount
option.Changed in version 3.10: Removed the
-X oldparser
option.
Removed in version 3.14: -J
is no longer reserved for use by Jython,
and now has no special meaning.
1.1.4. Controlling color¶
The Python interpreter is configured by default to use colors to highlight output in certain situations such as when displaying tracebacks. This behavior can be controlled by setting different environment variables.
Setting the environment variable TERM
to dumb
will disable color.
If the FORCE_COLOR
environment variable is set, then color will be
enabled regardless of the value of TERM. This is useful on CI systems which
aren’t terminals but can still display ANSI escape sequences.
If the NO_COLOR
environment variable is set, Python will disable all color
in the output. This takes precedence over FORCE_COLOR
.
All these environment variables are used also by other tools to control color
output. To control the color output only in the Python interpreter, the
PYTHON_COLORS
environment variable can be used. This variable takes
precedence over NO_COLOR
, which in turn takes precedence over
FORCE_COLOR
.
1.2. Environment variables¶
These environment variables influence Python’s behavior, they are processed before the command-line switches other than -E or -I. It is customary that command-line switches override environmental variables where there is a conflict.
- PYTHONHOME¶
Change the location of the standard Python libraries. By default, the libraries are searched in
prefix/lib/pythonversion
andexec_prefix/lib/pythonversion
, whereprefix
andexec_prefix
are installation-dependent directories, both defaulting to/usr/local
.When
PYTHONHOME
is set to a single directory, its value replaces bothprefix
andexec_prefix
. To specify different values for these, setPYTHONHOME
toprefix:exec_prefix
.
- PYTHONPATH¶
Augment the default search path for module files. The format is the same as the shell’s
PATH
: one or more directory pathnames separated byos.pathsep
(e.g. colons on Unix or semicolons on Windows). Non-existent directories are silently ignored.In addition to normal directories, individual
PYTHONPATH
entries may refer to zipfiles containing pure Python modules (in either source or compiled form). Extension modules cannot be imported from zipfiles.The default search path is installation dependent, but generally begins with
prefix/lib/pythonversion
(seePYTHONHOME
above). It is always appended toPYTHONPATH
.An additional directory will be inserted in the search path in front of
PYTHONPATH
as described above under Interface options. The search path can be manipulated from within a Python program as the variablesys.path
.
- PYTHONSAFEPATH¶
If this is set to a non-empty string, don’t prepend a potentially unsafe path to
sys.path
: see the-P
option for details.Added in version 3.11.
- PYTHONPLATLIBDIR¶
If this is set to a non-empty string, it overrides the
sys.platlibdir
value.Added in version 3.9.
- PYTHONSTARTUP¶
If this is the name of a readable file, the Python commands in that file are executed before the first prompt is displayed in interactive mode. The file is executed in the same namespace where interactive commands are executed so that objects defined or imported in it can be used without qualification in the interactive session. You can also change the prompts
sys.ps1
andsys.ps2
and the hooksys.__interactivehook__
in this file.Raises an auditing event
cpython.run_startup
with the filename as the argument when called on startup.
- PYTHONOPTIMIZE¶
If this is set to a non-empty string it is equivalent to specifying the
-O
option. If set to an integer, it is equivalent to specifying-O
multiple times.
- PYTHONBREAKPOINT¶
If this is set, it names a callable using dotted-path notation. The module containing the callable will be imported and then the callable will be run by the default implementation of
sys.breakpointhook()
which itself is called by built-inbreakpoint()
. If not set, or set to the empty string, it is equivalent to the value “pdb.set_trace”. Setting this to the string “0” causes the default implementation ofsys.breakpointhook()
to do nothing but return immediately.Added in version 3.7.
- PYTHONDEBUG¶
If this is set to a non-empty string it is equivalent to specifying the
-d
option. If set to an integer, it is equivalent to specifying-d
multiple times.This environment variable requires a debug build of Python, otherwise it’s ignored.
- PYTHONINSPECT¶
If this is set to a non-empty string it is equivalent to specifying the
-i
option.This variable can also be modified by Python code using
os.environ
to force inspect mode on program termination.Raises an auditing event
cpython.run_stdin
with no arguments.Changed in version 3.12.5: (also 3.11.10, 3.10.15, 3.9.20, and 3.8.20) Emits audit events.
Changed in version 3.13: Uses PyREPL if possible, in which case
PYTHONSTARTUP
is also executed. Emits audit events.
- PYTHONUNBUFFERED¶
If this is set to a non-empty string it is equivalent to specifying the
-u
option.
- PYTHONVERBOSE¶
If this is set to a non-empty string it is equivalent to specifying the
-v
option. If set to an integer, it is equivalent to specifying-v
multiple times.
- PYTHONCASEOK¶
If this is set, Python ignores case in
import
statements. This only works on Windows and macOS.
- PYTHONDONTWRITEBYTECODE¶
If this is set to a non-empty string, Python won’t try to write
.pyc
files on the import of source modules. This is equivalent to specifying the-B
option.
- PYTHONPYCACHEPREFIX¶
If this is set, Python will write
.pyc
files in a mirror directory tree at this path, instead of in__pycache__
directories within the source tree. This is equivalent to specifying the-X
pycache_prefix=PATH
option.Added in version 3.8.
- PYTHONHASHSEED¶
If this variable is not set or set to
random
, a random value is used to seed the hashes of str and bytes objects.If
PYTHONHASHSEED
is set to an integer value, it is used as a fixed seed for generating the hash() of the types covered by the hash randomization.Its purpose is to allow repeatable hashing, such as for selftests for the interpreter itself, or to allow a cluster of python processes to share hash values.
The integer must be a decimal number in the range [0,4294967295]. Specifying the value 0 will disable hash randomization.
Added in version 3.2.3.
- PYTHONINTMAXSTRDIGITS¶
If this variable is set to an integer, it is used to configure the interpreter’s global integer string conversion length limitation.
Added in version 3.11.
- PYTHONIOENCODING¶
If this is set before running the interpreter, it overrides the encoding used for stdin/stdout/stderr, in the syntax
encodingname:errorhandler
. Both theencodingname
and the:errorhandler
parts are optional and have the same meaning as instr.encode()
.For stderr, the
:errorhandler
part is ignored; the handler will always be'backslashreplace'
.Changed in version 3.4: The
encodingname
part is now optional.Changed in version 3.6: On Windows, the encoding specified by this variable is ignored for interactive console buffers unless
PYTHONLEGACYWINDOWSSTDIO
is also specified. Files and pipes redirected through the standard streams are not affected.
- PYTHONNOUSERSITE¶
If this is set, Python won’t add the
user site-packages directory
tosys.path
.See also
PEP 370 – Per user site-packages directory
- PYTHONUSERBASE¶
Defines the
user base directory
, which is used to compute the path of theuser site-packages directory
and installation paths forpython -m pip install --user
.See also
PEP 370 – Per user site-packages directory
- PYTHONEXECUTABLE¶
If this environment variable is set,
sys.argv[0]
will be set to its value instead of the value got through the C runtime. Only works on macOS.
- PYTHONWARNINGS¶
This is equivalent to the
-W
option. If set to a comma separated string, it is equivalent to specifying-W
multiple times, with filters later in the list taking precedence over those earlier in the list.The simplest settings apply a particular action unconditionally to all warnings emitted by a process (even those that are otherwise ignored by default):
PYTHONWARNINGS=default # Warn once per call location PYTHONWARNINGS=error # Convert to exceptions PYTHONWARNINGS=always # Warn every time PYTHONWARNINGS=all # Same as PYTHONWARNINGS=always PYTHONWARNINGS=module # Warn once per calling module PYTHONWARNINGS=once # Warn once per Python process PYTHONWARNINGS=ignore # Never warn
See The Warnings Filter and Describing Warning Filters for more details.
- PYTHONFAULTHANDLER¶
If this environment variable is set to a non-empty string,
faulthandler.enable()
is called at startup: install a handler forSIGSEGV
,SIGFPE
,SIGABRT
,SIGBUS
andSIGILL
signals to dump the Python traceback. This is equivalent to-X
faulthandler
option.Added in version 3.3.
- PYTHONTRACEMALLOC¶
If this environment variable is set to a non-empty string, start tracing Python memory allocations using the
tracemalloc
module. The value of the variable is the maximum number of frames stored in a traceback of a trace. For example,PYTHONTRACEMALLOC=1
stores only the most recent frame. See thetracemalloc.start()
function for more information. This is equivalent to setting the-X
tracemalloc
option.Added in version 3.4.
- PYTHONPROFILEIMPORTTIME¶
If this environment variable is set to
1
, Python will show how long each import takes. If set to2
, Python will include output for imported modules that have already been loaded. This is equivalent to setting the-X
importtime
option.Added in version 3.7.
Changed in version 3.14: Added
PYTHONPROFILEIMPORTTIME=2
to also trace imports of loaded modules.
- PYTHONASYNCIODEBUG¶
If this environment variable is set to a non-empty string, enable the debug mode of the
asyncio
module.Added in version 3.4.
- PYTHONMALLOC¶
Set the Python memory allocators and/or install debug hooks.
Set the family of memory allocators used by Python:
default
: use the default memory allocators.malloc
: use themalloc()
function of the C library for all domains (PYMEM_DOMAIN_RAW
,PYMEM_DOMAIN_MEM
,PYMEM_DOMAIN_OBJ
).pymalloc
: use the pymalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.mimalloc
: use the mimalloc allocator forPYMEM_DOMAIN_MEM
andPYMEM_DOMAIN_OBJ
domains and use themalloc()
function for thePYMEM_DOMAIN_RAW
domain.
Install debug hooks:
debug
: install debug hooks on top of the default memory allocators.malloc_debug
: same asmalloc
but also install debug hooks.pymalloc_debug
: same aspymalloc
but also install debug hooks.mimalloc_debug
: same asmimalloc
but also install debug hooks.
Added in version 3.6.
Changed in version 3.7: Added the
"default"
allocator.
- PYTHONMALLOCSTATS¶
If set to a non-empty string, Python will print statistics of the pymalloc memory allocator every time a new pymalloc object arena is created, and on shutdown.
This variable is ignored if the
PYTHONMALLOC
environment variable is used to force themalloc()
allocator of the C library, or if Python is configured withoutpymalloc
support.Changed in version 3.6: This variable can now also be used on Python compiled in release mode. It now has no effect if set to an empty string.
- PYTHONLEGACYWINDOWSFSENCODING¶
If set to a non-empty string, the default filesystem encoding and error handler mode will revert to their pre-3.6 values of ‘mbcs’ and ‘replace’, respectively. Otherwise, the new defaults ‘utf-8’ and ‘surrogatepass’ are used.
This may also be enabled at runtime with
sys._enablelegacywindowsfsencoding()
.Availability: Windows.
Added in version 3.6: See PEP 529 for more details.
- PYTHONLEGACYWINDOWSSTDIO¶
If set to a non-empty string, does not use the new console reader and writer. This means that Unicode characters will be encoded according to the active console code page, rather than using utf-8.
This variable is ignored if the standard streams are redirected (to files or pipes) rather than referring to console buffers.
Availability: Windows.
Added in version 3.6.
- PYTHONCOERCECLOCALE¶
If set to the value
0
, causes the main Python command line application to skip coercing the legacy ASCII-based C and POSIX locales to a more capable UTF-8 based alternative.If this variable is not set (or is set to a value other than
0
), theLC_ALL
locale override environment variable is also not set, and the current locale reported for theLC_CTYPE
category is either the defaultC
locale, or else the explicitly ASCII-basedPOSIX
locale, then the Python CLI will attempt to configure the following locales for theLC_CTYPE
category in the order listed before loading the interpreter runtime:C.UTF-8
C.utf8
UTF-8
If setting one of these locale categories succeeds, then the
LC_CTYPE
environment variable will also be set accordingly in the current process environment before the Python runtime is initialized. This ensures that in addition to being seen by both the interpreter itself and other locale-aware components running in the same process (such as the GNUreadline
library), the updated setting is also seen in subprocesses (regardless of whether or not those processes are running a Python interpreter), as well as in operations that query the environment rather than the current C locale (such as Python’s ownlocale.getdefaultlocale()
).Configuring one of these locales (either explicitly or via the above implicit locale coercion) automatically enables the
surrogateescape
error handler forsys.stdin
andsys.stdout
(sys.stderr
continues to usebackslashreplace
as it does in any other locale). This stream handling behavior can be overridden usingPYTHONIOENCODING
as usual.For debugging purposes, setting
PYTHONCOERCECLOCALE=warn
will cause Python to emit warning messages onstderr
if either the locale coercion activates, or else if a locale that would have triggered coercion is still active when the Python runtime is initialized.Also note that even when locale coercion is disabled, or when it fails to find a suitable target locale,
PYTHONUTF8
will still activate by default in legacy ASCII-based locales. Both features must be disabled in order to force the interpreter to useASCII
instead ofUTF-8
for system interfaces.Availability: Unix.
Added in version 3.7: See PEP 538 for more details.
- PYTHONDEVMODE¶
If this environment variable is set to a non-empty string, enable Python Development Mode, introducing additional runtime checks that are too expensive to be enabled by default. This is equivalent to setting the
-X
dev
option.Added in version 3.7.
- PYTHONUTF8¶
If set to
1
, enable the Python UTF-8 Mode.If set to
0
, disable the Python UTF-8 Mode.Setting any other non-empty string causes an error during interpreter initialisation.
Added in version 3.7.
- PYTHONWARNDEFAULTENCODING¶
If this environment variable is set to a non-empty string, issue a
EncodingWarning
when the locale-specific default encoding is used.See Opt-in EncodingWarning for details.
Added in version 3.10.
- PYTHONNODEBUGRANGES¶
If this variable is set, it disables the inclusion of the tables mapping extra location information (end line, start column offset and end column offset) to every instruction in code objects. This is useful when smaller code objects and pyc files are desired as well as suppressing the extra visual location indicators when the interpreter displays tracebacks.
Added in version 3.11.
- PYTHONPERFSUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf
command-line option and Python support for the Linux perf profiler.Added in version 3.12.
- PYTHON_PERF_JIT_SUPPORT¶
If this variable is set to a nonzero value, it enables support for the Linux
perf
profiler so Python calls can be detected by it using DWARF information.If set to
0
, disable Linuxperf
profiler support.See also the
-X perf_jit
command-line option and Python support for the Linux perf profiler.Added in version 3.13.
- PYTHON_DISABLE_REMOTE_DEBUG¶
If this variable is set to a non-empty string, it disables the remote debugging feature described in PEP 768. This includes both the functionality to schedule code for execution in another process and the functionality to receive code for execution in the current process.
See also the
-X disable_remote_debug
command-line option.Added in version 3.14.
- PYTHON_CPU_COUNT¶
If this variable is set to a positive integer, it overrides the return values of
os.cpu_count()
andos.process_cpu_count()
.See also the
-X cpu_count
command-line option.Added in version 3.13.
- PYTHON_FROZEN_MODULES¶
If this variable is set to
on
oroff
, it determines whether or not frozen modules are ignored by the import machinery. A value ofon
means they get imported andoff
means they are ignored. The default ison
for non-debug builds (the normal case) andoff
for debug builds. Note that theimportlib_bootstrap
andimportlib_bootstrap_external
frozen modules are always used, even if this flag is set tooff
.See also the
-X frozen_modules
command-line option.Added in version 3.13.
- PYTHON_COLORS¶
If this variable is set to
1
, the interpreter will colorize various kinds of output. Setting it to0
deactivates this behavior. See also Controlling color.Added in version 3.13.
- PYTHON_BASIC_REPL¶
If this variable is set to any value, the interpreter will not attempt to load the Python-based REPL that requires
readline
, and will instead use the traditional parser-based REPL.Added in version 3.13.
- PYTHON_HISTORY¶
This environment variable can be used to set the location of a
.python_history
file (by default, it is.python_history
in the user’s home directory).Added in version 3.13.
- PYTHON_GIL¶
If this variable is set to
1
, the global interpreter lock (GIL) will be forced on. Setting it to0
forces the GIL off (needs Python configured with the--disable-gil
build option).See also the
-X gil
command-line option, which takes precedence over this variable, and Free-threaded CPython.Added in version 3.13.
- PYTHON_THREAD_INHERIT_CONTEXT¶
If this variable is set to
1
thenThread
will, by default, use a copy of context of the caller ofThread.start()
when starting. Otherwise, new threads will start with an empty context. If unset, this variable defaults to1
on free-threaded builds and to0
otherwise. See also-X thread_inherit_context
.Added in version 3.14.
- PYTHON_CONTEXT_AWARE_WARNINGS¶
If set to
1
then thewarnings.catch_warnings
context manager will use aContextVar
to store warnings filter state. If unset, this variable defaults to1
on free-threaded builds and to0
otherwise. See-X context_aware_warnings
.Added in version 3.14.
- PYTHON_JIT¶
On builds where experimental just-in-time compilation is available, this variable can force the JIT to be disabled (
0
) or enabled (1
) at interpreter startup.Added in version 3.13.
- PYTHON_TLBC¶
If set to
1
enables thread-local bytecode. If set to0
thread-local bytecode and the specializing interpreter are disabled. Only applies to builds configured with--disable-gil
.See also the
-X tlbc
command-line option.Added in version 3.14.
1.2.1. Debug-mode variables¶
- PYTHONDUMPREFS¶
If set, Python will dump objects and reference counts still alive after shutting down the interpreter.
Needs Python configured with the
--with-trace-refs
build option.
- PYTHONDUMPREFSFILE¶
If set, Python will dump objects and reference counts still alive after shutting down the interpreter into a file under the path given as the value to this environment variable.
Needs Python configured with the
--with-trace-refs
build option.Added in version 3.11.
- PYTHON_PRESITE¶
If this variable is set to a module, that module will be imported early in the interpreter lifecycle, before the
site
module is executed, and before the__main__
module is created. Therefore, the imported module is not treated as__main__
.This can be used to execute code early during Python initialization.
To import a submodule, use
package.module
as the value, like in an import statement.See also the
-X presite
command-line option, which takes precedence over this variable.Needs Python configured with the
--with-pydebug
build option.Added in version 3.13.


15. Floating-Point Arithmetic: Issues and Limitations¶
Floating-point numbers are represented in computer hardware as base 2 (binary)
fractions. For example, the decimal fraction 0.625
has value 6/10 + 2/100 + 5/1000, and in the same way the binary fraction 0.101
has value 1/2 + 0/4 + 1/8. These two fractions have identical values, the only
real difference being that the first is written in base 10 fractional notation,
and the second in base 2.
Unfortunately, most decimal fractions cannot be represented exactly as binary fractions. A consequence is that, in general, the decimal floating-point numbers you enter are only approximated by the binary floating-point numbers actually stored in the machine.
The problem is easier to understand at first in base 10. Consider the fraction 1/3. You can approximate that as a base 10 fraction:
0.3
or, better,
0.33
or, better,
0.333
and so on. No matter how many digits you’re willing to write down, the result will never be exactly 1/3, but will be an increasingly better approximation of 1/3.
In the same way, no matter how many base 2 digits you’re willing to use, the decimal value 0.1 cannot be represented exactly as a base 2 fraction. In base 2, 1/10 is the infinitely repeating fraction
0.0001100110011001100110011001100110011001100110011...
Stop at any finite number of bits, and you get an approximation. On most
machines today, floats are approximated using a binary fraction with
the numerator using the first 53 bits starting with the most significant bit and
with the denominator as a power of two. In the case of 1/10, the binary fraction
is 3602879701896397 / 2 ** 55
which is close to but not exactly
equal to the true value of 1/10.
Many users are not aware of the approximation because of the way values are displayed. Python only prints a decimal approximation to the true decimal value of the binary approximation stored by the machine. On most machines, if Python were to print the true decimal value of the binary approximation stored for 0.1, it would have to display:
>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
That is more digits than most people find useful, so Python keeps the number of digits manageable by displaying a rounded value instead:
>>> 1 / 10
0.1
Just remember, even though the printed result looks like the exact value of 1/10, the actual stored value is the nearest representable binary fraction.
Interestingly, there are many different decimal numbers that share the same
nearest approximate binary fraction. For example, the numbers 0.1
and
0.10000000000000001
and
0.1000000000000000055511151231257827021181583404541015625
are all
approximated by 3602879701896397 / 2 ** 55
. Since all of these decimal
values share the same approximation, any one of them could be displayed
while still preserving the invariant eval(repr(x)) == x
.
Historically, the Python prompt and built-in repr()
function would choose
the one with 17 significant digits, 0.10000000000000001
. Starting with
Python 3.1, Python (on most systems) is now able to choose the shortest of
these and simply display 0.1
.
Note that this is in the very nature of binary floating point: this is not a bug in Python, and it is not a bug in your code either. You’ll see the same kind of thing in all languages that support your hardware’s floating-point arithmetic (although some languages may not display the difference by default, or in all output modes).
For more pleasant output, you may wish to use string formatting to produce a limited number of significant digits:
>>> format(math.pi, '.12g') # give 12 significant digits
'3.14159265359'
>>> format(math.pi, '.2f') # give 2 digits after the point
'3.14'
>>> repr(math.pi)
'3.141592653589793'
It’s important to realize that this is, in a real sense, an illusion: you’re simply rounding the display of the true machine value.
One illusion may beget another. For example, since 0.1 is not exactly 1/10, summing three values of 0.1 may not yield exactly 0.3, either:
>>> 0.1 + 0.1 + 0.1 == 0.3
False
Also, since the 0.1 cannot get any closer to the exact value of 1/10 and
0.3 cannot get any closer to the exact value of 3/10, then pre-rounding with
round()
function cannot help:
>>> round(0.1, 1) + round(0.1, 1) + round(0.1, 1) == round(0.3, 1)
False
Though the numbers cannot be made closer to their intended exact values,
the math.isclose()
function can be useful for comparing inexact values:
>>> math.isclose(0.1 + 0.1 + 0.1, 0.3)
True
Alternatively, the round()
function can be used to compare rough
approximations:
>>> round(math.pi, ndigits=2) == round(22 / 7, ndigits=2)
True
Binary floating-point arithmetic holds many surprises like this. The problem with “0.1” is explained in precise detail below, in the “Representation Error” section. See Examples of Floating Point Problems for a pleasant summary of how binary floating point works and the kinds of problems commonly encountered in practice. Also see The Perils of Floating Point for a more complete account of other common surprises.
As that says near the end, “there are no easy answers.” Still, don’t be unduly wary of floating point! The errors in Python float operations are inherited from the floating-point hardware, and on most machines are on the order of no more than 1 part in 2**53 per operation. That’s more than adequate for most tasks, but you do need to keep in mind that it’s not decimal arithmetic and that every float operation can suffer a new rounding error.
While pathological cases do exist, for most casual use of floating-point
arithmetic you’ll see the result you expect in the end if you simply round the
display of your final results to the number of decimal digits you expect.
str()
usually suffices, and for finer control see the str.format()
method’s format specifiers in Format String Syntax.
For use cases which require exact decimal representation, try using the
decimal
module which implements decimal arithmetic suitable for
accounting applications and high-precision applications.
Another form of exact arithmetic is supported by the fractions
module
which implements arithmetic based on rational numbers (so the numbers like
1/3 can be represented exactly).
If you are a heavy user of floating-point operations you should take a look at the NumPy package and many other packages for mathematical and statistical operations supplied by the SciPy project. See <https://scipy.org>.
Python provides tools that may help on those rare occasions when you really
do want to know the exact value of a float. The
float.as_integer_ratio()
method expresses the value of a float as a
fraction:
>>> x = 3.14159
>>> x.as_integer_ratio()
(3537115888337719, 1125899906842624)
Since the ratio is exact, it can be used to losslessly recreate the original value:
>>> x == 3537115888337719 / 1125899906842624
True
The float.hex()
method expresses a float in hexadecimal (base
16), again giving the exact value stored by your computer:
>>> x.hex()
'0x1.921f9f01b866ep+1'
This precise hexadecimal representation can be used to reconstruct the float value exactly:
>>> x == float.fromhex('0x1.921f9f01b866ep+1')
True
Since the representation is exact, it is useful for reliably porting values across different versions of Python (platform independence) and exchanging data with other languages that support the same format (such as Java and C99).
Another helpful tool is the sum()
function which helps mitigate
loss-of-precision during summation. It uses extended precision for
intermediate rounding steps as values are added onto a running total.
That can make a difference in overall accuracy so that the errors do not
accumulate to the point where they affect the final total:
>>> 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 == 1.0
False
>>> sum([0.1] * 10) == 1.0
True
The math.fsum()
goes further and tracks all of the “lost digits”
as values are added onto a running total so that the result has only a
single rounding. This is slower than sum()
but will be more
accurate in uncommon cases where large magnitude inputs mostly cancel
each other out leaving a final sum near zero:
>>> arr = [-0.10430216751806065, -266310978.67179024, 143401161448607.16,
... -143401161400469.7, 266262841.31058735, -0.003244936839808227]
>>> float(sum(map(Fraction, arr))) # Exact summation with single rounding
8.042173697819788e-13
>>> math.fsum(arr) # Single rounding
8.042173697819788e-13
>>> sum(arr) # Multiple roundings in extended precision
8.042178034628478e-13
>>> total = 0.0
>>> for x in arr:
... total += x # Multiple roundings in standard precision
...
>>> total # Straight addition has no correct digits!
-0.0051575902860057365
15.1. Representation Error¶
This section explains the “0.1” example in detail, and shows how you can perform an exact analysis of cases like this yourself. Basic familiarity with binary floating-point representation is assumed.
Representation error refers to the fact that some (most, actually) decimal fractions cannot be represented exactly as binary (base 2) fractions. This is the chief reason why Python (or Perl, C, C++, Java, Fortran, and many others) often won’t display the exact decimal number you expect.
Why is that? 1/10 is not exactly representable as a binary fraction. Since at least 2000, almost all machines use IEEE 754 binary floating-point arithmetic, and almost all platforms map Python floats to IEEE 754 binary64 “double precision” values. IEEE 754 binary64 values contain 53 bits of precision, so on input the computer strives to convert 0.1 to the closest fraction it can of the form J/2**N where J is an integer containing exactly 53 bits. Rewriting
1 / 10 ~= J / (2**N)
as
J ~= 2**N / 10
and recalling that J has exactly 53 bits (is >= 2**52
but < 2**53
),
the best value for N is 56:
>>> 2**52 <= 2**56 // 10 < 2**53
True
That is, 56 is the only value for N that leaves J with exactly 53 bits. The best possible value for J is then that quotient rounded:
>>> q, r = divmod(2**56, 10)
>>> r
6
Since the remainder is more than half of 10, the best approximation is obtained by rounding up:
>>> q+1
7205759403792794
Therefore the best possible approximation to 1/10 in IEEE 754 double precision is:
7205759403792794 / 2 ** 56
Dividing both the numerator and denominator by two reduces the fraction to:
3602879701896397 / 2 ** 55
Note that since we rounded up, this is actually a little bit larger than 1/10; if we had not rounded up, the quotient would have been a little bit smaller than 1/10. But in no case can it be exactly 1/10!
So the computer never “sees” 1/10: what it sees is the exact fraction given above, the best IEEE 754 double approximation it can get:
>>> 0.1 * 2 ** 55
3602879701896397.0
If we multiply that fraction by 10**55, we can see the value out to 55 decimal digits:
>>> 3602879701896397 * 10 ** 55 // 2 ** 55
1000000000000000055511151231257827021181583404541015625
meaning that the exact number stored in the computer is equal to the decimal value 0.1000000000000000055511151231257827021181583404541015625. Instead of displaying the full decimal value, many languages (including older versions of Python), round the result to 17 significant digits:
>>> format(0.1, '.17f')
'0.10000000000000001'
The fractions
and decimal
modules make these calculations
easy:
>>> from decimal import Decimal
>>> from fractions import Fraction
>>> Fraction.from_float(0.1)
Fraction(3602879701896397, 36028797018963968)
>>> (0.1).as_integer_ratio()
(3602879701896397, 36028797018963968)
>>> Decimal.from_float(0.1)
Decimal('0.1000000000000000055511151231257827021181583404541015625')
>>> format(Decimal.from_float(0.1), '.17')
'0.10000000000000001'


Enum HOWTO

Enum HOWTO¶
An Enum
is a set of symbolic names bound to unique values. They are
similar to global variables, but they offer a more useful repr()
,
grouping, type-safety, and a few other features.
They are most useful when you have a variable that can take one of a limited selection of values. For example, the days of the week:
>>> from enum import Enum
>>> class Weekday(Enum):
... MONDAY = 1
... TUESDAY = 2
... WEDNESDAY = 3
... THURSDAY = 4
... FRIDAY = 5
... SATURDAY = 6
... SUNDAY = 7
Or perhaps the RGB primary colors:
>>> from enum import Enum
>>> class Color(Enum):
... RED = 1
... GREEN = 2
... BLUE = 3
As you can see, creating an Enum
is as simple as writing a class that
inherits from Enum
itself.
Note
Case of Enum Members
Because Enums are used to represent constants, and to help avoid issues with name clashes between mixin-class methods/attributes and enum names, we strongly recommend using UPPER_CASE names for members, and will be using that style in our examples.
Depending on the nature of the enum a member’s value may or may not be important, but either way that value can be used to get the corresponding member:
>>> Weekday(3)
<Weekday.WEDNESDAY: 3>
As you can see, the repr()
of a member shows the enum name, the member name,
and the value. The str()
of a member shows only the enum name and member
name:
>>> print(Weekday.THURSDAY)
Weekday.THURSDAY
The type of an enumeration member is the enum it belongs to:
>>> type(Weekday.MONDAY)
<enum 'Weekday'>
>>> isinstance(Weekday.FRIDAY, Weekday)
True
Enum members have an attribute that contains just their name
:
>>> print(Weekday.TUESDAY.name)
TUESDAY
Likewise, they have an attribute for their value
:
>>> Weekday.WEDNESDAY.value
3
Unlike many languages that treat enumerations solely as name/value pairs,
Python Enums can have behavior added. For example, datetime.date
has two methods for returning the weekday:
weekday()
and isoweekday()
.
The difference is that one of them counts from 0-6 and the other from 1-7.
Rather than keep track of that ourselves we can add a method to the Weekday
enum to extract the day from the date
instance and return the matching
enum member:
@classmethod
def from_date(cls, date):
return cls(date.isoweekday())
The complete Weekday
enum now looks like this:
>>> class Weekday(Enum):
... MONDAY = 1
... TUESDAY = 2
... WEDNESDAY = 3
... THURSDAY = 4
... FRIDAY = 5
... SATURDAY = 6
... SUNDAY = 7
... #
... @classmethod
... def from_date(cls, date):
... return cls(date.isoweekday())
Now we can find out what today is! Observe:
>>> from datetime import date
>>> Weekday.from_date(date.today())
<Weekday.TUESDAY: 2>
Of course, if you’re reading this on some other day, you’ll see that day instead.
This Weekday
enum is great if our variable only needs one day, but
what if we need several? Maybe we’re writing a function to plot chores during
a week, and don’t want to use a list
– we could use a different type
of Enum
:
>>> from enum import Flag
>>> class Weekday(Flag):
... MONDAY = 1
... TUESDAY = 2
... WEDNESDAY = 4
... THURSDAY = 8
... FRIDAY = 16
... SATURDAY = 32
... SUNDAY = 64
We’ve changed two things: we’re inherited from Flag
, and the values are
all powers of 2.
Just like the original Weekday
enum above, we can have a single selection:
>>> first_week_day = Weekday.MONDAY
>>> first_week_day
<Weekday.MONDAY: 1>
But Flag
also allows us to combine several members into a single
variable:
>>> weekend = Weekday.SATURDAY | Weekday.SUNDAY
>>> weekend
<Weekday.SATURDAY|SUNDAY: 96>
You can even iterate over a Flag
variable:
>>> for day in weekend:
... print(day)
Weekday.SATURDAY
Weekday.SUNDAY
Okay, let’s get some chores set up:
>>> chores_for_ethan = {
... 'feed the cat': Weekday.MONDAY | Weekday.WEDNESDAY | Weekday.FRIDAY,
... 'do the dishes': Weekday.TUESDAY | Weekday.THURSDAY,
... 'answer SO questions': Weekday.SATURDAY,
... }
And a function to display the chores for a given day:
>>> def show_chores(chores, day):
... for chore, days in chores.items():
... if day in days:
... print(chore)
...
>>> show_chores(chores_for_ethan, Weekday.SATURDAY)
answer SO questions
In cases where the actual values of the members do not matter, you can save
yourself some work and use auto()
for the values:
>>> from enum import auto
>>> class Weekday(Flag):
... MONDAY = auto()
... TUESDAY = auto()
... WEDNESDAY = auto()
... THURSDAY = auto()
... FRIDAY = auto()
... SATURDAY = auto()
... SUNDAY = auto()
... WEEKEND = SATURDAY | SUNDAY
Programmatic access to enumeration members and their attributes¶
Sometimes it’s useful to access members in enumerations programmatically (i.e.
situations where Color.RED
won’t do because the exact color is not known
at program-writing time). Enum
allows such access:
>>> Color(1)
<Color.RED: 1>
>>> Color(3)
<Color.BLUE: 3>
If you want to access enum members by name, use item access:
>>> Color['RED']
<Color.RED: 1>
>>> Color['GREEN']
<Color.GREEN: 2>
If you have an enum member and need its name
or value
:
>>> member = Color.RED
>>> member.name
'RED'
>>> member.value
1
Duplicating enum members and values¶
Having two enum members with the same name is invalid:
>>> class Shape(Enum):
... SQUARE = 2
... SQUARE = 3
...
Traceback (most recent call last):
...
TypeError: 'SQUARE' already defined as 2
However, an enum member can have other names associated with it. Given two
entries A
and B
with the same value (and A
defined first), B
is an alias for the member A
. By-value lookup of the value of A
will
return the member A
. By-name lookup of A
will return the member A
.
By-name lookup of B
will also return the member A
:
>>> class Shape(Enum):
... SQUARE = 2
... DIAMOND = 1
... CIRCLE = 3
... ALIAS_FOR_SQUARE = 2
...
>>> Shape.SQUARE
<Shape.SQUARE: 2>
>>> Shape.ALIAS_FOR_SQUARE
<Shape.SQUARE: 2>
>>> Shape(2)
<Shape.SQUARE: 2>
Note
Attempting to create a member with the same name as an already defined attribute (another member, a method, etc.) or attempting to create an attribute with the same name as a member is not allowed.
Ensuring unique enumeration values¶
By default, enumerations allow multiple names as aliases for the same value.
When this behavior isn’t desired, you can use the unique()
decorator:
>>> from enum import Enum, unique
>>> @unique
... class Mistake(Enum):
... ONE = 1
... TWO = 2
... THREE = 3
... FOUR = 3
...
Traceback (most recent call last):
...
ValueError: duplicate values found in <enum 'Mistake'>: FOUR -> THREE
Using automatic values¶
If the exact value is unimportant you can use auto
:
>>> from enum import Enum, auto
>>> class Color(Enum):
... RED = auto()
... BLUE = auto()
... GREEN = auto()
...
>>> [member.value for member in Color]
[1, 2, 3]
The values are chosen by _generate_next_value_()
, which can be
overridden:
>>> class AutoName(Enum):
... @staticmethod
... def _generate_next_value_(name, start, count, last_values):
... return name
...
>>> class Ordinal(AutoName):
... NORTH = auto()
... SOUTH = auto()
... EAST = auto()
... WEST = auto()
...
>>> [member.value for member in Ordinal]
['NORTH', 'SOUTH', 'EAST', 'WEST']
Note
The _generate_next_value_()
method must be defined before any members.
Iteration¶
Iterating over the members of an enum does not provide the aliases:
>>> list(Shape)
[<Shape.SQUARE: 2>, <Shape.DIAMOND: 1>, <Shape.CIRCLE: 3>]
>>> list(Weekday)
[<Weekday.MONDAY: 1>, <Weekday.TUESDAY: 2>, <Weekday.WEDNESDAY: 4>, <Weekday.THURSDAY: 8>, <Weekday.FRIDAY: 16>, <Weekday.SATURDAY: 32>, <Weekday.SUNDAY: 64>]
Note that the aliases Shape.ALIAS_FOR_SQUARE
and Weekday.WEEKEND
aren’t shown.
The special attribute __members__
is a read-only ordered mapping of names
to members. It includes all names defined in the enumeration, including the
aliases:
>>> for name, member in Shape.__members__.items():
... name, member
...
('SQUARE', <Shape.SQUARE: 2>)
('DIAMOND', <Shape.DIAMOND: 1>)
('CIRCLE', <Shape.CIRCLE: 3>)
('ALIAS_FOR_SQUARE', <Shape.SQUARE: 2>)
The __members__
attribute can be used for detailed programmatic access to
the enumeration members. For example, finding all the aliases:
>>> [name for name, member in Shape.__members__.items() if member.name != name]
['ALIAS_FOR_SQUARE']
Note
Aliases for flags include values with multiple flags set, such as 3
,
and no flags set, i.e. 0
.
Comparisons¶
Enumeration members are compared by identity:
>>> Color.RED is Color.RED
True
>>> Color.RED is Color.BLUE
False
>>> Color.RED is not Color.BLUE
True
Ordered comparisons between enumeration values are not supported. Enum members are not integers (but see IntEnum below):
>>> Color.RED < Color.BLUE
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'Color' and 'Color'
Equality comparisons are defined though:
>>> Color.BLUE == Color.RED
False
>>> Color.BLUE != Color.RED
True
>>> Color.BLUE == Color.BLUE
True
Comparisons against non-enumeration values will always compare not equal
(again, IntEnum
was explicitly designed to behave differently, see
below):
>>> Color.BLUE == 2
False
Warning
It is possible to reload modules – if a reloaded module contains enums, they will be recreated, and the new members may not compare identical/equal to the original members.
Allowed members and attributes of enumerations¶
Most of the examples above use integers for enumeration values. Using integers is short and handy (and provided by default by the Functional API), but not strictly enforced. In the vast majority of use-cases, one doesn’t care what the actual value of an enumeration is. But if the value is important, enumerations can have arbitrary values.
Enumerations are Python classes, and can have methods and special methods as usual. If we have this enumeration:
>>> class Mood(Enum):
... FUNKY = 1
... HAPPY = 3
...
... def describe(self):
... # self is the member here
... return self.name, self.value
...
... def __str__(self):
... return 'my custom str! {0}'.format(self.value)
...
... @classmethod
... def favorite_mood(cls):
... # cls here is the enumeration
... return cls.HAPPY
...
Then:
>>> Mood.favorite_mood()
<Mood.HAPPY: 3>
>>> Mood.HAPPY.describe()
('HAPPY', 3)
>>> str(Mood.FUNKY)
'my custom str! 1'
The rules for what is allowed are as follows: names that start and end with
a single underscore are reserved by enum and cannot be used; all other
attributes defined within an enumeration will become members of this
enumeration, with the exception of special methods (__str__()
,
__add__()
, etc.), descriptors (methods are also descriptors), and
variable names listed in _ignore_
.
Note: if your enumeration defines __new__()
and/or __init__()
,
any value(s) given to the enum member will be passed into those methods.
See Planet for an example.
Note
The __new__()
method, if defined, is used during creation of the Enum
members; it is then replaced by Enum’s __new__()
which is used after
class creation for lookup of existing members. See When to use __new__() vs. __init__() for
more details.
Restricted Enum subclassing¶
A new Enum
class must have one base enum class, up to one concrete
data type, and as many object
-based mixin classes as needed. The
order of these base classes is:
class EnumName([mix-in, ...,] [data-type,] base-enum):
pass
Also, subclassing an enumeration is allowed only if the enumeration does not define any members. So this is forbidden:
>>> class MoreColor(Color):
... PINK = 17
...
Traceback (most recent call last):
...
TypeError: <enum 'MoreColor'> cannot extend <enum 'Color'>
But this is allowed:
>>> class Foo(Enum):
... def some_behavior(self):
... pass
...
>>> class Bar(Foo):
... HAPPY = 1
... SAD = 2
...
Allowing subclassing of enums that define members would lead to a violation of some important invariants of types and instances. On the other hand, it makes sense to allow sharing some common behavior between a group of enumerations. (See OrderedEnum for an example.)
Dataclass support¶
When inheriting from a dataclass
,
the __repr__()
omits the inherited class’ name. For example:
>>> from dataclasses import dataclass, field
>>> @dataclass
... class CreatureDataMixin:
... size: str
... legs: int
... tail: bool = field(repr=False, default=True)
...
>>> class Creature(CreatureDataMixin, Enum):
... BEETLE = 'small', 6
... DOG = 'medium', 4
...
>>> Creature.DOG
<Creature.DOG: size='medium', legs=4>
Use the dataclass()
argument repr=False
to use the standard repr()
.
Changed in version 3.12: Only the dataclass fields are shown in the value area, not the dataclass’ name.
Note
Adding dataclass()
decorator to Enum
and its subclasses is not supported. It will not raise any errors,
but it will produce very strange results at runtime, such as members
being equal to each other:
>>> @dataclass # don't do this: it does not make any sense
... class Color(Enum):
... RED = 1
... BLUE = 2
...
>>> Color.RED is Color.BLUE
False
>>> Color.RED == Color.BLUE # problem is here: they should not be equal
True
Pickling¶
Enumerations can be pickled and unpickled:
>>> from test.test_enum import Fruit
>>> from pickle import dumps, loads
>>> Fruit.TOMATO is loads(dumps(Fruit.TOMATO))
True
The usual restrictions for pickling apply: picklable enums must be defined in the top level of a module, since unpickling requires them to be importable from that module.
Note
With pickle protocol version 4 it is possible to easily pickle enums nested in other classes.
It is possible to modify how enum members are pickled/unpickled by defining
__reduce_ex__()
in the enumeration class. The default method is by-value,
but enums with complicated values may want to use by-name:
>>> import enum
>>> class MyEnum(enum.Enum):
... __reduce_ex__ = enum.pickle_by_enum_name
Note
Using by-name for flags is not recommended, as unnamed aliases will not unpickle.
Functional API¶
The Enum
class is callable, providing the following functional API:
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG')
>>> Animal
<enum 'Animal'>
>>> Animal.ANT
<Animal.ANT: 1>
>>> list(Animal)
[<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
The semantics of this API resemble namedtuple
. The first
argument of the call to Enum
is the name of the enumeration.
The second argument is the source of enumeration member names. It can be a
whitespace-separated string of names, a sequence of names, a sequence of
2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to
values. The last two options enable assigning arbitrary values to
enumerations; the others auto-assign increasing integers starting with 1 (use
the start
parameter to specify a different starting value). A
new class derived from Enum
is returned. In other words, the above
assignment to Animal
is equivalent to:
>>> class Animal(Enum):
... ANT = 1
... BEE = 2
... CAT = 3
... DOG = 4
...
The reason for defaulting to 1
as the starting number and not 0
is
that 0
is False
in a boolean sense, but by default enum members all
evaluate to True
.
Pickling enums created with the functional API can be tricky as frame stack implementation details are used to try and figure out which module the enumeration is being created in (e.g. it will fail if you use a utility function in a separate module, and also may not work on IronPython or Jython). The solution is to specify the module name explicitly as follows:
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', module=__name__)
Warning
If module
is not supplied, and Enum cannot determine what it is,
the new Enum members will not be unpicklable; to keep errors closer to
the source, pickling will be disabled.
The new pickle protocol 4 also, in some circumstances, relies on
__qualname__
being set to the location where pickle will be able
to find the class. For example, if the class was made available in class
SomeData in the global scope:
>>> Animal = Enum('Animal', 'ANT BEE CAT DOG', qualname='SomeData.Animal')
The complete signature is:
Enum(
value='NewEnumName',
names=<...>,
*,
module='...',
qualname='...',
type=<mixed-in class>,
start=1,
)
value: What the new enum class will record as its name.
names: The enum members. This can be a whitespace- or comma-separated string (values will start at 1 unless otherwise specified):
'RED GREEN BLUE' | 'RED,GREEN,BLUE' | 'RED, GREEN, BLUE'
or an iterator of names:
['RED', 'GREEN', 'BLUE']
or an iterator of (name, value) pairs:
[('CYAN', 4), ('MAGENTA', 5), ('YELLOW', 6)]
or a mapping:
{'CHARTREUSE': 7, 'SEA_GREEN': 11, 'ROSEMARY': 42}
module: name of module where new enum class can be found.
qualname: where in module new enum class can be found.
type: type to mix in to new enum class.
start: number to start counting at if only names are passed in.
Changed in version 3.5: The start parameter was added.
Derived Enumerations¶
IntEnum¶
The first variation of Enum
that is provided is also a subclass of
int
. Members of an IntEnum
can be compared to integers;
by extension, integer enumerations of different types can also be compared
to each other:
>>> from enum import IntEnum
>>> class Shape(IntEnum):
... CIRCLE = 1
... SQUARE = 2
...
>>> class Request(IntEnum):
... POST = 1
... GET = 2
...
>>> Shape == 1
False
>>> Shape.CIRCLE == 1
True
>>> Shape.CIRCLE == Request.POST
True
However, they still can’t be compared to standard Enum
enumerations:
>>> class Shape(IntEnum):
... CIRCLE = 1
... SQUARE = 2
...
>>> class Color(Enum):
... RED = 1
... GREEN = 2
...
>>> Shape.CIRCLE == Color.RED
False
IntEnum
values behave like integers in other ways you’d expect:
>>> int(Shape.CIRCLE)
1
>>> ['a', 'b', 'c'][Shape.CIRCLE]
'b'
>>> [i for i in range(Shape.SQUARE)]
[0, 1]
StrEnum¶
The second variation of Enum
that is provided is also a subclass of
str
. Members of a StrEnum
can be compared to strings;
by extension, string enumerations of different types can also be compared
to each other.
Added in version 3.11.
IntFlag¶
The next variation of Enum
provided, IntFlag
, is also based
on int
. The difference being IntFlag
members can be combined
using the bitwise operators (&, |, ^, ~) and the result is still an
IntFlag
member, if possible. Like IntEnum
, IntFlag
members are also integers and can be used wherever an int
is used.
Note
Any operation on an IntFlag
member besides the bit-wise operations will
lose the IntFlag
membership.
Bit-wise operations that result in invalid IntFlag
values will lose the
IntFlag
membership. See FlagBoundary
for
details.
Added in version 3.6.
Changed in version 3.11.
Sample IntFlag
class:
>>> from enum import IntFlag
>>> class Perm(IntFlag):
... R = 4
... W = 2
... X = 1
...
>>> Perm.R | Perm.W
<Perm.R|W: 6>
>>> Perm.R + Perm.W
6
>>> RW = Perm.R | Perm.W
>>> Perm.R in RW
True
It is also possible to name the combinations:
>>> class Perm(IntFlag):
... R = 4
... W = 2
... X = 1
... RWX = 7
...
>>> Perm.RWX
<Perm.RWX: 7>
>>> ~Perm.RWX
<Perm: 0>
>>> Perm(7)
<Perm.RWX: 7>
Note
Named combinations are considered aliases. Aliases do not show up during iteration, but can be returned from by-value lookups.
Changed in version 3.11.
Another important difference between IntFlag
and Enum
is that
if no flags are set (the value is 0), its boolean evaluation is False
:
>>> Perm.R & Perm.X
<Perm: 0>
>>> bool(Perm.R & Perm.X)
False
Because IntFlag
members are also subclasses of int
they can
be combined with them (but may lose IntFlag
membership:
>>> Perm.X | 4
<Perm.R|X: 5>
>>> Perm.X + 8
9
Note
The negation operator, ~
, always returns an IntFlag
member with a
positive value:
>>> (~Perm.X).value == (Perm.R|Perm.W).value == 6
True
IntFlag
members can also be iterated over:
>>> list(RW)
[<Perm.R: 4>, <Perm.W: 2>]
Added in version 3.11.
Flag¶
The last variation is Flag
. Like IntFlag
, Flag
members can be combined using the bitwise operators (&, |, ^, ~). Unlike
IntFlag
, they cannot be combined with, nor compared against, any
other Flag
enumeration, nor int
. While it is possible to
specify the values directly it is recommended to use auto
as the
value and let Flag
select an appropriate value.
Added in version 3.6.
Like IntFlag
, if a combination of Flag
members results in no
flags being set, the boolean evaluation is False
:
>>> from enum import Flag, auto
>>> class Color(Flag):
... RED = auto()
... BLUE = auto()
... GREEN = auto()
...
>>> Color.RED & Color.GREEN
<Color: 0>
>>> bool(Color.RED & Color.GREEN)
False
Individual flags should have values that are powers of two (1, 2, 4, 8, …), while combinations of flags will not:
>>> class Color(Flag):
... RED = auto()
... BLUE = auto()
... GREEN = auto()
... WHITE = RED | BLUE | GREEN
...
>>> Color.WHITE
<Color.WHITE: 7>
Giving a name to the “no flags set” condition does not change its boolean value:
>>> class Color(Flag):
... BLACK = 0
... RED = auto()
... BLUE = auto()
... GREEN = auto()
...
>>> Color.BLACK
<Color.BLACK: 0>
>>> bool(Color.BLACK)
False
Flag
members can also be iterated over:
>>> purple = Color.RED | Color.BLUE
>>> list(purple)
[<Color.RED: 1>, <Color.BLUE: 2>]
Added in version 3.11.
Note
For the majority of new code, Enum
and Flag
are strongly
recommended, since IntEnum
and IntFlag
break some
semantic promises of an enumeration (by being comparable to integers, and
thus by transitivity to other unrelated enumerations). IntEnum
and IntFlag
should be used only in cases where Enum
and
Flag
will not do; for example, when integer constants are replaced
with enumerations, or for interoperability with other systems.
Others¶
While IntEnum
is part of the enum
module, it would be very
simple to implement independently:
class IntEnum(int, ReprEnum): # or Enum instead of ReprEnum
pass
This demonstrates how similar derived enumerations can be defined; for example
a FloatEnum
that mixes in float
instead of int
.
Some rules:
When subclassing
Enum
, mix-in types must appear before theEnum
class itself in the sequence of bases, as in theIntEnum
example above.Mix-in types must be subclassable. For example,
bool
andrange
are not subclassable and will throw an error during Enum creation if used as the mix-in type.While
Enum
can have members of any type, once you mix in an additional type, all the members must have values of that type, e.g.int
above. This restriction does not apply to mix-ins which only add methods and don’t specify another type.When another data type is mixed in, the
value
attribute is not the same as the enum member itself, although it is equivalent and will compare equal.A
data type
is a mixin that defines__new__()
, or adataclass
%-style formatting:
%s
and%r
call theEnum
class’s__str__()
and__repr__()
respectively; other codes (such as%i
or%h
for IntEnum) treat the enum member as its mixed-in type.Formatted string literals,
str.format()
, andformat()
will use the enum’s__str__()
method.
When to use __new__()
vs. __init__()
¶
__new__()
must be used whenever you want to customize the actual value of
the Enum
member. Any other modifications may go in either
__new__()
or __init__()
, with __init__()
being preferred.
For example, if you want to pass several items to the constructor, but only want one of them to be the value:
>>> class Coordinate(bytes, Enum):
... """
... Coordinate with binary codes that can be indexed by the int code.
... """
... def __new__(cls, value, label, unit):
... obj = bytes.__new__(cls, [value])
... obj._value_ = value
... obj.label = label
... obj.unit = unit
... return obj
... PX = (0, 'P.X', 'km')
... PY = (1, 'P.Y', 'km')
... VX = (2, 'V.X', 'km/s')
... VY = (3, 'V.Y', 'km/s')
...
>>> print(Coordinate['PY'])
Coordinate.PY
>>> print(Coordinate(3))
Coordinate.VY
Warning
Do not call super().__new__()
, as the lookup-only __new__
is the one
that is found; instead, use the data type directly.
Finer Points¶
Supported __dunder__
names¶
__members__
is a read-only ordered mapping of member_name
:member
items. It is only available on the class.
__new__()
, if specified, must create and return the enum members; it is
also a very good idea to set the member’s _value_
appropriately. Once
all the members are created it is no longer used.
Supported _sunder_
names¶
_name_
– name of the member_value_
– value of the member; can be set in__new__
_missing_()
– a lookup function used when a value is not found; may be overridden_ignore_
– a list of names, either as alist
or astr
, that will not be transformed into members, and will be removed from the final class_generate_next_value_()
– used to get an appropriate value for an enum member; may be overridden_add_alias_()
– adds a new name as an alias to an existing member._add_value_alias_()
– adds a new value as an alias to an existing member. See MultiValueEnum for an example.Note
For standard
Enum
classes the next value chosen is the highest value seen incremented by one.For
Flag
classes the next value chosen will be the next highest power-of-two.Changed in version 3.13: Prior versions would use the last seen value instead of the highest value.
Added in version 3.6: _missing_
, _order_
, _generate_next_value_
Added in version 3.7: _ignore_
Added in version 3.13: _add_alias_
, _add_value_alias_
To help keep Python 2 / Python 3 code in sync an _order_
attribute can
be provided. It will be checked against the actual order of the enumeration
and raise an error if the two do not match:
>>> class Color(Enum):
... _order_ = 'RED GREEN BLUE'
... RED = 1
... BLUE = 3
... GREEN = 2
...
Traceback (most recent call last):
...
TypeError: member order does not match _order_:
['RED', 'BLUE', 'GREEN']
['RED', 'GREEN', 'BLUE']
Note
In Python 2 code the _order_
attribute is necessary as definition
order is lost before it can be recorded.
_Private__names¶
Private names are not converted to enum members, but remain normal attributes.
Changed in version 3.11.
Enum
member type¶
Enum members are instances of their enum class, and are normally accessed as
EnumClass.member
. In certain situations, such as writing custom enum
behavior, being able to access one member directly from another is useful,
and is supported; however, in order to avoid name clashes between member names
and attributes/methods from mixed-in classes, upper-case names are strongly
recommended.
Changed in version 3.5.
Creating members that are mixed with other data types¶
When subclassing other data types, such as int
or str
, with
an Enum
, all values after the =
are passed to that data type’s
constructor. For example:
>>> class MyEnum(IntEnum): # help(int) -> int(x, base=10) -> integer
... example = '11', 16 # so x='11' and base=16
...
>>> MyEnum.example.value # and hex(11) is...
17
Boolean value of Enum
classes and members¶
Enum classes that are mixed with non-Enum
types (such as
int
, str
, etc.) are evaluated according to the mixed-in
type’s rules; otherwise, all members evaluate as True
. To make your
own enum’s boolean evaluation depend on the member’s value add the following to
your class:
def __bool__(self):
return bool(self.value)
Enum
classes with methods¶
If you give your enum subclass extra methods, like the Planet
class below, those methods will show up in a dir()
of the member,
but not of the class:
>>> dir(Planet)
['EARTH', 'JUPITER', 'MARS', 'MERCURY', 'NEPTUNE', 'SATURN', 'URANUS', 'VENUS', '__class__', '__doc__', '__members__', '__module__']
>>> dir(Planet.EARTH)
['__class__', '__doc__', '__module__', 'mass', 'name', 'radius', 'surface_gravity', 'value']
Combining members of Flag
¶
Iterating over a combination of Flag
members will only return the members that
are comprised of a single bit:
>>> class Color(Flag):
... RED = auto()
... GREEN = auto()
... BLUE = auto()
... MAGENTA = RED | BLUE
... YELLOW = RED | GREEN
... CYAN = GREEN | BLUE
...
>>> Color(3) # named combination
<Color.YELLOW: 3>
>>> Color(7) # not named combination
<Color.RED|GREEN|BLUE: 7>
Flag
and IntFlag
minutia¶
Using the following snippet for our examples:
>>> class Color(IntFlag):
... BLACK = 0
... RED = 1
... GREEN = 2
... BLUE = 4
... PURPLE = RED | BLUE
... WHITE = RED | GREEN | BLUE
...
the following are true:
single-bit flags are canonical
multi-bit and zero-bit flags are aliases
only canonical flags are returned during iteration:
>>> list(Color.WHITE) [<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
negating a flag or flag set returns a new flag/flag set with the corresponding positive integer value:
>>> Color.BLUE <Color.BLUE: 4> >>> ~Color.BLUE <Color.RED|GREEN: 3>
names of pseudo-flags are constructed from their members’ names:
>>> (Color.RED | Color.GREEN).name 'RED|GREEN' >>> class Perm(IntFlag): ... R = 4 ... W = 2 ... X = 1 ... >>> (Perm.R & Perm.W).name is None # effectively Perm(0) True
multi-bit flags, aka aliases, can be returned from operations:
>>> Color.RED | Color.BLUE <Color.PURPLE: 5> >>> Color(7) # or Color(-1) <Color.WHITE: 7> >>> Color(0) <Color.BLACK: 0>
membership / containment checking: zero-valued flags are always considered to be contained:
>>> Color.BLACK in Color.WHITE True
otherwise, only if all bits of one flag are in the other flag will True be returned:
>>> Color.PURPLE in Color.WHITE True >>> Color.GREEN in Color.PURPLE False
There is a new boundary mechanism that controls how out-of-range / invalid
bits are handled: STRICT
, CONFORM
, EJECT
, and KEEP
:
STRICT –> raises an exception when presented with invalid values
CONFORM –> discards any invalid bits
EJECT –> lose Flag status and become a normal int with the given value
KEEP –> keep the extra bits
keeps Flag status and extra bits
extra bits do not show up in iteration
extra bits do show up in repr() and str()
The default for Flag is STRICT
, the default for IntFlag
is EJECT
,
and the default for _convert_
is KEEP
(see ssl.Options
for an
example of when KEEP
is needed).
How are Enums and Flags different?¶
Enums have a custom metaclass that affects many aspects of both derived Enum
classes and their instances (members).
Enum Classes¶
The EnumType
metaclass is responsible for providing the
__contains__()
, __dir__()
, __iter__()
and other methods that
allow one to do things with an Enum
class that fail on a typical
class, such as list(Color)
or some_enum_var in Color
. EnumType
is
responsible for ensuring that various other methods on the final Enum
class are correct (such as __new__()
, __getnewargs__()
,
__str__()
and __repr__()
).
Flag Classes¶
Flags have an expanded view of aliasing: to be canonical, the value of a flag
needs to be a power-of-two value, and not a duplicate name. So, in addition to the
Enum
definition of alias, a flag with no value (a.k.a. 0
) or with more than one
power-of-two value (e.g. 3
) is considered an alias.
Enum Members (aka instances)¶
The most interesting thing about enum members is that they are singletons.
EnumType
creates them all while it is creating the enum class itself,
and then puts a custom __new__()
in place to ensure that no new ones are
ever instantiated by returning only the existing member instances.
Flag Members¶
Flag members can be iterated over just like the Flag
class, and only the
canonical members will be returned. For example:
>>> list(Color)
[<Color.RED: 1>, <Color.GREEN: 2>, <Color.BLUE: 4>]
(Note that BLACK
, PURPLE
, and WHITE
do not show up.)
Inverting a flag member returns the corresponding positive value, rather than a negative value — for example:
>>> ~Color.RED
<Color.GREEN|BLUE: 6>
Flag members have a length corresponding to the number of power-of-two values they contain. For example:
>>> len(Color.PURPLE)
2
Enum Cookbook¶
While Enum
, IntEnum
, StrEnum
, Flag
, and
IntFlag
are expected to cover the majority of use-cases, they cannot
cover them all. Here are recipes for some different types of enumerations
that can be used directly, or as examples for creating one’s own.
Omitting values¶
In many use-cases, one doesn’t care what the actual value of an enumeration is. There are several ways to define this type of simple enumeration:
use instances of
auto
for the valueuse instances of
object
as the valueuse a descriptive string as the value
use a tuple as the value and a custom
__new__()
to replace the tuple with anint
value
Using any of these methods signifies to the user that these values are not important, and also enables one to add, remove, or reorder members without having to renumber the remaining members.
Using auto
¶
Using auto
would look like:
>>> class Color(Enum):
... RED = auto()
... BLUE = auto()
... GREEN = auto()
...
>>> Color.GREEN
<Color.GREEN: 3>
Using object
¶
Using object
would look like:
>>> class Color(Enum):
... RED = object()
... GREEN = object()
... BLUE = object()
...
>>> Color.GREEN
<Color.GREEN: <object object at 0x...>>
This is also a good example of why you might want to write your own
__repr__()
:
>>> class Color(Enum):
... RED = object()
... GREEN = object()
... BLUE = object()
... def __repr__(self):
... return "<%s.%s>" % (self.__class__.__name__, self._name_)
...
>>> Color.GREEN
<Color.GREEN>
Using a descriptive string¶
Using a string as the value would look like:
>>> class Color(Enum):
... RED = 'stop'
... GREEN = 'go'
... BLUE = 'too fast!'
...
>>> Color.GREEN
<Color.GREEN: 'go'>
Using a custom __new__()
¶
Using an auto-numbering __new__()
would look like:
>>> class AutoNumber(Enum):
... def __new__(cls):
... value = len(cls.__members__) + 1
... obj = object.__new__(cls)
... obj._value_ = value
... return obj
...
>>> class Color(AutoNumber):
... RED = ()
... GREEN = ()
... BLUE = ()
...
>>> Color.GREEN
<Color.GREEN: 2>
To make a more general purpose AutoNumber
, add *args
to the signature:
>>> class AutoNumber(Enum):
... def __new__(cls, *args): # this is the only change from above
... value = len(cls.__members__) + 1
... obj = object.__new__(cls)
... obj._value_ = value
... return obj
...
Then when you inherit from AutoNumber
you can write your own __init__
to handle any extra arguments:
>>> class Swatch(AutoNumber):
... def __init__(self, pantone='unknown'):
... self.pantone = pantone
... AUBURN = '3497'
... SEA_GREEN = '1246'
... BLEACHED_CORAL = () # New color, no Pantone code yet!
...
>>> Swatch.SEA_GREEN
<Swatch.SEA_GREEN: 2>
>>> Swatch.SEA_GREEN.pantone
'1246'
>>> Swatch.BLEACHED_CORAL.pantone
'unknown'
Note
The __new__()
method, if defined, is used during creation of the Enum
members; it is then replaced by Enum’s __new__()
which is used after
class creation for lookup of existing members.
Warning
Do not call super().__new__()
, as the lookup-only __new__
is the one
that is found; instead, use the data type directly – e.g.:
obj = int.__new__(cls, value)
OrderedEnum¶
An ordered enumeration that is not based on IntEnum
and so maintains
the normal Enum
invariants (such as not being comparable to other
enumerations):
>>> class OrderedEnum(Enum):
... def __ge__(self, other):
... if self.__class__ is other.__class__:
... return self.value >= other.value
... return NotImplemented
... def __gt__(self, other):
... if self.__class__ is other.__class__:
... return self.value > other.value
... return NotImplemented
... def __le__(self, other):
... if self.__class__ is other.__class__:
... return self.value <= other.value
... return NotImplemented
... def __lt__(self, other):
... if self.__class__ is other.__class__:
... return self.value < other.value
... return NotImplemented
...
>>> class Grade(OrderedEnum):
... A = 5
... B = 4
... C = 3
... D = 2
... F = 1
...
>>> Grade.C < Grade.A
True
DuplicateFreeEnum¶
Raises an error if a duplicate member value is found instead of creating an alias:
>>> class DuplicateFreeEnum(Enum):
... def __init__(self, *args):
... cls = self.__class__
... if any(self.value == e.value for e in cls):
... a = self.name
... e = cls(self.value).name
... raise ValueError(
... "aliases not allowed in DuplicateFreeEnum: %r --> %r"
... % (a, e))
...
>>> class Color(DuplicateFreeEnum):
... RED = 1
... GREEN = 2
... BLUE = 3
... GRENE = 2
...
Traceback (most recent call last):
...
ValueError: aliases not allowed in DuplicateFreeEnum: 'GRENE' --> 'GREEN'
Note
This is a useful example for subclassing Enum to add or change other
behaviors as well as disallowing aliases. If the only desired change is
disallowing aliases, the unique()
decorator can be used instead.
MultiValueEnum¶
Supports having more than one value per member:
>>> class MultiValueEnum(Enum):
... def __new__(cls, value, *values):
... self = object.__new__(cls)
... self._value_ = value
... for v in values:
... self._add_value_alias_(v)
... return self
...
>>> class DType(MultiValueEnum):
... float32 = 'f', 8
... double64 = 'd', 9
...
>>> DType('f')
<DType.float32: 'f'>
>>> DType(9)
<DType.double64: 'd'>
Planet¶
If __new__()
or __init__()
is defined, the value of the enum member
will be passed to those methods:
>>> class Planet(Enum):
... MERCURY = (3.303e+23, 2.4397e6)
... VENUS = (4.869e+24, 6.0518e6)
... EARTH = (5.976e+24, 6.37814e6)
... MARS = (6.421e+23, 3.3972e6)
... JUPITER = (1.9e+27, 7.1492e7)
... SATURN = (5.688e+26, 6.0268e7)
... URANUS = (8.686e+25, 2.5559e7)
... NEPTUNE = (1.024e+26, 2.4746e7)
... def __init__(self, mass, radius):
... self.mass = mass # in kilograms
... self.radius = radius # in meters
... @property
... def surface_gravity(self):
... # universal gravitational constant (m3 kg-1 s-2)
... G = 6.67300E-11
... return G * self.mass / (self.radius * self.radius)
...
>>> Planet.EARTH.value
(5.976e+24, 6378140.0)
>>> Planet.EARTH.surface_gravity
9.802652743337129
TimePeriod¶
An example to show the _ignore_
attribute in use:
>>> from datetime import timedelta
>>> class Period(timedelta, Enum):
... "different lengths of time"
... _ignore_ = 'Period i'
... Period = vars()
... for i in range(367):
... Period['day_%d' % i] = i
...
>>> list(Period)[:2]
[<Period.day_0: datetime.timedelta(0)>, <Period.day_1: datetime.timedelta(days=1)>]
>>> list(Period)[-2:]
[<Period.day_365: datetime.timedelta(days=365)>, <Period.day_366: datetime.timedelta(days=366)>]
Subclassing EnumType¶
While most enum needs can be met by customizing Enum
subclasses,
either with class decorators or custom functions, EnumType
can be
subclassed to provide a different Enum experience.


Iterator Objects

Iterator Objects¶
Python provides two general-purpose iterator objects. The first, a sequence
iterator, works with an arbitrary sequence supporting the __getitem__()
method. The second works with a callable object and a sentinel value, calling
the callable for each item in the sequence, and ending the iteration when the
sentinel value is returned.
-
PyTypeObject PySeqIter_Type¶
- Part of the Stable ABI.
Type object for iterator objects returned by
PySeqIter_New()
and the one-argument form of theiter()
built-in function for built-in sequence types.
-
int PySeqIter_Check(PyObject *op)¶
Return true if the type of op is
PySeqIter_Type
. This function always succeeds.
-
PyObject *PySeqIter_New(PyObject *seq)¶
- Return value: New reference. Part of the Stable ABI.
Return an iterator that works with a general sequence object, seq. The iteration ends when the sequence raises
IndexError
for the subscripting operation.
-
PyTypeObject PyCallIter_Type¶
- Part of the Stable ABI.
Type object for iterator objects returned by
PyCallIter_New()
and the two-argument form of theiter()
built-in function.
-
int PyCallIter_Check(PyObject *op)¶
Return true if the type of op is
PyCallIter_Type
. This function always succeeds.
-
PyObject *PyCallIter_New(PyObject *callable, PyObject *sentinel)¶
- Return value: New reference. Part of the Stable ABI.
Return a new iterator. The first parameter, callable, can be any Python callable object that can be called with no parameters; each call to it should return the next item in the iteration. When callable returns a value equal to sentinel, the iteration will be terminated.
Range Objects¶
-
PyTypeObject PyRange_Type¶
- Part of the Stable ABI.
The type object for
range
objects.
Builtin Iterator Types¶
These are built-in iteration types that are included in Python’s C API, but provide no additional functions. They are here for completeness.
C type |
Python type |
|---|---|
|
|
|
|
|
|
|
|
|
Other Iterator Objects¶
-
PyTypeObject PyByteArrayIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyBytesIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyListIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyListRevIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PySetIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyTupleIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyRangeIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyLongRangeIter_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyDictIterKey_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyDictRevIterKey_Type¶
- Part of the Stable ABI since version 3.8.
-
PyTypeObject PyDictIterValue_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyDictRevIterValue_Type¶
- Part of the Stable ABI since version 3.8.
-
PyTypeObject PyDictIterItem_Type¶
- Part of the Stable ABI.
-
PyTypeObject PyDictRevIterItem_Type¶
- Part of the Stable ABI since version 3.8.
-
PyTypeObject PyODictIter_Type¶
Type objects for iterators of various built-in objects.
Do not create instances of these directly; prefer calling
PyObject_GetIter()
instead.Note that there is no guarantee that a given built-in type uses a given iterator type. For example, iterating over
range
will use one of two iterator types depending on the size of the range. Other types may start using a similar scheme in the future, without warning.


distutils
— Building and installing Python modules¶
Deprecated since version 3.10, removed in version 3.12.
This module is no longer part of the Python standard library. It was removed in Python 3.12 after being deprecated in Python 3.10. The removal was decided in PEP 632, which has migration advice.
The last version of Python that provided the distutils
module was
Python 3.11.