How to publish a PIP package?

PIP is a package manager for Python packages, or modules [1]. Moreover, python.org recommends the usage of pip to install Python packages from PyPI [2]. Now, let us see a step-by-step processes to create the PIP package and publish it to pypi.org

I have an existing project called compileMD, let us continue working on this project:

1. The folder/file structure:

.
├── LICENSE
├── compileMD
│   ├── __init__.py
│   └── compile_markdown.py
└── setup.py
└── README.md

1.1. LICENSE
License for the project. In this case MIT.

1.2. compileMD
Main folder of the project.

1.2.1. init.py

from .compile_markdown import *

1.2.2. compile_markdown.py
Main Python module of the project:

#!/usr/bin/env python3

__author__ = 'Ashish Singh Maharjan'

import os

MD_LOC = './md_docs'
README = './README.md'

def compile_markdown():
    '''
    Compiles a collection of markdown file into single README.md.
    '''
    files = sorted(os.listdir(MD_LOC))

    with open(README, 'w') as output_file:

        for file in files:
            with open(os.path.join(MD_LOC, file)) as input_file:
                print(f'[info] Compiling {file} into {README}')
                content = input_file.read() + '\n'
                output_file.write(content)

if __name__ == '__main__':
    compile_markdown()

1.3. setup.py
setup.py is used for publishing PIP package.

from setuptools import setup, find_packages

setup (
    name="compileMD",
    version='0.1.0',
    description='Compiles multiple markdown files into a single README.md',
    author="Ashish S. Maharjan",
    author_email="<hello@amaharjan.de>",
    url='https://github.com/asis2016/compileMD',
    packages=find_packages(),
    entry_points={
        'console_scripts': [
            'compileMD = compileMD.compile_markdown:compile_markdown',
        ],
    },
    keywords=['python', 'markdown'],
    license='MIT',
    classifiers=[
        "Development Status :: 1 - Planning",
        "Intended Audience :: Developers",
        "Programming Language :: Python :: 3",
        "Operating System :: Unix",
    ]
)

Note: entry_points > console_scripts > compileMD

• This specifies the module and function that will be executed when the compileMD script is run.

1.4. README.md

• README docu for the project.

2. GitHub repo

• Setup a GitHub repo and upload above-mentioned source code.
• https://github.com/asis2016/compileMD

3. Working with PyPI

3.1. First, register with https://pypi.org/account/register/

3.2. API token

• Create an API token from https://pypi.org/manage/account/. There are two scopes for API tokens (1) For your entire project or, (2) specific project.

3.3. Install PIP packages locally:

$ pip3 install setuptools
$ pip3 install wheel
$ pip3 install twine

3.4. sdist bdist_wheel:
This is a common way to create both a source distribution and a binary distribution of a Python package.

$ pwd
/home/amaharjan/project/compileMD

$ python3 setup.py sdist bdist_wheel

3.5. Finally, upload compileMD to PyPI:

$ twine upload dist/*

Uploading distributions to https://upload.pypi.org/legacy/
Enter your username: __token__
Enter your password: "paste your token here"

4. pip install

If you want to install it locally:

$ pip install -e .

Or, from pip directly:

$ pip install --user compileMD

Collecting compileMD
  Downloading compileMD-0.2.0-py3-none-any.whl (2.2 kB)
Installing collected packages: compileMD
Successfully installed compileMD-0.2.0

5. Trying out compileMD

First, create the following folders and files:

$ mkdir testing
[ testing]$ mkdir md_docs

[ md_docs]$ vi 00_intro.md

# Project Title
A brief description of what this project does and who it's for.

[ md_docs]$ vi 01_installation.md

## Installation
Install my-project with npm ...

Now, run compileMD:

[ testing]$ compileMD

[info] Compiling 00_intro.md into ./README.md
[info] Compiling 01_installation.md into ./README.md

Related

Here are some related links for this article:

• Python Package Index: https://pypi.org/project/compileMD
• Source code: https://github.com/asis2016/compileMD

Articles recommended by the author:

• A Linux Crash Course for Absolute Beginners
• Learn Django over the weekend

References

[1]“Python PIP.” https://www.w3schools.com/python/python_pip.asp (accessed Dec. 23, 2023).

[2]“Tool recommendations,” Python Packaging User Guide. https://packaging.python.org/en/latest/guides/tool-recommendations/ (accessed Dec. 24, 2023).

[3]NeuralNine, “Publish Your Own Python Package,” YouTube. Feb. 12, 2021. Accessed: Dec. 24, 2023. [Video]. Available: https://www.youtube.com/watch?v=tEFkHEKypLI