Shuan Chen

PhD Student in KAIST CBE

0%

pypi-release

Posted on

Publishing your method on PyPI

Here are the 5 steps to publish your method on PyPI

  1. Install necessary packages
  2. Stucture the files
  3. Prepare setup files
  4. Install and test on local computer
  5. Publish on PyPI

I will show the whole process using my currently developed method R2SAScore on Windows OS. I found that odd issue could occur if I use Mac OS and I haven’t figured out the reason.

image

This tutorial is a refined version of this Youtube video by adding extra details based on my experience. This Youtube video is amazing, check it out if my tutorial is not clear to you.

Install necessary packages

To publish your method to PyPI you need three packages:

1
pip install setuptools wheel twine

Stucture the files

Next, the files of your method should be well-structured as follows so the setup tool we are using in the next step can recognize each file in a proper way.

1
2
3
4
5
6
7
8
9
10
R2SAScore/
├─R2SAScore/
│  ├─pickle/
│  │  └─R2SAScores_uspto_emolecules.pkl.gz
│  ├─__init__.py
│  └─R2SAScore.py
├─LISENCE
├─README.md
├─setup.cfg
└─setup.py
  1. The pickle/ directory stores the data (the pkl.gz file) I need to use for my method. This directory is not needed if you don’t need extra file for your method.
  2. The __init__.py is a file to initiate the method. Just write from .R2SAScore import R2SAScorer inside the file.
  3. The R2SAScore.py file contains a class of my method called R2SAScorer
  4. The LISENCE file is the file you want to claim your liscence.
  5. The README.md file is the file for you to explain your method, which will show up at the pypi page after releasing.

Prepare setup files

Next, we need to pepare the configuration file setup.cfg and python file setup.py to compress our files into a package for pypi release.

Because the configuration is all decribed in setup.cfg, you only need to write

1
2
from setuptools import setup
setup()

in setup.py.

For setup.cfg, you need to specify the following information for release:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
[metadata]
name = R2SAScore
version = 0.1
packages = find_packages()
description = Reaction and Resource-aware SAScore
author = Shuan Chen
license = MIT
long_description = file: README.md
long_description_content_type = text/markdown

[options]
packages = find:
python_requires = >= 3.6
zip_safe = False
include_package_data = True
install_requires =
    numpy>=1.16.4
    matplotlib>=3.3.4
    rdkit-pypi>=2021

[options.package_data]
R2SAScore =
    pickle/*

If you want to include data in the package, make sure to specify which files you want to keep in [options.package_data] Other than that, I guess all the entries in this file are very straightforward for you to replace to your own information.

After you prepare these two files, run

1
python setup.py sdist bdist_wheel

This will compress the files you specified in setup.cfg and create a bunch of files for installation.

Install and test on local computer

Before you publish to PyPL, you might want to test the package on your compupter to make sure the package you just created works just fine.

I’d prefer to create a new environment for testing, to avoid the package conflicts and also simulate the user’s situation. You can run

1
2
conda create -n test-env python=3.6 -y
conda activate test-env

And to install your package, run

1
pip install dist/R2SAScore-0.1-py3-none-any.whl

, where the name of the whl file locates in the dist directory created in the last step.

To test whether you successfully install your package and works, simply open a python shell and test the functions. For example

1
2
3
4
5
6
7
python
>>> from R2SAScore import R2SAScorer
>>> scorer = R2SAScorer()
>>> smi = 'CC(OC1=CC=CC=C1C(O)=O)=O' # Aspirin
>>> score, contribution = scorer.calculateScore(smi)
>>> score
0.8789047205405656

Publish on PyPI

Congrats! We are now ready to publish the package to the PyPI. Register a PyPI account homepage. There are two steps needed to be done after you create the account:

  1. Two factor authentication (2FA). I selected “Add 2FA with authentication application” and used Google Authenticator for the authentication.
  2. API token. Like GitHub, pypi no longer supports publishing pakcage using only username and password. Therefore, you need to create an API token to release your package. The token should be something like pypi-xxxx

Set the and before running the last code (change SET to export if you use linux or mac OS):

1
2
SET TWINE_USERNAME=__token__
SET TWINE_PASSWORD=pypi-xxxx

Finally, run

1
twine upload dist/*

Hooray, your package is ready to be installed on PyPI now!