### Non-Flake Usage with niv

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use poetry2nix in a traditional Nix setup without flakes, managing dependencies with `niv`. This example shows a `default.nix` file and setup commands.

```nix
# default.nix
let
  sources = import ./nix/sources.nix;
  pkgs = import sources.nixpkgs { };
  poetry2nix = import sources.poetry2nix { inherit pkgs; };
  myPythonApp = poetry2nix.mkPoetryApplication {
    projectDir = ./.;
  };
in myPythonApp

# Setup commands:
# nix-shell -p niv
# niv init
# niv add nix-community/poetry2nix
# nix-build default.nix
# ./result/bin/<script>
```

--------------------------------

### Quickstart Flake Nix Configuration

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Integrate poetry2nix into your flake.nix to package a Python application. This example defines an app that can be run using 'nix run .'.

```nix
# file: flake.nix
{
  description = "Python application packaged using poetry2nix";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  inputs.poetry2nix.url = "github:nix-community/poetry2nix";

  outputs = { self, nixpkgs, poetry2nix }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
      # create a custom "mkPoetryApplication" API function that under the hood uses
      # the packages and versions (python3, poetry etc.) from our pinned nixpkgs above:
      inherit (poetry2nix.lib.mkPoetry2Nix { inherit pkgs; }) mkPoetryApplication;
      myPythonApp = mkPoetryApplication { projectDir = ./.; };
    in
    {
      apps.${system}.default = {
        type = "app";
        # replace <script> with the name in the [tool.poetry.scripts] section of your pyproject.toml
        program = "${myPythonApp}/bin/<script>";
      };
    };
}

```

--------------------------------

### View build error log

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

Example of a build failure log resulting from missing build dependencies.

```text
Sourcing python-remove-tests-dir-hook
Sourcing python-catch-conflicts-hook.sh
Sourcing python-remove-bin-bytecode-hook.sh
Sourcing pip-install-hook
Using pipInstallPhase
Sourcing python-imports-check-hook.sh
Using pythonImportsCheckPhase
Sourcing python-namespaces-hook
Sourcing pip-build-hook
Using pipBuildPhase
Using pipShellHook
@nix { "action": "setPhase", "phase": "unpackPhase" }
unpacking sources
unpacking source archive /nix/store/w1gk95sf5lknw0mxav5gsvcijcwfqkwh-django-floppyforms-1.9.0.tar.gz
source root is django-floppyforms-1.9.0
setting SOURCE_DATE_EPOCH to timestamp 1589942379 of file django-floppyforms-1.9.0/setup.cfg
@nix { "action": "setPhase", "phase": "patchPhase" }
patching sources
@nix { "action": "setPhase", "phase": "configurePhase" }
configuring
no configure script, doing nothing
@nix { "action": "setPhase", "phase": "buildPhase" }
building
Executing pipBuildPhase
Creating a wheel...
WARNING: The directory '/homeless-shelter/.cache/pip' or its parent directory is not owned or is not writable by the current user. The cache has been disabled. Check the permissions and owner of that directory. If executing pip with sudo, you should use sudo's -H flag.
Processing /build/django-floppyforms-1.9.0
  Running command Preparing metadata (pyproject.toml)
  Preparing metadata (pyproject.toml) ... done
ERROR: Exception:
Traceback (most recent call last):
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/cli/base_command.py", line 167, in exc_logging_wrapper
    status = run_func(*args)
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/cli/req_command.py", line 247, in wrapper
    return func(self, options, args)
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/commands/wheel.py", line 145, in run
    requirement_set = resolver.resolve(reqs, check_supported_wheels=True)
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/resolver.py", line 73, in resolve
    collected = self.factory.collect_root_requirements(root_reqs)
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 491, in collect_root_requirements
    req = self._make_requirement_from_install_req(
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 453, in _make_requirement_from_install_req
    cand = self._make_candidate_from_link(
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/factory.py", line 206, in _make_candidate_from_link
    self._link_candidate_cache[link] = LinkCandidate(
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 297, in __init__
    super().__init__(
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 162, in __init__
    self.dist = self._prepare()
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 231, in _prepare
    dist = self._prepare_distribution()
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/resolution/resolvelib/candidates.py", line 308, in _prepare_distribution
    return preparer.prepare_linked_requirement(self._ireq, parallel_builds=True)
  File "/nix/store/85xz0a1v6kk26c8a78pckbylhkdmlb6g-python3.10-pip-22.2.2/lib/python3.10/site-packages/pip/_internal/operations/prepare.py", line 438, in prepare_linked_requirement
    return self._prepare_linked_requirement(req, parallel_builds)
```

--------------------------------

### Multiple Dependency Overrides

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

This example demonstrates how to apply multiple overrides for different dependencies within a single `poetry2nix.mkPoetryApplication` definition. Each override targets a specific dependency and modifies its build inputs.

```nix
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.defaultPoetryOverrides.extend
    (final: prev: {
      first-dependency = prev.first-dependency.overridePythonAttrs
      (
        old: {
          buildInputs = (old.buildInputs or [ ]) ++ [ prev.buildtools ];
        }
      );
      second-dependency = prev.second-dependency.overridePythonAttrs
      (
        old: {
          buildInputs = (old.buildInputs or [ ]) ++ [ prev.pdm-backend ];
        }
      );
    });
}
```

--------------------------------

### Quickstart Non-flake Nix Configuration

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use this Nix configuration in a default.nix file to package a Python application managed by Poetry. Ensure nixpkgs and poetry2nix are pinned using a tool like niv.

```nix
let
  sources = import ./nix/sources.nix;
  pkgs = import sources.nixpkgs { };
  # Let all API attributes like "poetry2nix.mkPoetryApplication" 
  # use the packages and versions (python3, poetry etc.) from our pinned nixpkgs above
  # under the hood:
  poetry2nix = import sources.poetry2nix { inherit pkgs; };
  myPythonApp = poetry2nix.mkPoetryApplication { projectDir = ./.; };
in
myPythonApp

```

--------------------------------

### Create Poetry Environment with Editable Packages

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Configure mkPoetryEnv to install specific packages in editable mode for development. Map package names to their source directories.

```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
        my-app = ./src;
    };
}
```

--------------------------------

### Flake Integration for Python Projects

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Set up a complete `flake.nix` for Python projects using poetry2nix, including development shells and package exports. This example demonstrates a deployable application and a development shell.

```nix
# flake.nix
{
  description = "Python application packaged using poetry2nix";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    poetry2nix.url = "github:nix-community/poetry2nix";
  };

  outputs = { self, nixpkgs, poetry2nix }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
      inherit (poetry2nix.lib.mkPoetry2Nix { inherit pkgs; }) mkPoetryApplication mkPoetryEnv;
    in {
      # Deployable application
      packages.${system}.default = mkPoetryApplication {
        projectDir = self;
      };

      # Development shell
      devShells.${system}.default = pkgs.mkShell {
        packages = [
          (mkPoetryEnv {
            projectDir = self;
            editablePackageSources = { my-app = ./src; };
          })
          pkgs.poetry
        ];
      };

      # Run with: nix run .
      apps.${system}.default = {
        type = "app";
        program = "${self.packages.${system}.default}/bin/my-cli";
      };
    };
}

# Alternative: Using overlay approach
{
  outputs = { self, nixpkgs, poetry2nix }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system}.extend poetry2nix.overlays.default;
    in {
      packages.${system}.default = pkgs.poetry2nix.mkPoetryApplication {
        projectDir = self;
      };
    };
}
```

--------------------------------

### Create Custom poetry2nix Instance

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Create a custom poetry2nix instance with modified default overrides for project-wide consistency. This example extends default overrides to modify a specific package's build inputs.

```nix
let
  p2nix = poetry2nix.overrideScope (final: prev: {
    defaultPoetryOverrides = prev.defaultPoetryOverrides.extend (pyfinal: pyprev: {
      my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: {
        buildInputs = (oldAttrs.buildInputs or [ ]) ++ [ pyfinal.setuptools ];
      });
    });
  });
in p2nix.mkPoetryApplication {
  projectDir = ./.;
}
```

--------------------------------

### Poetry Configuration for Private Repository

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Example of how to specify a private package repository in your pyproject.toml file.

```toml
[[tool.poetry.source]]
name = "private-repository"
url = "https://example.org/simple/"
priority = "primary"
...
```

--------------------------------

### mkPoetryEnv

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Creates a Python environment with project dependencies and allows for editable package installations.

```APIDOC
## mkPoetryEnv

### Description
Creates an environment that provides a Python interpreter along with all dependencies declared by the designated poetry project and lock files. Also allows package sources of an application to be installed in editable mode for fast development.

### Parameters
#### Path Parameters
- **projectDir** (path) - Required - Path to the root of the project.
- **pyproject** (path) - Optional - Path to `pyproject.toml` (default: `projectDir + "/pyproject.toml"`).
- **poetrylock** (path) - Optional - `poetry.lock` file path (default: `projectDir + "/poetry.lock"`).
- **overrides** (attribute set) - Optional - Python overrides to apply (default: `defaultPoetryOverrides`).
- **python** (interpreter) - Optional - The Python interpreter to use (default: `pkgs.python3`).
- **editablePackageSources** (mapping) - Optional - A mapping from package name to source directory, these will be installed in editable mode. Note that path dependencies with `develop = true` will be installed in editable mode unless explicitly passed to `editablePackageSources` as `null`. (default: `{}`).
- **extraPackages** (function) - Optional - A function taking a Python package set and returning a list of extra packages to include in the environment. This is intended for packages deliberately not added to `pyproject.toml` that you still want to include. An example of such a package may be `pip`. (default: `(ps: [ ])`).
- **preferWheels** (boolean) - Optional - Use wheels rather than sdist as much as possible (default: `false`).
- **groups** (list) - Optional - Which Poetry 1.2.0+ dependency groups to install (default: `[ "main" "dev" ]`).
- **checkGroups** (list) - Optional - Which Poetry 1.2.0+ dependency groups to install (independently of **groups**) to run unit tests (default: `[ "dev" ]`).
- **extras** (list) - Optional - Which Poetry `extras` to install (default: `[ "*" ]`, all extras).

### Request Example
```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
}
```

### Example with editable packages

```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
        my-app = ./src;
    };
}
```

### Example shell.nix

The `env` attribute of the attribute set created by `mkPoetryEnv` contains a shell environment.

```nix
{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env
```

### Example shell.nix with external dependencies

For a shell environment including external dependencies, override the `env` to add dependency packages (for example, `pkgs.hello`) as build inputs.

```nix
{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env.overrideAttrs (oldAttrs: {
  buildInputs = [ pkgs.hello ];
})
```

See [./tests/env/default.nix](./tests/env/default.nix) for a working example.
See [./tests/editable/default.nix](./tests/editable/default.nix) for a working example of an editable package.
```

--------------------------------

### Multiple Overrides with Build Systems

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use overrides to modify package build inputs or force specific build types like wheels. This example shows how to add build inputs and force a wheel for numpy.

```nix
poetry2nix.mkPoetryEnv {
  projectDir = ./.;
  overrides = poetry2nix.overrides.withDefaults (final: prev: {
    first-dependency = prev.first-dependency.overridePythonAttrs (old: {
      buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
    });
    second-dependency = prev.second-dependency.overridePythonAttrs (old: {
      buildInputs = (old.buildInputs or [ ]) ++ [ prev.pdm-backend ];
    });
    # Force wheel for problematic package
    numpy = prev.numpy.override { preferWheel = true; };
  });
}
```

--------------------------------

### Configure wheel preference for a dependency

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use this override pattern to force a specific package to install from a wheel instead of source.

```nix
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.overrides.withDefaults (final: prev: {
    # Notice that using .overridePythonAttrs or .overrideAttrs won't work!
    some-dependency = prev.some-dependency.override {
      preferWheel = true;
    };
  });
}
```

--------------------------------

### Batch Override Pattern

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Apply overrides to multiple packages efficiently using a batch override pattern. This example defines build requirements for several packages and maps them to overrides.

```nix
# Batch override pattern for many packages
let
  pypkgs-build-requirements = {
    tox = [ "hatchling" "hatch-vcs" ];
    universal-pathlib = [ "flit-core" ];
    pygithub = [ "setuptools-scm" ];
    beautifulsoup4 = [ "hatchling" ];
    xyzservices = [ "setuptools" ];
  };
  p2n-overrides = poetry2nix.defaultPoetryOverrides.extend (final: prev:
    builtins.mapAttrs (package: build-requirements:
      (builtins.getAttr package prev).overridePythonAttrs (old: {
        buildInputs = (old.buildInputs or [ ]) ++
          (builtins.map (pkg: builtins.getAttr pkg prev) build-requirements);
      })
    ) pypkgs-build-requirements
  );
in poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = p2n-overrides;
}
```

--------------------------------

### Custom Overrides Without Defaults

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use `overrides.withoutDefaults` when you need complete control and want to exclude all bundled default overrides. This example applies a custom override for the 'foo' package.

```nix
poetry2nix.mkPoetryEnv {
  projectDir = ./.;
  overrides = poetry2nix.overrides.withoutDefaults (final: prev: {
    # Complete custom overrides, no defaults applied
    foo = prev.foo.overridePythonAttrs (old: {
      buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
    });
  });
}
```

--------------------------------

### Infinite recursion error message example

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

An example of an error message indicating a circular dependency during derivation evaluation.

```text
error: infinite recursion encountered
       … while evaluating the attribute 'propagatedBuildInputs' of the derivation 'python3.11-distributed-2023.3.2'
       … while evaluating the attribute 'propagatedBuildInputs' of the derivation 'python3.11-dask-2023.3.2'
       … while evaluating the attribute 'propagatedBuildInputs' of the derivation 'python3.11-main-0.1.0'
```

--------------------------------

### Extending Default Overrides

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Extend default poetry2nix overrides with additional package fixes using a cleaner syntax for multiple overrides. This example adds an override for 'django-floppyforms'.

```nix
# Extend defaults with custom overrides
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.defaultPoetryOverrides.extend (final: prev: {
    django-floppyforms = prev.django-floppyforms.overridePythonAttrs (old: {
      buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
    });
  });
}
```

--------------------------------

### Passing NETRC Path via Nix Search Path (Non-Flake)

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

For non-flake projects, pass the NETRC file path as a Nix search path argument. This method is specific to non-flake setups and forwards the variable as an environment variable into the sandbox.

```shell
# non-flake project
nix-build -I NETRC=/etc/nix/netrc --option extra-sandbox-paths /etc/nix/netrc default.nix
```

--------------------------------

### Create a basic poetry application

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use mkPoetryApplication to build a Python application from the current directory.

```nix
poetry2nix.mkPoetryApplication {
    projectDir = ./.;
}
```

--------------------------------

### Enable PreferWheels in PoetryApplication

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

Use pre-compiled binary wheels as an escape hatch for complex build environments. Note that this may introduce security risks associated with binary distributions.

```nix
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  preferWheels = true;
}
```

--------------------------------

### mkPoetryApplication

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Creates a deployable Python application derivation from a Poetry project.

```APIDOC
## mkPoetryApplication

### Description
Creates a Python application from `pyproject.toml` and `poetry.lock` files. This is the primary function for building deployable Python applications as Nix packages.

### Parameters
#### Request Body
- **projectDir** (path) - Required - The directory containing pyproject.toml and poetry.lock
- **python** (derivation) - Optional - The Python interpreter to use
- **preferWheels** (boolean) - Optional - Whether to prefer wheels over building from source
- **groups** (list) - Optional - Dependency groups to include
- **checkGroups** (list) - Optional - Dependency groups to include for tests
- **extras** (list) - Optional - Extras to include
- **overrides** (function) - Optional - Custom package overrides
- **meta** (attribute set) - Optional - Metadata for the package
```

--------------------------------

### Create Poetry Environment

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use mkPoetryEnv to create a Nix environment with Python and project dependencies. Specify the project directory.

```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
}
```

--------------------------------

### Add Setuptools Build Dependency

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

Use this override to add `setuptools` as a build input for a specific Python package. This is useful when a package fails to build due to a missing `setuptools` dependency, as indicated by a `ModuleNotFoundError` during the build process.

```nix
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.defaultPoetryOverrides.extend
    (final: prev: {
      django-floppyforms = prev.django-floppyforms.overridePythonAttrs
      (
        old: {
          buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
        }
      );
    });
}
```

--------------------------------

### Apply Overrides with overrides.withDefaults

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Combine custom package overrides with default poetry2nix fixes to resolve build issues while maintaining standard behavior.

```nix
# Add setuptools to a package missing build dependencies
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  overrides = poetry2nix.overrides.withDefaults (final: prev: {
    django-floppyforms = prev.django-floppyforms.overridePythonAttrs (old: {
      buildInputs = (old.buildInputs or [ ]) ++ [ prev.setuptools ];
    });
  });
}
```

--------------------------------

### Apply poetry overrides

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use withDefaults to combine custom overlays with the default poetry2nix overrides, or withoutDefaults to use only the custom overlay.

```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    overrides = poetry2nix.overrides.withDefaults (final: prev: { foo = null; });
}
```

```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    overrides = poetry2nix.overrides.withoutDefaults (final: prev: { foo = null; });
}
```

--------------------------------

### Run project tests

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Commands for executing and managing the test suite locally.

```bash
nix-build --keep-going --show-trace tests/default.nix
```

```bash
nix eval --impure --expr 'let pkgs = import <nixpkgs> {}; in pkgs.lib.attrNames (import ./tests/default.nix {})'
```

```bash
nix-build --attr bcrypt --attr jq --keep-going --show-trace tests/default.nix
```

```bash
nix-build --expr 'with import <unstable> {}; callPackage ./tests/default.nix {}'
```

--------------------------------

### Flake Nix Configuration with Overlay

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

An alternative flake.nix configuration that merges poetry2nix into pkgs using an overlay, allowing access via pkgs.poetry2nix.mkPoetryApplication.

```nix
pkgs = nixpkgs.legacyPackages.${system}.extend poetry2nix.overlays.default;
myPythonApp = pkgs.poetry2nix.mkPoetryApplication { projectDir = self; };

```

--------------------------------

### Create Poetry Packages

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use mkPoetryPackages to generate an attribute set containing the Python interpreter, all poetry packages, and parsed project files. Specify the project directory and optionally the Python interpreter.

```nix
poetry2nix.mkPoetryPackages {
    projectDir = ./.;
    python3 = python39;
}
```

--------------------------------

### mkPoetryScriptsPackage

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Creates a Nix package containing scripts defined in the `tool.poetry.scripts` section of `pyproject.toml`.

```APIDOC
## mkPoetryScriptsPackage

### Description
Creates a package containing the scripts from `tool.poetry.scripts` of the `pyproject.toml`:

### Parameters
#### Path Parameters
- **projectDir** (path) - Required - Path to the root of the project.
- **pyproject** (path) - Optional - Path to `pyproject.toml` (default: `projectDir + "/pyproject.toml"`).
- **python** (interpreter) - Optional - The Python interpreter to use (default: `pkgs.python3`).

### Request Example
```nix
poetry2nix.mkPoetryScriptsPackage {
    projectDir = ./.;
    python3 = python39;
}
```
```

--------------------------------

### Build Python Applications with mkPoetryApplication

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use mkPoetryApplication to create deployable Python packages. The dependencyEnv attribute can be used to access the environment for running scripts like gunicorn.

```nix
# Basic usage - simple Python application
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
}

# Full example with all common options
poetry2nix.mkPoetryApplication {
  projectDir = ./.;
  python = pkgs.python311;
  preferWheels = false;  # Build from source by default
  groups = [ "main" ];   # Include main dependencies
  checkGroups = [ "dev" ];  # Include dev dependencies for tests
  extras = [ "*" ];  # Include all extras
  overrides = poetry2nix.overrides.withDefaults (final: prev: {
    # Override specific package to use wheel
    some-package = prev.some-package.override {
      preferWheel = true;
    };
  });
  meta = {
    description = "My Python application";
    homepage = "https://example.com";
  };
}

# Using the dependencyEnv for gunicorn/celery deployments
let
  app = poetry2nix.mkPoetryApplication {
    projectDir = ./.;
  };
in app.dependencyEnv
# Then run: ./result/bin/gunicorn myapp:app
```

--------------------------------

### Create an editable poetry package

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Use mkPoetryEditablePackage to allow real-time updates to source code within a nix-shell session.

```nix
poetry2nix.mkPoetryEditablePackage {
    projectDir = ./.;
    python3 = python39;
    editablePackageSources = {
        my-app = ./src;
    };
}
```

--------------------------------

### Mounting NETRC in Nix Build (Non-Flake)

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Build a non-flake project while mounting the NETRC file into the Nix sandbox using the `extra-sandbox-paths` option.

```shell
# non-flake project
nix-build --option extra-sandbox-paths /etc/nix/netrc default.nix
```

--------------------------------

### Nixpkgs Overlay for Custom poetry2nix

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use a Nixpkgs overlay to define a custom poetry2nix instance for reuse across multiple projects. This allows consistent modification of default overrides.

```nix
let
  pkgs = import <nixpkgs> {
    overlays = [ 
      (final: prev: {
        poetry2nix = prev.poetry2nix.overrideScope (p2nixfinal: p2nixprev: {
          defaultPoetryOverrides = p2nixprev.defaultPoetryOverrides.extend (pyfinal: pyprev: {
            my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });
          });
        });
      })
    ];
  };
in pkgs.poetry2nix.mkPoetryApplication {
  projectDir = ./.;
}
```

--------------------------------

### Create Poetry Scripts Package

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Generate a Nix package for scripts defined in 'tool.poetry.scripts'. Specify the project directory and the Python interpreter.

```nix
poetry2nix.mkPoetryScriptsPackage {
    projectDir = ./.;
    python3 = python39;
}
```

--------------------------------

### Shell.nix with External Dependencies

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Extend a Poetry environment in shell.nix to include external Nix packages. Override the 'env' attribute's buildInputs to add dependencies.

```nix
{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env.overrideAttrs (oldAttrs: {
  buildInputs = [ pkgs.hello ];
})
```

--------------------------------

### overrides.withDefaults

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Combines custom overlays with default poetry2nix overrides.

```APIDOC
## overrides.withDefaults

### Description
Returns a list combining your custom overlay with poetry2nix default overrides. Use this when you need to fix specific packages while keeping all bundled fixes.
```

--------------------------------

### mkPoetryApplication

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Creates a Python application using the Python interpreter specified based on the designated poetry project and lock files.

```APIDOC
## mkPoetryApplication

### Description
Creates a Python application using the Python interpreter specified based on the designated poetry project and lock files.

### Parameters
#### Request Body
- **projectDir** (path) - Required - Path to the root of the project.
- **src** (path) - Optional - Project source (default: cleanPythonSources { src = projectDir; }).
- **pyproject** (path) - Optional - Path to pyproject.toml (default: projectDir + "/pyproject.toml").
- **poetrylock** (path) - Optional - poetry.lock file path (default: projectDir + "/poetry.lock").
- **overrides** (set) - Optional - Python overrides to apply (default: defaultPoetryOverrides).
- **meta** (set) - Optional - Application meta data (default: {}).
- **python** (package) - Optional - The Python interpreter to use (default: pkgs.python3).
- **preferWheels** (boolean) - Optional - Use wheels rather than sdist as much as possible (default: false).
- **groups** (list) - Optional - Which Poetry 1.2.0+ dependency groups to install (default: [ "main" ]).
- **checkGroups** (list) - Optional - Which Poetry 1.2.0+ dependency groups to install to run unit tests (default: [ "dev" ]).
- **extras** (list) - Optional - Which Poetry extras to install (default: [ "*" ]).

### Request Example
poetry2nix.mkPoetryApplication {
    projectDir = ./.;
}
```

--------------------------------

### Mounting NETRC in Nix Build (Flake)

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Build a flake project while mounting the NETRC file into the Nix sandbox using the `extra-sandbox-paths` option.

```shell
# flake project
nix build . --extra-sandbox-paths /etc/nix/netrc
```

--------------------------------

### mkPoetryEnv

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Creates a Python environment for development shells.

```APIDOC
## mkPoetryEnv

### Description
Creates a Python environment with an interpreter and all packages specified in the lock file. Ideal for development shells and interactive work.

### Parameters
#### Request Body
- **projectDir** (path) - Required - The directory containing pyproject.toml and poetry.lock
- **editablePackageSources** (attribute set) - Optional - Mapping of package names to source paths for editable installs
- **extraPackages** (function) - Optional - Function to add extra packages to the environment
- **groups** (list) - Optional - Dependency groups to include
```

--------------------------------

### Execute application modules

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Run application modules using the interpreter provided by the dependency environment.

```shell
./result/bin/python -m admin
./result/bin/gunicorn web:app
```

--------------------------------

### Creating a custom poetry2nix instance

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Allows for the creation of a custom poetry2nix instance, enabling modifications to default overrides or other configurations.

```APIDOC
## Creating a custom Poetry2nix instance

### Description
Sometimes when it can be convenient to create a custom instance of `poetry2nix` with a different set of default overrides.

### Example 1: Custom Instance
```nix
let
  # final & prev refers to poetry2nix
  p2nix = poetry2nix.overrideScope (final: prev: {

    # pyself & pyprev refers to python packages
    defaultPoetryOverrides = prev.defaultPoetryOverrides.extend (pyfinal: pyprev: {

      my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });

    });

  });

in
p2nix.mkPoetryApplication {
  projectDir = ./.;
}
```

### Example 2: Nixpkgs Overlay
```nix
let
  pkgs = import <nixpkgs> {
    overlays = [ 
      # final & prev refers to nixpkgs
      (final: prev: {

        # p2nixfinal & p2nixprev refers to poetry2nix
        poetry2nix = prev.poetry2nix.overrideScope (p2nixfinal: p2nixprev: {

          # pyfinal & pyprev refers to python packages
          defaultPoetryOverrides = p2nixprev.defaultPoetryOverrides.extend (pyfinal: pyprev: {

            my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });

          });

        });
      })

    ];
  };

in pkgs.poetry2nix.mkPoetryApplication {
  projectDir = ./.;
}
```
```

--------------------------------

### Nix Configuration for extra-sandbox-paths (Global)

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Globally configure Nix to include the NETRC file in the sandbox. This is not recommended due to security implications.

```ini
# file: nix.conf
extra-sandbox-paths /etc/nix/netrc
```

--------------------------------

### Create Development Environments with mkPoetryEnv

Source: https://context7.com/nix-community/poetry2nix/llms.txt

mkPoetryEnv generates Python environments for development, supporting editable packages and additional native dependencies via shell.nix.

```nix
# Basic development environment
poetry2nix.mkPoetryEnv {
  projectDir = ./.;
}

# Development environment with editable packages
poetry2nix.mkPoetryEnv {
  projectDir = ./.;
  editablePackageSources = {
    my-app = ./src;  # Changes in ./src are immediately available
  };
}

# Environment with extra packages not in pyproject.toml
poetry2nix.mkPoetryEnv {
  projectDir = ./.;
  extraPackages = ps: [ ps.pip ps.ipython ];
  groups = [ "main" "dev" ];  # Include both main and dev dependencies
}

# shell.nix for nix-shell usage
{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env.overrideAttrs (oldAttrs: {
  buildInputs = [ pkgs.postgresql pkgs.redis ];  # Add native dependencies
})
```

--------------------------------

### Create a custom poetry2nix instance

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Override the default poetry2nix scope to inject custom package overrides, either directly or via a nixpkgs overlay.

```nix
let
  # final & prev refers to poetry2nix
  p2nix = poetry2nix.overrideScope (final: prev: {

    # pyself & pyprev refers to python packages
    defaultPoetryOverrides = prev.defaultPoetryOverrides.extend (pyfinal: pyprev: {

      my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });

    });

  });

in
p2nix.mkPoetryApplication {
  projectDir = ./.;
}
```

```nix
let
  pkgs = import <nixpkgs> {
    overlays = [
      # final & prev refers to nixpkgs
      (final: prev: {

        # p2nixfinal & p2nixprev refers to poetry2nix
        poetry2nix = prev.poetry2nix.overrideScope (p2nixfinal: p2nixprev: {

          # pyfinal & pyprev refers to python packages
          defaultPoetryOverrides = p2nixprev.defaultPoetryOverrides.extend (pyfinal: pyprev: {

            my-custom-pkg = pyprev.my-custom-pkg.overridePythonAttrs (oldAttrs: { });

          });

        });
      })

    ];
  };

in pkgs.poetry2nix.mkPoetryApplication {
  projectDir = ./.;
}
```

--------------------------------

### Access dependency environment

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Expose the dependency environment for applications that rely on dependency binaries.

```nix
let
    app = poetry2nix.mkPoetryApplication {
        projectDir = ./.;
    };
in app.dependencyEnv
```

--------------------------------

### Shell.nix for Poetry Environment

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Integrate mkPoetryEnv into a shell.nix file to create a development shell with project dependencies. The 'env' attribute provides the shell environment.

```nix
{ pkgs ? import <nixpkgs> {} }:
let
  myAppEnv = pkgs.poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    editablePackageSources = {
      my-app = ./src;
    };
  };
in myAppEnv.env
```

--------------------------------

### Create Editable Packages with mkPoetryEditablePackage

Source: https://context7.com/nix-community/poetry2nix/llms.txt

mkPoetryEditablePackage allows for rapid development by reflecting changes in specified source paths immediately within the nix-shell.

```nix
# Create editable package for development
poetry2nix.mkPoetryEditablePackage {
  projectDir = ./.;
  python = pkgs.python311;
  editablePackageSources = {
    my-app = ./src;
    my-lib = ./lib;
  };
}
```

--------------------------------

### Define poetry scripts in pyproject.toml

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Specify the main entry point for the application within the pyproject.toml file.

```toml
[tool.poetry.scripts]
poetry = "poetry.console.application:main"
```

--------------------------------

### Private Repository Authentication with NETRC

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Configure poetry2nix to download packages from private Python repositories using NETRC authentication. This involves creating a `~/.netrc` file and configuring NixOS to pass the NETRC environment variable to the nix-daemon.

```nix
# 1. Create ~/.netrc or /etc/nix/netrc:
# machine https://example.org
# login <username>
# password <token>

# 2. Configure NixOS to pass NETRC to nix-daemon:
{ config, ... }:
{
  systemd.services.nix-daemon = {
    serviceConfig = {
      Environment = "NETRC=/etc/nix/netrc";
    };
  };
}
```

--------------------------------

### Nix Configuration for trusted-users (Global)

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Configure Nix to trust a specific user for operations that require elevated privileges within the sandbox. This is often necessary for `extra-sandbox-paths` to function correctly.

```ini
# file: nix.conf
trusted-users <username>
```

--------------------------------

### overrides.withDefaults

Source: https://github.com/nix-community/poetry2nix/blob/master/README.md

Returns a list containing the specified overlay and defaultPoetryOverrides. Used for applying default overrides along with custom ones.

```APIDOC
## overrides.withDefaults

### Description
Returns a list containing the specified overlay and `defaultPoetryOverrides`. Takes an attribute set with the following attributes (attributes without default are mandatory).

### Parameters
#### Path Parameters
- **src** (directory) - Required - Project source directory.

### Request Example
```nix
poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    overrides = poetry2nix.overrides.withDefaults (final: prev: { foo = null; });
}
```

See [./tests/override-support/default.nix](./tests/override-support/default.nix) for a working example.
```

--------------------------------

### mkPoetryScriptsPackage

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Creates a package containing only the scripts defined in pyproject.toml.

```APIDOC
## mkPoetryScriptsPackage

### Description
Creates a package containing only the scripts defined in the `tool.poetry.scripts` section of `pyproject.toml`.
```

--------------------------------

### Access Package Metadata with mkPoetryPackages

Source: https://context7.com/nix-community/poetry2nix/llms.txt

mkPoetryPackages returns an attribute set containing the interpreter, generated packages, and parsed configuration files for fine-grained control.

```nix
# Get all packages and metadata
let
  poetryPkgs = poetry2nix.mkPoetryPackages {
    projectDir = ./.;
    python = pkgs.python39;
    groups = [ "main" ];
    extras = [ "*" ];
  };
in {
  # Access the configured Python interpreter
  python = poetryPkgs.python;

  # List of all generated Python packages
  packages = poetryPkgs.poetryPackages;

  # Parsed pyproject.toml
  projectConfig = poetryPkgs.pyProject;

  # Parsed poetry.lock
  lockFile = poetryPkgs.poetryLock;
}
```

--------------------------------

### mkPoetryPackages

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Provides access to generated packages and metadata.

```APIDOC
## mkPoetryPackages

### Description
Creates an attribute set providing access to all generated packages and artifacts.

### Response
- **python** (derivation) - The configured Python interpreter
- **poetryPackages** (list) - All generated Python packages
- **pyProject** (attribute set) - Parsed pyproject.toml content
- **poetryLock** (attribute set) - Parsed poetry.lock content
```

--------------------------------

### Extract Scripts with mkPoetryScriptsPackage

Source: https://context7.com/nix-community/poetry2nix/llms.txt

Use mkPoetryScriptsPackage to create a package containing only the scripts defined in the pyproject.toml tool.poetry.scripts section.

```nix
# Extract scripts from pyproject.toml
# Given pyproject.toml contains:
# [tool.poetry.scripts]
# my-cli = "myapp.cli:main"

poetry2nix.mkPoetryScriptsPackage {
  projectDir = ./.;
  python = pkgs.python311;
}
# Result: package with ./result/bin/my-cli
```

--------------------------------

### Poetry lock file package definition

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

A sample entry from a poetry.lock file defining a package version.

```toml
[[package]]
name = "foobar"
version = "1.0"
description = "A dummy package"
optional = false
python-versions = ">=3.7"
files = [
    {file = "foobar-1.0-py3-none-any.whl", hash = "sha256:ae74fb96c20a0277a1d615f1e4d73c8414f5a98db8b799a7931d1582f3390c28"},
]
```

--------------------------------

### Override package version in Nix

Source: https://github.com/nix-community/poetry2nix/blob/master/docs/edgecases.md

Demonstrates how to use poetryOverrides to change a package version, which will supersede the version specified in poetry.lock.

```nix
let poetryOverrides = final: prev: {
    foobar = prev.foobar.overridePythonAttrs (old: rec {
      version = "2.0";
      src = prev.pkgs.fetchFromGitHub {
        owner = "fakerepo";
        repo = "foobar";
        rev = "refs/tags/${version}";
        sha256 = lib.fakeSha256;
      };
    });
  };
in
poetry2nix.mkPoetryApplication {
  projectDir = ../.;
  overrides = poetry2nix.overrides.withDefaults poetryOverrides;
}
```