Getting Started with Python Packages. A straight forward tutorial.

A quick and easy way to setup your first python package. All code needed is included in the tutorial.

Illustration comes from Checkio.org

File structure needed:

For our example we will be making the EasyNumberMNIST package. Below is the file and folder structure:

.
├── EasyNumberMNIST
│ ├── EasyNumberMNIST.py
│ └── __init__.py
├── README.md
└── setup.py

To make the tree output clear, you will need a folder with 2 files and 1 folder in the main directory of your overall folder. The following files need to be created inside the main folder: README.md, setup.py, and a folder with the name of your package. Inside the package folder you will need the name of your main python file and an __init__.py file.

Setup.py

There is a lot of things here to talk about. Many variables are self explanatory. Everything will be broken down into the different sections in the article. The one thing worth noting now is that the name variable needs to replicate the same name as the package folder.

Example. sample.py code for EasyNumberMNIST example we are building together

__init__.py

This file is how your package knows the files exists in your folder. It is required to be in every folder you have in your package. The init file allows the function setuptools.findpackages() to find all other files when building the python package. To know more about what to put into the file. I suggest finding a tutorial.

# Contents of our __init__.py file
import EasyNumberMNIST
from .EasyNumberMNIST import Test

The code above is what is needed for our __init__.py file. Test will be the class that stores all of the functions. You can see the code for the Test class under the sub heading EasyNumberMNIST.py.

README.md

The README.md file is straight forward. It stores your documentation that will be shown on your PyPI package page. It uses a markup language called markdown.

## EasyNumberMNIST
First test of our medium code for the article.

Below is a snip of what you should see on your PyPI page.

Example of our README.md file working.

EasyNumberMNIST.py

Lets write some easy start up code to make it clear how everything will work.

EasyNumberMNIST.py example code used.

With this final code you are ready to start uploading your first package.

How to upload to PyPI:

Once you have stored all your files in your main folder with the proper setup.py and file structure your ready to upload to the PyPI public directory. PyPI is where pip looks to download your package.

python setup.py bdist_wheel sdist 

Once you have navigated to your directory where your setup.py is stored, run the code above in your terminal window. The code above will build your package so it is ready for publishing.

twine upload dist/* 

The code above will need to be uploaded to the PyPI public directory. If you have not already, you will need an account for this step. You can create one on the PyPI website.

Testing your first package:

To test your first package let’s install it and then run the code we made in our EasyNumberMNIST.py file. In your terminal you’ll want to:

pip3 install EasyNumberMNIST

Now create a python file anywhere on your computer and add this code to it.

import EasyNumberMNIST
object = EasyNumberMNIST.Test()
object.im_working()

Hopefully you will see a great message come out that shows you that you did it. You have created your first python package! Lets GO!

Im working and nothing is to worry about.

Thank you for reading,
Daniel Wilczak

[Extra] How imports work in packages:

Imports in packages can be one of the most frustrating things to deal with but that is why we make the big bucks! I wanted to talk about it in this tutorial because I have found out that a lot of the documentation is misleading or very hard to interpret.

All imports that are in your python package need to start with the main package name. For our example EasyNumberMNIST is what we would do if we want to import another file and another file in a different folder.

from EasyNumberMNIST import file

File in the same directory.

from EasyNumberMNIST.foldername import file

To import a file from another folder.