python-peps/peps/pep-0755.rst

PEP: 755
Title: Implicit namespace policy for PyPI
Author: Ofek Lev <ofekmeister@gmail.com>
Sponsor: Barry Warsaw <barry@python.org>
PEP-Delegate: Dustin Ingram <di@python.org>
Status: Draft
Type: Process
Topic: Packaging
Created: 05-Sep-2024

Abstract
========

This PEP codifies an implementation of :pep:`752` for PyPI [1]_.

Motivation
==========

Many projects and communities would benefit from the ability to reserve
namespaces. Since PyPI exists to serve the Python community, it is critical
to gather feedback to ensure that everyone's needs are met.

A dedicated PEP is required because the operational and policy nuances are up
to each package repository to decide.

Rationale
=========

PyPI has been understaffed, receiving the first `dedicated specialist`__ in
July 2024. Due to lack of resources, user support has been lacking for
`package name claims <https://discuss.python.org/t/27436/19>`__,
`organization requests <https://discuss.python.org/t/33764/15>`__,
`storage limit increases <https://discuss.python.org/t/54035>`__,
and even `account recovery <https://discuss.python.org/t/43422/122>`__.

__ https://pyfound.blogspot.com/2024/07/announcing-our-new-pypi-support.html

The `default policy <approval-criteria_>`_ of only allowing corporate
organizations to reserve namespaces (except in specific scenarios) provides
the following benefits:

* PyPI would have a constant source of funding for support specialists,
  infrastructure maintenance, bug fixes and new features.
* Although each application would require independent review, less human
  feedback would be required because the process to approve a paid organization
  already bestows a certain amount of trust.

Terminology
===========

Corporate Organization
    Corporate organizations are :pep:`organizations <752#organizations>` that
    pay for special functionality on PyPI.
Root Grant
    A grant as defined by :pep:`PEP 752 terminology <752#terminology>`.
Child Grant
    A grant created from a root grant with the associated namespace being a
    child namespace as defined by :pep:`PEP 752 terminology <752#terminology>`.

Implementation
==============

Grant Applications
------------------

Submission
''''''''''

Only organizations have access to the page for submitting grant applications.
Reviews of corporate organizations' applications will be prioritized.

.. _approval-criteria:

Approval Criteria
'''''''''''''''''

1. The namespace must not be something common like ``tool`` or ``apps``.
2. The namespace should be greater than three characters.
3. The namespace should properly and clearly identify the reservation owner.
4. The organization should be actively using the namespace.
5. There should be evidence that *not* reserving the namespace may cause
   ambiguity, confusion, or other harm to the community.

Organizations that are not corporate organizations will
represent one of the following:

* Large, popular open-source projects with many packages
* Universities that actively publish packages
* Government organizations that actively publish packages
* NPOs/NGOs that actively publish packages like
  `Our World in Data <https://github.com/owid>`__

Generally speaking, reviewers should be more tolerant of corporate
organizations that apply for grants for which they are not yet using.

For example, while it's reasonable to grant a namespace to a startup or an
existing company with a new product line, it's not as reasonable to grant a
namespace to a community project that doesn't have many users.

Rejections
''''''''''

Rejected applications will receive clear rationale for the decision based on
the approval criteria. Applications rejected due to the namespace being too
common will be persisted internally for future reviewers to reference and new
applications attempting to reserve a namespace that was previously rejected
for that reason will display a warning.

Grant Types
-----------

There are two types of grants.

.. _root-grant:

Root Grant
''''''''''

An organization gets a root grant for every approved application. This grant
may produce any number of `child grants <child-grant_>`_.

.. _child-grant:

Child Grant
'''''''''''

A child grant may be created by the owner of a `root grant <root-grant_>`_ at
any time without approval. The namespace associated with such grants must be a
child namespace of the root grant's namespace.

Child grants cannot have their own child grants.

.. _grant-ownership:

Grant Ownership
---------------

The owner of a grant may allow any number of other organizations to use the
grant. The grants behave as if they were owned by the organization. The owner
may revoke this permission at any time.

The owner may transfer ownership to another organization at any time without
approval from PyPI admins. If the organization is a corporate organization,
the target for transfer must also be a corporate organization. Settings for
permitted organizations are transferred as well.

.. _user-interface:

User Interface
--------------

Prefix
''''''

Every project's page
(`example <https://pypi.org/project/google-cloud-compute/1.19.2/>`__) that
matches an active namespace grant will indicate what the prefix is (NuGet
currently does not do this) and will stand out as a pill or label. This value
will match the ``prefix`` key in the
:pep:`namespace detail API <752#namespace-detail>`.

Clicking on the namespace will take the user to a page that has more
information such as the current owners, the time at which ownership was granted
and the total number of projects that match the namespace.

Visual Indicators
'''''''''''''''''

For projects that match an active namespace grant, users will be able to
quickly ascertain which of the following scenarios apply:

1. Projects that are tied to a `grant owner <grant-ownership_>`_ will not have
   a visual indicator and users should solely rely on the always-present
   prefix.
2. Projects that are not tied to a `grant owner <grant-ownership_>`_ and the
   matching grant is :pep:`open <752#open-namespaces>` will have a unique
   indicator that does not convey mistrust or danger. A good choice might be
   the `users <https://fontawesome.com/icons/users>`_ icon from Font Awesome or
   the `groups`__ icon from Google Fonts.
3. Projects that are not tied to a `grant owner <grant-ownership_>`_ and the
   matching grant is restricted will have a unique visual indicator. This
   situation arises when the project existed before the grant was created.
   The indicator will convey inauthenticity or lack of trust. A good choice
   might be a warning sign (⚠).

__ https://fonts.google.com/icons?selected=Material+Symbols+Outlined:groups

Open Namespaces
---------------

When a `child grant <child-grant_>`_ is created, its
:pep:`open <752#open-namespaces>` status will be inherited from the
`root grant <root-grant_>`_. Owners of child grants may make them open at any
time. If a grant is open, it cannot be made restricted unless the owner of the
grant is the owner of every project that matches the namespace.

Root grants given to `community projects <approval-criteria_>`_ should only be
open but is ultimately up to the reviewer of the application.

Grant Removal
-------------

If a grant is shared with other organizations, the owner organization must
initiate a transfer as a prerequisite for organization deletion.

If a grant is not shared, the owner may unclaim the namespace in either of the
following circumstances:

* The organization manually removes themselves as the owner.
* The organization is deleted.

When a reserved namespace becomes unclaimed, matching projects will no longer
have a `visual indicator <user-interface_>`_.

How to Teach This
=================

For organizations, we will document how to reserve namespaces, what the
benefits are and pricing.

Rejected Ideas
==============

Page for Viewing All Active Grants
----------------------------------

There is no page to view all active namespace grants because this has the
potential to leak private information such as upcoming products.

Visual Indicator for Owned Projects
-----------------------------------

There is no indicator for projects that are tied to a
`grant owner <grant-ownership_>`_ primarily to reduce clutter, especially since
this is the most common scenario.

If there was an indicator, it would not be a check mark or similar as NuGet
chose because it may mistakingly convey that there are associated security
guarantees inherent to the use of the package. Additionally, some social media
platforms use a check mark for verified users which may cause confusion.

References
==========

.. [1] The Python Package Index
   (https://pypi.org)

Copyright
=========

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