When we develop an open source project, we want to package it and publish it to pypi.org, where someone else can install it with the pip install command. The tutorial in this article comes from Python official documents If there is something wrong, please comment on it.

0x00 Create Project

The project directory used in this article is

➜  packaging-tutorial
.
└── bestpkg
    └── __init__.py

All subsequent operations are performed in the packing_tutorial directory. First, add the following to _init_. py in the directory bestpkg

info='packaging demo'

This information is mainly used for installation testing after successful packaging.

0x01 project structure

A project to be released also needs the following files: setup.py, LICENSE, and README.md

➜  packaging-tutorial
.
├── LICENSE
├── README.md
├── bestpkg
│   └── __init__.py
└── setup.py

0x02 setup.py

The setup.py file is a script for the setuptools tool to tell setuptools how to build our project. Open the editor, edit the setup.py file, and enter the following

import setuptools

# readme Introduction to Reading Items
with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="bestpkg",# Project name, ensure its uniqueness, do not conflict with existing package name
    version="0.0.1",
    author="hylinux1024", # Project author
    author_email="hylinux1024@gmail.com",
    description="A bullish program", # One-sentence description of the project
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/hylinux1024/niubiproject ", project address
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

• name
  Project name, ensure its uniqueness, do not conflict with existing package name, otherwise it will fail to release
• version
  version number
• author
  author
• author_email
  Author's mailbox
• description
  Describe the project in one sentence
• long_description
  Detailed description of the project, generally read the contents of README.md directly
• url
  Link Address of Project
• packages
  List the packages for the current project, usually directly using find_packages()
• classifiers
  The compatible version of Python is specified here as Python 3, and the open source protocol used by the project is also specified.

0x03 README.md

Add detailed README to the project

# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

0x04 LICENSE

To publish packages to pypi, it is important to choose an appropriate open source protocol. If you don't know how to choose, you can get there. https://choosealicense.com/ Look here.

0x05 project packaging

The project needs to be packaged before it can be released. To pack the project, you need to install the latest version of setuptools and wheel first.

➜ python3 -m pip install --user --upgrade setuptools wheel

Then use the following commands to package

➜ python3 setup.py sdist bdist_wheel

When you see the following information, it indicates that the package has been successfully packaged

...
...
...
adding license file "LICENSE" (matched pattern "LICEN[CS]E*")
creating build/bdist.macosx-10.14-x86_64/wheel/bestpkg-0.0.1.dist-info/WHEEL
creating 'dist/bestpkg-0.0.1-py3-none-any.whl' and adding 'build/bdist.macosx-10.14-x86_64/wheel' to it
adding 'bestpkg/__init__.py'
adding 'bestpkg-0.0.1.dist-info/LICENSE'
adding 'bestpkg-0.0.1.dist-info/METADATA'
adding 'bestpkg-0.0.1.dist-info/WHEEL'
adding 'bestpkg-0.0.1.dist-info/top_level.txt'
adding 'bestpkg-0.0.1.dist-info/RECORD'
removing build/bdist.macosx-10.14-x86_64/wheel

A dist and build folder is generated under the project directory

➜  packaging-tutorial tree
.
├── LICENSE
├── README.md
├── bestpkg
│   └── __init__.py
├── bestpkg.egg-info
│   ├── PKG-INFO
│   ├── SOURCES.txt
│   ├── dependency_links.txt
│   └── top_level.txt
├── build
│   ├── bdist.macosx-10.14-x86_64
│   ├── bdist.macosx-10.9-x86_64
│   └── lib
│       └── bestpkg
│           └── __init__.py
├── dist
│   ├── bestpkg-0.0.1-py3-none-any.whl
│   └── bestpkg-0.0.1.tar.gz
└── setup.py

8 directories, 11 files

There are two files in the dist file

dist
    ├── bestpkg-0.0.1-py3-none-any.whl
    └── bestpkg-0.0.1.tar.gz

The tar.gz file is the source file compression package, and. whl is the packaged file. The latest pip command installs this. whl file.

0x06 Upload

Now you can upload to the Python index library. We use Test PyPI, which is the Pypi for testing. This example also uses Test Pypi.

First come to https://test.pypi.org/account/register/ Register your account. In this case, my registered account is hylinux 1024.

Then use the twine tool to upload our package. Install using the following commands:

➜ python3 -m pip install --user --upgrade twine

Upload files in the dist directory using the following commands

➜ python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

This command prompts you to enter the password of the account you just registered with test.pypi.org, and the following information appears to indicate that the upload has been successful.

Enter your username: hylinux1024
Enter your password:
Uploading distributions to https://test.pypi.org/legacy/
Uploading bestpkg-0.0.1-py3-none-any.whl
100%|██████████████████████████████████████| 4.57k/4.57k [00:00<00:00, 8.01kB/s]
Uploading bestpkg-0.0.1.tar.gz
100%|██████████████████████████████████████| 4.18k/4.18k [00:01<00:00, 3.23kB/s]

Then open it https://test.pypi.org/project/bestpkg/ You can see the package we published at this address.

0x07 Installation

Once the release is successful, you can use pip to install it. We install it in a virtual environment. You can see me about the virtual environment. Previous article.

pipenv is used here, and I went directly into the project I created yesterday to better demonstrate the installation results.

➜ pip install --index-url https://test.pypi.org/simple/ --no-deps bestpkg

Here I use the -- index-url parameter to specify that the package to be installed is installed from test.pypi.org, not from the formal package index library. The -- no-deps parameter is also used because no other dependency libraries are used in this example.

At the terminal, you will see the following similar information indicating that the installation was successful

Looking in indexes: https://test.pypi.org/simple/
Collecting bestpkg
  Downloading https://test-files.pythonhosted.org/packages/5a/fc/c109b3872b6c06e7368c30b6e52501113846f90ca716a434766151093173/bestpkg-0.0.1-py3-none-any.whl
Installing collected packages: bestpkg
Successfully installed bestpkg-0.0.1

Enter the Interactive Interface

(pipenvdemo) ➜  pipenvdemo python
>>> import bestpkg
>>> bestpkg.info
'packaging demo'

info variables are variables defined in the _init_ py file. Since then, the process of releasing, installing and using our packages has been finished.

To publish in a formal Python index library, you only need to https://pypi.org/ Register your account and upload it.

Summary of 0x08

A simple example shows how Python packages through the setuptools tool and uploads it to test.pypi.org. If you want to upload to a formal pypi.org, you only need to register a formal account. Once the release is successful, you can install it using the pip install [your-package] command.

0x09 reference

• https://packaging.python.org/tutorials/packaging-projects/
  Packaging Python Projects