doc/languages-frameworks/python: Reword section to make commit rules a bit clearer (#339643)

Several versions of the Python interpreter are available on Nix, as well as a

high amount of packages. The attribute `python3` refers to the default

interpreter, which is currently CPython 3.11. The attribute `python` refers to

interpreter, which is currently CPython 3.12. The attribute `python` refers to

CPython 2.7 for backwards-compatibility. It is also possible to refer to

specific versions, e.g. `python311` refers to CPython 3.11, and `pypy` refers to

specific versions, e.g. `python312` refers to CPython 3.12, and `pypy` refers to

the default PyPy interpreter.

Python is used a lot, and in different ways. This affects also how it is

The interpreters have several common attributes. One of these attributes is

`pkgs`, which is a package set of Python libraries for this specific

interpreter. E.g., the `toolz` package corresponding to the default interpreter

is `python3.pkgs.toolz`, and the CPython 3.11 version is `python311.pkgs.toolz`.

is `python3.pkgs.toolz`, and the CPython 3.12 version is `python312.pkgs.toolz`.

The main package set contains aliases to these package sets, e.g.

`pythonPackages` refers to `python.pkgs` and `python311Packages` to

`python311.pkgs`.

`pythonPackages` refers to `python.pkgs` and `python312Packages` to

`python312.pkgs`.

#### Installing Python and packages {#installing-python-and-packages}

executables are wrapped to be able to find each other and all of the modules.

In the following examples we will start by creating a simple, ad-hoc environment

with a nix-shell that has `numpy` and `toolz` in Python 3.11; then we will create

with a nix-shell that has `numpy` and `toolz` in Python 3.12; then we will create

a re-usable environment in a single-file Python script; then we will create a

full Python environment for development with this same environment.

their runtime dependencies), with no other Python packages in the Python

interpreter's scope.

To create a Python 3.11 session with `numpy` and `toolz` available, run:

To create a Python 3.12 session with `numpy` and `toolz` available, run:

```sh

$ nix-shell -p 'python311.withPackages(ps: with ps; [ numpy toolz ])'

$ nix-shell -p 'python312.withPackages(ps: with ps; [ numpy toolz ])'

```

By default `nix-shell` will start a `bash` session with this interpreter in our

```Python console

[nix-shell:~/src/nixpkgs]$ python3

Python 3.11.3 (main, Apr  4 2023, 22:36:41) [GCC 12.2.0] on linux

Python 3.12.4 (main, Jun  6 2024, 18:26:44) [GCC 13.3.0] on linux

Type "help", "copyright", "credits" or "license" for more information.

>>> import numpy; import toolz

```

directly like so:

```sh

$ nix-shell -p "python311.withPackages (ps: with ps; [ numpy toolz requests ])" --run python3

this derivation will be built:

  /nix/store/r19yf5qgfiakqlhkgjahbg3zg79549n4-python3-3.11.2-env.drv

building '/nix/store/r19yf5qgfiakqlhkgjahbg3zg79549n4-python3-3.11.2-env.drv'...

created 273 symlinks in user environment

Python 3.11.2 (main, Feb  7 2023, 13:52:42) [GCC 12.2.0] on linux

$ nix-shell -p "python312.withPackages (ps: with ps; [ numpy toolz requests ])" --run python3

Python 3.12.4 (main, Jun  6 2024, 18:26:44) [GCC 13.3.0] on linux

Type "help", "copyright", "credits" or "license" for more information.

>>> import requests

>>>

in the previous section, we could startup a shell and just run it like so:

```ShellSession

$ nix-shell -p 'python311.withPackages (ps: with ps; [ numpy ])' --run 'python3 foo.py'

$ nix-shell -p 'python312.withPackages (ps: with ps; [ numpy ])' --run 'python3 foo.py'

The dot product of [1 2] and [3 4] is: 11

```

development we're usually working in an entire package repository.

As explained [in the `nix-shell` section](https://nixos.org/manual/nix/stable/command-ref/nix-shell) of the Nix manual, `nix-shell` can also load an expression from a `.nix` file.

Say we want to have Python 3.11, `numpy` and `toolz`, like before,

Say we want to have Python 3.12, `numpy` and `toolz`, like before,

in an environment. We can add a `shell.nix` file describing our dependencies:

```nix

with import <nixpkgs> {};

(python311.withPackages (ps: with ps; [

(python312.withPackages (ps: with ps; [

  numpy

  toolz

])).env

   imports the `<nixpkgs>` function, `{}` calls it and the `with` statement

   brings all attributes of `nixpkgs` in the local scope. These attributes form

   the main package set.

2. Then we create a Python 3.11 environment with the [`withPackages`](#python.withpackages-function) function, as before.

2. Then we create a Python 3.12 environment with the [`withPackages`](#python.withpackages-function) function, as before.

3. The [`withPackages`](#python.withpackages-function) function expects us to provide a function as an argument

   that takes the set of all Python packages and returns a list of packages to

   include in the environment. Here, we select the packages `numpy` and `toolz`

```nix

with import <nixpkgs> {};

let

  pythonEnv = python311.withPackages (ps: [

  pythonEnv = python312.withPackages (ps: [

    ps.numpy

    ps.toolz

  ]);

An expression for `toolz` can be found in the Nixpkgs repository. As explained

in the introduction of this Python section, a derivation of `toolz` is available

for each interpreter version, e.g. `python311.pkgs.toolz` refers to the `toolz`

derivation corresponding to the CPython 3.11 interpreter.

for each interpreter version, e.g. `python312.pkgs.toolz` refers to the `toolz`

derivation corresponding to the CPython 3.12 interpreter.

The above example works when you're directly working on

`pkgs/top-level/python-packages.nix` in the Nixpkgs repository. Often though,

with import <nixpkgs> {};

( let

    my_toolz = python311.pkgs.buildPythonPackage rec {

    my_toolz = python312.pkgs.buildPythonPackage rec {

      pname = "toolz";

      version = "0.10.0";

      pyproject = true;

      };

      build-system = [

        python311.pkgs.setuptools

        python312.pkgs.setuptools

      ];

      # has no tests

      };

    };

  in python311.withPackages (ps: with ps; [

  in python312.withPackages (ps: with ps; [

    numpy

    my_toolz

  ])

```

Executing `nix-shell` will result in an environment in which you can use

Python 3.11 and the `toolz` package. As you can see we had to explicitly mention

Python 3.12 and the `toolz` package. As you can see we had to explicitly mention

for which Python version we want to build a package.

So, what did we do here? Well, we took the Nix expression that we used earlier

When the environment variable `DETERMINISTIC_BUILD` is set, all bytecode will

have timestamp 1. The [`buildPythonPackage`](#buildpythonpackage-function) function sets `DETERMINISTIC_BUILD=1`

and [PYTHONHASHSEED=0](https://docs.python.org/3.11/using/cmdline.html#envvar-PYTHONHASHSEED).

and [PYTHONHASHSEED=0](https://docs.python.org/3.12/using/cmdline.html#envvar-PYTHONHASHSEED).

Both are also exported in `nix-shell`.

### How to provide automatic tests to Python packages? {#automatic-tests}

* `meta.platforms` takes the default value in many cases.

  It does not need to be set explicitly unless the package requires a specific platform.

* The file is formatted with `nixfmt-rfc-style`.

* Commit names of Python libraries should reflect that they are Python

  libraries, so write for example `python311Packages.numpy: 1.11 -> 1.12`.

  It is highly recommended to specify the current default version to enable

  automatic build by ofborg.

* Commit names of Python libraries must reflect that they are Python

  libraries (e.g. `python312Packages.numpy: 1.11 -> 1.12` rather than `numpy: 1.11 -> 1.12`).

* The current default version of python should be included

  in commit messages to enable automatic builds by ofborg.

  For example `python312Packages.numpy: 1.11 -> 1.12` should be used rather

  than `python3Packages.numpy: 1.11 -> 1.12`.

  Note that `pythonPackages` is an alias for `python27Packages`.

* Attribute names in `python-packages.nix` as well as `pname`s should match the

  library's name on PyPI, but be normalized according to [PEP