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

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

[Hartmut Goebel]

* doc/guix.texi (Python Modules): New sub-subsection "Specifying
  Dependencies".
---
 doc/guix.texi | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index 9bd8b43..f51ab75 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -12194,6 +12194,43 @@ 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
+
+@itemize
+
+@item
+All Python package required at run-time need to go into
+@code{propagated-inputs}.  These are typically defined in
+@code{install_requires} or in a requirements-file.
+
+@item
+Python packages required only for building (to be found e.g. in
+@code{setup_requires}) or testing (to be found e.g. in
+@code{tests_require}) go into @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 be
+set in @code{propagated-inputs}.
+
+@item
+@code{inputs} only contain programs or C-libraries (and such) required
+for building Python packages containing c-extensions (or such).
+
+@item
+If a Python package has optional extra dependencies
+(@code{extras_require}), not these are not listed here at all - except
+if there is a test-case in which case they are added 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.
+
+@end itemize
+
+
 @node Perl Modules
 @subsection Perl Modules
 
-- 
2.7.4

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

[Hartmut Goebel]

Am 04.10.2016 um 11:00 schrieb Hartmut Goebel:
> * doc/guix.texi (Python Modules): New sub-subsection "Specifying
>   Dependencies".

FYI: This documents what we discussed in
<http://lists.gnu.org/archive/html/guix-devel/2016-09/msg01450.html>.

I'll add a section about dependencies for Python applications in a later
patch. I first want to finish the work on the new python-build-system.

-- 
Regards
Hartmut Goebel

| Hartmut Goebel          | h.goebel@crazy-compilers.com               |
| www.crazy-compilers.com | compilers which you thought are impossible |

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

[Ludovic Courtès]

Hartmut Goebel <h.goebel@crazy-compilers.com> skribis:

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

Cool, thanks for working on it.

> +@subsubsection Specifying Dependencies
> +@cindex inputs, for Python packages
> +
> +@itemize

Could you add a sentence or two before @itemize to give some context?

> +@item
> +All Python package required at run-time need to go into

s/All Python package/Python packages/
s/run-time/run time/

> +@code{propagated-inputs}.  These are typically defined in
                           ^
(@pxref{package Reference, @code{propagated-inputs}})

> +@code{install_requires} or in a requirements-file.

Perhaps this is obvious to a seasoned Python programmer, but I think
we should clarify this:

  in the @code{install_requires} field of whatever(?), or in a
  @file{requirements.txt} file.

> +@item
> +Python packages required only for building (to be found e.g. in
> +@code{setup_requires}) or testing (to be found e.g. in

Remove “e.g.” here or put it at the beginning of the parenthetical
expression.

> +@code{tests_require}) go into @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 be
> +set in @code{propagated-inputs}.

s/to be set in/to go to/

I’m not entirely convinced that this is an improvement of what “package
Reference” says.  In particular, it describes ‘native-inputs’ as having
nothing to do with cross-compilation.  OTOH, it has the advantage of
providing concrete instructions to someone focusing on Python.

Thoughts?

> +@item
> +@code{inputs} only contain programs or C-libraries (and such) required
> +for building Python packages containing c-extensions (or such).

“C libraries” and “C extensions”; remove “(and/or such)”.

> +@item
> +If a Python package has optional extra dependencies

s/extra//

> +(@code{extras_require}), not these are not listed here at all - except
                            ^^^                                 ^^^
Remove “not”.
“at all---except”

> +if there is a test-case in which case they are added to
> +@code{native-inputs}.

“test case”

I’m not sure what “if there is a test case” means here; should it be “if
it is a test suite framework”?

> +
> +@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.

The question of optional dependencies in general is already covered in
“Submitting Patches”, item 5.

Could you send an updated patch?

Thanks,
Ludo’.

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

[Hartmut Goebel]

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

Hi Ludo,


thanks for the review and for proof-reading :-)

I'll send an updated patch in a few days, waiting for some more feedback
on this:


Am 06.10.2016 um 23:02 schrieb Ludovic Courtès:
>
>> +@code{tests_require}) go into @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 be
>> +set in @code{propagated-inputs}.
> I’m not entirely convinced that this is an improvement of what “package
> Reference” says.  In particular, it describes ‘native-inputs’ as having
> nothing to do with cross-compilation.  OTOH, it has the advantage of
> providing concrete instructions to someone focusing on Python.
>
> Thoughts?

My aim was to provide concrete instructions for those wanting to package
Python packages. But I will think about how to add some pointer to
cross-compilation.

From a Python programmers perspective, "cross-compilation" is a
non-issue in most cases. Most Python packages are pure Python, will be
compiled into byte-code and thus they are platform independent. (Much
like .jar files) This is why most python packages are marked as "noarch"
in other Linux distributions. As a Python programmer I think in terms of
build-time, maybe test-time and run-time.

This only exception for this are Python packages containing C-code
(called "extension modules")*.* But I have to admit that I have no clue
about cross-compiler these. (I do no even find good introductions on
this in the web.)

The official Python packaging guide [1] does not really talk about
cross-compilation. Only about "Cross-compiling on Windows".

[1] https://docs.python.org/3/distutils/builtdist.html

-- 
Regards
Hartmut Goebel

| Hartmut Goebel          | h.goebel@crazy-compilers.com               |
| www.crazy-compilers.com | compilers which you thought are impossible |


[-- Attachment #2: Type: text/html, Size: 2843 bytes --]

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

[Hartmut Goebel]

* doc/guix.texi (Python Modules): New sub-subsection "Specifying
  Dependencies".
---
 doc/guix.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)

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
 
-- 
2.7.4

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

[Ludovic Courtès]

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’.

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

[Hartmut Goebel]

Hi Ludo,

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

Yes, that's fine. Thanks.

-- 
Regards
Hartmut Goebel

| Hartmut Goebel          | h.goebel@crazy-compilers.com               |
| www.crazy-compilers.com | compilers which you thought are impossible |