alioth/nixpkgs
3
0
Fork 0
forked from mirrors/nixpkgs
Code Releases 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.
```nix
{ # ...
{ lib, buildPythonPackage, fetchPypi }:
toolz = buildPythonPackage rec {
pname = "toolz";
@ -199,8 +199,8 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
doCheck = false;
meta = {
homepage = "https://github.com/pytoolz/toolz/";
meta = with lib; {
homepage = https://github.com/pytoolz/toolz;
description = "List processing tools and functional utilities";
license = licenses.bsd3;
maintainers = with maintainers; [ fridh ];
@ -267,12 +267,13 @@ that we introduced with the `let` expression.
#### Handling dependencies
Our example, `toolz`, does not have any dependencies on other Python
packages or system libraries. According to the manual, `buildPythonPackage`
uses the arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If something is
exclusively a build-time dependency, then the dependency should be included as a
`buildInput`, but if it is (also) a runtime dependency, then it should be added
to `propagatedBuildInputs`. Test dependencies are considered build-time dependencies.
Our example, `toolz`, does not have any dependencies on other Python packages or
system libraries. According to the manual, `buildPythonPackage` uses the
arguments `buildInputs` and `propagatedBuildInputs` to specify dependencies. If
something is exclusively a build-time dependency, then the dependency should be
included as a `buildInput`, but if it is (also) a runtime dependency, then it
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
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 ];
propagatedBuildInputs = with self; [ numpy multipledispatch dateutil ];
meta = {
meta = with lib; {
homepage = https://github.com/ContinuumIO/datashape;
description = "A data description language";
license = licenses.bsd2;
@ -326,7 +327,7 @@ when building the bindings and are therefore added as `buildInputs`.
buildInputs = with self; [ pkgs.libxml2 pkgs.libxslt ];
meta = {
meta = with lib; {
description = "Pythonic binding for the libxml2 and libxslt libraries";
homepage = https://lxml.de;
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"
'';
meta = {
meta = with lib; {
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 ];
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`,
and in this case the `python35` interpreter is automatically used.
## Reference
### Interpreters
@ -549,31 +548,31 @@ The `buildPythonPackage` function is implemented in
The following is an example:
```nix
{ lib, buildPythonPackage, fetchPypi, hypothesis, setuptools_scm, attrs, py, setuptools, six, pluggy }:
buildPythonPackage rec {
version = "3.3.1";
pname = "pytest";
preCheck = ''
# don't test bash builtins
rm testing/test_argcomplete.py
'';
version = "3.3.1";
src = fetchPypi {
inherit pname version;
sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93";
};
preCheck = ''
# don't test bash builtins
rm testing/test_argcomplete.py
'';
checkInputs = [ hypothesis ];
buildInputs = [ setuptools_scm ];
propagatedBuildInputs = [ attrs py setuptools six pluggy ];
meta = with stdenv.lib; {
meta = with lib; {
maintainers = with maintainers; [ domenkozar lovek323 madjar lsix ];
description = "Framework for writing tests";
};
}
```
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
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
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
'';
meta = {
homepage = https://github.com/pytoolz/toolz/;
meta = with lib; {
homepage = https://github.com/pytoolz/toolz;
description = "List processing tools and functional utilities";
license = lib.licenses.bsd3;
maintainers = with lib.maintainers; [ fridh ];
license = licenses.bsd3;
maintainers = with maintainers; [ fridh ];
};
}