doc/python: document pyproject and remove usages of format

doc/languages-frameworks/python.section.md

@@ -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
+* `pyproject`: Whether the pyproject format should be used. When set to `true`,
-  `"setuptools"`, `"pyproject"`, `"flit"`, `"wheel"`, and `"other"`.
+  `pypaBuildHook` will be used, and you can add the required build dependencies
-  `"setuptools"` is for when the source has a `setup.py` and `setuptools` is
+  from `build-system.requires` to `nativeBuildInputs`. Note that the pyproject
-  used to build a wheel, `flit`, in case `flit` should be used to build a wheel,
+  format falls back to using `setuptools`, so you can use `pyproject = true`
-  and `wheel` in case a wheel is provided. Use `other` when a custom
+  even if the package only has a `setup.py`. When set to `false`, you can
-  `buildPhase` and/or `installPhase` is needed.
+  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,
+work with any of the existing [hooks](#setup-hooks).
-with the exception of `other` (see `format` in
-[`buildPythonPackage` parameters](#buildpythonpackage-parameters) for more details).
 
 #### 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/";