Python - Creating a Package

Creating a Package in Python

Introduction

As Python applications grow in complexity, organizing code becomes essential. Python supports this through packages, which are a way of structuring Python’s module namespace by using “dotted module names.” Packages help group related modules together into a hierarchical structure and enable modular development, better maintainability, and code reuse.

What is a Python Package?

A Python package is a directory that contains multiple related Python modules and includes a special file named __init__.py. This file tells Python that the directory should be treated as a package.

Difference Between Module and Package

• Module: A single Python file (.py)
• Package: A directory containing multiple modules and an __init__.py file

Why Use Packages?

• Organize code hierarchically
• Encapsulate functionalities into namespaces
• Enable reusable components and libraries
• Allow separation of concerns
• Essential for library distribution and deployment

Creating a Basic Python Package

Step-by-Step Guide

Step 1: Create the Package Directory

my_package/

Step 2: Add the __init__.py File

This file marks the directory as a package. It can be empty or include initialization code for the package.

my_package/
├── __init__.py

Step 3: Add Modules

Create Python files (modules) inside the package directory.

my_package/
├── __init__.py
├── math_ops.py
├── string_ops.py

math_ops.py

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

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

string_ops.py

def capitalize_words(text):
    return " ".join(word.capitalize() for word in text.split())

Importing from a Package

Import Specific Module

from my_package import math_ops

print(math_ops.add(2, 3))

Import Specific Function

from my_package.math_ops import multiply
print(multiply(3, 4))

Using Aliases

import my_package.string_ops as str_ops
print(str_ops.capitalize_words("hello world"))

Understanding __init__.py 

The __init__.py file allows you to define what is available when the package is imported. It can include imports, variables, or initialization logic.

Example

# my_package/__init__.py
from .math_ops import add
from .string_ops import capitalize_words

Now you can do:

from my_package import add, capitalize_words

Nested Packages

Packages can be nested to create sub-packages, allowing for deeper modular hierarchies.

Structure

my_package/
├── __init__.py
├── math/
│   ├── __init__.py
│   └── arithmetic.py
├── strings/
│   ├── __init__.py
│   └── formatting.py

Importing from Nested Packages

from my_package.math.arithmetic import add

Absolute vs Relative Imports

Absolute Import

from my_package.math_ops import add

Relative Import (used inside the package)

from .math_ops import add

Testing Your Package

Creating test.py

from my_package import add, capitalize_words

print(add(10, 20))
print(capitalize_words("hello from python"))

Distributing a Package

You can distribute your package using setuptools and upload it to PyPI for others to install via pip.

Setup Directory

my_package_project/
├── my_package/
│   ├── __init__.py
│   ├── math_ops.py
│   └── string_ops.py
├── setup.py
├── README.md

Example setup.py

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1",
    packages=find_packages(),
    description="A sample Python package",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    author="Your Name",
    author_email="your.email@example.com",
    url="https://github.com/yourusername/my_package",
    classifiers=[
        "Programming Language :: Python :: 3",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

Build and Upload

pip install setuptools wheel twine
python setup.py sdist bdist_wheel
twine upload dist/*

Installing the Package

Once uploaded, others can install it using pip:

pip install my_package

Best Practices for Package Creation

• Use meaningful and descriptive package names
• Group logically related modules
• Include __init__.py in every package directory
• Use relative imports for internal dependencies
• Add documentation in README.md and docstrings
• Follow semantic versioning for releases
• Include unit tests
• Use virtual environments for testing

Adding Type Annotations

def add(a: int, b: int) -> int:
    return a + b

Adding Documentation

"""
math_ops.py - Mathematical operations
"""

def add(a, b):
    """Returns the sum of a and b"""
    return a + b

Using a Package in Real-World Projects

Project Structure

ecommerce_app/
├── ecommerce/
│   ├── __init__.py
│   ├── cart.py
│   ├── payment.py
│   └── product.py
├── tests/
│   ├── test_cart.py
│   └── test_payment.py
├── setup.py
├── README.md

Example usage

from ecommerce.cart import add_to_cart
from ecommerce.payment import process_payment

Creating packages in Python is essential for building scalable, maintainable, and reusable code. Whether you are building a library for public distribution or structuring a large internal project, packages help enforce organization and encapsulation. With a solid understanding of directories, __init__.py, importing, and distribution tools, you can start creating and managing professional-grade Python packages effectively.

Start small, structure your projects with a package mindset from the beginning, and gradually adopt best practices like testing, documentation, and distribution. Packages are the building blocks of Python's vast ecosystem—and with this knowledge, you can contribute to it confidently.