python-peps/pep-0715.rst

PEP: 715
Title: Disabling bdist_egg distribution uploads on PyPI
Author: William Woodruff <william@yossarian.net>
Sponsor: Donald Stufft <donald@stufft.io>
PEP-Delegate: Donald Stufft <donald@stufft.io>
Discussions-To: https://discuss.python.org/t/27610
Status: Final
Type: Standards Track
Topic: Packaging
Content-Type: text/x-rst
Created: 06-Jun-2023
Post-History: `09-Jun-2023 <https://discuss.python.org/t/27610>`__
Resolution: https://discuss.python.org/t/pep-715-disabling-bdist-egg-distribution-uploads-on-pypi/27610/13

Abstract
========

This PEP recommends deprecating and then disabling new uploads of the
``bdist_egg`` distribution type on PyPI. In a parallel move, this PEP recommends
deprecating and then disabling new uploads of distribution filenames that have
the ``.egg`` suffix.

After this PEP, PyPI will only accept new uploads of the ``sdist``
and ``bdist_wheel`` types, corresponding to files with ``.tar.gz``/``.zip`` and
``.whl`` suffixes respectively.

This PEP does not recommend removing or otherwise affecting any previously
uploaded ``bdist_egg`` distributions or files with the ``.egg`` suffix.

Rationale
=========

Previous Work
-------------

The groundwork for this proposal was established with :pep:`527`, which
proposed deprecating and eventually removing upload support for a handful
of un(der)used file extensions and distribution types.

In particular, :pep:`527` proposed the removal of the ``bdist_dumb``,
``bdist_rpm``, ``bdist_dmg``, ``bdist_msi``, and ``bdist_wininst`` distribution
types, as well as the ``.tar``, ``.tar.bz2``, ``.tar.xz``, ``.tar.Z``,
``.tgz``, and ``.tbz`` file extensions on distribution filenames.

:pep:`527` was fully enacted with
`PR #7529 <https://github.com/pypi/warehouse/pull/7529>`_ to Warehouse,
which was merged on 13 April 2020.

The ``bdist_egg`` format
------------------------

The ``bdist_egg`` filetype identifies distributions in the
:term:`egg format <packaging:Egg>`. The
egg format was introduced by setuptools in 2004 and is roughly equivalent
in functionality to the
:term:`wheel format <packaging:Wheel>`
first introduced by :pep:`427` in 2012
as :ref:`the standardized format <packaging:binary-distribution-format>`
for :term:`built distributions <packaging:Built Distribution>`.

Despite its longevity, the egg format has had
`limited adoption on PyPI <https://github.com/pypi/warehouse/issues/10653>`_.
Some observations from that issue:

* In the month of May 2023, ``bdist_egg`` uploads accounted for 0.2% of all
  distribution uploads to PyPI;
* ``pip`` deprecated its ``--egg`` option in 2016;
* ``setuptools`` has considered egg support deprecated since 2019;
* ``build`` only supports the ``sdist`` and ``bdist_wheel`` filetypes.

Given the above, this PEP proposes the removal of the ``bdist_egg`` format
under the same justifications presented in :pep:`527`, namely:

* Egg distributions are of limited use to the broader ecosystem and
  therefore represent a non-reciprocal maintenance burden;
* Having an additional built distribution format
  is confusing to end users, who may
  mistakenly pick it over the wheel format;

This PEP *additionally* offers an argument for removal rooted in
standardization and duplication: the egg format is not standardized by any
PEP or other community standard, and overlaps heavily with its standardized
and well-supported alternative (wheel).

The ``.egg`` file extension
---------------------------

The ``.egg`` file extension is used exclusively for distributions of the
``bdist_egg`` format. As such, it serves no purpose in a scenario where
PyPI disables new distribution uploads for ``bdist_egg`` distributions.

Removal Process
===============

This PEP does **NOT** propose removing any existing files from PyPI, only
disallowing new ones from being uploaded.

PyPI will provide a deprecation period of one month. At the beginning
of the deprecation period, maintainers of projects that have uploaded one or
more egg distributions since 1 Jan 2023 will receive a one-time email informing
them of the upcoming end of support for egg distribution uploads.

During the deprecation period, users will continue to be allowed to upload egg
distributions to new and existing projects. Uploading an egg distribution
during this period will also send all maintainers of the project
a similar email as above, reminding them of the upcoming end of support.

After the deprecation period, support for uploading egg distributions will
cease to exist on PyPI.

Prior Art
---------

The removal process above was based on that of :pep:`527`, with the following
changes:

* All projects will be continue to be allowed to upload eggs
  during the deprecation period, not just those that have done so previously.
* Uploading an egg during the deprecation period will also trigger an email
  to maintainers, in addition to the one-time email at the beginning.

Backwards Compatibility
=======================

Limited Impact
--------------

As noted in the rationale section, this PEP is expected to have no impact
on the overwhelming majority of PyPI users and projects, and there has been
`substantial community coordination <https://github.com/pypi/warehouse/issues/10653>`_
over the past 1 1/2 years to minimize the impact on the few last use cases.

Hosted Files
------------

This PEP does **NOT** propose the removal of any egg distributions that have
already been uploaded to PyPI. All previously uploaded egg distributions will
remain downloadable, ensuring that existing users will continue to be able
to download them.

Deprecation Period
------------------

This PEP uses the removal process documented above, which specifies
a deprecation period of 1 month for projects that have previously uploaded
egg distributions to PyPI.

After the end of the deprecation period, support for uploading new egg
distributions will cease to exist on PyPI.

Security Implications
=====================

This PEP does not identify any positive or negative security implications
associated with removing upload support for egg distributions.

How To Teach This
=================

As part of the removal process, PyPI will send emails to all maintainers of
projects that have previously uploaded egg distributions in 2023.

Additionally, PyPI will write a post on the
`PyPI blog <https://blog.pypi.org/>`_ that publicly announces the deprecation
period's start and end.

Copyright
=========

This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive.