From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chris Marusich Subject: Re: Please review: documentation for python build system Date: Tue, 15 Nov 2016 00:24:29 -0800 Message-ID: <87shqtdubm.fsf@gmail.com> References: <374a61a2-128e-12ca-7994-48961c9ef0ef@crazy-compilers.com> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:35241) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1c6Z2m-0005ik-4L for guix-devel@gnu.org; Tue, 15 Nov 2016 03:24:41 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1c6Z2k-0000Hr-Cm for guix-devel@gnu.org; Tue, 15 Nov 2016 03:24:40 -0500 Received: from mail-pg0-x231.google.com ([2607:f8b0:400e:c05::231]:33953) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1c6Z2k-0000HX-1o for guix-devel@gnu.org; Tue, 15 Nov 2016 03:24:38 -0500 Received: by mail-pg0-x231.google.com with SMTP id x23so61537805pgx.1 for ; Tue, 15 Nov 2016 00:24:37 -0800 (PST) In-Reply-To: <374a61a2-128e-12ca-7994-48961c9ef0ef@crazy-compilers.com> (Hartmut Goebel's message of "Sun, 13 Nov 2016 23:25:04 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Hartmut Goebel Cc: Guix-devel --=-=-= Content-Type: text/plain Content-Transfer-Encoding: quoted-printable Hi Hartmut! Thank you very much for the documentation. It is quite clear, and it helps clarify the background and intent of the new python build system. My comments below are primarily grammatical or stylistic. I hope you find my feedback helpful. Hartmut Goebel writes: > In Python there are different ways to install packages: distutils, > setuptools, easy_install and pip. All of these are sharing the file > setup.py, I suggest changing "All of these are sharing the file setup.py" to "All of these use a file named setup.py". > introduced with distutils in Python 2.0. setup.py can be considered I'm not sure how we feel about starting a sentence with a lower case character, even if it is the name of a file that is usually lower case. Perhaps start the sentence with "The setup.py file" to avoid it? > as a kind of Makefile accepting targets (or commands) like "build" and > "install". As of autumn 2016 the recommended way to install Python > packages is using pip. I suggest changing "using pip" to "using pip, which is a Python-specific package manager, since it was not clarified earlier. Also, should we capitalize Pip, too? > For both distutils and setuptools running "python setup.py install" is > the way to install Python packages.=20 Maybe put a comma between "setuptools" and "running" so it looks like this: "For both distutils and setuptools, running..." > With distutils the "install" command basically copies all packages > into /lib/pythonX.Y/site-packages. > > Some time later "setuptools" have been established to enhance > distutils.=20=20 I suggest changing "have been" to "was". > To use setuptools, the developer imports setuptools in setup.py. When > importing setuptools, the original "install" command gets overwritten > by setuptools' "install" command. > > easy_install and pip are both command-line tools capable to search and > download the package source from PyPI (the Python Package Index).=20=20 I suggest rephrasing this as "The command-line tools easy_install and pip are both capable of finding and downloading the package source..." > Both of them import setuptools and execute the "setup.py" file under > their control. Thus the "setup.py" behaves as if the developer had > imported setuptools within setup.py - even is still using only > distutils. > > Setuptools' "install" command (to be more precise: the "easy_install" > command which is called by "install") will put the path of the > currently installed version of each package and it's dependencies (as > declared in setup.py) into an "easy-install.pth" file. In guix=20 I suggest changing "guix" to "Guix" or "GNU Guix". It is my understanding that we prefer to capitalize Guix unless we're talking about a command invocation. > each packages gets it's own "site-packages" directory and thus an > "easy-install.pth" of it's own.=20=20 Change "it's" to "its" because this is the possessive form. > To avoid conflicts this file gets renamed to .pth in > phase rename-pth-file.=20=20 I suggest rewording this like so: "To avoid conflicts, the python build system renames the file to .pth in the phase rename-pth-file. > To ensure the .pth-file=20 I think referring to this as ".pth file", without a hyphen, is more correct. > will be process,=20 I suggest changing this to "will be processed by Python," or rephrase the whole sentence to be non-passive, like so: "To ensure that Python will process the .pth file..." > easy_install also creates a basic "site.py" in each "site-packages" > directory. The file is the same for all packages, thus there is no > need to rename it. Perhaps either add a sentence to explain what site.py is, or provide a link to a document that explains it. > The .pth-files contain the file-system paths (pointing to the store) > of all dependencies. So the dependency is hidden in the .pth file but > is not visible in the file-system. Now if packages A and B both > required packages P, but in different versions, guix=20 Again, I think this should be "Guix" or "GNU Guix". > will not detect this when installing both A and B to a profile. (For > details and example see > https://lists.gnu.org/archive/html/guix-devel/2016-10/msg01233.html.) > > Now pip behaves a bit different: it always executes "setup.py" with > the option "--single-version-externally-managed" set.=20=20 When you say "now," do you mean that "previously, Pip behaved differently, but now, it behaves this way", or do you simply mean "Pip behaves differently than Guix"? I think you probably mean the latter, but if there is any ambiguity, perhaps you should omit the word "now". > This makes setuptools' "install" command to *not* run "easy_install" > but the original "install" command and thus no .pth-file (and no > site.py) will be created.=20 I suggest changing this to: "This makes setuptools' "install" command run the original "install" command instead of the "easy_install," so no .pth file (and no site.py) will be created." > The "site-packages" directory only contains the package and the > related .egg-info directory. > > This is exactly what we need for guix and this is what we mimic in the > install phase below. > > As a draw back, the magic of the .pth file of linking to the other requir= ed > packages is gone and these packages have now to be declared as > "propagated-inputs". I know I haven't reviewed the actual patch series, and I apologize for not having the time to do so, but it seems unfortunate that we have to use propagated inputs. (Of course, it seems like an improvement over what we had before, so that is good!) Are there any plans to make it so that we can use Python packages without propagation? For example, I imagine that we can (and probably do) wrap some scripts with a wrapper that sets the PYTHONPATH correctly. I am not sure if we could do that for Python libraries, though. That said, I have found that in practice Python's packaging system is very complicated, and .pth files almost always add an order of magnitude to that complexity. So I will not be surprised if the answer here is "there are no plans at this time." > Note: Importing setuptools also adds two sub-commands: > "install_egg_info" and "install_scripts". These sub-commands are > executed even if "--single-version-externally-managed" is set, thus > the .egg-info directory and the scripts defined in entry-points will > always be created. > > Note: Even if the "easy-install.pth" is not longer created, we kept this > phase. There still may be packages creating an "easy-install.pth" manual= ly > for some good reason. Are these notes truly necessary? Can they perhaps just be comments in the source code instead? If they are truly necessary in the manual, please consider including them as footnotes, so it is easy to tell which section of text you wanted to associate these notes with. =2D-=20 Chris --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQIcBAEBCAAGBQJYKsY9AAoJEN1AmhXYIkadYm0P/iNxBUHx84fTMJUwjN7sWMAk A+7GKirkIKVa+eFjpFHoMHWjul94P4cqOmdqlcHPRzBj4No71FjyvoC+yEwkDcNV hO0bgJACa9hnsfwEJtNNra/sD8U/1En/aU/CuFZOAxw2ACwHfWiuQXUQctOgOZol WAYCPkVIQp7fCYFaAQmJ//zeGJrhsqR58UGiszdnUdi43+PB7NRLypMLWfqHkEU9 IK8hlY7+ahV6YlHt6ELmmt43kugYrbU8YhH+smShJ3mJToCPfX1JcQEFfqWsECPD AqQTKy5mmZMRs93/hABc0/yddcTME2LiX/xabYo2LlXVRX/KZJOjwFjEXSXUkYeP jsQ+FIDdf2LQp/GKEMCxErO6K1Anni8Li5Fc3cC9SVFfemVQ+DSAoYZxD80oIvyy 1EwXJ5TzrSf2/FMLRQhmLXaXBJUif3Uws8asA4ZnnH3T7OqfibSPoZfIMIPsT1sp e7MeVgurg8XC8e8m+zhc3fdu3L9B8jPnkgQU9uwXouat0IInIc+Yk8bOgkgW0VQ9 RvYJ+onpiFJ2MHfQDUC7IBvYTZVk3srxSemQp8sUJCn9l3CMD6i8GLQLbzwc7nmp LWjCHawvHc+8iwnmuw0wjKMzXTasiap7m2jTuK64Q7JVcETy28uuP+IeepmFUo6+ AMlRT7mZ3/aRULBTrt/9 =2qOL -----END PGP SIGNATURE----- --=-=-=--