Principle:Langchain ai Langchain Test PyPI Publishing

Overview

Test PyPI Publishing is the practice of uploading distribution artifacts to a staging package index for validation before publishing to the production index.

Description

Before publishing a package to the production Python Package Index (PyPI), a prudent release pipeline first uploads the artifacts to Test PyPI (https://test.pypi.org). This staging step serves several purposes:

• Validation of the upload process: Confirms that the package metadata, naming, and artifact format are accepted by the index.
• Install testing: Allows downstream CI steps to pip install the package from Test PyPI to verify it installs correctly and its imports work.
• Risk mitigation: A broken upload to Test PyPI can be corrected without affecting production users.

Modern CI pipelines use OIDC trusted publishing rather than long-lived API tokens. Trusted publishing allows the CI environment to authenticate to PyPI using a short-lived identity token issued by the CI provider (e.g., GitHub Actions). This eliminates the need to store PyPI credentials as repository secrets and reduces the blast radius of a credential compromise.

The id-token: write permission on the CI job enables the OIDC token exchange, and the PyPI package must be pre-configured to trust the specific GitHub repository and workflow.

Usage

Use Test PyPI publishing when:

• Releasing any package, as a mandatory validation step before production publishing.
• Debugging packaging issues in a safe environment.
• Testing trusted publishing configuration for new packages.

Practical Guide

1. Build distribution artifacts (wheel + sdist) in an earlier job.
2. Download the artifacts in the Test PyPI publishing job.
3. Authenticate using OIDC trusted publishing (no stored secrets needed).
4. Upload to https://test.pypi.org/legacy/ with skip-existing enabled.
5. Downstream jobs install from Test PyPI to validate the package.

Pseudocode:

artifacts = download("dist")
oidc_token = request_id_token(audience="pypi")

upload(
    artifacts,
    repository_url="https://test.pypi.org/legacy/",
    auth=oidc_token,
    skip_existing=true
)

# Downstream validation:
pip_install(
    package_name + "==" + version,
    index_url="https://test.pypi.org/simple/",
    extra_index_url="https://pypi.org/simple/"  # for dependencies
)

Related Pages

• Implementation:Langchain_ai_Langchain_PyPI_Trusted_Publishing_Test