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