04/04: doc: Add guide on how to specify dependencies for Python packages.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit e940a2713dc16c470b0ac7d94f3ee3a9e1251f3d
Author: Hartmut Goebel <address@hidden>
Date:   Mon Oct 10 18:15:23 2016 +0200

    doc: Add guide on how to specify dependencies for Python packages.
    
    * doc/guix.texi (Python Modules): New sub-subsection "Specifying
    Dependencies".
    
    Co-authored-by: Ludovic Courtès <address@hidden>
---
 doc/guix.texi |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 1f6e0bb..74733f4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12345,6 +12345,54 @@ starts with @code{py} (e.g. @code{pytz}), we keep it 
and prefix it as
 described above.
 
 
address@hidden Specifying Dependencies
address@hidden inputs, for Python packages
+
+Dependency information for Python packages is usually available in the
+package source tree, with varying degrees of accuracy: in the
address@hidden file, in @file{requirements.txt}, or in @file{tox.ini}.
+
+Your mission, when writing a recipe for a Python package, 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.
+
address@hidden
+
address@hidden
+Python dependencies required at run time go into
address@hidden  They are typically defined with the
address@hidden keyword in @file{setup.py}, or in the
address@hidden file.
+
address@hidden
+Python packages required only at build time---e.g., those listed with
+the @code{setup_requires} keyword in @file{setup.py}---or only for
+testing---e.g., those in @code{tests_require}---go into
address@hidden  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.
+
+Examples are @code{setuptools}, which is usually needed only at build
+time, or the @code{pytest}, @code{mock}, and @code{nose} test
+frameworks.  Of course if any of these packages is also required at
+run-time, it needs to go to @code{propagated-inputs}.
+
address@hidden
+Anything that does not fall in the previous categories goes to
address@hidden, for example programs or C libraries required for building
+Python packages containing C extensions.
+
address@hidden
+If a Python package has optional dependencies (@code{extras_require}),
+it is up to you to decide whether to add them or not, based on their
+usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix
+size}}).
+
address@hidden itemize
+
+
 @node Perl Modules
 @subsection Perl Modules