Creating a Python Library: A Step-by-Step Guide with a Simple Example

Python is known for its rich ecosystem of libraries that make developers’ lives easier. Have you ever wanted to share your code with others in the same user-friendly way? Building and sharing a Python library on platforms like PyPI (Python Package Index) is the way to go. In this guide, we’ll walk through the process step by step, using a simple example to illustrate the concept.

Step 1: Choose Your Project

Before diving into library creation, you need a project or a piece of code that you want to share. For our example, let’s create a simple library for calculating the area of common geometric shapes: circles and rectangles.

Step 2: Structure Your Project

A well-organized project structure is crucial. Here’s a recommended structure for your project:

mygeometry/
    mygeometry/
        __init__.py
        circle.py
        rectangle.py
    setup.py

• mygeometry (the root folder) is the main project directory.
• mygeometry (inside the root folder) is the Python package.
• __init__.py in the package folder initializes the package.
• circle.py and rectangle.py are modules containing your code.
• setup.py is a script for packaging and distributing your library.

# circle.py
import math

def circle_area(radius):
    return math.pi * radius ** 2

# rectangle.py
def rectangle_area(length, width):
    return length * width

Step 4: Create ‘setup.py’

Your setup.py is crucial for packaging your library. Here's a minimal example:

from setuptools import setup, find_packages

setup(
    name='mygeometry',
    version='0.1',
    description='A simple Python library for calculating the area of geometric shapes.',
    author='Tushar Mahuri',
    packages=find_packages(),
)

It contains metadata about your project, such as its name, version, author information, and more. This metadata helps in distribution and installation of your library, making it easily accessible to others via tools like pip and PyPI.

Step 5: Build and Test (Optional step, but do it)

Before sharing your library, ensure it works as expected by running some tests. Create a tests folder and write test cases using libraries like unittest or pytest.

Step 6: Register on PyPI

To share your library on PyPI, you need an account. Register at https://pypi.org/ if you haven’t already. Try to add 2f authentication, it is reccomended.

Step 7: Upload Your Library to PyPI

Use the twine tool to upload your library to PyPI. First, install twine if you haven't:

pip install twine

Then, navigate to your project’s root folder and run:

python setup.py sdist bdist_wheel
twine upload dist/*

Step 8: Install and Use Your Library

Your library is now on PyPI! Others can install it using pip:

pip install mygeometry

Now it is ready to use.

# A sample example
from mygeometry import circle_area, rectangle_area

print(circle_area(5))  # Output: 78.53981633974483
print(rectangle_area(4, 6))  # Output: 24

Conclusion

Creating and sharing Python libraries doesn’t have to be complex. With a structured approach and a simple example like the one we’ve shown, you can make your code accessible to others and contribute to the Python community. So go ahead, package your code, and let others benefit from your work!