3.3.1. PyPI#

The Python Package Index (PyPI) is the official software repository for Python packages. It provides a centralized public platform to publish and share Python libraries and applications, streamlining the process of integrating third-party dependencies into projects. This promotes ease of access to community-contributed packages, facilitating rapid development and encouraging code reuse. Hosting more than six hundred thousand projects, PyPI is one of the largest and most diverse ecosystems for open-source software.

PyPI works in conjunction with Python’s packaging tools like pip to ensure that software can be easily installed, upgraded, and managed. By serving as the backbone of Python’s package distribution, PyPI plays a crucial role in the language’s scalability and accessibility.

Run by the Python Software Foundation with an open-source backend named Warehouse, PyPI is built using modern technologies and incorporates security practices like two-factor authentication (2FA), verified email requirements, and the use of the PEP 503 normalized URLs standard. It provides features such as API endpoints and public datasets, digital attestations, and organization accounts.

3.3.1.1. Project Metadata#

PyPI can read the metadata of uploaded packages and display them on the project’s webpage. While all available metadata fields are supported, some fields such as project URLs and README have additional guidelines for correct processing on PyPI.

3.3.1.1.1. URLs#

Project URLs that can be verified are displayed with a green checkmark, attesting that the URL is under control of the PyPI package owner at the time of verification. For example, URLs to the package’s source repository can be verified by enabling Trusted Publishing for that repository. Moreover, PyPI recognizes a number of patterns in URL labels and addresses to add a custom icon to the link (cf. Warehouse source code). For example, following URL labels (i.e., keys of the [project.url] table in pyproject.toml) are automatically recognized by PyPI (case-insensitive) and displayed with a custom icon:

  • home, homepage, home page

  • download

  • changelog, change log, changes, release notes, news, what's new, history

Keys starting with the following terms are recognized as well:

  • documentation, docs

  • issue, bug, tracker, report

  • sponsor, funding, donate, donation

3.3.1.1.2. README#

PyPI renders the full description of the package to HTML and displays it on the project’s webpage. In addition to plain text and HTML inputs, it also supports GitHub-Flavored Markdown and reStructuredText. However, like GitHub, PyPI also imposes several restrictions on the supported features, and perform additional post-processing and sanitization after rendering the contents to HTML. This is done by PyPA’s Readme Renderer library, which only allows a limited subset of HTML tags and attributes. Since these do not completely overlap with the features supported by GitHub (e.g., GitHub supports <picture> elements but PyPI does not), a separate PyPI-friendly README is usually required for PyPI, to ensure that the contents are correctly rendered.

The Twine Python package—PyPI’s recommended tool for uploading packages—has the twine check command to check the README file for PyPI compatibility. This uses Readme Renderer under the hood, which it only checks whether the file can be rendered by PyPI. However, if there are unsupported HTML tags or other minor problems in the file, twine check will pass, but those tags will be rendered as plain text on PyPI (cf. Twine’s source code). Therefore, a manual investigation is usually required to visually investigate the rendered README file.