doc/python: document `pyproject` and remove usages of `format` (39c64e23) · Commits · nix / nixpkgs

doc/languages-frameworks/python.section.md

+68 −18

Original line number	Diff line number	Diff line
		@@ -101,7 +101,7 @@ The following is an example:
		buildPythonPackage rec {
		pname = "pytest";
		version = "3.3.1";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		@@ -167,12 +167,15 @@ following are specific to `buildPythonPackage`:
		* `dontWrapPythonPrograms ? false`: Skip wrapping of Python programs.
		* `permitUserSite ? false`: Skip setting the `PYTHONNOUSERSITE` environment
		variable in wrapped programs.
		* `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.
		* `pyproject`: Whether the pyproject format should be used. When set to `true`,
		`pypaBuildHook` will be used, and you can add the required build dependencies
		from `build-system.requires` to `nativeBuildInputs`. Note that the pyproject
		format falls back to using `setuptools`, so you can use `pyproject = true`
		even if the package only has a `setup.py`. When set to `false`, you can
		use the existing [hooks](#setup-hooks0 or provide your own logic to build the
		package. This can be useful for packages that don't support the pyproject
		format. When unset, the legacy `setuptools` hooks are used for backwards
		compatibility.
		* `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
		@@ -286,20 +289,25 @@ specifying an interpreter version), like this:
		python3.pkgs.buildPythonApplication rec {
		pname = "luigi";
		version = "2.7.9";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-Pe229rT0aHwA98s+nTHQMEFKZPo/yw6sot8MivFDvAw=";
		};

		nativeBuildInputs = [
		python3.pkgs.setuptools
		python3.pkgs.wheel
		];

		propagatedBuildInputs = with python3.pkgs; [
		tornado
		python-daemon
		];

		meta = with lib; {
		...
		# ...
		};
		}
		```
		@@ -858,18 +866,25 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th
		{ lib
		, buildPythonPackage
		, fetchPypi
		, setuptools
		, wheel
		}:

		buildPythonPackage rec {
		pname = "toolz";
		version = "0.10.0";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
		};

		nativeBuildInputs = [
		setuptools
		wheel
		];

		# has no tests
		doCheck = false;

		@@ -918,13 +933,18 @@ with import <nixpkgs> {};
		my_toolz = python311.pkgs.buildPythonPackage rec {
		pname = "toolz";
		version = "0.10.0";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
		};

		nativeBuildInputs = [
		python311.pkgs.setuptools
		python311.pkgs.wheel
		];

		# has no tests
		doCheck = false;

		@@ -972,6 +992,9 @@ order to build [`datashape`](https://github.com/blaze/datashape).
		, buildPythonPackage
		, fetchPypi

		# build dependencies
		, setuptools, wheel

		# dependencies
		, numpy, multipledispatch, python-dateutil

		@@ -982,13 +1005,18 @@ order to build [`datashape`](https://github.com/blaze/datashape).
		buildPythonPackage rec {
		pname = "datashape";
		version = "0.4.7";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-FLLvdm1MllKrgTGC6Gb0k0deZeVYvtCCLji/B7uhong=";
		};

		nativeBuildInputs = [
		setuptools
		wheel
		];

		propagatedBuildInputs = [
		multipledispatch
		numpy
		@@ -1023,6 +1051,8 @@ when building the bindings and are therefore added as `buildInputs`.
		{ lib
		, buildPythonPackage
		, fetchPypi
		, setuptools
		, wheel
		, libxml2
		, libxslt
		}:
		@@ -1030,13 +1060,18 @@ when building the bindings and are therefore added as `buildInputs`.
		buildPythonPackage rec {
		pname = "lxml";
		version = "3.4.4";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-s9NiusRxFydHzaNRMjjxFcvWxfi45jGb9ql6eJJyQJk=";
		};

		nativeBuildInputs = [
		setuptools
		wheel
		];

		buildInputs = [
		libxml2
		libxslt
		@@ -1067,6 +1102,10 @@ therefore we have to set `LDFLAGS` and `CFLAGS`.
		, buildPythonPackage
		, fetchPypi

		# build dependencies
		, setuptools
		, wheel

		# dependencies
		, fftw
		, fftwFloat
		@@ -1078,13 +1117,18 @@ therefore we have to set `LDFLAGS` and `CFLAGS`.
		buildPythonPackage rec {
		pname = "pyFFTW";
		version = "0.9.2";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-9ru2r6kwhUCaskiFoaPNuJCfCVoUL01J40byvRt4kHQ=";
		};

		nativeBuildInputs = [
		setuptools
		wheel
		];

		buildInputs = [
		fftw
		fftwFloat
		@@ -1334,9 +1378,7 @@ instead of a dev dependency).

		Keep in mind that while the examples above are done with `requirements.txt`,
		`pythonRelaxDepsHook` works by modifying the resulting wheel file, so it should
		work in any of the formats supported by `buildPythonPackage` currently,
		with the exception of `other` (see `format` in
		[`buildPythonPackage` parameters](#buildpythonpackage-parameters) for more details).
		work with any of the existing [hooks](#setup-hooks).

		#### Using unittestCheckHook {#using-unittestcheckhook}

		@@ -1461,18 +1503,26 @@ We first create a function that builds `toolz` in `~/path/to/toolz/release.nix`
		```nix
		{ lib
		, buildPythonPackage
		, fetchPypi
		, setuptools
		, wheel
		}:

		buildPythonPackage rec {
		pname = "toolz";
		version = "0.10.0";
		format = "setuptools";
		pyproject = true;

		src = fetchPypi {
		inherit pname version;
		hash = "sha256-CP3V73yWSArRHBLUct4hrNMjWZlvaaUlkpm1QP66RWA=";
		};

		nativeBuildInputs = [
		setuptools
		wheel
		];

		meta = with lib; {
		changelog = "https://github.com/pytoolz/toolz/releases/tag/${version}";
		homepage = "https://github.com/pytoolz/toolz/";

Admin message