feat(back): fluidattacks#1171 make python environment

- Add makePythonEnvironment builtin
- Add documentation

Signed-off-by: Daniel Salazar <[email protected]>

docs/src/api/extensions/python.md

@@ -38,6 +38,58 @@ Example:
         Python 3.9
     ```
 
+## makePythonEnvironment
+
+Create a Python virtual environment using
+[poetry2nix](https://github.com/nix-community/poetry2nix/tree/74921da7e0cc8918adc2e9989bd3e9c127b25ff6).
+
+Pre-requisites:
+Having both `pyproject.toml` and `poetry.lock`.
+
+Types:
+
+- makePythonEnvironment: (`function { ... } -> package`):
+    - pythonProjectDir (`path`): Required.
+        Python project where both
+        `pyproject.toml` and `poetry.lock`
+        are located.
+    - pythonVersion (`str`): Required.
+        Python version used to build the environment.
+        Supported versions are `3.9`, `3.10`, `3.11` and `3.12`.
+    - preferWheels (`bool`): Optional.
+        Use pre-compiled wheels from PyPI.
+        Defaults to `true`.
+    - overrides (`function {...} -> ` ): Optional.
+        Override build attributes for libraries within the environment.
+        For more information see [here](https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md).
+        Defaults to `(self: super: {})`.
+
+Example:
+
+=== "main.nix"
+
+    ```nix
+    # /path/to/my/project/makes/example/main.nix
+    {
+      makePythonEnvironment,
+      projectPath,
+      ...
+    }:
+    makePythonEnvironment {
+      pythonProjectDir = projectPath "/makes/example";
+      pythonVersion = "3.11";
+      preferWheels = true;
+      # Consider pygments requiring setuptools to build properly
+      overrides = self: super: {
+        pygments = super.pygments.overridePythonAttrs (
+          old: {
+            buildInputs = [super.setuptools];
+          }
+        );
+      };
+    }
+    ```
+
 ## makePythonPypiEnvironment
 
 Create a virtual environment

src/args/agnostic.nix

@@ -84,6 +84,7 @@
     makeNodeJsVersion = import ./make-node-js-version/default.nix self;
     makeNomadEnvironment = import ./make-nomad-environment/default.nix self;
     makePythonPypiEnvironment = import ./make-python-pypi-environment/default.nix self;
+    makePythonEnvironment = import ./make-python-environment/default.nix self;
     makePythonPyprojectPackage = import ./make-python-pyproject-package/default.nix;
     makePythonVersion = import ./make-python-version/default.nix self;
     makePythonVscodeSettings = import ./make-python-vscode-settings/default.nix self;

src/args/make-python-environment/default.nix

@@ -0,0 +1,42 @@
+{
+  __nixpkgs__,
+  listOptional,
+  makePythonVersion,
+  makeSearchPaths,
+  ...
+}: {
+  pythonProjectDir,
+  pythonVersion,
+  preferWheels ? true,
+  overrides ? (self: super: {}),
+}: let
+  poetry2nix = let
+    commit = "528d500ea826383cc126a9be1e633fc92b19ce5d";
+    sha256 = "sha256:1q245v4q0bb30ncfj66gl6dl1k46am28x7kjj6d3y7r6l4fzppq8";
+    src = builtins.fetchTarball {
+      inherit sha256;
+      url = "https://api.github.com/repos/nix-community/poetry2nix/tarball/${commit}";
+    };
+  in
+    import src {pkgs = __nixpkgs__;};
+
+  is39 = pythonVersion == "3.9";
+  is310 = pythonVersion == "3.10";
+  is311 = pythonVersion == "3.11";
+  is312 = pythonVersion == "3.12";
+  python = makePythonVersion pythonVersion;
+
+  env = poetry2nix.mkPoetryEnv {
+    overrides = poetry2nix.defaultPoetryOverrides.extend overrides;
+    inherit preferWheels;
+    projectDir = pythonProjectDir;
+    inherit python;
+  };
+in
+  makeSearchPaths {
+    bin = [env];
+    pythonPackage39 = listOptional is39 env;
+    pythonPackage310 = listOptional is310 env;
+    pythonPackage311 = listOptional is311 env;
+    pythonPackage312 = listOptional is312 env;
+  }