Make your module pip installable.

Sometimes when we build a program, we realize its more than just for one program and can be useful to many, and it’s a good thing though, actually, the beauty of python is because of its huge collection of library and it is due to the contributors like you.

I will guide you step by step and let you understand each and every command we use.

First of all, if you haven’t registered on PyPI then create your account by clicking https://pypi.org/account/register/, we need the username and password later.

And we need Twine to upload the module. if you haven’t install twine, then to install it run following command.

 python3 -m pip install twine 

So after registering successfully and installing twine, we need to bundle up our files and upload it .

First of all, we need a file, probably you have a file, let me build my own

 def sum(a,b):
    c=a+b
    return c 

I am saving it as Sum.py

So we are on the same page now, we both have a file which we want to upload.

1. Creating a folder

Create a folder and name it something unique and user-friendly as it will become your module name.

Now open the folder and add another folder with the same name.

I choose to call it py2pyadd.

From now onwards we will save our files to this folder only, starting with program file.

2. Saving the file

Now I have two ways to save the file in it

  • sum_file.py
  • __init__.py
sum_file.py
__init__.py

lets understand the difference between two

Why sum_file.py ?

Suppose I have two seperate programs files which I need to upload but it should be called by same module like Sum_file.py and Difference_file.py and both function contain sum() and diff() respectivelly

so the import method will be

from py2pyadd import Sum_file as s
from py2pyadd import Difference_file as d

s.sum(a,b)
d.diff(a,b)

and it makes sense in this case.

why __init__.py ?

but if I have only one file then importing full path doesn’t make sense. I need import function like.

import py2pyadd as py

py.sum(a,b)

So to do this we can change the file name to __init__.py

Here when we import a module, __init__.py file will import with the module itself.

So both have its own use and save it according to the requirement.

3. README.md

After uploading the file on PyPI, you get a kind of page like below in which you can showcase your module, share some insight and applications and all sort of stuff but you can’t edit after uploading, all you have to do it now and save this as README.md file.

note: its readme.MD file, not readme.TXT. here .md is a markdown file 

this procedure is far more then just writing a blank text document,

If you write as a document or paragraph it will show like this..

Readme.txt

 which is dull and not appealing 

but if you want your module  become more user friendly, then you should edit your files to get something like this

Readme.md
Same markdown version of above text file

You can use any text editor. There are plugins for many editors (e.g. AtomEmacsSublime TextVim, and Visual Studio Code) that allow you to preview Markdown while you are editing it.

You can also use a dedicated Markdown editor like Typora or an online one like StackEdit or Dillinger

I am adding few tips, but you will find out lot more when you start working on it. So make something attractive and user friendly

  • underline with ======= make the heading bigger and bold. usually should be used top of the page
  • then underline with ——————- make the heading like 2nd level heading
  • **anyword** within astriks anything become bold but size will be same as other text
  • “> -“ without quote, this greater then and hyphn is used to make the bullets

I am also adding a raw version and rendered version of one of my package so you can edit there if you want.

Readme.md Raw version: https://raw.githubusercontent.com/Pushkar-Singh-14/Polygon-Analysis/master/README.md

Readme.md Rendered Version: https://github.com/Pushkar-Singh-14/Polygon-Analysis/blob/master/README.md

Once you done all editing just save it as README.md in the same folder.

4. Licence

Licence is must for any program even for a free open source.

for open source program you can just save from here.

Licence: https://raw.githubusercontent.com/Pushkar-Singh-14/Polygon-Analysis/master/LICENSE.txt

For other licence you can visit https://choosealicense.com/

Save as LICENCE.txt in the same folder containing program and readme file

5. Setup.py file

Now next step is to edit our setup file. which pretty much contain every information regarding the module. let’s take a look on it, you can also edit it and save as setup.py

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    #Here is the module name.
    name="py2pyadd",

    #version of the module
    version="0.0.1",

    #Name of Author
    author="Pushkar Singh",

    #your Email address
    author_email="[email protected]",

    #Small Description about module
    description="adding number",

    long_description=long_description,

    #Specifying that we are using markdown file for description
    long_description_content_type="text/markdown",

    #Any link to reach this module, if you have any webpage or github profile
    url="https://github.com/Pushkar-Singh-14/",
    packages=setuptools.find_packages(),

    #classifiers like program is suitable for python3, just leave as it is.
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
)

The program has comments which are self-explanatory now just edit the file and save it as setup.py in the same folder.

At this moment your package folder should look like this.

Now its time to run some commands

open cmd or Terminal in a folder, To do so

for windows right click on folder and click on Open Command Windows here.

Opening cmd at folder

for Terminal two finger tap on a folder and click on New terminal at Folder

in Mac, if you don’t find this option here, open System Preference> Keyboard>shortcut then select service on left tab and then check New Terminal at windows

Once you are in cmd or terminal just type the command below

python3 setup.py bdist_wheel

This command make a binary distribution file which is required to upload on PyPI.

You will get the following output

Make sure that correct version of python “py3” is mention in this line. if its “py2” then the module will install only in python2.x and not in python3.x

Now your folder must have files like this

Now our files are ready to upload, to upload the files, open cmd or terminal again at the same folder and type 

twine upload dist/*

then enter the username and then password, password will not show as you type. so just type it and hit enter, 

Great, we are done, We have uploaded the module. To check, just open your account.

Click on view 

So here we can see our module is live. To verify, lets install our module.

python3 -m pip install py2pyadd

We get the following output

Clearly we can see that our module is successfully installed. Lets run it for Final check

import py2pyadd as py
py.sum(3,4)

and we get the output

Everything is working fine, congratulations you are now the official contributor to python.

How to update your package on PyPI

Now If at some point you change your code and want to upgrade it on PyPI then just delete files from the dist folder and change the version in setup.py file. then open the terminal or cmd in that folder and run the command.

python3 setup.py bdist_wheel

after this command you are ready to upgrade the module, just type.

twine upload dist/* 

Now Enter username and password and then hit enter, your package get updated.

This is all from my side. If you have any doubt then please feel free to ask in the comments.

Thanks.

Leave a Reply

Your email address will not be published. Required fields are marked *