python: update documentation #48132
python: update documentation #48132
Conversation
This touches up a handful of places in the python documentation to try to make the current best-practices more obvious. In particular, I often find the function signatures (what to pass, what not to pass) confusing and have added them to the docs. Also updated the metas to be more consistent with the most frequently used modern style.
| @@ -655,6 +654,9 @@ Another difference is that `buildPythonPackage` by default prefixes the names of | |||
| the packages with the version of the interpreter. Because this is irrelevant for | |||
| applications, the prefix is omitted. | |||
|
|
|||
| When packaging a python application with `buildPythonApplication`, it should be | |||
| invoked with `callPackage` and passed `python` or `pythonPackages`. | |||
There was a problem hiding this comment.
One of the issues with the python packages is that there are a handful of historical bad examples floating around. In this PR I'm making an effort to start noting some of the best practices, though there's more editing to be done for sure.
There was a problem hiding this comment.
Maybe show an example of a Python application?
|
|
||
| src = fetchPypi { | ||
| inherit pname version; | ||
| sha256 = "cf8436dc59d8695346fcd3ab296de46425ecab00d64096cebe79fb51ecb2eb93"; | ||
| }; | ||
|
|
||
| preCheck = '' |
There was a problem hiding this comment.
Maybe this should be a patchPhase?
There was a problem hiding this comment.
postPatch so that patches can still be used
| @@ -186,7 +186,7 @@ building Python libraries is `buildPythonPackage`. Let's see how we can build th | |||
| `toolz` package. | |||
|
|
|||
| ```nix | |||
| { # ... | |||
| { lib, buildPythonPackage, fetchPypi }: | |||
There was a problem hiding this comment.
I think it's useful to have these to note that you don't just pass python to python modules.
|
Success on aarch64-linux (full log) Attempted: python Partial log (click to expand)
|
|
Success on x86_64-linux (full log) Attempted: python Partial log (click to expand)
|
|
Just a suggestion (while you are at it :D) if you have time, it would be cool to expand on how to provide python bindings for programs like gpgme/notmuch/bcc. There was some standard here I think #40470, like you should use { pythonSupport ? false/true } etc. Also this is not specific to python but maybe having a rationale in nixpkgs doc as to the "why" we do things like this could be interesting (though it could also be another PR). |
|
Success on aarch64-linux (full log) Attempted: python Partial log (click to expand)
|
|
Success on x86_64-linux (full log) Attempted: python Partial log (click to expand)
|
This touches up a handful of places in the python documentation to try to make
the current best-practices more obvious. In particular, I often find the
function signatures (what to pass, what not to pass) confusing and have added
them to the docs.
Also updated the metas to be more consistent with the most frequently used
modern style.