nixpkgs manual: python section: interface reference coverage

[alejandrosame]

Context

This issue outlines the Python related nixpkgs interfaces. This outline surfaces the interfaces uncovered by the Python reference in the manual, but covered in the other sections of the Python documentation.

In order to address TODO#2 below, the outline proposes a new presentation structure which makes explicit the placement of the given interface from the root prepending pkgs. File representation of the interfaces is relevant information reserved for the content of each subsection.

Conventions used

• pkgs: At root level, it corresponds with all attributes exposed by nixpkgs, pkgs = import <nixpkgs>{}.
• ${python}: Represents a given Python interpreter attribute name. The writing hints at the reader to check the interpreters' table, pythonInterpreters.<TAB> or lib.attrNames pythonInterpreters for supported interpreters when in doubt.
• ${pypkg}: Represents a given Python package attribute name, e.g. pandas.
• ps: stands for nixpkgs package set, as used in the user guide. Note: It might be a good idea to use nixpkgs python package set to avoid confusion with other package sets inside nixpkgs.

TODO

• [ ] Align the reference presentation with the REPL and developer experience.

The outline is rooted in pkgs as the de-facto convention for nixpkgs. In the REPL, all attributes under pkgs tend to be immediately TAB-discoverable since it's common to call it with import <nixpkgs>{}, instead of {pkgs = import <nixpkgs>{};}.

• [ ] Cover missing interfaces inside the Reference section.

Each attribute in the outline is flagged inside parenthesis to note if it's documented/mentioned in the FAQ or user guide. These flags won't be used in the documentation source, they exist only to help navigate this task.

Outline

• [ ] pkgs
  • [ ] fetchPypi (in user guide)
  • [ ] mkShell (in FAQ)
  • [ ] venvdir (in FAQ)
  • [x] ${python}
  • [x] buildEnv (in FAQ, user guide)
    • [x] env
    • [x] extraLibs
    • [x] ignoreCollisions
    • [x] permitUserSite
    • [x] postBuild
  • [x] executable
  • [x] interpreter
  • [x] libPrefix
  • [ ] packageOverrides (in FAQ)
  • [x] ${python}Packages
  • [x] pkgs (in FAQ, user guide)
    • [x] buildPythonApplication
    • [x] buildPythonPackage (in FAQ, user guide)
    • [ ] buildInputs (in FAQ, user guide)
      • [ ] postShellHook (in FAQ)
      • [ ] postVenvCreation (in FAQ)
    • [ ] CFLAGS (in user guide)
    • [x] buildPhase
    • [x] catchConflicts
    • [ ] checkPhase (in FAQ, in user guide)
    • [x] disabled
    • [ ] disabledTests (in user guide)
    • [ ] disabledTestPaths (in user guide)
    • [x] doCheck (in user guide)
    • [x] dontWrapPythonPrograms
    • [x] format
    • [x] installCheck
    • [x] installPhase
    • [ ] LDFLAGS (in user guide)
    • [x] makeWrappersArgs
    • [x] namePrefix
    • [x] nativeBuildInputs (in user guide)
    • [x] nativeCheckInputs
    • [x] overridePythonAttrs
    • [x] permitUserSite
    • [x] pipInstallFlags
    • [x] postFixup
    • [ ] preInstall (in FAQ)
    • [x] preShellHook
    • [x] propagatedBuildInputs (in user guide)
    • [ ] pytestFlagsArray (in user guide)
    • [ ] pythonImportsCheck (in user guide)
    • [x] pythonPath
    • [ ] pythonRelaxDeps (in user guide)
    • [ ] pythonRemoveDeps (in user guide)
    • [x] removeBinByteCode
    • [x] setupPyBuildFlags
    • [x] setupPyGlobalFlags
    • [x] shellPhase
    • [ ] sphinxBuilders (in user guide)
    • [ ] sphinxRoot (in user guide)
    • [ ] src (custom logic for development mode, in user guide)
    • [ ] unittestFlagsArray (in user guide)
    • [x] override
    • [ ] enableOptimizations (in FAQ)
    • [ ] reproducibleBuild (in FAQ)
    • [ ] python (in FAQ)
    • [x] toPythonApplication
    • [x] toPythonModule
    • [ ] ${pypkg}
    • [ ] overridePythonAttrs (in FAQ)
  • [x] setupHooks
    • [x] eggBuildHook
    • [x] eggInstallHook
    • [x] eggUnpackHook
    • [x] flitBuildHook
    • [x] pipBuildHook
    • [x] pipInstallHook
    • [x] pytestCheckHook (in FAQ, user guide)
    • [x] pythonCatchConflictsHook
    • [x] pythonImportsCheckHook
    • [x] pythonRelaxDepsHook (user guide)
    • [x] pythonRemoveBinBytecodeHook
    • [x] setuptoolsBuildHook
    • [x] setuptoolsCheckHook
    • [x] sphinxHook (in user guide)
    • [x] unittestCheckHook (in user guide)
    • [x] venvShellHook (in FAQ)
    • [x] wheelUnpackHook
  • [x] sitePackages
  • [x] withPackages (in FAQ, user guide)

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-08-23-documentation-team-meeting-notes-75/32142/1

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/making-packages-projects-available-to-nixos/38462/3