Creating and Distributing Python Packages

Python allows developers to create and distribute reusable packages via PyPI (Python Package Index). This guide will walk through creating, packaging, and publishing a Python package.

---

1. Why Create a Python Package?

Code Reusability – Share code across projects.
Collaboration – Share code with others via PyPI.
Versioning – Maintain different versions for updates.
Modularization – Keep code organized and maintainable.

---

2. Creating a Python Package

A package is a directory containing Python modules and a special __init__.py file.

2.1 Define the Project Structure

my_package/
│── my_package/         # Package Directory
│   │── __init__.py     # Marks the directory as a package
│   │── math_utils.py   # A module with functions
│── setup.py            # Package metadata
│── README.md           # Package description
│── LICENSE             # License file
│── requirements.txt    # Dependencies (optional)
│── tests/              # Test cases

---

3. Writing the Package Code

3.1 Create math_utils.py

# my_package/math_utils.py

def add(a, b):
    """Returns the sum of two numbers."""
    return a + b

def subtract(a, b):
    """Returns the difference of two numbers."""
    return a - b

3.2 Add __init__.py

# my_package/__init__.py

from .math_utils import add, subtract

🔹 The __init__.py file initializes the package and allows importing functions.

---

4. Writing the setup.py File

This file contains package metadata.

from setuptools import setup, find_packages

setup(
    name="my_package",
    version="0.1.0",
    author="Your Name",
    author_email="your_email@example.com",
    description="A simple math utilities package",
    long_description=open("README.md").read(),
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package",
    packages=find_packages(),
    install_requires=[],  # Add dependencies here
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
)

🔹 find_packages() automatically detects modules inside my_package/.
🔹 install_requires=[] allows specifying dependencies.

---

5. Adding a README and LICENSE

• README.md – Describes package usage.
• LICENSE – Defines usage rights (e.g., MIT, Apache, GPL).

Example README.md

# My Package
A simple Python package for basic math operations.

## Installation
```sh
pip install my_package

Usage

from my_package import add

print(add(5, 3))  # Output: 8

---

## **6. Building the Package**  
Run the following command to package the project:
```sh
python setup.py sdist bdist_wheel

This generates:

• dist/my_package-0.1.0.tar.gz (Source distribution)
• dist/my_package-0.1.0-py3-none-any.whl (Wheel format)

---

7. Uploading to PyPI

First, install twine:

pip install twine

7.1 Test Upload to TestPyPI

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Check the package on TestPyPI.

7.2 Upload to PyPI

twine upload dist/*

You will need a PyPI account (Register here).

---

8. Installing and Testing the Package

Once uploaded, install it using pip:

pip install my_package

8.1 Using the Package

from my_package import add

print(add(10, 5))  # Output: 15

---

9. Updating the Package

To release a new version:

1. Update version="0.2.0" in setup.py.
2. Rebuild and upload: shCopyEditpython setup.py sdist bdist_wheel twine upload dist/*

---

10. Summary

Step	Command
Create a package	Organize files (__init__.py, setup.py)
Build package	python setup.py sdist bdist_wheel
Upload to TestPyPI	twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Upload to PyPI	twine upload dist/*
Install package	pip install my_package
Update package	Change version in setup.py and re-upload