Skip to content

Commit

Permalink
Note issues with Provides-Dist and Obsoletes-Dist (#513)
Browse files Browse the repository at this point in the history
The design of Provides-Dist and Obsoletes-Dist was lifted pretty
much directly from the design of Linux system package managers,
without accounting for the fact that Linux distro repos are collaboratively
maintained curated collections of packages with the ability to make
repository wide changes, while PyPI is an open publishing platform
with few practical restrictions other than size quotas and the default
first-come-first-served policy on claiming names.

As a result, tools generally don't pay any attention to them, and
hence there also isn't much reason for package publishers to
bother setting them.
  • Loading branch information
ncoghlan authored May 29, 2018
1 parent b3bf60b commit 6f5fae7
Showing 1 changed file with 85 additions and 70 deletions.
155 changes: 85 additions & 70 deletions source/specifications/core-metadata.rst
Original file line number Diff line number Diff line change
Expand Up @@ -459,76 +459,6 @@ Examples::
Requires-Dist: pywin32 >1.0; sys_platform == 'win32'


Provides-Dist (multiple use)
============================

.. versionadded:: 1.2
.. versionchanged:: 2.1
The field format specification was relaxed to accept the syntax used by
popular publishing tools.

Each entry contains a string naming a Distutils project which
is contained within this distribution. This field *must* include
the project identified in the ``Name`` field, followed by the
version : Name (Version).

A distribution may provide additional names, e.g. to indicate that
multiple projects have been bundled together. For instance, source
distributions of the ``ZODB`` project have historically included
the ``transaction`` project, which is now available as a separate
distribution. Installing such a source distribution satisfies
requirements for both ``ZODB`` and ``transaction``.

A distribution may also provide a "virtual" project name, which does
not correspond to any separately-distributed project: such a name
might be used to indicate an abstract capability which could be supplied
by one of multiple projects. E.g., multiple projects might supply
RDBMS bindings for use by a given ORM: each project might declare
that it provides ``ORM-bindings``, allowing other projects to depend
only on having at most one of them installed.

A version declaration may be supplied and must follow the rules described
in :doc:`version-specifiers`. The distribution's version number will be implied
if none is specified.

This field may be followed by an environment marker after a semicolon.

Examples::

Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package; python_version >= "3.4"


Obsoletes-Dist (multiple use)
=============================

.. versionadded:: 1.2
.. versionchanged:: 2.1
The field format specification was relaxed to accept the syntax used by
popular publishing tools.

Each entry contains a string describing a distutils project's distribution
which this distribution renders obsolete, meaning that the two projects
should not be installed at the same time.

Version declarations can be supplied. Version numbers must be in the
format specified in :doc:`version-specifiers`.

This field may be followed by an environment marker after a semicolon.

The most common use of this field will be in case a project name
changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0.
When you install Torqued Python, the Gorgon distribution should be
removed.

Examples::

Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)
Obsoletes-Dist: Foo; os_name == "posix"


Requires-Python
===============

Expand Down Expand Up @@ -633,6 +563,91 @@ It is legal to specify ``Provides-Extra:`` without referencing it in any
``Requires-Dist:``.


Rarely Used Fields
==================

The fields in this section are currently rarely used, as their design
was inspired by comparable mechanisms in Linux package management systems,
and it isn't at all clear how tools should interpret them in the context
of an open index server such as `PyPI <https://pypi.org>`__.

As a result, popular installation tools ignore them completely, which in
turn means there is little incentive for package publishers to set them
appropriately. However, they're retained in the metadata specification,
as they're still potentially useful for informational purposes, and can
also be used for their originally intended purpose in combination with
a curated package repository.


Provides-Dist (multiple use)
----------------------------

.. versionadded:: 1.2
.. versionchanged:: 2.1
The field format specification was relaxed to accept the syntax used by
popular publishing tools.

Each entry contains a string naming a Distutils project which
is contained within this distribution. This field *must* include
the project identified in the ``Name`` field, followed by the
version : Name (Version).

A distribution may provide additional names, e.g. to indicate that
multiple projects have been bundled together. For instance, source
distributions of the ``ZODB`` project have historically included
the ``transaction`` project, which is now available as a separate
distribution. Installing such a source distribution satisfies
requirements for both ``ZODB`` and ``transaction``.

A distribution may also provide a "virtual" project name, which does
not correspond to any separately-distributed project: such a name
might be used to indicate an abstract capability which could be supplied
by one of multiple projects. E.g., multiple projects might supply
RDBMS bindings for use by a given ORM: each project might declare
that it provides ``ORM-bindings``, allowing other projects to depend
only on having at most one of them installed.

A version declaration may be supplied and must follow the rules described
in :doc:`version-specifiers`. The distribution's version number will be implied
if none is specified.

This field may be followed by an environment marker after a semicolon.

Examples::

Provides-Dist: OtherProject
Provides-Dist: AnotherProject (3.4)
Provides-Dist: virtual_package; python_version >= "3.4"


Obsoletes-Dist (multiple use)
-----------------------------

.. versionadded:: 1.2
.. versionchanged:: 2.1
The field format specification was relaxed to accept the syntax used by
popular publishing tools.

Each entry contains a string describing a distutils project's distribution
which this distribution renders obsolete, meaning that the two projects
should not be installed at the same time.

Version declarations can be supplied. Version numbers must be in the
format specified in :doc:`version-specifiers`.

This field may be followed by an environment marker after a semicolon.

The most common use of this field will be in case a project name
changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0.
When you install Torqued Python, the Gorgon distribution should be
removed.

Examples::

Obsoletes-Dist: Gorgon
Obsoletes-Dist: OtherProject (<3.0)
Obsoletes-Dist: Foo; os_name == "posix"

----

.. [1] reStructuredText markup:
Expand Down

0 comments on commit 6f5fae7

Please sign in to comment.