CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 755 – Implicit namespace policy for PyPI | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0755/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 755 – Implicit namespace policy for PyPI | peps.python.org'> <meta property="og:description" content="This PEP codifies an implementation of PEP 752 for PyPI 1."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0755/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="This PEP codifies an implementation of PEP 752 for PyPI 1."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 755</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 755 – Implicit namespace policy for PyPI</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Ofek Lev <ofekmeister at gmail.com></dd> <dt class="field-even">Sponsor<span class="colon">:</span></dt> <dd class="field-even">Barry Warsaw <barry at python.org></dd> <dt class="field-odd">PEP-Delegate<span class="colon">:</span></dt> <dd class="field-odd">Dustin Ingram <di at python.org></dd> <dt class="field-even">Discussions-To<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="https://discuss.python.org/t/63191">Discourse thread</a></dd> <dt class="field-odd">Status<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Proposal under active discussion and revision">Draft</abbr></dd> <dt class="field-even">Type<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Normative PEP describing or proposing a change to a Python community process, workflow or governance">Process</abbr></dd> <dt class="field-odd">Topic<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="../topic/packaging/">Packaging</a></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">05-Sep-2024</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="https://discuss.python.org/t/63191" title="Discourse thread">07-Sep-2024</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#terminology">Terminology</a></li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#grant-applications">Grant Applications</a><ul> <li><a class="reference internal" href="#submission">Submission</a></li> <li><a class="reference internal" href="#approval-criteria">Approval Criteria</a></li> <li><a class="reference internal" href="#rejections">Rejections</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> </ul> </li> <li><a class="reference internal" href="#grant-types">Grant Types</a><ul> <li><a class="reference internal" href="#root-grant">Root Grant</a></li> <li><a class="reference internal" href="#child-grant">Child Grant</a></li> </ul> </li> <li><a class="reference internal" href="#grant-ownership">Grant Ownership</a></li> <li><a class="reference internal" href="#user-interface">User Interface</a><ul> <li><a class="reference internal" href="#namespace-page">Namespace Page</a></li> <li><a class="reference internal" href="#project-page">Project Page</a></li> <li><a class="reference internal" href="#visual-indicators">Visual Indicators</a></li> </ul> </li> <li><a class="reference internal" href="#open-namespaces">Open Namespaces</a></li> <li><a class="reference internal" href="#grant-removal">Grant Removal</a></li> </ul> </li> <li><a class="reference internal" href="#how-to-teach-this">How to Teach This</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#page-for-viewing-all-active-grants">Page for Viewing All Active Grants</a></li> <li><a class="reference internal" href="#visual-indicator-for-owned-projects">Visual Indicator for Owned Projects</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>This PEP codifies an implementation of <a class="pep reference internal" href="../pep-0752/" title="PEP 752 – Implicit namespaces for package repositories">PEP 752</a> for PyPI <a class="footnote-reference brackets" href="#id11" id="id1">[1]</a>.</p> </section> <section id="motivation"> <h2><a class="toc-backref" href="#motivation" role="doc-backlink">Motivation</a></h2> <p>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.</p> <p>A dedicated PEP is required because the operational and policy nuances are up to each package repository to decide.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>PyPI has been understaffed, receiving the first <a class="reference external" href="https://pyfound.blogspot.com/2024/07/announcing-our-new-pypi-support.html">dedicated specialist</a> in July 2024. Due to lack of resources, user support has been lacking for <a class="reference external" href="https://discuss.python.org/t/27436/19">package name claims</a>, <a class="reference external" href="https://discuss.python.org/t/33764/15">organization requests</a>, <a class="reference external" href="https://discuss.python.org/t/54035">storage limit increases</a>, and even <a class="reference external" href="https://discuss.python.org/t/43422/122">account recovery</a>.</p> <p>The <a class="reference internal" href="#approval-criteria">default policy</a> of giving paid organizations more leniency when reserving namespaces provides the following benefits:</p> <ul class="simple"> <li>PyPI would have a constant source of funding for support specialists, infrastructure maintenance, bug fixes and new features.</li> <li>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.</li> </ul> </section> <section id="terminology"> <h2><a class="toc-backref" href="#terminology" role="doc-backlink">Terminology</a></h2> <dl class="simple"> <dt>Paid/Corporate Organization</dt><dd><a class="reference external" href="https://docs.pypi.org/organization-accounts/pricing-and-payments/#corporate-organizations">Corporate organizations</a> are <a class="pep reference internal" href="../pep-0752/#organizations" title="PEP 752 – Implicit namespaces for package repositories § Organizations">organizations</a> that pay for special functionality on PyPI. This PEP refers to them as paid in most circumstances for brevity and to ease understanding for non-native speakers.</dd> <dt>Root Grant</dt><dd>A grant as defined by <a class="pep reference internal" href="../pep-0752/#terminology" title="PEP 752 – Implicit namespaces for package repositories § Terminology">PEP 752 terminology</a>.</dd> <dt>Child Grant</dt><dd>A grant created from a root grant with the associated namespace being a child namespace as defined by <a class="pep reference internal" href="../pep-0752/#terminology" title="PEP 752 – Implicit namespaces for package repositories § Terminology">PEP 752 terminology</a>.</dd> </dl> </section> <section id="implementation"> <h2><a class="toc-backref" href="#implementation" role="doc-backlink">Implementation</a></h2> <section id="grant-applications"> <h3><a class="toc-backref" href="#grant-applications" role="doc-backlink">Grant Applications</a></h3> <section id="submission"> <h4><a class="toc-backref" href="#submission" role="doc-backlink">Submission</a></h4> <p>Only organization (non-user) accounts have access to the grant application form.</p> <p>Applications for paid organizations receive priority in the reviewing queue. This is both to offer a meaningful benefit to paid organizations and to ensure that funding is available for PyPI’s operational costs, including more reviewers.</p> </section> <section id="approval-criteria"> <span id="id4"></span><h4><a class="toc-backref" href="#approval-criteria" role="doc-backlink">Approval Criteria</a></h4> <ol class="arabic simple"> <li>The namespace must not be something common like <code class="docutils literal notranslate"><span class="pre">tool</span></code> or <code class="docutils literal notranslate"><span class="pre">apps</span></code>.</li> <li>The namespace should be greater than three characters.</li> <li>The namespace should properly and clearly identify the reservation owner.</li> <li>The organization should be actively using the namespace.</li> <li>There should be evidence that <em>not</em> reserving the namespace may cause ambiguity, confusion, or other harm to the community.</li> </ol> <p>Organizations that are not paid organizations will represent one of the following:</p> <ul class="simple"> <li>Large, popular open-source projects with many packages</li> <li>Universities that actively publish packages</li> <li>Government organizations that actively publish packages</li> <li>NPOs/NGOs that actively publish packages like <a class="reference external" href="https://github.com/owid">Our World in Data</a></li> </ul> <p>Generally speaking, reviewers should be more tolerant of paid organizations that apply for grants for which they are not yet using.</p> <p>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.</p> </section> <section id="rejections"> <h4><a class="toc-backref" href="#rejections" role="doc-backlink">Rejections</a></h4> <p>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.</p> </section> <section id="acceptance"> <h4><a class="toc-backref" href="#acceptance" role="doc-backlink">Acceptance</a></h4> <p>When an application is accepted for a namespace that is used by projects outside of the organization, an email will be sent to the owners of the projects notifying them of the new grant. The email will contain a link to the <a class="reference internal" href="#namespace-page">namespace’s page</a>.</p> </section> </section> <section id="grant-types"> <h3><a class="toc-backref" href="#grant-types" role="doc-backlink">Grant Types</a></h3> <p>There are two types of grants.</p> <section id="root-grant"> <span id="id5"></span><h4><a class="toc-backref" href="#root-grant" role="doc-backlink">Root Grant</a></h4> <p>An organization gets a root grant for every approved application. This grant may produce any number of <a class="reference internal" href="#child-grant">child grants</a>.</p> </section> <section id="child-grant"> <span id="id6"></span><h4><a class="toc-backref" href="#child-grant" role="doc-backlink">Child Grant</a></h4> <p>A child grant may be created by the owner of a <a class="reference internal" href="#root-grant">root grant</a> at any time without approval. The namespace associated with such grants must be a child namespace of the root grant’s namespace.</p> <p>Child grants cannot have their own child grants.</p> </section> </section> <section id="grant-ownership"> <span id="id7"></span><h3><a class="toc-backref" href="#grant-ownership" role="doc-backlink">Grant Ownership</a></h3> <p>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.</p> <p>The owner may transfer ownership to another organization at any time without approval from PyPI admins. If the organization is a paid organization, the target for transfer must also be a paid organization. Settings for permitted organizations are transferred as well.</p> </section> <section id="user-interface"> <span id="id8"></span><h3><a class="toc-backref" href="#user-interface" role="doc-backlink">User Interface</a></h3> <section id="namespace-page"> <span id="id9"></span><h4><a class="toc-backref" href="#namespace-page" role="doc-backlink">Namespace Page</a></h4> <p>The namespace of every active grant will have its own page that has information such as its <a class="pep reference internal" href="../pep-0752/#open-namespaces" title="PEP 752 – Implicit namespaces for package repositories § Open Namespaces">open</a> status, the current owners, the time at which ownership was granted and the total number of projects that match the namespace.</p> </section> <section id="project-page"> <h4><a class="toc-backref" href="#project-page" role="doc-backlink">Project Page</a></h4> <p>Every project’s page (<a class="reference external" href="https://pypi.org/project/google-cloud-compute/1.19.2/">example</a>) 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 <code class="docutils literal notranslate"><span class="pre">prefix</span></code> key in the <a class="pep reference internal" href="../pep-0752/#namespace-detail" title="PEP 752 – Implicit namespaces for package repositories § Namespace Detail">namespace detail API</a>.</p> <p>Clicking on the namespace will take the user to <a class="reference internal" href="#namespace-page">its page</a>.</p> </section> <section id="visual-indicators"> <h4><a class="toc-backref" href="#visual-indicators" role="doc-backlink">Visual Indicators</a></h4> <p>For projects that match an active namespace grant, users will be able to quickly ascertain which of the following scenarios apply:</p> <ol class="arabic simple"> <li>Projects that are tied to a <a class="reference internal" href="#grant-ownership">grant owner</a> will not have a visual indicator and users should solely rely on the always-present prefix.</li> <li>Projects that are not tied to a <a class="reference internal" href="#grant-ownership">grant owner</a> and the matching grant is <a class="pep reference internal" href="../pep-0752/#open-namespaces" title="PEP 752 – Implicit namespaces for package repositories § Open Namespaces">open</a> will have a unique indicator that does not convey mistrust or danger. A good choice might be the <a class="reference external" href="https://fontawesome.com/icons/users">users</a> icon from Font Awesome or the <a class="reference external" href="https://fonts.google.com/icons?selected=Material+Symbols+Outlined:groups">groups</a> icon from Google Fonts.</li> <li>Projects that are not tied to a <a class="reference internal" href="#grant-ownership">grant owner</a> 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 (⚠).</li> </ol> </section> </section> <section id="open-namespaces"> <h3><a class="toc-backref" href="#open-namespaces" role="doc-backlink">Open Namespaces</a></h3> <p>When a <a class="reference internal" href="#child-grant">child grant</a> is created, its <a class="pep reference internal" href="../pep-0752/#open-namespaces" title="PEP 752 – Implicit namespaces for package repositories § Open Namespaces">open</a> status will be inherited from the <a class="reference internal" href="#root-grant">root grant</a>. 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.</p> </section> <section id="grant-removal"> <h3><a class="toc-backref" href="#grant-removal" role="doc-backlink">Grant Removal</a></h3> <p>If a grant is shared with other organizations, the owner organization must initiate a transfer as a prerequisite for organization deletion.</p> <p>If a grant is not shared, the owner may unclaim the namespace in either of the following circumstances:</p> <ul class="simple"> <li>The organization manually removes themselves as the owner.</li> <li>The organization is deleted.</li> </ul> <p>When a reserved namespace becomes unclaimed, the <a class="reference internal" href="#user-interface">UI</a> will reflect this such that matching projects will no longer have any indicators on their page nor will the namespace have a dedicated page.</p> </section> </section> <section id="how-to-teach-this"> <h2><a class="toc-backref" href="#how-to-teach-this" role="doc-backlink">How to Teach This</a></h2> <p>For organizations, we will document how to reserve namespaces, what the benefits are and pricing.</p> <p>We will document <a class="pep reference internal" href="../pep-0541/" title="PEP 541 – Package Index Name Retention">PEP 541</a> on the same pages so that organizations are aware of the main mechanism to report improper uses of existing packages matching their grants.</p> </section> <section id="rejected-ideas"> <h2><a class="toc-backref" href="#rejected-ideas" role="doc-backlink">Rejected Ideas</a></h2> <section id="page-for-viewing-all-active-grants"> <h3><a class="toc-backref" href="#page-for-viewing-all-active-grants" role="doc-backlink">Page for Viewing All Active Grants</a></h3> <p>There is no page to view all active namespace grants because this has the potential to leak private information such as upcoming products.</p> </section> <section id="visual-indicator-for-owned-projects"> <h3><a class="toc-backref" href="#visual-indicator-for-owned-projects" role="doc-backlink">Visual Indicator for Owned Projects</a></h3> <p>There is no indicator for projects that are tied to a <a class="reference internal" href="#grant-ownership">grant owner</a> primarily to reduce clutter, especially since this is the most common scenario.</p> <p>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.</p> </section> </section> <section id="references"> <h2><a class="toc-backref" href="#references" role="doc-backlink">References</a></h2> <aside class="footnote-list brackets"> <aside class="footnote brackets" id="id11" role="doc-footnote"> <dt class="label" id="id11">[<a href="#id1">1</a>]</dt> <dd>The Python Package Index (<a class="reference external" href="https://pypi.org">https://pypi.org</a>)</aside> </aside> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0755.rst">https://github.com/python/peps/blob/main/peps/pep-0755.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0755.rst">2024-09-16 20:31:00 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#terminology">Terminology</a></li> <li><a class="reference internal" href="#implementation">Implementation</a><ul> <li><a class="reference internal" href="#grant-applications">Grant Applications</a><ul> <li><a class="reference internal" href="#submission">Submission</a></li> <li><a class="reference internal" href="#approval-criteria">Approval Criteria</a></li> <li><a class="reference internal" href="#rejections">Rejections</a></li> <li><a class="reference internal" href="#acceptance">Acceptance</a></li> </ul> </li> <li><a class="reference internal" href="#grant-types">Grant Types</a><ul> <li><a class="reference internal" href="#root-grant">Root Grant</a></li> <li><a class="reference internal" href="#child-grant">Child Grant</a></li> </ul> </li> <li><a class="reference internal" href="#grant-ownership">Grant Ownership</a></li> <li><a class="reference internal" href="#user-interface">User Interface</a><ul> <li><a class="reference internal" href="#namespace-page">Namespace Page</a></li> <li><a class="reference internal" href="#project-page">Project Page</a></li> <li><a class="reference internal" href="#visual-indicators">Visual Indicators</a></li> </ul> </li> <li><a class="reference internal" href="#open-namespaces">Open Namespaces</a></li> <li><a class="reference internal" href="#grant-removal">Grant Removal</a></li> </ul> </li> <li><a class="reference internal" href="#how-to-teach-this">How to Teach This</a></li> <li><a class="reference internal" href="#rejected-ideas">Rejected Ideas</a><ul> <li><a class="reference internal" href="#page-for-viewing-all-active-grants">Page for Viewing All Active Grants</a></li> <li><a class="reference internal" href="#visual-indicator-for-owned-projects">Visual Indicator for Owned Projects</a></li> </ul> </li> <li><a class="reference internal" href="#references">References</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0755.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>