mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Review sysconfig docs.

Browse source
This commit is contained in:
Georg Brandl 2010-02-06 10:23:16 +00:00
parent 1c7c7304a3
commit b79dc307ad
1 changed files with 80 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

160
Doc/library/sysconfig.rst
View file

@ -10,96 +10,98 @@
single: configuration information single: configuration information
The :mod:`sysconfig` module provides access to Python's configuration The :mod:`sysconfig` module provides access to Python's configuration
information like the list of installation paths and the configuration information like the list of installation paths and the configuration variables
variables relevant for the current platform. relevant for the current platform.
Configuration variables Configuration variables
----------------------- -----------------------
A Python distribution contains a :file:`Makefile` file and a :file:`python.h` A Python distribution contains a :file:`Makefile` file and a :file:`python.h`
that are used to build the Python binary itself, but also any C extension that are necessary to build the Python binary itself, but also any C extension
created in a third party project and compiled using :mod:`distutils`. created in a third party project and compiled using :mod:`distutils`.
:mod:`sysconfig` put all variables found in these files in a dictionnary :mod:`sysconfig` puts all variables found in these files in a dictionary that
that can be accessed using :func:`get_config_vars` or :func:`get_config_var`. can be accessed using :func:`get_config_vars` or :func:`get_config_var`.
Notice that on Windows, it's a much smaller set. Notice that on Windows, it's a much smaller set.
.. function:: get_config_vars(\*args) .. function:: get_config_vars(\*args)
With no arguments, return a dictionary of all configuration With no arguments, return a dictionary of all configuration variables
variables relevant for the current platform. relevant for the current platform.
With arguments, return a list of values that result from looking up With arguments, return a list of values that result from looking up each
each argument in the configuration variable dictionary. argument in the configuration variable dictionary.
For each argument, if the value is not found, return ``None``.
For each argument, if the value is not found, returns None.
.. function:: get_config_var(name) .. function:: get_config_var(name)
Return the value of a single variable *name*. Equivalent to Return the value of a single variable *name*. Equivalent to
get_config_vars().get(name). ``get_config_vars().get(name)``.
If *name* is not found, return None. If *name* is not found, return ``None``.
Example of usage:: Example of usage::
>>> import sysconfig >>> import sysconfig
>>> sysconfig.get_config_var('Py_ENABLE_SHARED') >>> sysconfig.get_config_var('Py_ENABLE_SHARED')
0 0
>>> sysconfig.get_config_var('LIBDIR') >>> sysconfig.get_config_var('LIBDIR')
'/usr/local/lib' '/usr/local/lib'
>>> sysconfig.get_config_vars('AR', 'CXX') >>> sysconfig.get_config_vars('AR', 'CXX')
['ar', 'g++'] ['ar', 'g++']
Installation paths Installation paths
------------------ ------------------
Python uses an installation scheme that differs depending on the platform Python uses an installation scheme that differs depending on the platform and on
and on the installation options. These schemes are stored in :mod:`sysconfig` the installation options. These schemes are stored in :mod:`sysconfig` under
under unique identifiers based on the value returned by :const:`os.name`. unique identifiers based on the value returned by :const:`os.name`.
Every new component that is installed using :mod:`distutils` or a 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 Distutils-based system will follow the same scheme to copy its file in the right
right places. places.
Python currently supports seven schemes: Python currently supports seven schemes:
- *posix_prefix*: scheme for posix platforms like Linux or Mac OS X. This is the - *posix_prefix*: scheme for Posix platforms like Linux or Mac OS X. This is
default scheme used when Python or a component is installed. the default scheme used when Python or a component is installed.
- *posix_home*: scheme for posix platform used when a *home* option is used - *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 upon installation. This scheme is used when a component is installed through
Distutils with a specific home prefix. Distutils with a specific home prefix.
- *posix_user*: scheme for posix platform used when a component is installed - *posix_user*: scheme for Posix platforms used when a component is installed
through Distutils and the *user* option is used. This scheme defines paths through Distutils and the *user* option is used. This scheme defines paths
located under the user home directory. located under the user home directory.
- *nt*: scheme for nt platforms like Windows. - *nt*: scheme for NT platforms like Windows.
- *nt_user*: scheme for nt platforms, when the *user* option is used. - *nt_user*: scheme for NT platforms, when the *user* option is used.
- *os2*: scheme for OS2 platforms. - *os2*: scheme for OS/2 platforms.
- *os2_home*: scheme for OS2 patforms, when the *user* option is used. - *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 Each scheme is itself composed of a series of paths and each path has a unique
identifier. Python currently uses eight paths: identifier. Python currently uses eight paths:
- *stdlib*: directory containing the standard Python library files that are - *stdlib*: directory containing the standard Python library files that are not
not platform-specific. platform-specific.
- *platstdlib*: directory containing the standard Python library files that - *platstdlib*: directory containing the standard Python library files that are
are platform-specific files. platform-specific.
- *platlib*: directory for the site-specific, platform-specific files. - *platlib*: directory for site-specific, platform-specific files.
- *purelib*: directory for the site-specific, non platform-specific files. - *purelib*: directory for site-specific, non-platform-specific files.
- *include*: directory containing the non-platform-specific header files. - *include*: directory for non-platform-specific header files.
- *platinclude*: directory containing the platform-specific header files. - *platinclude*: directory for platform-specific header files.
- *scripts*: directory containing the script files. - *scripts*: directory for script files.
- *data*: directory containing the data files. - *data*: directory for data files.
:mod:`sysconfig` provides some functions to read these paths. :mod:`sysconfig` provides some functions to determine these paths.
.. function:: get_scheme_names() .. function:: get_scheme_names()
Return a tuple containing all schemes currently supported in Return a tuple containing all schemes currently supported in
:mod:`sysconfig`. :mod:`sysconfig`.
.. function:: get_path_names() .. function:: get_path_names()
Return a tuple containing all path names currently supported in Return a tuple containing all path names currently supported in
@ -113,37 +115,37 @@ identifier. Python currently uses eight paths:
*name* has to be a value from the list returned by :func:`get_path_names`. *name* has to be a value from the list returned by :func:`get_path_names`.
:mod:`sysconfig` stores installation paths corresponding to the each :mod:`sysconfig` stores installation paths corresponding to each path name,
path name, for each platform, with variables to be expanded. For instance for each platform, with variables to be expanded. For instance the *stdlib*
the `stdlib` path for the `nt` scheme is: `{base}/Lib`. path for the *nt* scheme is: ``{base}/Lib``.
:func:`get_path` will use the variables returned by :func:`get_config_vars` :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 to expand the path. All variables have default values for each platform so
so one may call this function and get the default value. one may call this function and get the default value.
If *scheme* is provided, it must be a value from the list returned by 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 :func:`get_path_names`. Otherwise, the default scheme for the current
platform is used. platform is used.
If *vars* is provided, it must be a dictionnary of variables that will If *vars* is provided, it must be a dictionary of variables that will update
update the dictionnary return by :func:`get_config_vars`. the dictionary return by :func:`get_config_vars`.
If *expand* is set to False, the path will not be expanded using If *expand* is set to ``False``, the path will not be expanded using the
the variables. variables.
If *name* is not found, return None. If *name* is not found, return ``None``.
.. function:: get_paths([scheme, [vars, [expand]]]) .. function:: get_paths([scheme, [vars, [expand]]])
Return a dictionnary containing all installation paths corresponding to an Return a dictionary containing all installation paths corresponding to an
installation scheme. See :func:`get_path` for more information. installation scheme. See :func:`get_path` for more information.
If *scheme* is not provided, will use the default scheme for the current If *scheme* is not provided, will use the default scheme for the current
platform. platform.
If *vars* is provided, it must be a dictionnary of variables that will If *vars* is provided, it must be a dictionary of variables that will
update the dictionnary used to expand the paths. update the dictionary used to expand the paths.
If *expand* is set to False, the paths will not be expanded. If *expand* is set to False, the paths will not be expanded.
@ -156,20 +158,20 @@ Other functions
.. function:: get_python_version() .. function:: get_python_version()
Return the MAJOR.MINOR Python version number as a string. Similar to Return the ``MAJOR.MINOR`` Python version number as a string. Similar to
``sys.version[:3]``. ``sys.version[:3]``.
.. function:: get_platform() .. function:: get_platform()
Return a string that identifies the current platform. Return a string that identifies the current platform.
This is used mainly to distinguish platform-specific build directories and This is used mainly to distinguish platform-specific build directories and
platform-specific built distributions. Typically includes the OS name platform-specific built distributions. Typically includes the OS name and
and version and the architecture (as supplied by 'os.uname()'), version and the architecture (as supplied by :func:`os.uname`), although the
although the exact information included depends on the OS; eg. for IRIX exact information included depends on the OS; e.g. for IRIX the architecture
the architecture isn't particularly important (IRIX only runs on SGI isn't particularly important (IRIX only runs on SGI hardware), but for Linux
hardware), but for Linux the kernel version isn't particularly the kernel version isn't particularly important.
important.
Examples of returned values: Examples of returned values:
@ -185,34 +187,32 @@ Other functions
- win-ia64 (64bit Windows on Itanium) - win-ia64 (64bit Windows on Itanium)
- win32 (all others - specifically, sys.platform is returned) - win32 (all others - specifically, sys.platform is returned)
Mac OS X can return : Mac OS X can return:
- macosx-10.6-ppc - macosx-10.6-ppc
- macosx-10.4-ppc64 - macosx-10.4-ppc64
- macosx-10.3-i386 - macosx-10.3-i386
- macosx-10.4-fat - macosx-10.4-fat
For other non-POSIX platforms, currently just returns 'sys.platform'. For other non-POSIX platforms, currently just returns :data:`sys.platform`.
.. function:: is_python_build(): .. function:: is_python_build()
Returns True if the current Python installation was built from source. Return ``True`` if the current Python installation was built from source.
.. function:: parse_config_h(fp[, vars]): .. function:: parse_config_h(fp[, vars])
Parse a config.h-style file. Parse a :file:`config.h`\-style file.
*fp* is a file-like object pointing to the config.h-like 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 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 dictionary is passed in as the second argument, it is used instead of a new
new dictionary, and updated with the values read in the file. dictionary, and updated with the values read in the file.
.. function:: get_config_h_filename(): .. function:: get_config_h_filename()
Returns the path of pyconfig.h
Return the path of :file:`pyconfig.h`.