Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 1 | :mod:`sysconfig` --- Provide access to Python's configuration information |
| 2 | ========================================================================= |
| 3 | |
| 4 | .. module:: sysconfig |
| 5 | :synopsis: Python's configuration information |
| 6 | .. moduleauthor:: Tarek Ziade <tarek@ziade.org> |
| 7 | .. sectionauthor:: Tarek Ziade <tarek@ziade.org> |
Ezio Melotti | f8754a6 | 2010-03-21 07:16:43 +0000 | [diff] [blame^] | 8 | .. versionadded:: 3.2 |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 9 | .. index:: |
| 10 | single: configuration information |
| 11 | |
| 12 | The :mod:`sysconfig` module provides access to Python's configuration |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 13 | information like the list of installation paths and the configuration variables |
| 14 | relevant for the current platform. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 15 | |
| 16 | Configuration variables |
| 17 | ----------------------- |
| 18 | |
| 19 | A Python distribution contains a :file:`Makefile` file and a :file:`python.h` |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 20 | that are necessary to build the Python binary itself, but also any C extension |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 21 | created in a third party project and compiled using :mod:`distutils`. |
| 22 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 23 | :mod:`sysconfig` puts all variables found in these files in a dictionary that |
| 24 | can be accessed using :func:`get_config_vars` or :func:`get_config_var`. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 25 | |
| 26 | Notice that on Windows, it's a much smaller set. |
| 27 | |
| 28 | .. function:: get_config_vars(\*args) |
| 29 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 30 | With no arguments, return a dictionary of all configuration variables |
| 31 | relevant for the current platform. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 32 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 33 | With arguments, return a list of values that result from looking up each |
| 34 | argument in the configuration variable dictionary. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 35 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 36 | For each argument, if the value is not found, return ``None``. |
| 37 | |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 38 | |
| 39 | .. function:: get_config_var(name) |
| 40 | |
| 41 | Return the value of a single variable *name*. Equivalent to |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 42 | ``get_config_vars().get(name)``. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 43 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 44 | If *name* is not found, return ``None``. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 45 | |
| 46 | Example of usage:: |
| 47 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 48 | >>> import sysconfig |
| 49 | >>> sysconfig.get_config_var('Py_ENABLE_SHARED') |
| 50 | 0 |
| 51 | >>> sysconfig.get_config_var('LIBDIR') |
| 52 | '/usr/local/lib' |
| 53 | >>> sysconfig.get_config_vars('AR', 'CXX') |
| 54 | ['ar', 'g++'] |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 55 | |
| 56 | |
| 57 | Installation paths |
| 58 | ------------------ |
| 59 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 60 | Python uses an installation scheme that differs depending on the platform and on |
| 61 | the installation options. These schemes are stored in :mod:`sysconfig` under |
| 62 | unique identifiers based on the value returned by :const:`os.name`. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 63 | |
| 64 | Every new component that is installed using :mod:`distutils` or a |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 65 | Distutils-based system will follow the same scheme to copy its file in the right |
| 66 | places. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 67 | |
| 68 | Python currently supports seven schemes: |
| 69 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 70 | - *posix_prefix*: scheme for Posix platforms like Linux or Mac OS X. This is |
| 71 | the default scheme used when Python or a component is installed. |
| 72 | - *posix_home*: scheme for Posix platforms used when a *home* option is used |
| 73 | upon installation. This scheme is used when a component is installed through |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 74 | Distutils with a specific home prefix. |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 75 | - *posix_user*: scheme for Posix platforms used when a component is installed |
| 76 | through Distutils and the *user* option is used. This scheme defines paths |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 77 | located under the user home directory. |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 78 | - *nt*: scheme for NT platforms like Windows. |
| 79 | - *nt_user*: scheme for NT platforms, when the *user* option is used. |
| 80 | - *os2*: scheme for OS/2 platforms. |
| 81 | - *os2_home*: scheme for OS/2 patforms, when the *user* option is used. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 82 | |
| 83 | Each scheme is itself composed of a series of paths and each path has a unique |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 84 | identifier. Python currently uses eight paths: |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 85 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 86 | - *stdlib*: directory containing the standard Python library files that are not |
| 87 | platform-specific. |
| 88 | - *platstdlib*: directory containing the standard Python library files that are |
| 89 | platform-specific. |
| 90 | - *platlib*: directory for site-specific, platform-specific files. |
| 91 | - *purelib*: directory for site-specific, non-platform-specific files. |
| 92 | - *include*: directory for non-platform-specific header files. |
| 93 | - *platinclude*: directory for platform-specific header files. |
| 94 | - *scripts*: directory for script files. |
| 95 | - *data*: directory for data files. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 96 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 97 | :mod:`sysconfig` provides some functions to determine these paths. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 98 | |
| 99 | .. function:: get_scheme_names() |
| 100 | |
| 101 | Return a tuple containing all schemes currently supported in |
| 102 | :mod:`sysconfig`. |
| 103 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 104 | |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 105 | .. function:: get_path_names() |
| 106 | |
| 107 | Return a tuple containing all path names currently supported in |
| 108 | :mod:`sysconfig`. |
| 109 | |
| 110 | |
| 111 | .. function:: get_path(name, [scheme, [vars, [expand]]]) |
| 112 | |
| 113 | Return an installation path corresponding to the path *name*, from the |
| 114 | install scheme named *scheme*. |
| 115 | |
| 116 | *name* has to be a value from the list returned by :func:`get_path_names`. |
| 117 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 118 | :mod:`sysconfig` stores installation paths corresponding to each path name, |
| 119 | for each platform, with variables to be expanded. For instance the *stdlib* |
| 120 | path for the *nt* scheme is: ``{base}/Lib``. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 121 | |
| 122 | :func:`get_path` will use the variables returned by :func:`get_config_vars` |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 123 | to expand the path. All variables have default values for each platform so |
| 124 | one may call this function and get the default value. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 125 | |
| 126 | If *scheme* is provided, it must be a value from the list returned by |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 127 | :func:`get_path_names`. Otherwise, the default scheme for the current |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 128 | platform is used. |
| 129 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 130 | If *vars* is provided, it must be a dictionary of variables that will update |
| 131 | the dictionary return by :func:`get_config_vars`. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 132 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 133 | If *expand* is set to ``False``, the path will not be expanded using the |
| 134 | variables. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 135 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 136 | If *name* is not found, return ``None``. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 137 | |
| 138 | |
| 139 | .. function:: get_paths([scheme, [vars, [expand]]]) |
| 140 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 141 | Return a dictionary containing all installation paths corresponding to an |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 142 | installation scheme. See :func:`get_path` for more information. |
| 143 | |
| 144 | If *scheme* is not provided, will use the default scheme for the current |
| 145 | platform. |
| 146 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 147 | If *vars* is provided, it must be a dictionary of variables that will |
| 148 | update the dictionary used to expand the paths. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 149 | |
| 150 | If *expand* is set to False, the paths will not be expanded. |
| 151 | |
| 152 | If *scheme* is not an existing scheme, :func:`get_paths` will raise a |
| 153 | :exc:`KeyError`. |
| 154 | |
| 155 | |
| 156 | Other functions |
| 157 | --------------- |
| 158 | |
| 159 | .. function:: get_python_version() |
| 160 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 161 | Return the ``MAJOR.MINOR`` Python version number as a string. Similar to |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 162 | ``sys.version[:3]``. |
| 163 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 164 | |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 165 | .. function:: get_platform() |
| 166 | |
| 167 | Return a string that identifies the current platform. |
| 168 | |
| 169 | This is used mainly to distinguish platform-specific build directories and |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 170 | platform-specific built distributions. Typically includes the OS name and |
| 171 | version and the architecture (as supplied by :func:`os.uname`), although the |
| 172 | exact information included depends on the OS; e.g. for IRIX the architecture |
| 173 | isn't particularly important (IRIX only runs on SGI hardware), but for Linux |
| 174 | the kernel version isn't particularly important. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 175 | |
| 176 | Examples of returned values: |
| 177 | |
| 178 | - linux-i586 |
| 179 | - linux-alpha (?) |
| 180 | - solaris-2.6-sun4u |
| 181 | - irix-5.3 |
| 182 | - irix64-6.2 |
| 183 | |
| 184 | Windows will return one of: |
| 185 | |
| 186 | - win-amd64 (64bit Windows on AMD64 (aka x86_64, Intel64, EM64T, etc) |
| 187 | - win-ia64 (64bit Windows on Itanium) |
| 188 | - win32 (all others - specifically, sys.platform is returned) |
| 189 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 190 | Mac OS X can return: |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 191 | |
| 192 | - macosx-10.6-ppc |
| 193 | - macosx-10.4-ppc64 |
| 194 | - macosx-10.3-i386 |
| 195 | - macosx-10.4-fat |
| 196 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 197 | For other non-POSIX platforms, currently just returns :data:`sys.platform`. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 198 | |
| 199 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 200 | .. function:: is_python_build() |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 201 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 202 | Return ``True`` if the current Python installation was built from source. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 203 | |
| 204 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 205 | .. function:: parse_config_h(fp[, vars]) |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 206 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 207 | Parse a :file:`config.h`\-style file. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 208 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 209 | *fp* is a file-like object pointing to the :file:`config.h`\-like file. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 210 | |
| 211 | A dictionary containing name/value pairs is returned. If an optional |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 212 | dictionary is passed in as the second argument, it is used instead of a new |
| 213 | dictionary, and updated with the values read in the file. |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 214 | |
| 215 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 216 | .. function:: get_config_h_filename() |
Tarek Ziadé | 1875570 | 2010-02-02 23:17:47 +0000 | [diff] [blame] | 217 | |
Tarek Ziadé | 667882f | 2010-02-11 20:47:18 +0000 | [diff] [blame] | 218 | Return the path of :file:`pyconfig.h`. |