cpython/Doc/library/sysconfig.rst

255 lines
8.4 KiB
ReStructuredText
Raw Normal View History

:mod:`sysconfig` --- Provide access to Python's configuration information
=========================================================================
.. module:: sysconfig
:synopsis: Python's configuration information
.. moduleauthor:: Tarek Ziade <tarek@ziade.org>
.. sectionauthor:: Tarek Ziade <tarek@ziade.org>
2010-03-21 04:16:43 -03:00
.. versionadded:: 3.2
.. index::
single: configuration information
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 :mod:`distutils`.
: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
------------------
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 seven schemes:
- *posix_prefix*: scheme for Posix platforms like Linux or Mac OS X. 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.
- *nt*: scheme for NT platforms like Windows.
- *nt_user*: scheme for NT platforms, when the *user* option is used.
- *os2*: scheme for OS/2 platforms.
- *os2_home*: scheme for OS/2 patforms, 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.
- *platinclude*: directory for platform-specific header files.
- *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_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
:func:`get_path_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, return ``None``.
.. 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
``sys.version[:3]``.
.. 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 :func:`os.uname`), although the
exact information included depends on the OS; e.g. for IRIX the architecture
isn't particularly important (IRIX only runs on SGI hardware), but for Linux
the kernel version isn't particularly important.
Examples of returned values:
- linux-i586
- linux-alpha (?)
- solaris-2.6-sun4u
- irix-5.3
- irix64-6.2
Windows will return one of:
- win-amd64 (64bit Windows on AMD64 (aka x86_64, Intel64, EM64T, etc)
- win-ia64 (64bit Windows on Itanium)
- win32 (all others - specifically, sys.platform is returned)
Mac OS X 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 current Python installation was built from source.
.. 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::
$ 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"
ASDLGEN = "./Parser/asdl_c.py"
...
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`.