diff options
Diffstat (limited to 'doc/languages-frameworks/python.section.md')
| -rw-r--r-- | doc/languages-frameworks/python.section.md | 90 |
1 files changed, 65 insertions, 25 deletions
diff --git a/doc/languages-frameworks/python.section.md b/doc/languages-frameworks/python.section.md index 174686d24c6c..04303d741d67 100644 --- a/doc/languages-frameworks/python.section.md +++ b/doc/languages-frameworks/python.section.md @@ -254,17 +254,19 @@ The next example shows a non trivial overriding of the `blas` implementation to be used through out all of the Python package set: ```nix -python3MyBlas = pkgs.python3.override { - packageOverrides = self: super: { - # We need toPythonModule for the package set to evaluate this - blas = super.toPythonModule(super.pkgs.blas.override { - blasProvider = super.pkgs.mkl; - }); - lapack = super.toPythonModule(super.pkgs.lapack.override { - lapackProvider = super.pkgs.mkl; - }); +{ + python3MyBlas = pkgs.python3.override { + packageOverrides = self: super: { + # We need toPythonModule for the package set to evaluate this + blas = super.toPythonModule(super.pkgs.blas.override { + blasProvider = super.pkgs.mkl; + }); + lapack = super.toPythonModule(super.pkgs.lapack.override { + lapackProvider = super.pkgs.mkl; + }); + }; }; -}; +} ``` This is particularly useful for numpy and scipy users who want to gain speed with other blas implementations. @@ -322,7 +324,9 @@ python3Packages.buildPythonApplication rec { This is then added to `all-packages.nix` just as any other application would be. ```nix -luigi = callPackage ../applications/networking/cluster/luigi { }; +{ + luigi = callPackage ../applications/networking/cluster/luigi { }; +} ``` Since the package is an application, a consumer doesn't need to care about @@ -342,7 +346,9 @@ the attribute in `python-packages.nix`, and the `toPythonApplication` shall be applied to the reference: ```nix -youtube-dl = with python3Packages; toPythonApplication youtube-dl; +{ + youtube-dl = with python3Packages; toPythonApplication youtube-dl; +} ``` #### `toPythonModule` function {#topythonmodule-function} @@ -354,10 +360,12 @@ bindings should be made available from `python-packages.nix`. The modifications. ```nix -opencv = toPythonModule (pkgs.opencv.override { - enablePython = true; - pythonPackages = self; -}); +{ + opencv = toPythonModule (pkgs.opencv.override { + enablePython = true; + pythonPackages = self; + }); +} ``` Do pay attention to passing in the right Python version! @@ -1198,6 +1206,7 @@ Pytest is the most common test runner for python repositories. A trivial test run would be: ```nix +{ nativeCheckInputs = [ pytest ]; checkPhase = '' runHook preCheck @@ -1206,6 +1215,7 @@ test run would be: runHook postCheck ''; +} ``` However, many repositories' test suites do not translate well to nix's build @@ -1214,6 +1224,7 @@ sandbox, and will generally need many tests to be disabled. To filter tests using pytest, one can do the following: ```nix +{ nativeCheckInputs = [ pytest ]; # avoid tests which need additional data or touch network checkPhase = '' @@ -1223,6 +1234,7 @@ To filter tests using pytest, one can do the following: runHook postCheck ''; +} ``` `--ignore` will tell pytest to ignore that file or directory from being @@ -1249,6 +1261,7 @@ when a package may need many items disabled to run the test suite. Using the example above, the analogous `pytestCheckHook` usage would be: ```nix +{ nativeCheckInputs = [ pytestCheckHook ]; @@ -1268,12 +1281,14 @@ Using the example above, the analogous `pytestCheckHook` usage would be: disabledTestPaths = [ "tests/test_failing.py" ]; +} ``` This is especially useful when tests need to be conditionally disabled, for example: ```nix +{ disabledTests = [ # touches network "download" @@ -1285,6 +1300,7 @@ for example: # can fail when building with other packages "socket" ]; +} ``` Trying to concatenate the related strings to disable tests in a regular @@ -1299,19 +1315,23 @@ To help ensure the package still works, [`pythonImportsCheck`](#using-pythonimpo the listed modules. ```nix +{ pythonImportsCheck = [ "requests" "urllib" ]; +} ``` roughly translates to: ```nix +{ postCheck = '' PYTHONPATH=$out/${python.sitePackages}:$PYTHONPATH python -c "import requests; import urllib" ''; +} ``` However, this is done in its own phase, and not dependent on whether [`doCheck = true;`](#var-stdenv-doCheck). @@ -1343,6 +1363,7 @@ pkg3>=1.0,<=2.0 we can do: ```nix +{ nativeBuildInputs = [ pythonRelaxDepsHook ]; @@ -1353,6 +1374,7 @@ we can do: pythonRemoveDeps = [ "pkg2" ]; +} ``` which would result in the following `requirements.txt` file: @@ -1366,8 +1388,10 @@ Another option is to pass `true`, that will relax/remove all dependencies, for example: ```nix +{ nativeBuildInputs = [ pythonRelaxDepsHook ]; pythonRelaxDeps = true; +} ``` which would result in the following `requirements.txt` file: @@ -1393,6 +1417,7 @@ work with any of the [existing hooks](#setup-hooks). `unittestCheckHook` is a hook which will substitute the setuptools `test` command for a [`checkPhase`](#ssec-check-phase) which runs `python -m unittest discover`: ```nix +{ nativeCheckInputs = [ unittestCheckHook ]; @@ -1400,6 +1425,7 @@ work with any of the [existing hooks](#setup-hooks). unittestFlagsArray = [ "-s" "tests" "-v" ]; +} ``` #### Using sphinxHook {#using-sphinxhook} @@ -1410,6 +1436,7 @@ It is setup to automatically find common documentation source paths and render them using the default `html` style. ```nix +{ outputs = [ "out" "doc" @@ -1418,6 +1445,7 @@ render them using the default `html` style. nativeBuildInputs = [ sphinxHook ]; +} ``` The hook will automatically build and install the artifact into the @@ -1425,6 +1453,7 @@ The hook will automatically build and install the artifact into the for the artifacts of the `man` builder into the `man` target. ```nix +{ outputs = [ "out" "doc" @@ -1436,14 +1465,17 @@ for the artifacts of the `man` builder into the `man` target. "singlehtml" "man" ]; +} ``` Overwrite `sphinxRoot` when the hook is unable to find your documentation source root. ```nix +{ # Configure sphinxRoot for uncommon paths sphinxRoot = "weird/docs/path"; +} ``` The hook is also available to packages outside the python ecosystem by @@ -1827,6 +1859,7 @@ folder and not downloaded again. If you need to change a package's attribute(s) from `configuration.nix` you could do: ```nix +{ nixpkgs.config.packageOverrides = super: { python3 = super.python3.override { packageOverrides = python-self: python-super: { @@ -1841,6 +1874,7 @@ If you need to change a package's attribute(s) from `configuration.nix` you coul }; }; }; +} ``` `python3Packages.twisted` is now globally overridden. @@ -1853,11 +1887,13 @@ To modify only a Python package set instead of a whole Python derivation, use this snippet: ```nix +{ myPythonPackages = python3Packages.override { overrides = self: super: { - twisted = ...; + twisted = "..."; }; - } + }; +} ``` ### How to override a Python package using overlays? {#how-to-override-a-python-package-using-overlays} @@ -1893,7 +1929,7 @@ final: prev: { ( python-final: python-prev: { foo = python-prev.foo.overridePythonAttrs (oldAttrs: { - ... + # ... }); } ) @@ -1938,17 +1974,21 @@ Some packages define optional dependencies for additional features. With `extras-require`, while PEP 621 calls these `optional-dependencies`. ```nix -optional-dependencies = { - complete = [ distributed ]; -}; +{ + optional-dependencies = { + complete = [ distributed ]; + }; +} ``` and letting the package requiring the extra add the list to its dependencies ```nix -dependencies = [ - ... -] ++ dask.optional-dependencies.complete; +{ + dependencies = [ + # ... + ] ++ dask.optional-dependencies.complete; +} ``` This method is using `passthru`, meaning that changing `optional-dependencies` of a package won't cause it to rebuild. |