diff mbox

[v2] doc: Add guide how to specify dependencies for Python packages

Message ID 1476116123-20994-1-git-send-email-h.goebel@crazy-compilers.com
State New
Headers show

Commit Message

Hartmut Goebel Oct. 10, 2016, 4:15 p.m. UTC
* doc/guix.texi (Python Modules): New sub-subsection "Specifying
  Dependencies".
---
 doc/guix.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

Comments

Ludovic Courtès Oct. 12, 2016, 9 p.m. UTC | #1
Hartmut Goebel <h.goebel@crazy-compilers.com> skribis:

> * doc/guix.texi (Python Modules): New sub-subsection "Specifying
>   Dependencies".

I’ve rewritten parts of it, mostly to provide more context to a
non-Pythonista like me.

Several uses of the cross-reference commands (@xref, @ref, etc.)  were
incorrect.  They’re a bit tricky to get right, see
<https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Cross-References.html>.

I’m pushing it in a minute, let me know if I introduced any mistakes in
the process!

Thanks,
Ludo’.
Hartmut Goebel Oct. 13, 2016, 1:18 p.m. UTC | #2
Hi Ludo,

> I’ve rewritten parts of it, mostly to provide more context to a
> non-Pythonista like me.

Yes, that's fine. Thanks.
diff mbox

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index 57821c5..6d74f4e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12251,6 +12251,53 @@  starts with @code{py} (e.g. @code{pytz}), we keep it and prefix it as
 described above.
 
 
+@subsubsection Specifying Dependencies
+@cindex inputs, for Python packages
+
+This section helps mapping the parameters given to @code{setup()} in the
+@file{setup.py} file to the different types of package inputs
+@xref{package Reference}.  To verify and detail the information found
+in @file{setup.py} it is recommended to @command{grep} the source, and
+have a look at any @file{requirements.txt}, @file{tox.ini}, or
+@file{.travis.yml} file.
+
+@itemize
+
+@item
+Python packages required at run time need to go into @pxref{package
+Reference, @code{propagated-inputs}}. These are typically defined in
+@code{install_requires}, or in a @file{requirements.txt} file.
+
+@item
+Python packages required only for building (e.g. to be found in
+@code{setup_requires}) or testing (e.g. to be found in
+@code{tests_require}) go into @pxref{package
+Reference, @code{native-inputs}}.  Examples are @emph{setuptools},
+@emph{pytest}, @emph{mock}, and @emph{nose}.  Of course if any of these
+packages is required at run-time, it needs to go to
+@code{propagated-inputs}.
+
+@item
+@code{inputs} only contain programs or C libraries required for building
+Python packages containing C extensions.
+
+@item
+If a Python package has optional dependencies (@code{extras_require}),
+these are not listed here at all--except if these are used for testing
+in which case they go to @code{native-inputs}.
+
+@item
+If a packages has complicated optional extra dependencies you may want
+to define another package to ease resolving these dependencies for the
+user.  E.g. @code{python-abcdef-ssh} inherits @code{python-abcdef} and
+adds the dependencies required for the @emph{ssh} extra feature.
+
+Optional dependencies are discusses in detail in @ref{Submitting
+Patches}.
+
+@end itemize
+
+
 @node Perl Modules
 @subsection Perl Modules