doc/python: document fixed-point arguments (#271387) by doronbehar · Pull Request #477149 · NixOS/nixpkgs

doronbehar · 2026-01-05T13:27:39Z

Things done

Add a 👍 reaction to pull requests you find important.

MattSturgeon · 2026-01-05T14:13:51Z

Thanks for working on the docs!

I had assumed that fixpoint-args support was deliberately undocumented until support was fully backported to all supported versions (currently just 26.05 and 25.11) and had some time to incubate. This prevents confusion when someone reads the unstable docs and assumes that they apply equally to stable Nixpkgs.

I'll defer to @ShamrockLee w.r.t. when we're ready to publicly document fixpoint-args support.

ambroisie · 2026-01-05T14:43:59Z

doc/languages-frameworks/python.section.md

+    pname = "pyspread";
+    inherit (finalAttrs) version;


I'd expect it to inherit pname as well, this is one of the few times I'd think using pname would be fine (as opposed to e.g: fetchFromGitHub's repo argument).

It isn't really. We normalize pname (e.g. apply lowercasing), but the pypi name may not reflect that, so it is often untied.

it is often untied

So this means while this documentation suggest untying it, tying pname is also accepted?

Yeah, it might be stable, if the library name already is normalized, but uppercase, dashes, etc. will cause flapping every once in a while.

Even if you do reuse the name for pname and src.pname, it's best to use a locally defined variable rather than finalAttrs.pname. Values in finalAttrs represent the final state, including any user defined overrides.

pname is an example of something an end-user may wish to override, e.g. pname = prevAttrs.pname + "-with-my-tweaks". Such an override shouldn't propagate to the src's project.

Sigmanificient

Lets use this opportunity to document arguments unable to referenced directly in finalAttrs, such as format or optional-dependency. See:

#477007

doronbehar · 2026-01-06T15:03:18Z

Thanks for the suggestion @Sigmanificient , I'm not sure about the full list of those, so I wrote only optional-dependencies and format. When you linked https://github.com/NixOS/nixpkgs/pull/271387/changes#diff-c263b18f23de7c1f00ed846783c3b977718aae8cdfdd89fc82adcf365d1d8bebR107-R120 I wasn't sure what is the full list of attributes.

Sigmanificient · 2026-01-06T15:11:04Z

@ShamrockLee might be able to give you a proper list

MattSturgeon · 2026-01-06T15:50:42Z

Thanks for the suggestion @Sigmanificient , I'm not sure about the full list of those, so I wrote only optional-dependencies and format. When you linked #271387 (changes) I wasn't sure what is the full list of attributes.

This isn't just some args being passthru attrs instead of derivation attrs, it's also some args being entirely renamed to other attrnames. The most prominent example is renaming everything checkPhase related to installCheckPhase, mostly for historic reasons.¹

That is already documented under #testing-python-packages, so we probably need a separate PR to consolidate the "args to buildPythonPackage" vs "final attrs to mkDerivation" difference and clarify that finalAttrs itself comes from the underlying mkDerivation call not the outer buildPythonPackage call.

Taking a step back, I don't think it's practical to list every single attr that is or isn't accessed via passthru² and every single attr that gets transformed or renamed when calling the underlying mkDerivation. Instead, I think the docs should focus on highlighting that there is an intermediate step and clarify with a few demonstrative examples.

↩
these kinda manually maintained exhaustive docs are a nightmare to maintain and keep in-sync with reality. ↩

ShamrockLee · 2026-01-06T16:48:50Z

Thanks for the suggestion @Sigmanificient , I'm not sure about the full list of those, so I wrote only optional-dependencies and format. When you linked https://github.com/NixOS/nixpkgs/pull/271387/changes#diff-c263b18f23de7c1f00ed846783c3b977718aae8cdfdd89fc82adcf365d1d8bebR107-R120 I wasn't sure what is the full list of attributes.

You can find them by seeing both excludeDrvArgNames and passthru, and see if their intersections are referenced as finalAttrs.passthru.${name} somewhere elde inside extendDrvArgs.

As GitHub mobile is suffering from https://github.com/orgs/community/discussions/181590 , could someone help me start a review comment thread targeting lines from NOTE: to the end of the argument list? I will be able to post a suggestion then.

doronbehar · 2026-01-06T17:04:10Z

doc/languages-frameworks/python.section.md

+NOTE: The following attributes, are not available in `finalAttrs`, but are available in `finalAttrs.passthru`:
+
+- `format`
+- `optional-dependencies`


@ShamrockLee please suggest something different here.

Suggested change

NOTE: The following attributes, are not available in `finalAttrs`, but are available in `finalAttrs.passthru`:

- `format`

- `optional-dependencies`

::: {.note}

Some `buildPythonPackage`/`buildPythonApplication` arguments are passed down to `stdenv.mkDerivation` via `passthru` instead of passing directly.

Their final states can be accessed via `finalAttrs.passthru.${name}`, and they can be overridden via [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs) under the `passthru` attribute.

Such arguments include:

- `disabled`

- `pyproject`

- `build-system`, `dependencies` and `optional-dependencies`

:::

This looks good to me, @MattSturgeon what do you think?

As always, we could polish the wording a little. But, yes it LGTM.

I still feel like a followup PR may be able to consolidate some of the "be aware: the args you pass to buildPythonPackage are not the same as what's in finalAttrs" documentation, as per my rambling in #477149 (comment)

As always, we could polish the wording a little. But, yes it LGTM.

I reworded it a little bit, I hope it is better.

I still feel like a followup PR may be able to consolidate some of the "be aware: the args you pass to buildPythonPackage are not the same as what's in finalAttrs" documentation, as per my rambling in #477149 (comment)

I agree, but I feel this topic is going under substantial changes and it might be better to document this subject once we are satisfied with the behavior :). See also my  comment there.

Seems reasonable overall 👍🏻

If I'm nitpicking,

Don't worry about it, I'm patient and your comments are great 👍 .

it feels odd to explicitly mention overrideAttrs here:

Therefore the final states of these attributes can be accessed via finalAttrs.passthru.${name}, and they can be overridden via <pkg>.overrideAttrs under the passthru attribute.

...overrideAttrs uses the same finalAttrs fixpoint arg as mkDerivation (and by extension buildPythonPackage), so calling it out explicitly with an "and" feels like we're implying it does things differently.

That said, I get where you're coming from. It's probably helpful to highlight that this "finalAttrs is different to the initial args" quirk also applies in overrideAttrs.

TBH I'm not sure I fully understood how you understood the docs I read :). I think when @ShamrockLee chose to explicitly mention overrideAttrs they did that to imply to use .overrideAttrs and not .overridePythonAttrs, since the latter doesn't support the signature (finalAttrs: prevAttrs: {}). I tried to do that while not shaming ourselves that this feature is not yet supported due to #258246 :). The TODO comment below is the comment that should remind us to update that text once #258246 is resolved.

Maybe we can be optimistic that #258246 will be resolved soon and we can postpone this .note phrasing to afterwards? There were other voices who wanted to hold back this PR a little bit to let this new exciting feature stabilize.

How about:

Their final states can be accessed via `finalAttrs.passthru.${name}`, or overridden via [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs) in the same way.

The TODO comment below is the comment that should remind us to update that text once #258246 is resolved.

Personally, I'm in favour of adding finalAttrs support to overridePythonAttrs. It's actually a trivial change (I had a patch somewhere, but I can't find it to link).

I think the main argument against doing so is the desire to deprecate overridePythonAttrs entirely, in favor of exclusively using overrideAttrs:

As for overridePythonAttrs, it should be deprecated after overrideAttrs for Python packages is ready.
-- #258246 (comment)

I personally hope to push overrideAttrs, but recognize that overridePythonAttrs are still widely used and that Python packages' overrideAttrsinterface still has some unsettled parts (i.e., the check/installCheck attributes).
-- #258246 (comment)

Personally, I don't see the two ideas as mutually exclusive; we could add fixpoint-arg support now and still deprecate the function later, if we wanted to.

On the basis that its future direction is uncertain, I'm on the fence w.r.t. including the TODO comment, but I won't block on it 🙂

There were other voices who wanted to hold back this PR a little bit to let this new exciting feature stabilize.

I think that was just me justifying why we initially merged fixpoint-args support without new docs. Once @ShamrockLee is happy for this to be documented, I am too.

I think the main argument against doing so is the desire to deprecate overridePythonAttrs entirely, in favor of exclusively using overrideAttrs:

OK I see, I wasn't aware of that since I haven't read thoroughly all of #258246. I have revised the TODO comment a bit to reflect that.

I personally hope to push overrideAttrs, but recognize that overridePythonAttrs are still widely used and that Python packages' overrideAttrsinterface still has some unsettled parts (i.e., the check/installCheck attributes).
-- #258246 (comment)

@doronbehar Could you please help me recover the content of the quoted comment from your mailbox? GitHub Mobile tricked me into deleting it.

You mean this?

It is from another thread technically.

doc/languages-frameworks/python.section.md

Co-authored-by: Matt Sturgeon <matt@sturgeon.me.uk>

nixpkgs-ci bot requested review from mweinelt and natsukium January 5, 2026 13:32

doronbehar force-pushed the doc/buildPython@fixed-point branch from 5ad3d8b to 99403d3 Compare January 5, 2026 13:42

doc/python: document fixed-point arguments (NixOS#271387)

5339e49

doronbehar force-pushed the doc/buildPython@fixed-point branch from 99403d3 to 5339e49 Compare January 5, 2026 13:47

nixpkgs-ci bot requested a review from GetPsyched January 5, 2026 13:52

doronbehar mentioned this pull request Jan 5, 2026

buildPython*: support fixed-point arguments #271387

Merged

13 tasks

MattSturgeon requested review from MattSturgeon and ShamrockLee January 5, 2026 14:14

ambroisie reviewed Jan 5, 2026

View reviewed changes

Sigmanificient reviewed Jan 5, 2026

View reviewed changes

ShamrockLee mentioned this pull request Jan 5, 2026

Tracking: Python packages' overrideAttrs overriding and finalAttrs referencing #379602

Open

doronbehar commented Jan 6, 2026

View reviewed changes

doronbehar force-pushed the doc/buildPython@fixed-point branch 2 times, most recently from fe37bc4 to bd1e678 Compare January 7, 2026 00:45

mdaniels5757 added the backport release-25.11 Backport PR automatically label Jan 7, 2026

natsukium mentioned this pull request Jan 7, 2026

python3Packages.yamlcore: init at 0.0.4 #471711

Merged

1 task

python.section.md: List finalAttrs.passthru only attributes

ad54fe3

doronbehar force-pushed the doc/buildPython@fixed-point branch from bd1e678 to ad54fe3 Compare January 7, 2026 12:42

MattSturgeon reviewed Jan 7, 2026

View reviewed changes

doc/languages-frameworks/python.section.md Outdated Show resolved Hide resolved

ShamrockLee mentioned this pull request Jan 12, 2026

Python: overridePythonAttrs should support final: prev: style overrides #258246

Open

doronbehar and others added 2 commits January 12, 2026 20:44

doc/python: explain better passthru note

daf1d46

Co-authored-by: Matt Sturgeon <matt@sturgeon.me.uk>

doc/python: simplify packageOverrides example

5ac2996

doronbehar force-pushed the doc/buildPython@fixed-point branch from 424a126 to 5ac2996 Compare January 12, 2026 18:54

-NOTE: The following attributes, are not available in `finalAttrs`, but are available in `finalAttrs.passthru`:
-- `format`
-- `optional-dependencies`
+::: {.note}
+Some `buildPythonPackage`/`buildPythonApplication` arguments are passed down to `stdenv.mkDerivation` via `passthru` instead of passing directly.
+Their final states can be accessed via `finalAttrs.passthru.${name}`, and they can be overridden via [`<pkg>.overrideAttrs`](#sec-pkg-overrideAttrs) under the `passthru` attribute.
+Such arguments include:
+- `disabled`
+- `pyproject`
+- `build-system`, `dependencies` and `optional-dependencies`
+:::

Uh oh!

Conversation

doronbehar commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Things done

Uh oh!

MattSturgeon commented Jan 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MattSturgeon Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Sigmanificient left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

doronbehar commented Jan 6, 2026

Uh oh!

Sigmanificient commented Jan 6, 2026

Uh oh!

MattSturgeon commented Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Footnotes

Uh oh!

ShamrockLee commented Jan 6, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShamrockLee Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShamrockLee Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

doronbehar commented Jan 5, 2026 •

edited

Loading

MattSturgeon Jan 12, 2026 •

edited

Loading

Sigmanificient left a comment •

edited

Loading

MattSturgeon commented Jan 6, 2026 •

edited

Loading

ShamrockLee Jan 6, 2026 •

edited

Loading

ShamrockLee Jan 7, 2026 •

edited

Loading