Introduction
What is pyproject.nix
Pyproject.nix is a collection of Nix utilities to work with Python project metadata in Nix.
It mainly targets PEP-621 compliant pyproject.toml
files and data formats, but also implement support for other & legacy formats such as Poetry & requirements.txt
.
Pyproject.nix aims to be a swiss army knife of simple customizable utilities that works together with the nixpkgs Python infrastructure.
Foreword
This documentation only helps you to get started with pyproject.nix
.
As it's a toolkit with many use cases not every use case can be documented fully.
This documentation is centered around packaging Python applications & managing development environments. For other use cases see the reference documentation.
Concepts
pyproject.nix
introduces a few high level abstract concepts.
The best way to get started is to understand these concepts and how they fit together.
Project
A project
attribute set is a high-level representation of a project that includes:
- The parsed
pyproject.toml
file - Parsed dependencies
- Project root directory
It can can be loaded from many different sources:
- PEP-621
pyproject.toml
- PEP-621
pyproject.toml
with PDM extensions - Poetry
pyproject.toml
requirements.txt
Validators
Validators work on dependency constraints as defined in a project
and offers validation for them.
This can be useful to check that a package set is compilant with the specification.
Renderers
A renderer
takes a project
together with a Python interpreter derivation and renders it into a form understood by various pieces of nixpkgs Python infrastructure.
For example: The buildPythonPackage
renderer returns an attribute set that can be passed to either nixpkgs function buildPythonPackage
or buildPythonApplication
.
There might be information missing from what a renderer returned depending on what can be computed from the project
.
If any attributes are missing you can manually merge your own attribute set with what the renderer returned.
Tying it together
For a concrete example use see Use cases -> pyproject.toml.