cpython/Doc/library/sysconfig.rst

314 lines
10 KiB
ReStructuredText
Raw Normal View History

:mod:`sysconfig` --- Provide access to Python's configuration information
=========================================================================
.. module:: sysconfig
:synopsis: Python's configuration information
.. moduleauthor:: Tarek Ziadé <tarek@ziade.org>
.. sectionauthor:: Tarek Ziadé <tarek@ziade.org>
2011-01-26 21:20:32 -04:00
.. versionadded:: 3.2
**Source code:** :source:`Lib/sysconfig.py`
.. index::
single: configuration information
2011-01-26 21:20:32 -04:00
--------------
The :mod:`sysconfig` module provides access to Python's configuration
information like the list of installation paths and the configuration variables
relevant for the current platform.
Configuration variables
-----------------------
Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line Add various items ........ r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines Fix doubled 'the'. Markup fixes to use :exc:, :option: in a few places. (Glitch: unittest.main's -c ends up a link to the Python interpreter's -c option. Should we skip using :option: for that switch, or disable the auto-linking somehow?) ........ r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line Add various unittest items ........ r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line update pypy description ........ r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line update pypy url ........ r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line Always add space after RFC; reword paragraph ........ r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines Reword paragraph to make its meaning clearer. Antoine Pitrou: is my version of the paragraph still correct? R. David Murray: is this more understandable than the previous version? ........ r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line Fix typos ........ r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line Markup fix; clarify by adding 'in that order' ........ r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line Add various items; rearrange unittest section a bit ........ r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line Minor grammar re-wording ........ r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line Add item ........ r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line Add various items ........ r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line Minor grammar fix ........ r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line Describe memoryview ........ r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines Fix attribution. Travis didn't do much and he did a bad work. (yes, this is a sensitive subject, sorry) ........ r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line Add some more items; the urlparse change is added twice ........ r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line Reword paragraph; fix filename, which should be pyconfig.h ........ r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line Add various items ........ r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items ........ r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line Add 2 items; record ideas for two initial sections; clarify wording ........ r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line Change section title; point to unittest2 ........ r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line Add a new section on the development plan; add an item ........ r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines Fix some markup and a class name. Also, wrap a long line. ........ r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line Re-word text ........ r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line Add two items ........ r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line Get accents correct ........ r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line Add logging.dictConfig example; give up on writing a Ttk example ........ r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line Markup fixes ........ r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines Write summary of the 2.7 release; rewrite the future section some more; mention PYTHONWARNINGS env. var; tweak some examples for readability. And with this commit, the "What's New" is done... except for a complete read-through to polish the text, and fixing any reported errors, but those tasks can easily wait until after beta2. ........ r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line finish clause ........ r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line Markup fix; re-word a sentence ........ r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line Use title case ........ r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line Link to unittest2 article ........ r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines Add a link on maketrans(). ........ r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line Fix typo ........ r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line Revision pass: lots of edits, typo fixes, rearrangements ........ r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line Let's call this done ........ r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line Grammar fix ........ r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line #8696: add documentation for logging.config.dictConfig (PEP 391) ........ r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line Add cross-reference to later section ........ r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line Fixed minor typo in ReST markup. ........ r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line Updated logging documentation with more dictConfig information. ........ r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line #8785: less confusing description of regex.find*. ........ r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line Add three items ........ r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line Rewrite wxWidgets section ........ r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line Remove top-level 'General Questions' section, pushing up the questions it contains ........ r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line Add item ........ r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line #8616: add new turtle demo "nim". ........ r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order. ........ r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files. ........ r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines Issue8810: Clearing up docstring for tzinfo.utcoffset. ........ r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered. ........ r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line #8875: Remove duplicated paragraph ........ r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line Add a few more items ........ r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line Fix punctuation. ........ r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line Document that an existing directory raises in mkdir(). ........ r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line Update version in README. ........ r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line Use newer toctree syntax. ........ r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line Add document on how to build. ........ r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line Fix gratuitous indentation. ........ r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line Update README. ........ r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line Grammar fix ........ r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line #8993: fix reference. ........ r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line Add another bunch of items ........ r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up ........ r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line remove reverted changed ........ r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line Confusing punctuation. ........ r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line Use designated syntax for optional grammar element. ........ r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line Fix URL. ........ r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line Two typos. ........
2010-06-27 19:32:30 -03:00
A Python distribution contains a :file:`Makefile` and a :file:`pyconfig.h`
header file that are necessary to build both the Python binary itself and
third-party C extensions compiled using ``setuptools``.
:mod:`sysconfig` puts all variables found in these files in a dictionary that
can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
Notice that on Windows, it's a much smaller set.
.. function:: get_config_vars(*args)
With no arguments, return a dictionary of all configuration variables
relevant for the current platform.
With arguments, return a list of values that result from looking up each
argument in the configuration variable dictionary.
For each argument, if the value is not found, return ``None``.
.. function:: get_config_var(name)
Return the value of a single variable *name*. Equivalent to
``get_config_vars().get(name)``.
If *name* is not found, return ``None``.
Example of usage::
>>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0
>>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++']
.. _installation_paths:
Installation paths
------------------
Python uses an installation scheme that differs depending on the platform and on
the installation options. These schemes are stored in :mod:`sysconfig` under
unique identifiers based on the value returned by :const:`os.name`.
Every new component that is installed using :mod:`distutils` or a
Distutils-based system will follow the same scheme to copy its file in the right
places.
Python currently supports nine schemes:
- *posix_prefix*: scheme for POSIX platforms like Linux or macOS. This is
the default scheme used when Python or a component is installed.
- *posix_home*: scheme for POSIX platforms used when a *home* option is used
upon installation. This scheme is used when a component is installed through
Distutils with a specific home prefix.
- *posix_user*: scheme for POSIX platforms used when a component is installed
through Distutils and the *user* option is used. This scheme defines paths
located under the user home directory.
- *posix_venv*: scheme for :mod:`Python virtual environments <venv>` on POSIX
platforms; by default it is the same as *posix_prefix* .
- *nt*: scheme for NT platforms like Windows.
- *nt_user*: scheme for NT platforms, when the *user* option is used.
- *nt_venv*: scheme for :mod:`Python virtual environments <venv>` on NT
platforms; by default it is the same as *nt* .
- *venv*: a scheme with values from ether *posix_venv* or *nt_venv* depending
on the platform Python runs on
- *osx_framework_user*: scheme for macOS, when the *user* option is used.
Each scheme is itself composed of a series of paths and each path has a unique
identifier. Python currently uses eight paths:
- *stdlib*: directory containing the standard Python library files that are not
platform-specific.
- *platstdlib*: directory containing the standard Python library files that are
platform-specific.
- *platlib*: directory for site-specific, platform-specific files.
- *purelib*: directory for site-specific, non-platform-specific files.
- *include*: directory for non-platform-specific header files for
the Python C-API.
- *platinclude*: directory for platform-specific header files for
the Python C-API.
- *scripts*: directory for script files.
- *data*: directory for data files.
:mod:`sysconfig` provides some functions to determine these paths.
.. function:: get_scheme_names()
Return a tuple containing all schemes currently supported in
:mod:`sysconfig`.
.. function:: get_default_scheme()
Return the default scheme name for the current platform.
.. versionadded:: 3.10
This function was previously named ``_get_default_scheme()`` and
considered an implementation detail.
.. versionchanged:: 3.11
When Python runs from a virtual environment,
the *venv* scheme is returned.
.. function:: get_preferred_scheme(key)
Return a preferred scheme name for an installation layout specified by *key*.
*key* must be either ``"prefix"``, ``"home"``, or ``"user"``.
The return value is a scheme name listed in :func:`get_scheme_names`. It
can be passed to :mod:`sysconfig` functions that take a *scheme* argument,
such as :func:`get_paths`.
.. versionadded:: 3.10
.. versionchanged:: 3.11
When Python runs from a virtual environment and ``key="prefix"``,
the *venv* scheme is returned.
.. function:: _get_preferred_schemes()
Return a dict containing preferred scheme names on the current platform.
Python implementers and redistributors may add their preferred schemes to
the ``_INSTALL_SCHEMES`` module-level global value, and modify this function
to return those scheme names, to e.g. provide different schemes for system
and language package managers to use, so packages installed by either do not
mix with those by the other.
End users should not use this function, but :func:`get_default_scheme` and
:func:`get_preferred_scheme()` instead.
.. versionadded:: 3.10
.. function:: get_path_names()
Return a tuple containing all path names currently supported in
:mod:`sysconfig`.
.. function:: get_path(name, [scheme, [vars, [expand]]])
Return an installation path corresponding to the path *name*, from the
install scheme named *scheme*.
*name* has to be a value from the list returned by :func:`get_path_names`.
:mod:`sysconfig` stores installation paths corresponding to each path name,
for each platform, with variables to be expanded. For instance the *stdlib*
path for the *nt* scheme is: ``{base}/Lib``.
:func:`get_path` will use the variables returned by :func:`get_config_vars`
to expand the path. All variables have default values for each platform so
one may call this function and get the default value.
If *scheme* is provided, it must be a value from the list returned by
2011-11-29 11:34:58 -04:00
:func:`get_scheme_names`. Otherwise, the default scheme for the current
platform is used.
If *vars* is provided, it must be a dictionary of variables that will update
the dictionary return by :func:`get_config_vars`.
If *expand* is set to ``False``, the path will not be expanded using the
variables.
If *name* is not found, raise a :exc:`KeyError`.
.. function:: get_paths([scheme, [vars, [expand]]])
Return a dictionary containing all installation paths corresponding to an
installation scheme. See :func:`get_path` for more information.
If *scheme* is not provided, will use the default scheme for the current
platform.
If *vars* is provided, it must be a dictionary of variables that will
update the dictionary used to expand the paths.
If *expand* is set to false, the paths will not be expanded.
If *scheme* is not an existing scheme, :func:`get_paths` will raise a
:exc:`KeyError`.
Other functions
---------------
.. function:: get_python_version()
Return the ``MAJOR.MINOR`` Python version number as a string. Similar to
``'%d.%d' % sys.version_info[:2]``.
.. function:: get_platform()
Return a string that identifies the current platform.
This is used mainly to distinguish platform-specific build directories and
platform-specific built distributions. Typically includes the OS name and
version and the architecture (as supplied by 'os.uname()'), although the
exact information included depends on the OS; e.g., on Linux, the kernel
version isn't particularly important.
Examples of returned values:
- linux-i586
- linux-alpha (?)
- solaris-2.6-sun4u
Windows will return one of:
- win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T)
- win32 (all others - specifically, sys.platform is returned)
macOS can return:
- macosx-10.6-ppc
- macosx-10.4-ppc64
- macosx-10.3-i386
- macosx-10.4-fat
For other non-POSIX platforms, currently just returns :data:`sys.platform`.
.. function:: is_python_build()
Return ``True`` if the running Python interpreter was built from source and
is being run from its built location, and not from a location resulting from
e.g. running ``make install`` or installing via a binary installer.
.. function:: parse_config_h(fp[, vars])
Parse a :file:`config.h`\-style file.
*fp* is a file-like object pointing to the :file:`config.h`\-like file.
A dictionary containing name/value pairs is returned. If an optional
dictionary is passed in as the second argument, it is used instead of a new
dictionary, and updated with the values read in the file.
.. function:: get_config_h_filename()
Return the path of :file:`pyconfig.h`.
.. function:: get_makefile_filename()
Return the path of :file:`Makefile`.
Using :mod:`sysconfig` as a script
----------------------------------
You can use :mod:`sysconfig` as a script with Python's *-m* option:
.. code-block:: shell-session
$ python -m sysconfig
Platform: "macosx-10.4-i386"
Python version: "3.2"
Current installation scheme: "posix_prefix"
Paths:
data = "/usr/local"
include = "/Users/tarek/Dev/svn.python.org/py3k/Include"
platinclude = "."
platlib = "/usr/local/lib/python3.2/site-packages"
platstdlib = "/usr/local/lib/python3.2"
purelib = "/usr/local/lib/python3.2/site-packages"
scripts = "/usr/local/bin"
stdlib = "/usr/local/lib/python3.2"
Variables:
AC_APPLE_UNIVERSAL_BUILD = "0"
AIX_GENUINE_CPLUSPLUS = "0"
AR = "ar"
ARFLAGS = "rc"
...
This call will print in the standard output the information returned by
:func:`get_platform`, :func:`get_python_version`, :func:`get_path` and
:func:`get_config_vars`.