Python EGG guidelines need updating

[Orion Poplawski]

Python folks -

The FPC needs your help with cleaning up these guidelines:

https://fedoraproject.org/wiki/Packaging:Python_Eggs

I have a draft here:

https://fedoraproject.org/wiki/PackagingDrafts:Python_Eggs

that makes use of some new %py{2,3}_{build,install}_egg macros.

However, I think a lot more cleanup needs to be done:

- Just remove Why eggs through [edit] Providing Egg Metadata Using Setuptools
as that is just the standard course now?

- Make __requires__='MODULE[VERSIONINFO]' the recommended way to require a
version as setuptools seems to officially support this?

- Drop Egg "Features" to avoid

- Need updated links, or just drop them?

Please comment here and/or in https://fedorahosted.org/fpc/ticket/663

Thank you!

[Nick Coghlan]

On 9 December 2016 at 04:35, Orion Poplawski  wrote:
> Python folks -
>
> The FPC needs your help with cleaning up these guidelines:
>
> https://fedoraproject.org/wiki/Packaging:Python_Eggs
>
> I have a draft here:
>
> https://fedoraproject.org/wiki/PackagingDrafts:Python_Eggs
>
> that makes use of some new %py{2,3}_{build,install}_egg macros.
>
> However, I think a lot more cleanup needs to be done:
> Just remove Why eggs through [edit] Providing Egg Metadata Using Setuptools
>
> as that is just the standard course now?

The main Python guidelines link out to the Python Eggs page for more
detail, so we probably don't want to just delete these sections
without replacing them something.

Perhaps replaces these first four entries with a single section like:

================
# Python level metadata for installed components

To provide machine readable metadata regarding the Python components
that are installed, Python projects may generate:

* .egg-info files containing basic metadata regarding the package
(e.g. plain distutils)
* .egg-info directories containing a PKG-INFO file and other metadata
files related to the component (e.g. setuptools, pip)
* .dist-info directories containing a METADATA file and other metadata
files related to the component (e.g. setuptools, pip)

These files are read at runtime by various Python libraries (such as
`pkg_resources`) and thus should be packaged for installation along
with other files provided by the upstream project.
If a project emits both `.egg-info` and `.dist-info`, both sets of
metadata should be packaged (`.dist-info` is the newer standard
format, but not all potential consumers of the data have been
updated to read it)

For more details on the other files these directories may contain,
refer to PEP 376: https://www.python.org/dev/peps/pep-0376/
================
> Make __requires__='MODULE[VERSIONINFO]' the recommended way to require a
>
> version as setuptools seems to officially support this?

Indeed, this is a documented feature now:
http://setuptools.readthedocs.io/en/latest/pkg_resources.html?highlight=__re...
(Jason's less opposed to it than PJE used to be)

We need to use it in Fedora over pkg_resources.requires() because the
latter can encounter version conflicts when there's a default version
installed directly into site-packages (also documented now at the
above link and in the Python packaging guide:
https://packaging.python.org/multi_version_install/ ).

While this mostly works reliably, we may want to alert folks to this
highly confusing bug that I believe can still be triggered in some
cases: https://github.com/pypa/setuptools/issues/6
> Drop Egg "Features" to avoid

This could be changed to "Avoid easy_install", since build scripts
should use the relevant install macros.
> Need updated links, or just drop them?

Updated, I think, with references to:

* https://packaging.python.org/specifications/#recording-installed-distributio...
* http://setuptools.readthedocs.io/en/latest/setuptools.html
* https://packaging.python.org/multi_version_install/
* https://packaging.python.org/wheel_egg/
* https://packaging.python.org/pip_easy_install/

Cheers,
Nick.