poetry2nix

poetry2nix turns Poetry projects into Nix derivations without the need to actually write Nix expressions. It does so by parsing pyproject.toml and poetry.lock and converting them to Nix derivations on the fly.

API

The poetry2nix public API consists of the following attributes:

• mkPoetryApplication: Creates a Python application.
• mkPoetryEnv: Creates a Python environment with an interpreter and all packages from poetry.lock.
• mkPoetryPackages: Creates an attribute set providing access to the generated packages and other artifacts.
• defaultPoetryOverrides: A set of bundled overrides fixing problems with Python packages.
• overrides.withDefaults: A convenience function for specifying overrides on top of the defaults.
• overrides.withoutDefaults: A convenience function for specifying overrides without defaults.
• cleanPythonSources: A function to create a source filter for python projects.

mkPoetryApplication

Creates a Python application using the Python interpreter specified based on the designated poetry project and lock files. mkPoetryApplication takes an attribute set with the following attributes (attributes without default are mandatory):

• projectDir: path to the root of the project.
• src: project source (default: cleanPythonSources { src = projectDir; }).
• pyproject: path to pyproject.toml (default: projectDir + "/pyproject.toml").
• poetrylock: poetry.lock file path (default: projectDir + "/poetry.lock").
• overrides: Python overrides to apply (default: [defaultPoetryOverrides]).
• meta: application meta data (default: {}).
• python: The Python interpreter to use (default: pkgs.python3).

Other attributes are passed through to buildPythonApplication.

Example

poetry2nix.mkPoetryApplication {
    projectDir = ./.;
}

See ./pkgs/poetry/default.nix for a working example.

mkPoetryEnv

Creates an environment that provides a Python interpreter along with all dependencies declared by the designated poetry project and lock files. mkPoetryEnv takes an attribute set with the following attributes (attributes without default are mandatory):

• projectDir: path to the root of the project.
• pyproject: path to pyproject.toml (default: projectDir + "/pyproject.toml").
• poetrylock: poetry.lock file path (default: projectDir + "/poetry.lock").
• overrides: Python overrides to apply (default: [defaultPoetryOverrides]).
• python: The Python interpreter to use (default: pkgs.python3).

Example

poetry2nix.mkPoetryEnv {
    projectDir = ./.;
}

See ./tests/env/default.nix for a working example.

mkPoetryPackages

Creates an attribute set of the shape { python, poetryPackages, pyProject, poetryLock }. Where python is the interpreter specified, poetryPackages is a list of all generated python packages, pyProject is the parsed pyproject.toml and poetryLock is the parsed poetry.lock file. mkPoetryPackages takes an attribute set with the following attributes (attributes without default are mandatory):

• projectDir: path to the root of the project.
• pyproject: path to pyproject.toml (default: projectDir + "/pyproject.toml").
• poetrylock: poetry.lock file path (default: projectDir + "/poetry.lock").
• overrides: Python overrides to apply (default: [defaultPoetryOverrides]).
• python: The Python interpreter to use (default: pkgs.python3).

Example

poetry2nix.mkPoetryPackages {
    projectDir = ./.;
    python = python35;
}

defaultPoetryOverrides

poetry2nix bundles a set of default overrides that fix problems with various Python packages. These overrides are implemented in overrides.nix.

overrides.withDefaults

Returns a list containing the specified overlay and defaultPoetryOverrides.

Takes an attribute set with the following attributes (attributes without default are mandatory):

• src: project source directory

Example

poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    overrides = poetry2nix.overrides.withDefaults (self: super: { foo = null; });
}

See ./tests/override-support/default.nix for a working example.

overrides.withoutDefaults

Returns a list containing just the specified overlay, ignoring defaultPoetryOverrides.

Example

poetry2nix.mkPoetryEnv {
    projectDir = ./.;
    overrides = poetry2nix.overrides.withoutDefaults (self: super: { foo = null; });
}

cleanPythonSources

Provides a source filtering mechanism that:

• Filters gitignore's
• Filters pycache/pyc files
• Uses cleanSourceFilter to filter out .git/.hg, .o/.so, editor backup files & nix result symlinks

Example

poetry2nix.cleanPythonSources {
    src = ./.;
}

Contributing

Contributions to this project are welcome in the form of GitHub PRs. Please consider the following before creating PRs:

• This project uses nixpkgs-fmt for formatting the Nix code. You can use `nix-shell --run "nixpkgs-fmt ." to format everything.
• If you are planning to make any considerable changes, you should first present your plans in a GitHub issue so it can be discussed.
• If you add new features please consider adding tests.

License

poetry2nix is released under the terms of the MIT license.