Package Release

5. Package Release#

This chapter is intended for collaborators who are responsible for releasing and maintaining Molass packages. It provides concise instructions for managing the package release process.

5.1. Packages to be managed#

There are the following Python packages to be managed.

No

Package Name

GitHub Repository

Description

1

molass_legacy

reesemt/molass-legacy

Molass GUI application

2

molass

nshimizu0721/molass-library

Molass Library

3

molass_data

freesemt/molass-data

data for Molass Tutorial

5.2. Package Management Specification#

Management of the above packages is specified in the pyproject.toml file in each repository. Especially, the package names as PyPI project names, used in the above table, are defined in the respective pyproject.toml files.

5.3. About PyPI#

The Python Package Index (PyPI) is the official repository for Python packages. It allows developers to publish and distribute their Python libraries to a global audience. Users can install these packages using tools like pip. For Molass, PyPI serves as the platform for releasing and maintaining its packages, ensuring they are easily accessible to the community.

5.4. PyPI Account#

To publish packages to PyPI, you need a PyPI account. This account is required to authenticate yourself as a trusted maintainer and to manage the packages you release.

5.4.1. How to Create a PyPI Account#

  1. Go to the PyPI website.

  2. Click on the “Register” button in the top-right corner.

  3. Fill in the required details, including:

    • Username: Choose a unique username.

    • Email Address: Provide a valid email address for verification and notifications.

    • Password: Create a strong password.

  4. Complete the CAPTCHA and click “Register”.

  5. Verify your email address by clicking the link sent to your inbox.

Once your account is created and verified, you can use it to upload and manage Molass packages on PyPI.

5.5. PyPI API Token#

A PyPI API token is a secure way to authenticate yourself when uploading packages to PyPI. Instead of using your username and password, which can be less secure, the API token allows you to perform package uploads while keeping your credentials safe.

5.5.1. How to Create a PyPI API Token#

  1. Log in to your PyPI account.

  2. Click on your username in the top-right corner and select “Account settings”.

  3. Scroll down to the “API tokens” section and click “Add API token”.

  4. Provide a name for the token (e.g., “Molass Package Upload”).

  5. Under “Scope”, select the appropriate option:

    • Entire account: Allows the token to manage all your packages.

    • Specific project: Restricts the token to a specific package (recommended for security).

  6. Click “Add token”.

  7. Copy the generated token and store it securely. You won’t be able to view it again.

5.5.2. How to keep PyPI API Token#

For the default GitHub Actions procedure, only one PyPI API token is required. This token should be securely stored as a repository secret and will be used by the workflow to authenticate uploads. Collaborators do not need direct access to this token, as it is securely stored in the repository secrets.

5.6. PyPI Upload#

5.6.1. Default Procedure: Using GitHub Actions [1]#

The default and recommended procedure for uploading Molass packages to PyPI is through a GitHub Actions workflow. This method ensures consistency, security, and ease of use for all collaborators.

Steps:#

  1. Go to the "Actions" tab in the Molass Library repository.

  2. Select the "Manual Upload Python Package to PyPI" workflow.

  3. Click the "Run workflow" button.

Notes for Collaborators:#

  • Permissions:
    Ensure you have write or admin access to the repository to trigger the workflow.

  • PyPI API Token:
    The workflow uses a PyPI API token stored securely in the repository secrets. Collaborators do not need direct access to the token.

  • Accountability:
    If multiple collaborators are uploading packages, it is recommended that each collaborator has their own PyPI account and API token. These tokens can be added as separate secrets in the repository for better security and traceability.

Note

If you are a collaborator (e.g., Person B) and encounter issues running the workflow, ensure that:

  1. You have the necessary permissions in the repository.

  2. The workflow is properly configured to allow manual triggering (workflow_dispatch).

If the GitHub Actions workflow cannot be used, you can manually upload the package using Twine, as described below.

5.6.2. Alternative Procedure: Using Twine#

To build required files, do as follows in the repository root folder.

python -m build

This will generate the distribution files in the dist subfolder.

To upload them to PyPI, you will need to provide your API token[2] to authenticate the upload when running the following twine command:

twine upload dist/*

Note

When following this alternative procedure, each collaborator should generate their own API token under their individual PyPI accounts to ensure accountability and security.

By following the steps outlined in this chapter, collaborators can securely and efficiently manage the release of Molass packages to PyPI. The default GitHub Actions workflow ensures consistency and ease of use, while the Twine procedure provides a reliable fallback option when needed.

See also:

Contents