Kaydet (Commit) 7dc76fde authored tarafından Éric Araujo's avatar Éric Araujo

Merge doc changes from 3.2 (#8617, #10745).

In the install and library docs, I changed the text to refer to
packaging instead of distutils.  I also checked that the documented
paths correctly reflect what’s really defined in sysconfig; the main
difference with paths defined in distutils.install is that include
directories don’t end with the distribution name anymore (i.e. distutils
uses include/python3.3/spam, sysconfig include/python3.3), I have no
idea why.
...@@ -279,6 +279,14 @@ statements shown below, and get the output as shown, to find out my ...@@ -279,6 +279,14 @@ statements shown below, and get the output as shown, to find out my
>>> sys.exec_prefix >>> sys.exec_prefix
'/usr' '/usr'
A few other placeholders are used in this document: :file:`{X.Y}` stands for the
version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by
the value of :data:`sys.abiflags` or the empty string for platforms which don't
define ABI flags; :file:`{distname}` will be replaced by the name of the module
distribution being installed. Dots and capitalization are important in the
paths; for example, a value that uses ``python3.2`` on UNIX will typically use
``Python32`` on Windows.
If you don't want to install modules to the standard location, or if you don't If you don't want to install modules to the standard location, or if you don't
have permission to write there, then you need to read about alternate have permission to write there, then you need to read about alternate
installations in section :ref:`inst-alt-install`. If you want to customize your installations in section :ref:`inst-alt-install`. If you want to customize your
...@@ -307,8 +315,61 @@ scheme*) under this base directory in which to install files. The details ...@@ -307,8 +315,61 @@ scheme*) under this base directory in which to install files. The details
differ across platforms, so read whichever of the following sections applies to differ across platforms, so read whichever of the following sections applies to
you. you.
Note that the various alternate installation schemes are mutually exclusive: you
can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
``--install-base`` and ``--install-platbase``, but you can't mix from these
groups.
.. _inst-alt-install-user:
Alternate installation: the user scheme
---------------------------------------
This scheme is designed to be the most convenient solution for users that don't
have write permission to the global site-packages directory or don't want to
install into it. It is enabled with a simple option::
python setup.py install --user
Files will be installed into subdirectories of :data:`site.USER_BASE` (written
as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
extension modules in the same location (also known as :data:`site.USER_SITE`).
Here are the values for UNIX, including Mac OS X:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}/lib/python{X.Y}/site-packages`
scripts :file:`{userbase}/bin`
data :file:`{userbase}`
C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}`
=============== ===========================================================
And here are the values used on Windows:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}\\Python{XY}\\site-packages`
scripts :file:`{userbase}\\Scripts`
data :file:`{userbase}`
C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}`
=============== ===========================================================
The advantage of using this scheme compared to the other ones described below is
that the user site-packages directory is under normal conditions always included
in :data:`sys.path` (see :mod:`site` for more information), which means that
there is no additional step to perform after running the :file:`setup.py` script
to finalize the installation.
The :command:`build_ext` command also has a ``--user`` option to add
:file:`{userbase}/include` to the compiler search path for header files and
:file:`{userbase}/lib` to the compiler search path for libraries as well as to
the runtime search path for shared C libraries (rpath).
.. _inst-alt-install-prefix:
.. _inst-alt-install-home:
Alternate installation: the home scheme Alternate installation: the home scheme
--------------------------------------- ---------------------------------------
...@@ -330,23 +391,27 @@ will expand this to your home directory:: ...@@ -330,23 +391,27 @@ will expand this to your home directory::
python setup.py install --home=~ python setup.py install --home=~
To make Python find the distributions installed with this scheme, you may have
to :ref:`modify Python's search path <inst-search-path>` or edit
:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
:data:`sys.path`.
The :option:`--home` option defines the installation base directory. Files are The :option:`--home` option defines the installation base directory. Files are
installed to the following directories under the installation base as follows: installed to the following directories under the installation base as follows:
+------------------------------+---------------------------+-----------------------------+ =============== ===========================================================
| Type of file | Installation Directory | Override option | Type of file Installation directory
+==============================+===========================+=============================+ =============== ===========================================================
| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | modules :file:`{home}/lib/python`
+------------------------------+---------------------------+-----------------------------+ scripts :file:`{home}/bin`
| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | data :file:`{home}`
+------------------------------+---------------------------+-----------------------------+ C headers :file:`{home}/include/python/{distname}`
| scripts | :file:`{home}/bin` | :option:`--install-scripts` | =============== ===========================================================
+------------------------------+---------------------------+-----------------------------+
| data | :file:`{home}/share` | :option:`--install-data` |
+------------------------------+---------------------------+-----------------------------+
(Mentally replace slashes with backslashes if you're on Windows.)
.. _inst-alt-install-home:
.. _inst-alt-install-prefix-unix:
Alternate installation: Unix (the prefix scheme) Alternate installation: Unix (the prefix scheme)
------------------------------------------------ ------------------------------------------------
...@@ -355,7 +420,7 @@ The "prefix scheme" is useful when you wish to use one Python installation to ...@@ -355,7 +420,7 @@ The "prefix scheme" is useful when you wish to use one Python installation to
perform the build/install (i.e., to run the setup script), but install modules perform the build/install (i.e., to run the setup script), but install modules
into the third-party module directory of a different Python installation (or into the third-party module directory of a different Python installation (or
something that looks like a different Python installation). If this sounds a something that looks like a different Python installation). If this sounds a
trifle unusual, it is---that's why the "home scheme" comes first. However, trifle unusual, it is---that's why the user and home schemes come before. However,
there are at least two known cases where the prefix scheme will be useful. there are at least two known cases where the prefix scheme will be useful.
First, consider that many Linux distributions put Python in :file:`/usr`, rather First, consider that many Linux distributions put Python in :file:`/usr`, rather
...@@ -383,17 +448,15 @@ non-pure module distributions, but could be expanded to C libraries, binary ...@@ -383,17 +448,15 @@ non-pure module distributions, but could be expanded to C libraries, binary
executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to
:option:`--prefix`. Files are installed as follows: :option:`--prefix`. Files are installed as follows:
+------------------------------+-----------------------------------------------------+-----------------------------+ ================= ==========================================================
| Type of file | Installation Directory | Override option | Type of file Installation directory
+==============================+=====================================================+=============================+ ================= ==========================================================
| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
+------------------------------+-----------------------------------------------------+-----------------------------+ extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | scripts :file:`{prefix}/bin`
+------------------------------+-----------------------------------------------------+-----------------------------+ data :file:`{prefix}`
| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}`
+------------------------------+-----------------------------------------------------+-----------------------------+ ================= ==========================================================
| data | :file:`{prefix}/share` | :option:`--install-data` |
+------------------------------+-----------------------------------------------------+-----------------------------+
There is no requirement that :option:`--prefix` or :option:`--exec-prefix` There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
actually point to an alternate Python installation; if the directories listed actually point to an alternate Python installation; if the directories listed
...@@ -418,7 +481,7 @@ if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an ...@@ -418,7 +481,7 @@ if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an
alternate Python installation, this is immaterial.) alternate Python installation, this is immaterial.)
.. _inst-alt-install-windows: .. _inst-alt-install-prefix-windows:
Alternate installation: Windows (the prefix scheme) Alternate installation: Windows (the prefix scheme)
--------------------------------------------------- ---------------------------------------------------
...@@ -433,20 +496,18 @@ locations on Windows. :: ...@@ -433,20 +496,18 @@ locations on Windows. ::
to install modules to the :file:`\\Temp\\Python` directory on the current drive. to install modules to the :file:`\\Temp\\Python` directory on the current drive.
The installation base is defined by the :option:`--prefix` option; the The installation base is defined by the :option:`--prefix` option; the
:option:`--exec-prefix` option is not supported under Windows. Files are :option:`--exec-prefix` option is not supported under Windows, which means that
installed as follows: pure Python modules and extension modules are installed into the same location.
Files are installed as follows:
+------------------------------+---------------------------+-----------------------------+
| Type of file | Installation Directory | Override option | =============== ==========================================================
+==============================+===========================+=============================+ Type of file Installation directory
| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | =============== ==========================================================
+------------------------------+---------------------------+-----------------------------+ modules :file:`{prefix}\\Lib\\site-packages`
| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | scripts :file:`{prefix}\\Scripts`
+------------------------------+---------------------------+-----------------------------+ data :file:`{prefix}`
| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | C headers :file:`{prefix}\\Include\\{distname}`
+------------------------------+---------------------------+-----------------------------+ =============== ==========================================================
| data | :file:`{prefix}\\Data` | :option:`--install-data` |
+------------------------------+---------------------------+-----------------------------+
.. _inst-custom-install: .. _inst-custom-install:
...@@ -460,13 +521,29 @@ one or two directories while keeping everything under the same base directory, ...@@ -460,13 +521,29 @@ one or two directories while keeping everything under the same base directory,
or you might want to completely redefine the installation scheme. In either or you might want to completely redefine the installation scheme. In either
case, you're creating a *custom installation scheme*. case, you're creating a *custom installation scheme*.
You probably noticed the column of "override options" in the tables describing To create a custom installation scheme, you start with one of the alternate
the alternate installation schemes above. Those options are how you define a schemes and override some of the installation directories used for the various
custom installation scheme. These override options can be relative, absolute, types of files, using these options:
====================== =======================
Type of file Override option
====================== =======================
Python modules ``--install-purelib``
extension modules ``--install-platlib``
all modules ``--install-lib``
scripts ``--install-scripts``
data ``--install-data``
C headers ``--install-headers``
====================== =======================
These override options can be relative, absolute,
or explicitly defined in terms of one of the installation base directories. or explicitly defined in terms of one of the installation base directories.
(There are two installation base directories, and they are normally the same--- (There are two installation base directories, and they are normally the same---
they only differ when you use the Unix "prefix scheme" and supply different they only differ when you use the Unix "prefix scheme" and supply different
:option:`--prefix` and :option:`--exec-prefix` options.) ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will
override values computed or given for ``--install-purelib`` and
``--install-platlib``, and is recommended for schemes that don't make a
difference between Python and extension modules.)
For example, say you're installing a module distribution to your home directory For example, say you're installing a module distribution to your home directory
under Unix---but you want scripts to go in :file:`~/scripts` rather than under Unix---but you want scripts to go in :file:`~/scripts` rather than
...@@ -493,15 +570,16 @@ If you maintain Python on Windows, you might want third-party modules to live in ...@@ -493,15 +570,16 @@ If you maintain Python on Windows, you might want third-party modules to live in
a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
itself. This is almost as easy as customizing the script installation directory itself. This is almost as easy as customizing the script installation directory
---you just have to remember that there are two types of modules to worry about, ---you just have to remember that there are two types of modules to worry about,
pure modules and non-pure modules (i.e., modules from a non-pure distribution). Python and extension modules, which can conveniently be both controlled by one
For example:: option::
python setup.py install --install-purelib=Site --install-platlib=Site python setup.py install --install-lib=Site
The specified installation directories are relative to :file:`{prefix}`. Of The specified installation directory is relative to :file:`{prefix}`. Of
course, you also have to ensure that these directories are in Python's module course, you also have to ensure that this directory is in Python's module
search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See search path, such as by putting a :file:`.pth` file in a site directory (see
section :ref:`inst-search-path` to find out how to modify Python's search path. :mod:`site`). See section :ref:`inst-search-path` to find out how to modify
Python's search path.
If you want to define an entire installation scheme, you just have to supply all If you want to define an entire installation scheme, you just have to supply all
of the installation directory options. The recommended way to do this is to of the installation directory options. The recommended way to do this is to
...@@ -553,8 +631,8 @@ base directory when you run the setup script. For example, :: ...@@ -553,8 +631,8 @@ base directory when you run the setup script. For example, ::
python setup.py install --install-base=/tmp python setup.py install --install-base=/tmp
would install pure modules to :file:`{/tmp/python/lib}` in the first case, and would install pure modules to :file:`/tmp/python/lib` in the first case, and
to :file:`{/tmp/lib}` in the second case. (For the second case, you probably to :file:`/tmp/lib` in the second case. (For the second case, you probably
want to supply an installation base of :file:`/tmp/python`.) want to supply an installation base of :file:`/tmp/python`.)
You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample
...@@ -571,7 +649,7 @@ for details. ...@@ -571,7 +649,7 @@ for details.
needed on those platforms? needed on those platforms?
.. XXX I'm not sure where this section should go. .. XXX Move this to Doc/using
.. _inst-search-path: .. _inst-search-path:
......
...@@ -293,6 +293,14 @@ and get the output as shown, to find out my :file:`{prefix}` and :file:`{exec-pr ...@@ -293,6 +293,14 @@ and get the output as shown, to find out my :file:`{prefix}` and :file:`{exec-pr
>>> sys.exec_prefix >>> sys.exec_prefix
'/usr' '/usr'
A few other placeholders are used in this document: :file:`{X.Y}` stands for the
version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by
the value of :data:`sys.abiflags` or the empty string for platforms which don't
define ABI flags; :file:`{distname}` will be replaced by the name of the module
distribution being installed. Dots and capitalization are important in the
paths; for example, a value that uses ``python3.2`` on UNIX will typically use
``Python32`` on Windows.
If you don't want to install modules to the standard location, or if you don't If you don't want to install modules to the standard location, or if you don't
have permission to write there, then you need to read about alternate have permission to write there, then you need to read about alternate
installations in section :ref:`packaging-alt-install`. If you want to customize your installations in section :ref:`packaging-alt-install`. If you want to customize your
...@@ -320,8 +328,72 @@ scheme*) under this base directory in which to install files. The details ...@@ -320,8 +328,72 @@ scheme*) under this base directory in which to install files. The details
differ across platforms, so read whichever of the following sections applies to differ across platforms, so read whichever of the following sections applies to
you. you.
Note that the various alternate installation schemes are mutually exclusive: you
can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or
``--install-base`` and ``--install-platbase``, but you can't mix from these
groups.
.. _packaging-alt-install-prefix: .. _packaging-alt-install-user:
Alternate installation: the user scheme
---------------------------------------
This scheme is designed to be the most convenient solution for users that don't
have write permission to the global site-packages directory or don't want to
install into it. It is enabled with a simple option::
pysetup run install_dist --user
Files will be installed into subdirectories of :data:`site.USER_BASE` (written
as :file:`{userbase}` hereafter). This scheme installs pure Python modules and
extension modules in the same location (also known as :data:`site.USER_SITE`).
Here are the values for UNIX, including non-framework builds on Mac OS X:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}/lib/python{X.Y}/site-packages`
scripts :file:`{userbase}/bin`
data :file:`{userbase}`
C headers :file:`{userbase}/include/python{X.Y}`
=============== ===========================================================
Framework builds on Mac OS X use these paths:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}/lib/python/site-packages`
scripts :file:`{userbase}/bin`
data :file:`{userbase}`
C headers :file:`{userbase}/include/python`
=============== ===========================================================
And here are the values used on Windows:
=============== ===========================================================
Type of file Installation directory
=============== ===========================================================
modules :file:`{userbase}\\Python{XY}\\site-packages`
scripts :file:`{userbase}\\Scripts`
data :file:`{userbase}`
C headers :file:`{userbase}\\Python{XY}\\Include`
=============== ===========================================================
The advantage of using this scheme compared to the other ones described below is
that the user site-packages directory is under normal conditions always included
in :data:`sys.path` (see :mod:`site` for more information), which means that
there is no additional step to perform after running ``pysetup`` to finalize the
installation.
The :command:`build_ext` command also has a ``--user`` option to add
:file:`{userbase}/include` to the compiler search path for header files and
:file:`{userbase}/lib` to the compiler search path for libraries as well as to
the runtime search path for shared C libraries (rpath).
.. _packaging-alt-install-home:
Alternate installation: the home scheme Alternate installation: the home scheme
--------------------------------------- ---------------------------------------
...@@ -343,23 +415,27 @@ will expand this to your home directory:: ...@@ -343,23 +415,27 @@ will expand this to your home directory::
pysetup run install_dist --home ~ pysetup run install_dist --home ~
To make Python find the distributions installed with this scheme, you may have
to :ref:`modify Python's search path <inst-search-path>` or edit
:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit
:data:`sys.path`.
The :option:`--home` option defines the base directory for the installation. The :option:`--home` option defines the base directory for the installation.
Under it, files are installed to the following directories: Under it, files are installed to the following directories:
+------------------------------+---------------------------+-----------------------------+ =============== ===========================================================
| Type of file | Installation Directory | Override option | Type of file Installation directory
+==============================+===========================+=============================+ =============== ===========================================================
| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | modules :file:`{home}/lib/python`
+------------------------------+---------------------------+-----------------------------+ scripts :file:`{home}/bin`
| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | data :file:`{home}`
+------------------------------+---------------------------+-----------------------------+ C headers :file:`{home}/include/python`
| scripts | :file:`{home}/bin` | :option:`--install-scripts` | =============== ===========================================================
+------------------------------+---------------------------+-----------------------------+
| data | :file:`{home}/share` | :option:`--install-data` |
+------------------------------+---------------------------+-----------------------------+
(Mentally replace slashes with backslashes if you're on Windows.)
.. _packaging-alt-install-home:
.. _packaging-alt-install-prefix-unix:
Alternate installation: Unix (the prefix scheme) Alternate installation: Unix (the prefix scheme)
------------------------------------------------ ------------------------------------------------
...@@ -368,8 +444,8 @@ The "prefix scheme" is useful when you wish to use one Python installation to ...@@ -368,8 +444,8 @@ The "prefix scheme" is useful when you wish to use one Python installation to
run the build command, but install modules into the third-party module directory run the build command, but install modules into the third-party module directory
of a different Python installation (or something that looks like a different of a different Python installation (or something that looks like a different
Python installation). If this sounds a trifle unusual, it is ---that's why the Python installation). If this sounds a trifle unusual, it is ---that's why the
"home scheme" comes first. However, there are at least two known cases where the user and home schemes come before. However, there are at least two known cases
prefix scheme will be useful. where the prefix scheme will be useful.
First, consider that many Linux distributions put Python in :file:`/usr`, rather First, consider that many Linux distributions put Python in :file:`/usr`, rather
than the more traditional :file:`/usr/local`. This is entirely appropriate, than the more traditional :file:`/usr/local`. This is entirely appropriate,
...@@ -396,17 +472,17 @@ non-pure module distributions, but could be expanded to C libraries, binary ...@@ -396,17 +472,17 @@ non-pure module distributions, but could be expanded to C libraries, binary
executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to
:option:`--prefix`. Files are installed as follows: :option:`--prefix`. Files are installed as follows:
+------------------------------+-----------------------------------------------------+-----------------------------+ ================= ==========================================================
| Type of file | Installation Directory | Override option | Type of file Installation directory
+==============================+=====================================================+=============================+ ================= ==========================================================
| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | Python modules :file:`{prefix}/lib/python{X.Y}/site-packages`
+------------------------------+-----------------------------------------------------+-----------------------------+ extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages`
| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | scripts :file:`{prefix}/bin`
+------------------------------+-----------------------------------------------------+-----------------------------+ data :file:`{prefix}`
| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | C headers :file:`{prefix}/include/python{X.Y}{abiflags}`
+------------------------------+-----------------------------------------------------+-----------------------------+ ================= ==========================================================
| data | :file:`{prefix}/share` | :option:`--install-data` |
+------------------------------+-----------------------------------------------------+-----------------------------+ .. XXX misses an entry for platinclude
There is no requirement that :option:`--prefix` or :option:`--exec-prefix` There is no requirement that :option:`--prefix` or :option:`--exec-prefix`
actually point to an alternate Python installation; if the directories listed actually point to an alternate Python installation; if the directories listed
...@@ -432,7 +508,7 @@ and :option:`--exec-prefix` don't even point to an alternate Python installation ...@@ -432,7 +508,7 @@ and :option:`--exec-prefix` don't even point to an alternate Python installation
this is immaterial.) this is immaterial.)
.. _packaging-alt-install-windows: .. _packaging-alt-install-prefix-windows:
Alternate installation: Windows (the prefix scheme) Alternate installation: Windows (the prefix scheme)
--------------------------------------------------- ---------------------------------------------------
...@@ -447,20 +523,18 @@ locations. :: ...@@ -447,20 +523,18 @@ locations. ::
to install modules to the :file:`\\Temp\\Python` directory on the current drive. to install modules to the :file:`\\Temp\\Python` directory on the current drive.
The installation base is defined by the :option:`--prefix` option; the The installation base is defined by the :option:`--prefix` option; the
:option:`--exec-prefix` option is unsupported under Windows. Files are :option:`--exec-prefix` option is not supported under Windows, which means that
installed as follows: pure Python modules and extension modules are installed into the same location.
Files are installed as follows:
+------------------------------+---------------------------+-----------------------------+
| Type of file | Installation Directory | Override option | =============== ==========================================================
+==============================+===========================+=============================+ Type of file Installation directory
| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | =============== ==========================================================
+------------------------------+---------------------------+-----------------------------+ modules :file:`{prefix}\\Lib\\site-packages`
| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | scripts :file:`{prefix}\\Scripts`
+------------------------------+---------------------------+-----------------------------+ data :file:`{prefix}`
| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | C headers :file:`{prefix}\\Include`
+------------------------------+---------------------------+-----------------------------+ =============== ==========================================================
| data | :file:`{prefix}\\Data` | :option:`--install-data` |
+------------------------------+---------------------------+-----------------------------+
.. _packaging-custom-install: .. _packaging-custom-install:
...@@ -474,13 +548,29 @@ just one or two directories while keeping everything under the same base ...@@ -474,13 +548,29 @@ just one or two directories while keeping everything under the same base
directory, or you might want to completely redefine the installation scheme. directory, or you might want to completely redefine the installation scheme.
In either case, you're creating a *custom installation scheme*. In either case, you're creating a *custom installation scheme*.
You probably noticed the column of "override options" in the tables describing To create a custom installation scheme, you start with one of the alternate
the alternate installation schemes above. Those options are how you define a schemes and override some of the installation directories used for the various
custom installation scheme. These override options can be relative, absolute, types of files, using these options:
====================== =======================
Type of file Override option
====================== =======================
Python modules ``--install-purelib``
extension modules ``--install-platlib``
all modules ``--install-lib``
scripts ``--install-scripts``
data ``--install-data``
C headers ``--install-headers``
====================== =======================
These override options can be relative, absolute,
or explicitly defined in terms of one of the installation base directories. or explicitly defined in terms of one of the installation base directories.
(There are two installation base directories, and they are normally the same (There are two installation base directories, and they are normally the same
---they only differ when you use the Unix "prefix scheme" and supply different ---they only differ when you use the Unix "prefix scheme" and supply different
:option:`--prefix` and :option:`--exec-prefix` options.) ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will
override values computed or given for ``--install-purelib`` and
``--install-platlib``, and is recommended for schemes that don't make a
difference between Python and extension modules.)
For example, say you're installing a module distribution to your home directory For example, say you're installing a module distribution to your home directory
under Unix, but you want scripts to go in :file:`~/scripts` rather than under Unix, but you want scripts to go in :file:`~/scripts` rather than
...@@ -507,17 +597,18 @@ If you maintain Python on Windows, you might want third-party modules to live in ...@@ -507,17 +597,18 @@ If you maintain Python on Windows, you might want third-party modules to live in
a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
itself. This is almost as easy as customizing the script installation directory itself. This is almost as easy as customizing the script installation directory
---you just have to remember that there are two types of modules to worry about, ---you just have to remember that there are two types of modules to worry about,
pure modules and non-pure modules (i.e., modules from a non-pure distribution). Python and extension modules, which can conveniently be both controlled by one
For example:: option::
pysetup run install_dist --install-purelib Site --install-platlib Site pysetup run install_dist --install-lib Site
.. XXX Nothing is installed right under prefix in windows, is it?? .. XXX Nothing is installed right under prefix in windows, is it??
The specified installation directories are relative to :file:`{prefix}`. Of The specified installation directory is relative to :file:`{prefix}`. Of
course, you also have to ensure that these directories are in Python's module course, you also have to ensure that this directory is in Python's module
search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See search path, such as by putting a :file:`.pth` file in a site directory (see
section :ref:`packaging-search-path` to find out how to modify Python's search path. :mod:`site`). See section :ref:`packaging-search-path` to find out how to modify
Python's search path.
If you want to define an entire installation scheme, you just have to supply all If you want to define an entire installation scheme, you just have to supply all
of the installation directory options. Using relative paths is recommended here. of the installation directory options. Using relative paths is recommended here.
......
...@@ -2,22 +2,24 @@ ...@@ -2,22 +2,24 @@
================================================ ================================================
.. module:: site .. module:: site
:synopsis: A standard way to reference site-specific modules. :synopsis: Module responsible for site-specific configuration.
**Source code:** :source:`Lib/site.py` **Source code:** :source:`Lib/site.py`
-------------- --------------
.. highlightlang:: none
**This module is automatically imported during initialization.** The automatic **This module is automatically imported during initialization.** The automatic
import can be suppressed using the interpreter's :option:`-S` option. import can be suppressed using the interpreter's :option:`-S` option.
.. index:: triple: module; search; path .. index:: triple: module; search; path
Importing this module will append site-specific paths to the module search Importing this module will append site-specific paths to the module search path
path, unless :option:`-S` was used. In that case, this module can be safely and add a few builtins, unless :option:`-S` was used. In that case, this module
imported with no automatic modifications to the module search path. To can be safely imported with no automatic modifications to the module search path
explicitly trigger the usual site-specific additions, call the or additions to the builtins. To explicitly trigger the usual site-specific
:func:`site.main` function. additions, call the :func:`site.main` function.
.. versionchanged:: 3.3 .. versionchanged:: 3.3
Importing the module used to trigger paths manipulation even when using Importing the module used to trigger paths manipulation even when using
...@@ -36,11 +38,11 @@ Unix and Macintosh). For each of the distinct head-tail combinations, it sees ...@@ -36,11 +38,11 @@ Unix and Macintosh). For each of the distinct head-tail combinations, it sees
if it refers to an existing directory, and if so, adds it to ``sys.path`` and if it refers to an existing directory, and if so, adds it to ``sys.path`` and
also inspects the newly added path for configuration files. also inspects the newly added path for configuration files.
A path configuration file is a file whose name has the form :file:`package.pth` A path configuration file is a file whose name has the form :file:`{name}.pth`
and exists in one of the four directories mentioned above; its contents are and exists in one of the four directories mentioned above; its contents are
additional items (one per line) to be added to ``sys.path``. Non-existing items additional items (one per line) to be added to ``sys.path``. Non-existing items
are never added to ``sys.path``, but no check is made that the item refers to a are never added to ``sys.path``, and no check is made that the item refers to a
directory (rather than a file). No item is added to ``sys.path`` more than directory rather than a file. No item is added to ``sys.path`` more than
once. Blank lines and lines beginning with ``#`` are skipped. Lines starting once. Blank lines and lines beginning with ``#`` are skipped. Lines starting
with ``import`` (followed by space or tab) are executed. with ``import`` (followed by space or tab) are executed.
...@@ -50,8 +52,7 @@ with ``import`` (followed by space or tab) are executed. ...@@ -50,8 +52,7 @@ with ``import`` (followed by space or tab) are executed.
For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to For example, suppose ``sys.prefix`` and ``sys.exec_prefix`` are set to
:file:`/usr/local`. The Python X.Y library is then installed in :file:`/usr/local`. The Python X.Y library is then installed in
:file:`/usr/local/lib/python{X.Y}` (where only the first three characters of :file:`/usr/local/lib/python{X.Y}`. Suppose this has
``sys.version`` are used to form the installation path name). Suppose this has
a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three a subdirectory :file:`/usr/local/lib/python{X.Y}/site-packages` with three
subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path subsubdirectories, :file:`foo`, :file:`bar` and :file:`spam`, and two path
configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume configuration files, :file:`foo.pth` and :file:`bar.pth`. Assume
...@@ -84,42 +85,59 @@ not mentioned in either path configuration file. ...@@ -84,42 +85,59 @@ not mentioned in either path configuration file.
After these path manipulations, an attempt is made to import a module named After these path manipulations, an attempt is made to import a module named
:mod:`sitecustomize`, which can perform arbitrary site-specific customizations. :mod:`sitecustomize`, which can perform arbitrary site-specific customizations.
If this import fails with an :exc:`ImportError` exception, it is silently It is typically created by a system administrator in the site-packages
ignored. directory. If this import fails with an :exc:`ImportError` exception, it is
silently ignored.
.. index:: module: sitecustomize .. index:: module: usercustomize
After this, an attempt is made to import a module named :mod:`usercustomize`,
which can perform arbitrary user-specific customizations, if
:data:`ENABLE_USER_SITE` is true. This file is intended to be created in the
user site-packages directory (see below), which is part of ``sys.path`` unless
disabled by :option:`-s`. An :exc:`ImportError` will be silently ignored.
Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are Note that for some non-Unix systems, ``sys.prefix`` and ``sys.exec_prefix`` are
empty, and the path manipulations are skipped; however the import of empty, and the path manipulations are skipped; however the import of
:mod:`sitecustomize` is still attempted. :mod:`sitecustomize` and :mod:`usercustomize` is still attempted.
.. data:: PREFIXES .. data:: PREFIXES
A list of prefixes for site package directories A list of prefixes for site-packages directories.
.. data:: ENABLE_USER_SITE .. data:: ENABLE_USER_SITE
Flag showing the status of the user site directory. True means the Flag showing the status of the user site-packages directory. ``True`` means
user site directory is enabled and added to sys.path. When the flag that it is enabled and was added to ``sys.path``. ``False`` means that it
is None the user site directory is disabled for security reasons. was disabled by user request (with :option:`-s` or
:envvar:`PYTHONNOUSERSITE`). ``None`` means it was disabled for security
reasons (mismatch between user or group id and effective id) or by an
administrator.
.. data:: USER_SITE .. data:: USER_SITE
Path to the user site directory for the current Python version or None Path to the user site-packages for the running Python. Can be ``None`` if
:func:`getusersitepackages` hasn't been called yet. Default value is
:file:`~/.local/lib/python{X.Y}/site-packages` for UNIX and non-framework Mac
OS X builds, :file:`~/Library/Python/{X.Y}/lib/python/site-packages` for Mac
framework builds, and :file:`{%APPDATA%}\\Python\\Python{XY}\\site-packages`
on Windows. This directory is a site directory, which means that
:file:`.pth` files in it will be processed.
.. data:: USER_BASE .. data:: USER_BASE
Path to the base directory for user site directories Path to the base directory for the user site-packages. Can be ``None`` if
:func:`getuserbase` hasn't been called yet. Default value is
:file:`~/.local` for UNIX and Mac OS X non-framework builds,
.. envvar:: PYTHONNOUSERSITE :file:`~/Library/Python/{X.Y}` for Mac framework builds, and
:file:`{%APPDATA%}\\Python` for Windows. This value is used by Packaging to
compute the installation directories for scripts, data files, Python modules,
.. envvar:: PYTHONUSERBASE etc. for the :ref:`user installation scheme <packaging-alt-install-user>`.
See also :envvar:`PYTHONUSERBASE`.
.. function:: main() .. function:: main()
...@@ -135,34 +153,67 @@ empty, and the path manipulations are skipped; however the import of ...@@ -135,34 +153,67 @@ empty, and the path manipulations are skipped; however the import of
.. function:: addsitedir(sitedir, known_paths=None) .. function:: addsitedir(sitedir, known_paths=None)
Adds a directory to sys.path and processes its pth files. Add a directory to sys.path and process its :file:`.pth` files. Typically
used in :mod:`sitecustomize` or :mod:`usercustomize` (see above).
.. function:: getsitepackages() .. function:: getsitepackages()
Returns a list containing all global site-packages directories Return a list containing all global site-packages directories (and possibly
(and possibly site-python). site-python).
.. versionadded:: 3.2 .. versionadded:: 3.2
.. function:: getuserbase()
Returns the "user base" directory path. .. function:: getuserbase()
The "user base" directory can be used to store data. If the global Return the path of the user base directory, :data:`USER_BASE`. If it is not
variable ``USER_BASE`` is not initialized yet, this function will also set initialized yet, this function will also set it, respecting
it. :envvar:`PYTHONUSERBASE`.
.. versionadded:: 3.2 .. versionadded:: 3.2
.. function:: getusersitepackages()
Returns the user-specific site-packages directory path. .. function:: getusersitepackages()
If the global variable ``USER_SITE`` is not initialized yet, this Return the path of the user-specific site-packages directory,
function will also set it. :data:`USER_SITE`. If it is not initialized yet, this function will also set
it, respecting :envvar:`PYTHONNOUSERSITE` and :data:`USER_BASE`.
.. versionadded:: 3.2 .. versionadded:: 3.2
.. XXX Update documentation
.. XXX document python -m site --user-base --user-site
The :mod:`site` module also provides a way to get the user directories from the
command line:
.. code-block:: sh
$ python3 -m site --user-site
/home/user/.local/lib/python3.3/site-packages
.. program:: site
If it is called without arguments, it will print the contents of
:data:`sys.path` on the standard output, followed by the value of
:data:`USER_BASE` and whether the directory exists, then the same thing for
:data:`USER_SITE`, and finally the value of :data:`ENABLE_USER_SITE`.
.. cmdoption:: --user-base
Print the path to the user base directory.
.. cmdoption:: --user-site
Print the path to the user site-packages directory.
If both options are given, user base and user site will be printed (always in
this order), separated by :data:`os.pathsep`.
If any option is given, the script will exit with one of these values: ``O`` if
the user site-packages directory is enabled, ``1`` if it was disabled by the
user, ``2`` if it is disabled for security reasons or by an administrator, and a
value greater than 2 if there is an error.
.. seealso::
:pep:`370` -- Per user site-packages directory
...@@ -12,6 +12,12 @@ their options. ...@@ -12,6 +12,12 @@ their options.
description. Use pysetup run <command> --help to get help about the options description. Use pysetup run <command> --help to get help about the options
of one command. of one command.
.. XXX sections from this document should be merged with other docs (e.g. check
and upload with uploading.rst, install_* with install/install.rst, etc.);
there is no value in partially duplicating information. this file could
however serve as an index, i.e. just a list of all commands with links to
every section that describes options or usage
Preparing distributions Preparing distributions
======================= =======================
...@@ -310,13 +316,8 @@ the target system. ...@@ -310,13 +316,8 @@ the target system.
----------------------- -----------------------
Install a distribution, delegating to the other :command:`install_*` commands to Install a distribution, delegating to the other :command:`install_*` commands to
do the work. do the work. See :ref:`packaging-how-install-works` for complete usage
instructions.
.. program:: packaging install_dist
.. cmdoption:: --user
Install in user site-packages directory (see :PEP:`370`).
:command:`install_data` :command:`install_data`
......
...@@ -156,17 +156,18 @@ symbol table. A command to check (or even suggest) matching parentheses, ...@@ -156,17 +156,18 @@ symbol table. A command to check (or even suggest) matching parentheses,
quotes, etc., would also be useful. quotes, etc., would also be useful.
One alternative enhanced interactive interpreter that has been around for quite One alternative enhanced interactive interpreter that has been around for quite
some time is `IPython`_, which features tab completion, object exploration and some time is IPython_, which features tab completion, object exploration and
advanced history management. It can also be thoroughly customized and embedded advanced history management. It can also be thoroughly customized and embedded
into other applications. Another similar enhanced interactive environment is into other applications. Another similar enhanced interactive environment is
`bpython`_. bpython_.
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#] Python will execute the contents of a file identified by the .. [#] Python will execute the contents of a file identified by the
:envvar:`PYTHONSTARTUP` environment variable when you start an interactive :envvar:`PYTHONSTARTUP` environment variable when you start an interactive
interpreter. interpreter. To customize Python even for non-interactive mode, see
:ref:`tut-customize`.
.. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html .. _GNU Readline: http://tiswww.case.edu/php/chet/readline/rltop.html
......
...@@ -236,6 +236,29 @@ in the script:: ...@@ -236,6 +236,29 @@ in the script::
exec(open(filename).read()) exec(open(filename).read())
.. _tut-customize:
The Customization Modules
-------------------------
Python provides two hooks to let you customize it: :mod:`sitecustomize` and
:mod:`usercustomize`. To see how it works, you need first to find the location
of your user site-packages directory. Start Python and run this code:
>>> import site
>>> site.getusersitepackages()
'/home/user/.local/lib/python3.2/site-packages'
Now you can create a file named :file:`usercustomize.py` in that directory and
put anything you want in it. It will affect every invocation of Python, unless
it is started with the :option:`-s` option to disable the automatic import.
:mod:`sitecustomize` works in the same way, but is typically created by an
administrator of the computer in the global site-packages directory, and is
imported before :mod:`usercustomize`. See the documentation of the :mod:`site`
module for more details.
.. rubric:: Footnotes .. rubric:: Footnotes
.. [#] On Unix, the Python 3.x interpreter is by default not installed with the .. [#] On Unix, the Python 3.x interpreter is by default not installed with the
...@@ -243,4 +266,3 @@ in the script:: ...@@ -243,4 +266,3 @@ in the script::
simultaneously installed Python 2.x executable. simultaneously installed Python 2.x executable.
.. [#] A problem with the GNU Readline package may prevent this. .. [#] A problem with the GNU Readline package may prevent this.
...@@ -229,7 +229,8 @@ Miscellaneous options ...@@ -229,7 +229,8 @@ Miscellaneous options
.. cmdoption:: -s .. cmdoption:: -s
Don't add user site directory to sys.path Don't add the :data:`user site-packages directory <site.USER_SITE>` to
:data:`sys.path`.
.. seealso:: .. seealso::
...@@ -470,7 +471,8 @@ These environment variables influence Python's behavior. ...@@ -470,7 +471,8 @@ These environment variables influence Python's behavior.
.. envvar:: PYTHONNOUSERSITE .. envvar:: PYTHONNOUSERSITE
If this is set, Python won't add the user site directory to sys.path If this is set, Python won't add the :data:`user site-packages directory
<site.USER_SITE>` to :data:`sys.path`.
.. seealso:: .. seealso::
...@@ -479,7 +481,10 @@ These environment variables influence Python's behavior. ...@@ -479,7 +481,10 @@ These environment variables influence Python's behavior.
.. envvar:: PYTHONUSERBASE .. envvar:: PYTHONUSERBASE
Sets the base directory for the user site directory Defines the :data:`user base directory <site.USER_BASE>`, which is used to
compute the path of the :data:`user site-packages directory <site.USER_SITE>`
and :ref:`Packaging installation paths <packaging-alt-install-user>` for
``pysetup run install_dist --user``.
.. seealso:: .. seealso::
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment