This is an automated email from the git hooks/post-receive script.
guix_mirror_bot pushed a commit to branch master
in repository guix.
The following commit(s) were added to refs/heads/master by this push:
new e4cc67782e doc: Refresh python documentation.
e4cc67782e is described below
commit e4cc67782eb2e68428e38973c580f371122b2f14
Author: Nicolas Graves <[email protected]>
AuthorDate: Sat Sep 27 12:30:34 2025 +0200
doc: Refresh python documentation.
* doc/contributing.texi: Refresh python documentation (avoid uses of
"we " and "you", remove the reference to pyproject-build-system as
experimental, and adjust the setuptools situation comments).
Merges: https://codeberg.org/guix/guix/pulls/6427
Change-Id: Idb065befc975063ad97e6bdafb724e50d6891cb5
Reviewed-by: Yan Abu Arab <[email protected]>
Reviewed-by: Maxim Cournoyer <[email protected]>
Signed-off-by: Sharlatan Hellseher <[email protected]>
---
doc/contributing.texi | 73 +++++++++++++++++++++++----------------------------
1 file changed, 33 insertions(+), 40 deletions(-)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index eb5e7f760a..f1ab1b56da 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -1514,37 +1514,30 @@ satisfied.
@subsection Python Modules
@cindex python
-We currently package Python 2 and Python 3, under the Scheme variable names
-@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
-To avoid confusion and naming clashes with other programming languages, it
-seems desirable that the name of a package for a Python module contains
-the word @code{python}.
-
-Some modules are compatible with only one version of Python, others with
-both. If the package Foo is compiled with Python 3, we name it
-@code{python-foo}. If it is compiled with Python 2, we name it
-@code{python2-foo}. Python 2 packages are being removed from the
-distribution; please do no not submit any new Python 2 packages.
-
-If a project already contains the word @code{python}, we drop this;
-for instance, the module python-dateutil is packaged under the names
-@code{python-dateutil} and @code{python2-dateutil}. If the project name
-starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
-described above.
+The standard way to generate a package definition is to use
+@code{guix import pypi <name>}, where @var{name} is the name of the
+Python package on @url{https://pypi.org, PyPI}, see @pxref{Invoking guix
+import}. Please check with @code{guix lint <package-name>} that the
+generated package is valid.
+
+To avoid confusion and naming clashes with other programming languages,
+Python module packages should be prefixed with @code{python-}.
+
+If a project already contains the word @code{python}, please do not
+repeat it; for instance, the module python-dateutil is packaged under
+the name @code{python-dateutil}. If the project name starts with
+@code{py}, it is kept and prefixed as described above (e.g.@:
+@code{python-pytz}).
@quotation Note
-Currently there are two different build systems for Python packages in Guix:
-@var{python-build-system} and @var{pyproject-build-system}. For the
-longest time, Python packages were built from an informally specified
-@file{setup.py} file. That worked amazingly well, considering Python's
-success, but was difficult to build tooling around. As a result, a host
-of alternative build systems emerged and the community eventually settled on a
-@url{https://peps.python.org/pep-0517/, formal standard} for specifying build
-requirements. @var{pyproject-build-system} is Guix's implementation of this
-standard. It is considered ``experimental'' in that it does not yet support
-all the various PEP-517 @emph{build backends}, but you are encouraged to try
-it for new Python packages and report any problems. It will eventually be
-deprecated and merged into @var{python-build-system}.
+The standard build system for Python packages is Guix's implementation
+of the @url{https://peps.python.org/pep-0517/, formal Python standard}
+for specifying build requirements: @var{pyproject-build-system}.
+The @var{python-build-system} which corresponds to the way Python
+packages were built before PEP517, using the informally specified
+@file{setup.py} file, is now deprecated. @var{pyproject-build-system}
+will eventually be deprecated and renamed into
+@var{python-build-system} after its removal.
@end quotation
@subsubsection Specifying Dependencies
@@ -1556,21 +1549,21 @@ package source tree, with varying degrees of accuracy:
in the
@file{requirements.txt}, or in @file{tox.ini} (the latter mostly for
test dependencies).
-Your mission, when writing a recipe for a Python package, is to map
-these dependencies to the appropriate type of ``input'' (@pxref{package
+When editing a recipe for a Python package, the goal is to map these
+dependencies to the appropriate type of ``input'' (@pxref{package
Reference, inputs}). Although the @code{pypi} importer normally does a
-good job (@pxref{Invoking guix import}), you may want to check the
-following check list to determine which dependency goes where.
+good job (@pxref{Invoking guix import}), please verify the following
+check list to determine which dependency goes where.
@itemize
@item
-We currently package Python with @code{setuptools} and @code{pip}
-installed per default. This is about to change, and users are encouraged
-to use @code{python-toolchain} if they want a build environment for Python.
+Python is packaged @emph{without} @code{setuptools} and @code{pip}
+installed per default. @code{python-toolchain} provides a build
+environment for Python.
-@command{guix lint} will warn if @code{setuptools} or @code{pip} are
-added as native-inputs because they are generally not necessary.
+@command{guix lint} will warn if @code{pip} or other unneeded
+native-inputs are added.
@item
Python dependencies required at run time go into
@@ -1585,9 +1578,9 @@ Python packages required only at build time---e.g., those
listed under
for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into
@code{native-inputs}. The rationale is that (1) they do not need to be
propagated because they are not needed at run time, and (2) in a
-cross-compilation context, it's the ``native'' input that we'd want.
+cross-compilation context, it's the target ``native'' input.
-Examples are the @code{pytest}, @code{mock}, and @code{nose} test
+Examples are the @code{pytest}, @code{mock}, and @code{stestr} test
frameworks. Of course if any of these packages is also required at
run-time, it needs to go to @code{propagated-inputs}.
