b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

python: update documentation

Browse source 
This touches up a handful of places in the python documentation to try to make
the current best-practices more obvious. In particular, I often find the
function signatures (what to pass, what not to pass) confusing and have added
them to the docs.

Also updated the metas to be more consistent with the most frequently used
modern style.
This commit is contained in:
Benjamin Hipple 2018-10-09 20:42:29 -04:00 committed by Frederik Rietdijk
parent 9cba2f54fa
commit c0af13f1c8
2 changed files with 29 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
doc/languages-frameworks/python.section.md
View file

@ -186,7 +186,7 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
`toolz` package. `toolz` package.
```nix ```nix
{ # ... { lib, buildPythonPackage, fetchPypi }:
toolz = buildPythonPackage rec { toolz = buildPythonPackage rec {
pname = "toolz"; pname = "toolz";
@ -199,8 +199,8 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
doCheck = false; doCheck = false;
meta = { meta = with lib; {
homepage = "https://github.com/pytoolz/toolz/"; homepage = https://github.com/pytoolz/toolz;
description = "List processing tools and functional utilities"; description = "List processing tools and functional utilities";
license = licenses.bsd3; license = licenses.bsd3;
maintainers = with maintainers; [ fridh ]; maintainers = with maintainers; [ fridh ];
@ -267,12 +267,13 @@ that we introduced with the `let` expression.
#### Handling dependencies #### Handling dependencies
Our example, `toolz`, does not have any dependencies on other Python Our example, `toolz`, does not have any dependencies on other Python packages or
packages or system libraries. According to the manual, `buildPythonPackage` system libraries. According to the manual, `buildPythonPackage` uses the
uses the arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If something is arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If
exclusively a build-time dependency, then the dependency should be included as a something is exclusively a build-time dependency, then the dependency should be
`buildInput`, but if it is (also) a runtime dependency, then it should be added included as a `buildInput`, but if it is (also) a runtime dependency, then it
to `propagatedBuildInputs`. Test dependencies are considered build-time dependencies. should be added to `propagatedBuildInputs`. Test dependencies are considered
build-time dependencies and passed to `checkInputs`.
The following example shows which arguments are given to `buildPythonPackage` in The following example shows which arguments are given to `buildPythonPackage` in
order to build [`datashape`](https://github.com/blaze/datashape). order to build [`datashape`](https://github.com/blaze/datashape).
@ -292,7 +293,7 @@ order to build [`datashape`](https://github.com/blaze/datashape).
checkInputs = with self; [ pytest ]; checkInputs = with self; [ pytest ];
propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ]; propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
meta = { meta = with lib; {
homepage = https://github.com/ContinuumIO/datashape; homepage = https://github.com/ContinuumIO/datashape;
description = "A data description language"; description = "A data description language";
license = licenses.bsd2; license = licenses.bsd2;
@ -326,7 +327,7 @@ when building the bindings and are therefore added as `buildInputs`.
buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ]; buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
meta = { meta = with lib; {
description = "Pythonic binding for the libxml2 and libxslt libraries"; description = "Pythonic binding for the libxml2 and libxslt libraries";
homepage = https://lxml.de; homepage = https://lxml.de;
license = licenses.bsd3; license = licenses.bsd3;
@ -370,9 +371,9 @@ and `CFLAGS`.
export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include" export CFLAGS="-I${pkgs.fftw.dev}/include -I${pkgs.fftwFloat.dev}/include -I${pkgs.fftwLongDouble.dev}/include"
''; '';
meta = { meta = with lib; {
description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms"; description = "A pythonic wrapper around FFTW, the FFT library, presenting a unified interface for all the supported transforms";
homepage = http://hgomersall.github.com/pyFFTW/; homepage = http://hgomersall.github.com/pyFFTW;
license = with licenses; [ bsd2 bsd3 ]; license = with licenses; [ bsd2 bsd3 ];
maintainers = with maintainers; [ fridh ]; maintainers = with maintainers; [ fridh ];
}; };
@ -478,8 +479,6 @@ don't explicitly define which `python` derivation should be used. In the above
example we use `buildPythonPackage` that is part of the set `python35Packages`, example we use `buildPythonPackage` that is part of the set `python35Packages`,
and in this case the `python35` interpreter is automatically used. and in this case the `python35` interpreter is automatically used.
## Reference ## Reference
### Interpreters ### Interpreters
@ -549,31 +548,31 @@ The `buildPythonPackage` function is implemented in
The following is an example: The following is an example:
```nix ```nix
{ lib, buildPythonPackage, fetchPypi, hypothesis, setuptools_scm, attrs, py, setuptools, six, pluggy }:
buildPythonPackage rec { buildPythonPackage rec {
version = "3.3.1";
pname = "pytest"; pname = "pytest";
version = "3.3.1";
preCheck = ''
# don't test bash builtins
rm testing/test_argcomplete.py
'';
src = fetchPypi { src = fetchPypi {
inherit pname version; inherit pname version;
sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93"; sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93";
}; };
preCheck = ''
# don't test bash builtins
rm testing/test_argcomplete.py
'';
checkInputs = [ hypothesis ]; checkInputs = [ hypothesis ];
buildInputs = [ setuptools_scm ]; buildInputs = [ setuptools_scm ];
propagatedBuildInputs = [ attrs py setuptools six pluggy ]; propagatedBuildInputs = [ attrs py setuptools six pluggy ];
meta = with stdenv.lib; { meta = with lib; {
maintainers = with maintainers; [ domenkozar lovek323 madjar lsix ]; maintainers = with maintainers; [ domenkozar lovek323 madjar lsix ];
description = "Framework for writing tests"; description = "Framework for writing tests";
}; };
} }
``` ```
The `buildPythonPackage` mainly does four things: The `buildPythonPackage` mainly does four things:
@ -655,6 +654,9 @@ Another difference is that `buildPythonPackage` by default prefixes the names of
the packages with the version of the interpreter. Because this is irrelevant for the packages with the version of the interpreter. Because this is irrelevant for
applications, the prefix is omitted. applications, the prefix is omitted.
When packaging a python application with `buildPythonApplication`, it should be
invoked with `callPackage` and passed `python` or `pythonPackages`.
#### `toPythonApplication` function #### `toPythonApplication` function
A distinction is made between applications and libraries, however, sometimes a A distinction is made between applications and libraries, however, sometimes a

8
pkgs/development/python-modules/toolz/default.nix
View file

@ -21,10 +21,10 @@ buildPythonPackage rec{
nosetests toolz/tests nosetests toolz/tests
''; '';
meta = { meta = with lib; {
homepage = https://github.com/pytoolz/toolz/; homepage = https://github.com/pytoolz/toolz;
description = "List processing tools and functional utilities"; description = "List processing tools and functional utilities";
license = lib.licenses.bsd3; license = licenses.bsd3;
maintainers = with lib.maintainers; [ fridh ]; maintainers = with maintainers; [ fridh ];
}; };
} }