Create and Install Your First Python Package

Understanding Python packages is important. If you want to become a Python developer, you should also learn how to build your own packages. In this post, we will build a simple calculator package.

Create your first custom package

In your workspace, create a directory named my_calculator. Use lowercase letters and underscores where needed. The directory name will be the package name. Inside it, create an empty __init__.py file. This makes the directory a regular Python package. Finally, create a file named simple_calculator.py and add the following Python code:

def add_two_numbers(a, b):
    return a + b

def sub(a, b):
    return a - b

def multiply(a, b):
    return a * b

Create a my_script.py file alongside the package directory. At this point, your directory should look like this:

Workspace/
├── my_calculator/
│   ├── __init__.py
│   └── simple_calculator.py
└── my_script.py

This is our small calculator package. Now let's see how to access it.

Accessing the package without modifying __init__.py

Here, we will update the my_script.py file to access our package. We can use the . operator or Python's from ... import ... syntax to import and use it.

# my_script.py
# Using the dot operator
import my_calculator.simple_calculator

a = my_calculator.simple_calculator.add_two_numbers(4, 5)
print(a)  # 9

# Using a from-import statement
from my_calculator import simple_calculator

a = simple_calculator.add_two_numbers(4, 5)
print(a)  # 9

Run the script from the Workspace directory:

$ python my_script.py

The $ symbol represents the shell prompt; enter the command without it.

Accessing the package after modifying __init__.py

I prefer this approach because it makes the package easier to use. Import the three functions (add_two_numbers, sub, and multiply) from simple_calculator.py into __init__.py:

# __init__.py
from .simple_calculator import add_two_numbers, sub, multiply

After adding this line to __init__.py, we can use the package as shown below:

# my_script.py
import my_calculator

a = my_calculator.add_two_numbers(5, 5)
b = my_calculator.sub(5, 5)
c = my_calculator.multiply(5, 5)

print(a)  # 10
print(b)  # 0
print(c)  # 25

Run python my_script.py again to see the updated results. This code looks cleaner and more readable. So far, we have seen how to create and use our own package.

Set up your Python package

To set up a custom package for installation, we first need to define its metadata and any dependencies. To do so, create setup.py and update it based on your needs. The optional requirements.txt file shown below can be used to manage an environment. The updated directory will look like this:

Workspace/
├── my_calculator/
│   ├── __init__.py
│   └── simple_calculator.py
├── my_script.py
├── setup.py
└── requirements.txt

In the setup.py file, we define information about our package, including its name, version, description, author details, and dependencies:

# setup.py
from setuptools import setup

setup(
    name='my_calculator',
    version='0.0.1',
    description='This is my first Python package',
    author='Nabin Bhandari',
    author_email='****@gmail.com',
    packages=['my_calculator'],
    install_requires=[]  # If your package depends on other packages, list them here.
)

This calculator uses no third-party packages, so install_requires is empty. If your package needs another library, list it here. For example, use install_requires=['matplotlib'] only if your package actually uses matplotlib.

A requirements.txt file is optional and can list packages needed for an environment. For this calculator, it can be omitted or contain only comments:

# requirements.txt
# No third-party dependencies are needed for this calculator.
# Example only: uncomment the next line if your project needs matplotlib.
# matplotlib

python -m pip install . reads dependencies from the package metadata; it does not automatically read requirements.txt. If you choose to use a requirements file, install its contents explicitly:

$ python -m pip install -r requirements.txt

Install your package in your Python environment

With setup.py in place, we can use the pip install command to install our custom package into our Python environment. Run this command from the directory containing setup.py:

$ python -m pip install .

You can list the installed packages with this command:

$ python -m pip list

Example output showing our package:

(.venv) Workspace$ python -m pip list

Package           Version
----------------- ---------
my_calculator     0.0.1