[PR PATCH] xbps-src: Explain python module dependencies in Manual.md

[ahesford <ahesford@users.noreply.github.com>]

[-- Attachment #1: Type: text/plain, Size: 468 bytes --]

There is a new pull request by ahesford against master on the void-packages repository

https://github.com/ahesford/void-packages pydocs
https://github.com/void-linux/void-packages/pull/23525

xbps-src: Explain python module dependencies in Manual.md
Proper handling of python module dependencies in xbps-src needs some clarification. This is a first attempt.

cc: @ericonr 

A patch file from https://github.com/void-linux/void-packages/pull/23525.patch is attached

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: github-pr-pydocs-23525.patch --]
[-- Type: text/x-diff, Size: 2785 bytes --]

From 3ccdb9cc5bb4d48a86a80efa44fe20c2384dd6aa Mon Sep 17 00:00:00 2001
From: "Andrew J. Hesford" <ajh@sideband.org>
Date: Sat, 11 Jul 2020 13:31:58 -0400
Subject: [PATCH] xbps-src: Explain python module dependencies in Manual.md

---
 Manual.md | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/Manual.md b/Manual.md
index 10082b68da5..a4bfb7dbcab 100644
--- a/Manual.md
+++ b/Manual.md
@@ -1444,9 +1444,25 @@ Python packages should be built with the `python{,2,3}-module` build style, if p
 This sets some environment variables required to allow cross compilation. Support to allow
 building a python module for multiple versions from a single template is also possible.
 
-To allow cross compilation, the `python-devel` package (for python 2.7) must be added
-to `hostmakedepends` and `makedepends`. If any other python version is also supported,
-for example python3.4, those must also be added as host and target build dependencies.
+If a python package includes a compiled extension, the `python-devel` (for python 2.7) or
+`python3-devel` (for python 3.X) packages should be added to `makedepends`. Generally,
+dependencies on `python-*` or `python3-*` packages should be included in `hostmakedepends` because
+the package build process often requires the host interpreter be run with the necessary packages
+available. In most cases, especially those with pure-python dependencies, it is not necessary to
+duplicate these in `makedepends`. Exceptions are dependencies that provide both a python modul and
+libraries or headers against which extensions will be built (*e.g.*, `python3-numpy`). In these
+cases, the packages should typically be listed in both `hostmakedepends` and `makedepends`.
+
+**NB**: Specifying `python-*` or `python3-*` dependencies in `makedepends` rather than
+`hostmakedepends` may lead to non-reproducible packaging rather than obvious failures because the
+python `setuptools` package will attempt to use `pip` or `easy_install` to fetch missing
+dependencies on the host while building the package. There is currently no way to intercept this
+process and force packaging to fail when such dependencies are incorrectly specified. Care should
+be given when creating python package templates to watch the build process for warnings about
+falling back to the deprecated `EasyInstall` for handling dependencies, as this is a sign that
+`setuptools` is attempting to fetch depencies that should be specified in `hostmakedepends`.
+Another sign of missing `hostmakedepends` is the presence of an `.eggs` directory in `$wrksrc`,
+which is where `setuptools` places any dependencies that it fetches.
 
 The following variables may influence how the python packages are built and configured
 at post-install time: