forked from mirrors/nixpkgs
doc: consistent formatting on python manual section
No material changes to docs, but trying to sanitize them for consistent readability prior to looking at #75837. - Use `*` for lists instead of `-`. I have no opinion one way or the other, but the latter was only used in 1-2 places. - Pad the code blocks with whitespace. - Wrap to 80 characters, except for a few 1-liners that were only slightly over.
This commit is contained in:
Benjamin Hipple
parent
500a8ffd96
commit
4988805287
|
|
@ -72,8 +72,9 @@ Now you can use the Python interpreter, as well as the extra packages (`numpy`,
|
|||
|
||||
##### Environment defined in `~/.config/nixpkgs/config.nix`
|
||||
|
||||
If you prefer to, you could also add the environment as a package override to the Nixpkgs set, e.g.
|
||||
using `config.nix`,
|
||||
If you prefer you could also add the environment as a package override to the
|
||||
Nixpkgs set, e.g. using `config.nix`,
|
||||
|
||||
```nix
|
||||
{ # ...
|
||||
|
||||
|
|
@ -83,15 +84,18 @@ using `config.nix`,
|
|||
}
|
||||
```
|
||||
and install it in your profile with
|
||||
|
||||
```shell
|
||||
nix-env -iA nixpkgs.myEnv
|
||||
```
|
||||
|
||||
The environment is is installed by referring to the attribute, and considering
|
||||
the `nixpkgs` channel was used.
|
||||
|
||||
##### Environment defined in `/etc/nixos/configuration.nix`
|
||||
|
||||
For the sake of completeness, here's another example how to install the environment system-wide.
|
||||
For the sake of completeness, here's another example how to install the
|
||||
environment system-wide.
|
||||
|
||||
```nix
|
||||
{ # ...
|
||||
|
|
@ -109,40 +113,56 @@ into a profile. For development you may need to use multiple environments.
|
|||
`nix-shell` gives the possibility to temporarily load another environment, akin
|
||||
to `virtualenv`.
|
||||
|
||||
There are two methods for loading a shell with Python packages. The first and recommended method
|
||||
is to create an environment with `python.buildEnv` or `python.withPackages` and load that. E.g.
|
||||
There are two methods for loading a shell with Python packages. The first and
|
||||
recommended method is to create an environment with `python.buildEnv` or
|
||||
`python.withPackages` and load that. E.g.
|
||||
|
||||
```sh
|
||||
$ nix-shell -p 'python35.withPackages(ps: with ps; [ numpy toolz ])'
|
||||
```
|
||||
|
||||
opens a shell from which you can launch the interpreter
|
||||
|
||||
```sh
|
||||
[nix-shell:~] python3
|
||||
```
|
||||
The other method, which is not recommended, does not create an environment and requires you to list the packages directly,
|
||||
|
||||
The other method, which is not recommended, does not create an environment and
|
||||
requires you to list the packages directly,
|
||||
|
||||
```sh
|
||||
$ nix-shell -p python35.pkgs.numpy python35.pkgs.toolz
|
||||
```
|
||||
Again, it is possible to launch the interpreter from the shell.
|
||||
The Python interpreter has the attribute `pkgs` which contains all Python libraries for that specific interpreter.
|
||||
|
||||
Again, it is possible to launch the interpreter from the shell. The Python
|
||||
interpreter has the attribute `pkgs` which contains all Python libraries for
|
||||
that specific interpreter.
|
||||
|
||||
##### Load environment from `.nix` expression
|
||||
As explained in the Nix manual, `nix-shell` can also load an
|
||||
expression from a `.nix` file. Say we want to have Python 3.5, `numpy`
|
||||
and `toolz`, like before, in an environment. Consider a `shell.nix` file
|
||||
with
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
(python35.withPackages (ps: [ps.numpy ps.toolz])).env
|
||||
```
|
||||
|
||||
Executing `nix-shell` gives you again a Nix shell from which you can run Python.
|
||||
|
||||
What's happening here?
|
||||
|
||||
1. We begin with importing the Nix Packages collections. `import <nixpkgs>` imports the `<nixpkgs>` function, `{}` calls it and the `with` statement brings all attributes of `nixpkgs` in the local scope. These attributes form the main package set.
|
||||
1. We begin with importing the Nix Packages collections. `import <nixpkgs>`
|
||||
imports the `<nixpkgs>` function, `{}` calls it and the `with` statement
|
||||
brings all attributes of `nixpkgs` in the local scope. These attributes form
|
||||
the main package set.
|
||||
2. Then we create a Python 3.5 environment with the `withPackages` function.
|
||||
3. The `withPackages` function expects us to provide a function as an argument that takes the set of all python packages and returns a list of packages to include in the environment. Here, we select the packages `numpy` and `toolz` from the package set.
|
||||
3. The `withPackages` function expects us to provide a function as an argument
|
||||
that takes the set of all python packages and returns a list of packages to
|
||||
include in the environment. Here, we select the packages `numpy` and `toolz`
|
||||
from the package set.
|
||||
|
||||
To combine this with `mkShell` you can:
|
||||
|
||||
|
|
@ -166,20 +186,23 @@ in mkShell {
|
|||
A convenient option with `nix-shell` is the `--run`
|
||||
option, with which you can execute a command in the `nix-shell`. We can
|
||||
e.g. directly open a Python shell
|
||||
|
||||
```sh
|
||||
$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3"
|
||||
```
|
||||
|
||||
or run a script
|
||||
|
||||
```sh
|
||||
$ nix-shell -p python35Packages.numpy python35Packages.toolz --run "python3 myscript.py"
|
||||
```
|
||||
|
||||
##### `nix-shell` as shebang
|
||||
In fact, for the second use case, there is a more convenient method. You can
|
||||
add a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
|
||||
In fact, for the second use case, there is a more convenient method. You can add
|
||||
a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) to your script
|
||||
specifying which dependencies `nix-shell` needs. With the following shebang, you
|
||||
can just execute `./myscript.py`, and it will make available all dependencies and
|
||||
run the script in the `python3` shell.
|
||||
can just execute `./myscript.py`, and it will make available all dependencies
|
||||
and run the script in the `python3` shell.
|
||||
|
||||
```py
|
||||
#! /usr/bin/env nix-shell
|
||||
|
|
@ -270,6 +293,7 @@ with import <nixpkgs> {};
|
|||
in python35.withPackages (ps: [ps.numpy my_toolz])
|
||||
).env
|
||||
```
|
||||
|
||||
Executing `nix-shell` will result in an environment in which you can use
|
||||
Python 3.5 and the `toolz` package. As you can see we had to explicitly mention
|
||||
for which Python version we want to build a package.
|
||||
|
|
@ -355,12 +379,12 @@ buildPythonPackage rec {
|
|||
In this example `lxml` and Nix are able to work out exactly where the relevant
|
||||
files of the dependencies are. This is not always the case.
|
||||
|
||||
The example below shows bindings to The Fastest Fourier Transform in the West, commonly known as
|
||||
FFTW. On Nix we have separate packages of FFTW for the different types of floats
|
||||
(`"single"`, `"double"`, `"long-double"`). The bindings need all three types,
|
||||
and therefore we add all three as `buildInputs`. The bindings don't expect to
|
||||
find each of them in a different folder, and therefore we have to set `LDFLAGS`
|
||||
and `CFLAGS`.
|
||||
The example below shows bindings to The Fastest Fourier Transform in the West,
|
||||
commonly known as FFTW. On Nix we have separate packages of FFTW for the
|
||||
different types of floats (`"single"`, `"double"`, `"long-double"`). The
|
||||
bindings need all three types, and therefore we add all three as `buildInputs`.
|
||||
The bindings don't expect to find each of them in a different folder, and
|
||||
therefore we have to set `LDFLAGS` and `CFLAGS`.
|
||||
|
||||
```nix
|
||||
{ lib, pkgs, buildPythonPackage, fetchPypi, numpy, scipy }:
|
||||
|
|
@ -404,17 +428,18 @@ instead of installing the package this command creates a special link to the pro
|
|||
That way, you can run updated code without having to reinstall after each and every change you make.
|
||||
Development mode is also available. Let's see how you can use it.
|
||||
|
||||
In the previous Nix expression the source was fetched from an url. We can also refer to a local source instead using
|
||||
`src = ./path/to/source/tree;`
|
||||
In the previous Nix expression the source was fetched from an url. We can also
|
||||
refer to a local source instead using `src = ./path/to/source/tree;`
|
||||
|
||||
If we create a `shell.nix` file which calls `buildPythonPackage`, and if `src`
|
||||
is a local source, and if the local source has a `setup.py`, then development
|
||||
mode is activated.
|
||||
|
||||
In the following example we create a simple environment that
|
||||
has a Python 3.5 version of our package in it, as well as its dependencies and
|
||||
other packages we like to have in the environment, all specified with `propagatedBuildInputs`.
|
||||
Indeed, we can just add any package we like to have in our environment to `propagatedBuildInputs`.
|
||||
In the following example we create a simple environment that has a Python 3.5
|
||||
version of our package in it, as well as its dependencies and other packages we
|
||||
like to have in the environment, all specified with `propagatedBuildInputs`.
|
||||
Indeed, we can just add any package we like to have in our environment to
|
||||
`propagatedBuildInputs`.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
|
@ -427,7 +452,8 @@ buildPythonPackage rec {
|
|||
}
|
||||
```
|
||||
|
||||
It is important to note that due to how development mode is implemented on Nix it is not possible to have multiple packages simultaneously in development mode.
|
||||
It is important to note that due to how development mode is implemented on Nix
|
||||
it is not possible to have multiple packages simultaneously in development mode.
|
||||
|
||||
|
||||
### Organising your packages
|
||||
|
|
@ -497,13 +523,13 @@ and in this case the `python35` interpreter is automatically used.
|
|||
### Interpreters
|
||||
|
||||
Versions 2.7, 3.5, 3.6, 3.7 and 3.8 of the CPython interpreter are available as
|
||||
respectively `python27`, `python35`, `python36`, `python37` and `python38`. The aliases
|
||||
`python2` and `python3` correspond to respectively `python27` and
|
||||
respectively `python27`, `python35`, `python36`, `python37` and `python38`. The
|
||||
aliases `python2` and `python3` correspond to respectively `python27` and
|
||||
`python37`. The default interpreter, `python`, maps to `python2`. The PyPy
|
||||
interpreters compatible with Python 2.7 and 3 are available as `pypy27` and
|
||||
`pypy3`, with aliases `pypy2` mapping to `pypy27` and `pypy` mapping to
|
||||
`pypy2`. The Nix expressions for the interpreters can be
|
||||
found in `pkgs/development/interpreters/python`.
|
||||
`pypy3`, with aliases `pypy2` mapping to `pypy27` and `pypy` mapping to `pypy2`.
|
||||
The Nix expressions for the interpreters can be found in
|
||||
`pkgs/development/interpreters/python`.
|
||||
|
||||
All packages depending on any Python interpreter get appended
|
||||
`out/{python.sitePackages}` to `$PYTHONPATH` if such directory
|
||||
|
|
@ -532,9 +558,10 @@ Python libraries and applications that use `setuptools` or
|
|||
`buildPythonApplication` functions. These two functions also support installing a `wheel`.
|
||||
|
||||
All Python packages reside in `pkgs/top-level/python-packages.nix` and all
|
||||
applications elsewhere. In case a package is used as both a library and an application,
|
||||
then the package should be in `pkgs/top-level/python-packages.nix` since only those packages are made
|
||||
available for all interpreter versions. The preferred location for library expressions is in
|
||||
applications elsewhere. In case a package is used as both a library and an
|
||||
application, then the package should be in `pkgs/top-level/python-packages.nix`
|
||||
since only those packages are made available for all interpreter versions. The
|
||||
preferred location for library expressions is in
|
||||
`pkgs/development/python-modules`. It is important that these packages are
|
||||
called from `pkgs/top-level/python-packages.nix` and not elsewhere, to guarantee
|
||||
the right version of the package is built.
|
||||
|
|
@ -562,6 +589,7 @@ The `buildPythonPackage` function is implemented in
|
|||
using setup hooks.
|
||||
|
||||
The following is an example:
|
||||
|
||||
```nix
|
||||
{ lib, buildPythonPackage, fetchPypi, hypothesis, setuptools_scm, attrs, py, setuptools, six, pluggy }:
|
||||
|
||||
|
|
@ -608,38 +636,67 @@ as the interpreter unless overridden otherwise.
|
|||
|
||||
##### `buildPythonPackage` parameters
|
||||
|
||||
All parameters from `stdenv.mkDerivation` function are still supported. The following are specific to `buildPythonPackage`:
|
||||
All parameters from `stdenv.mkDerivation` function are still supported. The
|
||||
following are specific to `buildPythonPackage`:
|
||||
|
||||
* `catchConflicts ? true`: If `true`, abort package build if a package name appears more than once in dependency tree. Default is `true`.
|
||||
* `disabled` ? false: If `true`, package is not built for the particular Python interpreter version.
|
||||
* `catchConflicts ? true`: If `true`, abort package build if a package name
|
||||
appears more than once in dependency tree. Default is `true`.
|
||||
* `disabled` ? false: If `true`, package is not built for the particular Python
|
||||
interpreter version.
|
||||
* `dontWrapPythonPrograms ? false`: Skip wrapping of python programs.
|
||||
* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped programs.
|
||||
* `installFlags ? []`: A list of strings. Arguments to be passed to `pip install`. To pass options to `python setup.py install`, use `--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`.
|
||||
* `format ? "setuptools"`: Format of the source. Valid options are `"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`. `"setuptools"` is for when the source has a `setup.py` and `setuptools` is used to build a wheel, `flit`, in case `flit` should be used to build a wheel, and `wheel` in case a wheel is provided. Use `other` when a custom `buildPhase` and/or `installPhase` is needed.
|
||||
* `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to `makeWrapper`, which wraps generated binaries. By default, the arguments to `makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling the binary. Additional arguments here can allow a developer to set environment variables which will be available when the binary is run. For example, `makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
|
||||
* `namePrefix`: Prepends text to `${name}` parameter. In case of libraries, this defaults to `"python3.5-"` for Python 3.5, etc., and in case of applications to `""`.
|
||||
* `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
|
||||
* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment
|
||||
variable in wrapped programs.
|
||||
* `installFlags ? []`: A list of strings. Arguments to be passed to `pip
|
||||
install`. To pass options to `python setup.py install`, use
|
||||
`--install-option`. E.g., `installFlags=["--install-option='--cpp_implementation'"]`.
|
||||
* `format ? "setuptools"`: Format of the source. Valid options are
|
||||
`"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`.
|
||||
`"setuptools"` is for when the source has a `setup.py` and `setuptools` is
|
||||
used to build a wheel, `flit`, in case `flit` should be used to build a wheel,
|
||||
and `wheel` in case a wheel is provided. Use `other` when a custom
|
||||
`buildPhase` and/or `installPhase` is needed.
|
||||
* `makeWrapperArgs ? []`: A list of strings. Arguments to be passed to
|
||||
`makeWrapper`, which wraps generated binaries. By default, the arguments to
|
||||
`makeWrapper` set `PATH` and `PYTHONPATH` environment variables before calling
|
||||
the binary. Additional arguments here can allow a developer to set environment
|
||||
variables which will be available when the binary is run. For example,
|
||||
`makeWrapperArgs = ["--set FOO BAR" "--set BAZ QUX"]`.
|
||||
* `namePrefix`: Prepends text to `${name}` parameter. In case of libraries, this
|
||||
defaults to `"python3.5-"` for Python 3.5, etc., and in case of applications
|
||||
to `""`.
|
||||
* `pythonPath ? []`: List of packages to be added into `$PYTHONPATH`. Packages
|
||||
in `pythonPath` are not propagated (contrary to `propagatedBuildInputs`).
|
||||
* `preShellHook`: Hook to execute commands before `shellHook`.
|
||||
* `postShellHook`: Hook to execute commands after `shellHook`.
|
||||
* `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only created when the filenames end with `.py`.
|
||||
* `removeBinByteCode ? true`: Remove bytecode from `/bin`. Bytecode is only
|
||||
created when the filenames end with `.py`.
|
||||
* `setupPyGlobalFlags ? []`: List of flags passed to `setup.py` command.
|
||||
* `setupPyBuildFlags ? []`: List of flags passed to `setup.py build_ext` command.
|
||||
|
||||
The `stdenv.mkDerivation` function accepts various parameters for describing build inputs (see "Specifying dependencies"). The following are of special
|
||||
interest for Python packages, either because these are primarily used, or because their behaviour is different:
|
||||
The `stdenv.mkDerivation` function accepts various parameters for describing
|
||||
build inputs (see "Specifying dependencies"). The following are of special
|
||||
interest for Python packages, either because these are primarily used, or
|
||||
because their behaviour is different:
|
||||
|
||||
* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables as well as the items listed in `setup_requires`.
|
||||
* `buildInputs ? []`: Build and/or run-time dependencies that need to be be compiled for the host machine. Typically non-Python libraries which are being linked.
|
||||
* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These are added to `nativeBuildInputs` when `doCheck = true`. Items listed in `tests_require` go here.
|
||||
* `propagatedBuildInputs ? []`: Aside from propagating dependencies, `buildPythonPackage` also injects code into and wraps executables with the paths included in this list. Items listed in `install_requires` go here.
|
||||
* `nativeBuildInputs ? []`: Build-time only dependencies. Typically executables
|
||||
as well as the items listed in `setup_requires`.
|
||||
* `buildInputs ? []`: Build and/or run-time dependencies that need to be be
|
||||
compiled for the host machine. Typically non-Python libraries which are being
|
||||
linked.
|
||||
* `checkInputs ? []`: Dependencies needed for running the `checkPhase`. These
|
||||
are added to `nativeBuildInputs` when `doCheck = true`. Items listed in
|
||||
`tests_require` go here.
|
||||
* `propagatedBuildInputs ? []`: Aside from propagating dependencies,
|
||||
`buildPythonPackage` also injects code into and wraps executables with the
|
||||
paths included in this list. Items listed in `install_requires` go here.
|
||||
|
||||
##### Overriding Python packages
|
||||
|
||||
The `buildPythonPackage` function has a `overridePythonAttrs` method that
|
||||
can be used to override the package. In the following example we create an
|
||||
environment where we have the `blaze` package using an older version of `pandas`.
|
||||
We override first the Python interpreter and pass
|
||||
`packageOverrides` which contains the overrides for packages in the package set.
|
||||
The `buildPythonPackage` function has a `overridePythonAttrs` method that can be
|
||||
used to override the package. In the following example we create an environment
|
||||
where we have the `blaze` package using an older version of `pandas`. We
|
||||
override first the Python interpreter and pass `packageOverrides` which contains
|
||||
the overrides for packages in the package set.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
|
@ -725,15 +782,18 @@ youtube-dl = with pythonPackages; toPythonApplication youtube-dl;
|
|||
#### `toPythonModule` function
|
||||
|
||||
In some cases, such as bindings, a package is created using
|
||||
`stdenv.mkDerivation` and added as attribute in `all-packages.nix`.
|
||||
The Python bindings should be made available from `python-packages.nix`.
|
||||
The `toPythonModule` function takes a derivation and makes certain Python-specific modifications.
|
||||
`stdenv.mkDerivation` and added as attribute in `all-packages.nix`. The Python
|
||||
bindings should be made available from `python-packages.nix`. The
|
||||
`toPythonModule` function takes a derivation and makes certain Python-specific
|
||||
modifications.
|
||||
|
||||
```nix
|
||||
opencv = toPythonModule (pkgs.opencv.override {
|
||||
enablePython = true;
|
||||
pythonPackages = self;
|
||||
});
|
||||
```
|
||||
|
||||
Do pay attention to passing in the right Python version!
|
||||
|
||||
#### `python.buildEnv` function
|
||||
|
|
@ -741,6 +801,7 @@ Do pay attention to passing in the right Python version!
|
|||
Python environments can be created using the low-level `pkgs.buildEnv` function.
|
||||
This example shows how to create an environment that has the Pyramid Web Framework.
|
||||
Saving the following as `default.nix`
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
|
|
@ -751,6 +812,7 @@ python.buildEnv.override {
|
|||
```
|
||||
|
||||
and running `nix-build` will create
|
||||
|
||||
```
|
||||
/nix/store/cf1xhjwzmdki7fasgr4kz6di72ykicl5-python-2.7.8-env
|
||||
```
|
||||
|
|
@ -760,6 +822,7 @@ with wrapped binaries in `bin/`.
|
|||
You can also use the `env` attribute to create local environments with needed
|
||||
packages installed. This is somewhat comparable to `virtualenv`. For example,
|
||||
running `nix-shell` with the following `shell.nix`
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
|
|
@ -777,7 +840,8 @@ specified packages in its path.
|
|||
* `extraLibs`: List of packages installed inside the environment.
|
||||
* `postBuild`: Shell command executed after the build of environment.
|
||||
* `ignoreCollisions`: Ignore file collisions inside the environment (default is `false`).
|
||||
* `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in wrapped binaries in the environment.
|
||||
* `permitUserSite`: Skip setting the `PYTHONNOUSERSITE` environment variable in
|
||||
wrapped binaries in the environment.
|
||||
|
||||
#### `python.withPackages` function
|
||||
|
||||
|
|
@ -785,15 +849,17 @@ The `python.withPackages` function provides a simpler interface to the `python.b
|
|||
It takes a function as an argument that is passed the set of python packages and returns the list
|
||||
of the packages to be included in the environment. Using the `withPackages` function, the previous
|
||||
example for the Pyramid Web Framework environment can be written like this:
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
python.withPackages (ps: [ps.pyramid])
|
||||
```
|
||||
|
||||
`withPackages` passes the correct package set for the specific interpreter version as an
|
||||
argument to the function. In the above example, `ps` equals `pythonPackages`.
|
||||
But you can also easily switch to using python3:
|
||||
`withPackages` passes the correct package set for the specific interpreter
|
||||
version as an argument to the function. In the above example, `ps` equals
|
||||
`pythonPackages`. But you can also easily switch to using python3:
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
|
|
@ -802,30 +868,35 @@ python3.withPackages (ps: [ps.pyramid])
|
|||
|
||||
Now, `ps` is set to `python3Packages`, matching the version of the interpreter.
|
||||
|
||||
As `python.withPackages` simply uses `python.buildEnv` under the hood, it also supports the `env`
|
||||
attribute. The `shell.nix` file from the previous section can thus be also written like this:
|
||||
As `python.withPackages` simply uses `python.buildEnv` under the hood, it also
|
||||
supports the `env` attribute. The `shell.nix` file from the previous section can
|
||||
thus be also written like this:
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
(python36.withPackages (ps: [ps.numpy ps.requests])).env
|
||||
```
|
||||
|
||||
In contrast to `python.buildEnv`, `python.withPackages` does not support the more advanced options
|
||||
such as `ignoreCollisions = true` or `postBuild`. If you need them, you have to use `python.buildEnv`.
|
||||
In contrast to `python.buildEnv`, `python.withPackages` does not support the
|
||||
more advanced options such as `ignoreCollisions = true` or `postBuild`. If you
|
||||
need them, you have to use `python.buildEnv`.
|
||||
|
||||
Python 2 namespace packages may provide `__init__.py` that collide. In that case `python.buildEnv`
|
||||
should be used with `ignoreCollisions = true`.
|
||||
Python 2 namespace packages may provide `__init__.py` that collide. In that case
|
||||
`python.buildEnv` should be used with `ignoreCollisions = true`.
|
||||
|
||||
#### Setup hooks
|
||||
|
||||
The following are setup hooks specifically for Python packages. Most of these are
|
||||
used in `buildPythonPackage`.
|
||||
The following are setup hooks specifically for Python packages. Most of these
|
||||
are used in `buildPythonPackage`.
|
||||
|
||||
- `eggUnpackhook` to move an egg to the correct folder so it can be installed with the `eggInstallHook`
|
||||
- `eggUnpackhook` to move an egg to the correct folder so it can be installed
|
||||
with the `eggInstallHook`
|
||||
- `eggBuildHook` to skip building for eggs.
|
||||
- `eggInstallHook` to install eggs.
|
||||
- `flitBuildHook` to build a wheel using `flit`.
|
||||
- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system (e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
|
||||
- `pipBuildHook` to build a wheel using `pip` and PEP 517. Note a build system
|
||||
(e.g. `setuptools` or `flit`) should still be added as `nativeBuildInput`.
|
||||
- `pipInstallHook` to install wheels.
|
||||
- `pytestCheckHook` to run tests with `pytest`.
|
||||
- `pythonCatchConflictsHook` to check whether a Python package is not already existing.
|
||||
|
|
@ -833,8 +904,10 @@ used in `buildPythonPackage`.
|
|||
- `pythonRemoveBinBytecode` to remove bytecode from the `/bin` folder.
|
||||
- `setuptoolsBuildHook` to build a wheel using `setuptools`.
|
||||
- `setuptoolsCheckHook` to run tests with `python setup.py test`.
|
||||
- `venvShellHook` to source a Python 3 `venv` at the `venvDir` location. A `venv` is created if it does not yet exist.
|
||||
- `wheelUnpackHook` to move a wheel to the correct folder so it can be installed with the `pipInstallHook`.
|
||||
- `venvShellHook` to source a Python 3 `venv` at the `venvDir` location. A
|
||||
`venv` is created if it does not yet exist.
|
||||
- `wheelUnpackHook` to move a wheel to the correct folder so it can be installed
|
||||
with the `pipInstallHook`.
|
||||
|
||||
### Development mode
|
||||
|
||||
|
|
@ -856,11 +929,11 @@ pythonPackages.buildPythonPackage {
|
|||
}
|
||||
```
|
||||
|
||||
Running `nix-shell` with no arguments should give you
|
||||
the environment in which the package would be built with
|
||||
`nix-build`.
|
||||
Running `nix-shell` with no arguments should give you the environment in which
|
||||
the package would be built with `nix-build`.
|
||||
|
||||
Shortcut to setup environments with C headers/libraries and python packages:
|
||||
|
||||
```shell
|
||||
nix-shell -p pythonPackages.pyramid zlib libjpeg git
|
||||
```
|
||||
|
|
@ -872,19 +945,22 @@ Note: There is a boolean value `lib.inNixShell` set to `true` if nix-shell is in
|
|||
Packages inside nixpkgs are written by hand. However many tools exist in
|
||||
community to help save time. No tool is preferred at the moment.
|
||||
|
||||
- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix expressions for your Python project. Note that [sharing derivations from pypi2nix with nixpkgs is possible but not encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376).
|
||||
- [pypi2nix](https://github.com/nix-community/pypi2nix): Generate Nix
|
||||
expressions for your Python project. Note that [sharing derivations from
|
||||
pypi2nix with nixpkgs is possible but not
|
||||
encouraged](https://github.com/nix-community/pypi2nix/issues/222#issuecomment-443497376).
|
||||
- [python2nix](https://github.com/proger/python2nix) by Vladimir Kirillov.
|
||||
|
||||
### Deterministic builds
|
||||
|
||||
The Python interpreters are now built deterministically.
|
||||
Minor modifications had to be made to the interpreters in order to generate
|
||||
deterministic bytecode. This has security implications and is relevant for
|
||||
those using Python in a `nix-shell`.
|
||||
The Python interpreters are now built deterministically. Minor modifications had
|
||||
to be made to the interpreters in order to generate deterministic bytecode. This
|
||||
has security implications and is relevant for those using Python in a
|
||||
`nix-shell`.
|
||||
|
||||
When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will have timestamp 1.
|
||||
The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1` and
|
||||
[PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
|
||||
When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will
|
||||
have timestamp 1. The `buildPythonPackage` function sets `DETERMINISTIC_BUILD=1`
|
||||
and [PYTHONHASHSEED=0](https://docs.python.org/3.5/using/cmdline.html#envvar-PYTHONHASHSEED).
|
||||
Both are also exported in `nix-shell`.
|
||||
|
||||
|
||||
|
|
@ -899,9 +975,10 @@ example of such a situation is when `py.test` is used.
|
|||
|
||||
#### Common issues
|
||||
|
||||
- Non-working tests can often be deselected. By default `buildPythonPackage` runs `python setup.py test`.
|
||||
Most python modules follows the standard test protocol where the pytest runner can be used instead.
|
||||
`py.test` supports a `-k` parameter to ignore test methods or classes:
|
||||
* Non-working tests can often be deselected. By default `buildPythonPackage`
|
||||
runs `python setup.py test`. Most python modules follows the standard test
|
||||
protocol where the pytest runner can be used instead. `py.test` supports a
|
||||
`-k` parameter to ignore test methods or classes:
|
||||
|
||||
```nix
|
||||
buildPythonPackage {
|
||||
|
|
@ -913,7 +990,8 @@ example of such a situation is when `py.test` is used.
|
|||
'';
|
||||
}
|
||||
```
|
||||
- Tests that attempt to access `$HOME` can be fixed by using the following work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
|
||||
* Tests that attempt to access `$HOME` can be fixed by using the following
|
||||
work-around before running tests (e.g. `preCheck`): `export HOME=$(mktemp -d)`
|
||||
|
||||
## FAQ
|
||||
|
||||
|
|
@ -925,8 +1003,9 @@ should also be done when packaging `A`.
|
|||
|
||||
### How to override a Python package?
|
||||
|
||||
We can override the interpreter and pass `packageOverrides`.
|
||||
In the following example we rename the `pandas` package and build it.
|
||||
We can override the interpreter and pass `packageOverrides`. In the following
|
||||
example we rename the `pandas` package and build it.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
||||
|
|
@ -939,14 +1018,16 @@ with import <nixpkgs> {};
|
|||
|
||||
in python.withPackages(ps: [ps.pandas])).env
|
||||
```
|
||||
|
||||
Using `nix-build` on this expression will build an environment that contains the
|
||||
package `pandas` but with the new name `foo`.
|
||||
|
||||
All packages in the package set will use the renamed package.
|
||||
A typical use case is to switch to another version of a certain package.
|
||||
For example, in the Nixpkgs repository we have multiple versions of `django` and `scipy`.
|
||||
In the following example we use a different version of `scipy` and create an environment that uses it.
|
||||
All packages in the Python package set will now use the updated `scipy` version.
|
||||
All packages in the package set will use the renamed package. A typical use case
|
||||
is to switch to another version of a certain package. For example, in the
|
||||
Nixpkgs repository we have multiple versions of `django` and `scipy`. In the
|
||||
following example we use a different version of `scipy` and create an
|
||||
environment that uses it. All packages in the Python package set will now use
|
||||
the updated `scipy` version.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> {};
|
||||
|
|
@ -958,10 +1039,13 @@ with import <nixpkgs> {};
|
|||
in (pkgs.python35.override {inherit packageOverrides;}).withPackages (ps: [ps.blaze])
|
||||
).env
|
||||
```
|
||||
|
||||
The requested package `blaze` depends on `pandas` which itself depends on `scipy`.
|
||||
|
||||
If you want the whole of Nixpkgs to use your modifications, then you can use `overlays`
|
||||
as explained in this manual. In the following example we build a `inkscape` using a different version of `numpy`.
|
||||
If you want the whole of Nixpkgs to use your modifications, then you can use
|
||||
`overlays` as explained in this manual. In the following example we build a
|
||||
`inkscape` using a different version of `numpy`.
|
||||
|
||||
```nix
|
||||
let
|
||||
pkgs = import <nixpkgs> {};
|
||||
|
|
@ -982,19 +1066,28 @@ Executing `python setup.py bdist_wheel` in a `nix-shell `fails with
|
|||
ValueError: ZIP does not support timestamps before 1980
|
||||
```
|
||||
|
||||
This is because files from the Nix store (which have a timestamp of the UNIX epoch of January 1, 1970) are included in the .ZIP, but .ZIP archives follow the DOS convention of counting timestamps from 1980.
|
||||
This is because files from the Nix store (which have a timestamp of the UNIX
|
||||
epoch of January 1, 1970) are included in the .ZIP, but .ZIP archives follow the
|
||||
DOS convention of counting timestamps from 1980.
|
||||
|
||||
The command `bdist_wheel` reads the `SOURCE_DATE_EPOCH` environment variable, which `nix-shell` sets to 1. Unsetting this variable or giving it a value corresponding to 1980 or later enables building wheels.
|
||||
The command `bdist_wheel` reads the `SOURCE_DATE_EPOCH` environment variable,
|
||||
which `nix-shell` sets to 1. Unsetting this variable or giving it a value
|
||||
corresponding to 1980 or later enables building wheels.
|
||||
|
||||
Use 1980 as timestamp:
|
||||
|
||||
```shell
|
||||
nix-shell --run "SOURCE_DATE_EPOCH=315532800 python3 setup.py bdist_wheel"
|
||||
```
|
||||
|
||||
or the current time:
|
||||
|
||||
```shell
|
||||
nix-shell --run "SOURCE_DATE_EPOCH=$(date +%s) python3 setup.py bdist_wheel"
|
||||
```
|
||||
|
||||
or unset `SOURCE_DATE_EPOCH`:
|
||||
|
||||
```shell
|
||||
nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
|
||||
```
|
||||
|
|
@ -1002,13 +1095,18 @@ nix-shell --run "unset SOURCE_DATE_EPOCH; python3 setup.py bdist_wheel"
|
|||
### `install_data` / `data_files` problems
|
||||
|
||||
If you get the following error:
|
||||
|
||||
```
|
||||
could not create '/nix/store/6l1bvljpy8gazlsw2aw9skwwp4pmvyxw-python-2.7.8/etc':
|
||||
Permission denied
|
||||
```
|
||||
This is a [known bug](https://github.com/pypa/setuptools/issues/130) in `setuptools`.
|
||||
Setuptools `install_data` does not respect `--prefix`. An example of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
|
||||
|
||||
This is a [known bug](https://github.com/pypa/setuptools/issues/130) in
|
||||
`setuptools`. Setuptools `install_data` does not respect `--prefix`. An example
|
||||
of such package using the feature is `pkgs/tools/X11/xpra/default.nix`.
|
||||
|
||||
As workaround install it as an extra `preInstall` step:
|
||||
|
||||
```shell
|
||||
${python.interpreter} setup.py install_data --install-dir=$out --root=$out
|
||||
sed -i '/ = data\_files/d' setup.py
|
||||
|
|
@ -1031,13 +1129,16 @@ function.
|
|||
|
||||
### How to consume python modules using pip in a virtual environment like I am used to on other Operating Systems?
|
||||
|
||||
While this approach is not very idiomatic from Nix perspective, it can still be useful when dealing with pre-existing
|
||||
projects or in situations where it's not feasible or desired to write derivations for all required dependencies.
|
||||
While this approach is not very idiomatic from Nix perspective, it can still be
|
||||
useful when dealing with pre-existing projects or in situations where it's not
|
||||
feasible or desired to write derivations for all required dependencies.
|
||||
|
||||
This is an example of a `default.nix` for a `nix-shell`, which allows to consume a virtual environment created by `venv`,
|
||||
and install python modules through `pip` the traditional way.
|
||||
This is an example of a `default.nix` for a `nix-shell`, which allows to consume
|
||||
a virtual environment created by `venv`, and install python modules through
|
||||
`pip` the traditional way.
|
||||
|
||||
Create this `default.nix` file, together with a `requirements.txt` and simply execute `nix-shell`.
|
||||
Create this `default.nix` file, together with a `requirements.txt` and simply
|
||||
execute `nix-shell`.
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> { };
|
||||
|
|
@ -1082,8 +1183,9 @@ in pkgs.mkShell rec {
|
|||
}
|
||||
```
|
||||
|
||||
In case the supplied venvShellHook is insufficient, or when python 2 support is needed,
|
||||
you can define your own shell hook and adapt to your needs like in the following example:
|
||||
In case the supplied venvShellHook is insufficient, or when python 2 support is
|
||||
needed, you can define your own shell hook and adapt to your needs like in the
|
||||
following example:
|
||||
|
||||
```nix
|
||||
with import <nixpkgs> { };
|
||||
|
|
@ -1152,11 +1254,11 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul
|
|||
```
|
||||
|
||||
`pythonPackages.zerobin` is now globally overridden. All packages and also the
|
||||
`zerobin` NixOS service use the new definition.
|
||||
Note that `python-super` refers to the old package set and `python-self`
|
||||
to the new, overridden version.
|
||||
`zerobin` NixOS service use the new definition. Note that `python-super` refers
|
||||
to the old package set and `python-self` to the new, overridden version.
|
||||
|
||||
To modify only a Python package set instead of a whole Python derivation, use this snippet:
|
||||
To modify only a Python package set instead of a whole Python derivation, use
|
||||
this snippet:
|
||||
|
||||
```nix
|
||||
myPythonPackages = pythonPackages.override {
|
||||
|
|
@ -1188,11 +1290,12 @@ self: super: {
|
|||
|
||||
### How to use Intel's MKL with numpy and scipy?
|
||||
|
||||
A `site.cfg` is created that configures BLAS based on the `blas` parameter
|
||||
of the `numpy` derivation. By passing in `mkl`, `numpy` and packages depending
|
||||
on `numpy` will be built with `mkl`.
|
||||
A `site.cfg` is created that configures BLAS based on the `blas` parameter of
|
||||
the `numpy` derivation. By passing in `mkl`, `numpy` and packages depending on
|
||||
`numpy` will be built with `mkl`.
|
||||
|
||||
The following is an overlay that configures `numpy` to use `mkl`:
|
||||
|
||||
```nix
|
||||
self: super: {
|
||||
python37 = super.python37.override {
|
||||
|
|
@ -1228,10 +1331,21 @@ In a `setup.py` or `setup.cfg` it is common to declare dependencies:
|
|||
|
||||
Following rules are desired to be respected:
|
||||
|
||||
* Python libraries are called from `python-packages.nix` and packaged with `buildPythonPackage`. The expression of a library should be in `pkgs/development/python-modules/<name>/default.nix`. Libraries in `pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid merge conflicts.
|
||||
* Python applications live outside of `python-packages.nix` and are packaged with `buildPythonApplication`.
|
||||
* Python libraries are called from `python-packages.nix` and packaged with
|
||||
`buildPythonPackage`. The expression of a library should be in
|
||||
`pkgs/development/python-modules/<name>/default.nix`. Libraries in
|
||||
`pkgs/top-level/python-packages.nix` are sorted quasi-alphabetically to avoid
|
||||
merge conflicts.
|
||||
* Python applications live outside of `python-packages.nix` and are packaged
|
||||
with `buildPythonApplication`.
|
||||
* Make sure libraries build for all Python interpreters.
|
||||
* By default we enable tests. Make sure the tests are found and, in the case of libraries, are passing for all interpreters. If certain tests fail they can be disabled individually. Try to avoid disabling the tests altogether. In any case, when you disable tests, leave a comment explaining why.
|
||||
* Commit names of Python libraries should reflect that they are Python libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
|
||||
* Attribute names in `python-packages.nix` should be normalized according to [PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names).
|
||||
This means that characters should be converted to lowercase and `.` and `_` should be replaced by a single `-` (foo-bar-baz instead of Foo__Bar.baz )
|
||||
* By default we enable tests. Make sure the tests are found and, in the case of
|
||||
libraries, are passing for all interpreters. If certain tests fail they can be
|
||||
disabled individually. Try to avoid disabling the tests altogether. In any
|
||||
case, when you disable tests, leave a comment explaining why.
|
||||
* Commit names of Python libraries should reflect that they are Python
|
||||
libraries, so write for example `pythonPackages.numpy: 1.11 -> 1.12`.
|
||||
* Attribute names in `python-packages.nix` should be normalized according to
|
||||
[PEP 0503](https://www.python.org/dev/peps/pep-0503/#normalized-names). This
|
||||
means that characters should be converted to lowercase and `.` and `_` should
|
||||
be replaced by a single `-` (foo-bar-baz instead of Foo__Bar.baz )
|
||||
|
|
|
|||
Loading…
Reference in a new issue