mirror of
https://github.com/vale981/poetry2nix
synced 2025-03-05 09:11:39 -05:00
Provide API documentation in README
This provides a more complete API documetnation covering the public interface of poetry2nix
This commit is contained in:
Tobias Pflug
parent
e731e88a74
commit
47d9dfa46a
1 changed files with 79 additions and 23 deletions
102
README.md
102
README.md
|
|
@ -1,58 +1,114 @@
|
|||
[](https://gitlab.com/nix-community/poetry2nix/-/jobs)
|
||||
|
||||
# poetry2nix
|
||||
poetry2nix turns [Poetry](https://poetry.eustace.io/) 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.
|
||||
_poetry2nix_ turns [Poetry](https://poetry.eustace.io/) 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.
|
||||
|
||||
## Usage
|
||||
## API
|
||||
|
||||
poetry2nix has 2 main use-cases:
|
||||
The _poetry2nix_ public API consists of the following attributes:
|
||||
|
||||
- `mkPoetryApplication`: For building poetry based Python applications.
|
||||
- `mkPoetryEnv`: For creating a python environment with the dependencies of a `poetry.lock` file.
|
||||
|
||||
## Notes
|
||||
|
||||
Whenever possible poetry2nix uses source archives to install Python dependencies. Some packages however only provide binaries in
|
||||
the form of `.whl` files. If no source archives are provided, `poetry2nix` tries to select an appropriate `manylinux` binary and
|
||||
automatically adds the required dependencies to the python package. **Note** that for manylinux packages to work you need to use
|
||||
very recent nixpkgs.
|
||||
|
||||
## Examples
|
||||
- [mkPoetryApplication](#mkPoetryApplication): Creates a Python application.
|
||||
- [mkPoetryEnv](#mkPoetryEnv): Creates a Python environment with an interpreter and all packages from `poetry.lock`.
|
||||
- [mkPoetryPackages](#mkPoetryPackages): Creates an attribute set providing access to the generated packages and other artifacts.
|
||||
- [defaultPoetryOverrides](#defaultPoetryOverrides): A set of bundled overrides fixing problems with Python packages.
|
||||
- [overrides.withDefaults](#overrides.withDefaults): A convenience function for specifying overrides on top of the defaults.
|
||||
- [overrides.withoutDefaults](#overrides.withoutDefaults): A convenience function for specifying overrides without defaults.
|
||||
|
||||
### 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):
|
||||
|
||||
- **src**: project source.
|
||||
- **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]`).
|
||||
- **meta**: application [meta](https://nixos.org/nixpkgs/manual/#chap-meta) data (_default:_ `{}`).
|
||||
- **python**: The Python interpreter to use (_default:_ `pkgs.python3`).
|
||||
|
||||
#### Example
|
||||
```nix
|
||||
poetry2nix.mkPoetryApplication {
|
||||
src = lib.cleanSource ./.;
|
||||
pyproject = ./pyproject.toml;
|
||||
poetrylock = ./poetry.lock;
|
||||
python = python3;
|
||||
projectDir = ./.;
|
||||
}
|
||||
```
|
||||
|
||||
See [./pkgs/poetry/default.nix](./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
|
||||
```nix
|
||||
poetry2nix.mkPoetryEnv {
|
||||
poetrylock = ./poetry.lock;
|
||||
python = python3;
|
||||
projectDir = ./.;
|
||||
}
|
||||
```
|
||||
|
||||
The above expression returns a package with a python interpreter and all packages specified
|
||||
in the `poetry.lock` lock file. See [./tests/env/default.nix](./tests/env/default.nix) for a working example.
|
||||
See [./tests/env/default.nix](./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
|
||||
```nix
|
||||
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.nix).
|
||||
|
||||
### overrides.withDefaults
|
||||
Returns a list containing the specified overlay and `defaultPoetryOverrides`.
|
||||
|
||||
#### Example
|
||||
|
||||
```nix
|
||||
poetry2nix.mkPoetryEnv {
|
||||
projectDir = ./.;
|
||||
overrides = poetry2nix.overrides.withDefaults (self: super: { foo = null; });
|
||||
}
|
||||
```
|
||||
See [./tests/override-support/default.nix](./tests/override-support/default.nix) for a working example.
|
||||
|
||||
### overrides.withoutDefaults
|
||||
Returns a list containing just the specified overlay, ignoring `defaultPoetryOverrides`.
|
||||
|
||||
#### Example
|
||||
|
||||
```nix
|
||||
poetry2nix.mkPoetryEnv {
|
||||
projectDir = ./.;
|
||||
overrides = poetry2nix.overrides.withoutDefaults (self: super: { foo = null; });
|
||||
}
|
||||
```
|
||||
|
||||
## 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](https://github.com/nix-community/nixpkgs-fmt) for fomatting the Nix code. You can use
|
||||
- This project uses [nixpkgs-fmt](https://github.com/nix-community/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.
|
||||
_poetry2nix_ is released under the terms of the MIT license.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue