Python Package Creation, Management & Distribution Guide

1. Introduction

The Importance of Packages in Python

Purpose and Overview of This Article

• Fundamental concepts and structure of packages
• How to create your own package
• How to import packages
• Managing packages using pip
• Steps to publish to PyPI (Python Package Index)
• Common errors and their solutions (FAQ)

Intended Audience

• Those who understand basic Python syntax and have experience writing simple scripts or functions
• Those who want to organize Python projects and write reusable code
• Those who want to create their own packages and publish them to PyPI

2. What Are Python Packages?

Differences Between Packages and Modules

• Module (Module) Refers to a single Python script (.py file). For example, a Python file like the one below constitutes a module.

  # sample_module.py
  def greet():
      return "Hello, Python!"

• Package (Package) A directory that groups multiple modules together and typically contains an __init__.py file. Using packages allows you to organize and manage multiple modules.

  mypackage/
  ├── __init__.py
  ├── module1.py
  ├── module2.py

Differences from Libraries

Purpose of __init__.py

Basics of __init__.py

# mypackage/__init__.py
from .module1 import greet

def welcome():
    return "Welcome to mypackage!"

from mypackage import greet
print(greet())  # Hello, Python!

Namespace Packages

Summary

• Module is a single .py file, while a package has a directory structure containing multiple modules.
• Library is a collection of software that combines packages and modules.
• __init__.py is required to identify a package and can define initialization settings and convenient imports.
• Since Python 3.3, packages without __init__.py (namespace packages) are also possible.

3. How to Create a Python Package

Basic Package Directory Structure

mypackage/
├── __init__.py  # package identifier file
├── module1.py   # module 1
├── module2.py   # module 2
└── subpackage/  # subpackage
    ├── __init__.py
    ├── submodule1.py
    └── submodule2.py

Roles of Each File

• mypackage/ ：package root directory
• __init__.py ：file that indicates this folder is a package (optional for Python 3.3 and later)
• module1.py、module2.py ：modules within the package
• subpackage/ ：subpackage (contains additional modules inside)

__init__.py Creation and Role

Simple __init__.py

# mypackage/__init__.py

Adding Initial Settings to __init__.py

# mypackage/__init__.py
from .module1 import greet

def welcome():
    return "Welcome to mypackage!"

from mypackage import greet
print(greet())  # "Hello, Python!"

Creating Modules and Subpackages

Creating a Module (module1.py)

# mypackage/module1.py
def greet():
    return "Hello, Python!"

Creating a Subpackage (subpackage/)

mypackage/
└── subpackage/
    ├── __init__.py
    ├── submodule1.py
    └── submodule2.py

# mypackage/subpackage/__init__.py
from .submodule1 import sub_function

def subpackage_greeting():
    return "Hello from subpackage!"

Verifying the Package

1. Navigate to the parent directory of mypackage

   cd path/to/your/package

2. Open the Python shell

   python

3. Import mypackage and run functions

   import mypackage
   print(mypackage.welcome())  # "Welcome to mypackage!"

Summary

• Python packages consist of directories and __init__.py.
• __init__.py is used for package identification and initialization.
• Leveraging modules and subpackages makes code organization easier.
• After creation, verify in the Python shell to ensure it works correctly.

4. How to Import Packages

Importing Modules Within a Package

mypackage/
├── __init__.py
├── module1.py
├── module2.py
└── subpackage/
    ├── __init__.py
    ├── submodule1.py

Direct Module Import

# mypackage/module1.py
def greet():
    return "Hello from module1!"

import mypackage.module1

print(mypackage.module1.greet())  # Hello from module1!

from Keyword Import

from mypackage.module1 import greet

print(greet())  # Hello from module1!

Differences Between Relative and Absolute Imports

Absolute Import

# mypackage/module2.py
from mypackage.module1 import greet

def call_greet():
    return greet()

Relative Import

# mypackage/module2.py
from .module1 import greet

def call_greet():
    return greet()

• from .module1 import greet → import greet() from module1.py in the same package
• from ..subpackage.submodule1 import some_function → import some_function from subpackage/submodule1.py one level up

Relative Import vs Absolute Import

Simplifying Imports Using __init__.py

# mypackage/__init__.py
from .module1 import greet

from mypackage import greet

print(greet())  # Hello from module1!

Summary

• Module import methods include two types: import and from ... import.
• Absolute imports have high readability with explicit path specifications, but can become verbose.
• Relative imports are concise, but can cause ImportError depending on how the script is executed.
• By leveraging __init__.py, you can simplify package imports.

5. Managing Python Packages (Using pip)

pip for Installing and Uninstalling Packages

Installing Packages

pip install package_name

pip install requests

import requests

response = requests.get("https://example.com")
print(response.status_code)

Uninstalling Packages

pip uninstall package_name

pip uninstall requests

pip freeze and requirements.txt for Environment Management

Outputting the Current Package List

pip freeze

requests==2.26.0
numpy==1.21.2
pandas==1.3.3

pip freeze > requirements.txt

Bulk Installing Packages from requirements.txt

pip install -r requirements.txt

Package Management in Virtual Environments (Using venv)

Creating a Virtual Environment

python -m venv myenv

Activating the Virtual Environment

• Windows (PowerShell)

  myenvScriptsActivate

• Mac / Linux

  source myenv/bin/activate

Package Management Inside the Virtual Environment

pip install flask

deactivate

Package Version Management

Checking Versions of Installed Packages

pip list

pip show package_name

pip show numpy

Name: numpy
Version: 1.21.2
Summary: NumPy is the fundamental package for array computing with Python.

Upgrading Packages to the Latest Version

pip install --upgrade package_name

pip install --upgrade requests

pip list --outdated | awk '{print $1}' | xargs pip install --upgrade

Summary

• You can install packages with pip install package_name and remove them with pip uninstall.
• Using pip freeze > requirements.txt makes it easier to manage project dependencies.
• Using virtual environments (venv) lets you create isolated environments for each project.
• You can check installed package versions with pip list and update them with pip install --upgrade.

6. How to Distribute Python Packages

Package configuration using pyproject.toml

Basic structure of pyproject.toml

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"
[project]

name = "mypackage" version = "0.1.0" description = "My Python package" authors = [{ name = "Your Name", email = "your_email@example.com" }] license = { text = "MIT" } dependencies = ["requests", "numpy"]

Creating packages using setuptools

Preparing the package

mypackage/
├── mypackage/
│   ├── __init__.py
│   ├── module1.py
│   ├── module2.py
├── pyproject.toml
├── README.md
└── LICENSE

• mypackage/: the actual package code
• pyproject.toml: package configuration file
• README.md: package description
• LICENSE: license information

Building the package

python -m build

dist/
├── mypackage-0.1.0-py3-none-any.whl
├── mypackage-0.1.0.tar.gz

Uploading to PyPI using twine

Testing on TestPyPI

pip install twine

python -m twine upload --repository testpypi dist/*

pip install --index-url https://test.pypi.org/simple/ mypackage

Uploading to PyPI (production)

python -m twine upload dist/*

Installing the package from PyPI

pip install mypackage

Summary

• It is recommended to manage package information using pyproject.toml.
• Convert to distributable formats (sdist, whl) using python -m build.
• After verifying on TestPyPI using twine, upload to PyPI.
• The published package can be installed with pip install.

7. Frequently Asked Questions (FAQ)

__init__.py is always required?

# mypackage/__init__.py

What is the difference between relative and absolute imports?

• Absolute imports

  from mypackage.module1 import greet

• Specify the path from the root directory, making the package structure clear
• Highly readable and less prone to errors
• Relative imports

  from .module1 import greet

• Use a . (dot) to refer to modules within the same package
• May raise ImportError when run from outside the package

Are there naming conventions for packages?

• Package names → use all‑lowercase words

  mypackage, utilities, datahandler

• Module names → use short, clear lowercase words

  module1, parser, reader

What is the purpose of requirements.txt?

pip freeze > requirements.txt

pip install -r requirements.txt

Why do ModuleNotFoundError and ImportError occur?

Solutions for ModuleNotFoundError

1. Check whether the package is installed

   pip list | grep package_name

2. If it is not installed, add it with pip install

   pip install package_name

Solutions for ImportError

1. Try an absolute import

   from mypackage.module1 import greet

2. Check the Python execution directory

   import sys
   print(sys.path)

Why can’t I pip install after uploading to PyPI?

1. Verify that the upload succeeded

   twine check dist/*

2. Specify the correct package name

   pip install mypackage

3. Wait for PyPI to reflect the upload

• It may take a few minutes for the package to appear on PyPI after upload.

• If you uploaded to TestPyPI
• Specify --index-url instead of plain pip install

   pip install --index-url https://test.pypi.org/simple/ mypackage

Summary

• __init__.py is not required from Python 3.3 onward, but adding it is common.
• Absolute imports are recommended because they are more readable and less error‑prone.
• Using requirements.txt makes it easy to manage package dependencies.
• ModuleNotFoundError and ImportError can be resolved by checking package installation status and import paths.

8. Summary

Basic Concepts of Python Packages

• Module is a single .py file, and a Package is a directory that groups multiple modules.
• Library is a collection of software that bundles multiple packages and modules.
• __init__.py helps identify a package and simplify imports.

How to Create a Python Package

• Create a mypackage/ directory and add __init__.py to have it recognized as a package.
• Split modules appropriately and design code for easy reuse.
• Using absolute imports makes module references within a package clear.

Managing Packages

• Install a package with pip install package_name and remove it with pip uninstall package_name.
• Using pip freeze > requirements.txt makes it easier to reproduce a project’s environment.
• Create a virtual environment with python -m venv myenv to build an isolated environment per project.

Distributing Packages

• Use pyproject.toml to manage package metadata and build in a standard format.
• Build the package into the dist/ directory with python -m build.
• Use twine to test on TestPyPI, and if everything looks good, upload to PyPI.
• The published package can be easily installed with pip install mypackage.

Common Errors and Solutions

• For ModuleNotFoundError, check that the package is installed and verify the sys.path settings.
• For ImportError, try using absolute imports instead of relative imports.
• Use pip list --outdated to check for newer package versions and upgrade as needed.

Best Practices for Python Package Management

1. Follow package naming conventions

• Use simple, lowercase names and keep readability in mind.

1. Leverage virtual environments (venv)

• Encourage development that does not depend on the global environment.

1. Always manage requirements.txt

• Prevent issues in team development and deployment.

1. Test on TestPyPI before publishing to PyPI

• Prevent errors in advance and ensure quality.

Summary and Future Learning

• Advanced package development (adding custom scripts, introducing C extensions)
• Automated package deployment using CI/CD
• Environment setup combined with Docker