PEP 755: Implicit namespace policy for PyPI (#3947)
* PEP 755: Implicit namespace policy for PyPI * address feedback * address
This commit is contained in:
Ofek Lev
GitHub
parent
3dc61f086e
commit
98f250e6e3
|
|
@ -0,0 +1,252 @@
|
||||||
|
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.
|
||||||
Loading…
Reference in New Issue