Creating Python Packages: Distribution and Publishing

# Package Structure and Organization

"""
Standard Python Package Structure:

mypackage/
├── mypackage/              # Main package directory
│   ├── __init__.py        # Package initialization
│   ├── core.py            # Core functionality
│   ├── utils.py           # Utility functions
│   └── subpackage/        # Sub-package
│       ├── __init__.py
│       └── module.py
├── tests/                 # Test directory
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
├── docs/                  # Documentation
│   ├── index.md
│   └── api.md
├── examples/              # Usage examples
│   └── example_usage.py
├── setup.py               # Package configuration (legacy)
├── pyproject.toml         # Modern package configuration
├── setup.cfg              # Static configuration
├── README.md              # Project description
├── LICENSE                # License file
├── MANIFEST.in            # Include additional files
├── requirements.txt       # Development dependencies
├── .gitignore             # Git ignore rules
└── CHANGELOG.md           # Version history
"""

# === mypackage/__init__.py ===

"""
Package initialization file.
Defines what's exported when package is imported.
"""

# Package metadata
__version__ = "1.0.0"
__author__ = "Your Name"
__email__ = "[email protected]"
__license__ = "MIT"

# Import main components for easy access
from .core import MainClass, main_function
from .utils import helper_function, validate_input

# Define public API
__all__ = [
    'MainClass',
    'main_function',
    'helper_function',
    'validate_input'
]

# === mypackage/core.py ===

"""
Core functionality of the package.
"""

class MainClass:
    """Main class providing primary functionality."""
    
    def __init__(self, config=None):
        """Initialize with optional configuration."""
        self.config = config or {}
    
    def process(self, data):
        """Process data and return result."""
        # Processing logic
        return f"Processed: {data}"

def main_function(arg1, arg2):
    """
    Main function for package.
    
    Args:
        arg1: First argument
        arg2: Second argument
    
    Returns:
        Processed result
    """
    return f"Result: {arg1} + {arg2}"

# === mypackage/utils.py ===

"""
Utility functions.
"""

def helper_function(value):
    """
    Helper function.
    
    Args:
        value: Input value
    
    Returns:
        Transformed value
    """
    return value * 2

def validate_input(data):
    """
    Validate input data.
    
    Args:
        data: Data to validate
    
    Raises:
        ValueError: If data is invalid
    
    Returns:
        bool: True if valid
    """
    if not data:
        raise ValueError("Data cannot be empty")
    return True

# === mypackage/subpackage/__init__.py ===

"""
Sub-package initialization.
"""

from .module import SubClass

__all__ = ['SubClass']

# === mypackage/subpackage/module.py ===

"""
Sub-package module.
"""

class SubClass:
    """Sub-package class."""
    
    def __init__(self):
        pass
    
    def sub_method(self):
        """Sub-package method."""
        return "Sub-package result"

# === tests/test_core.py ===

"""
Tests for core functionality.
"""

import unittest
from mypackage.core import MainClass, main_function

class TestMainClass(unittest.TestCase):
    """Test cases for MainClass."""
    
    def setUp(self):
        """Set up test fixtures."""
        self.instance = MainClass()
    
    def test_process(self):
        """Test process method."""
        result = self.instance.process("test data")
        self.assertIn("Processed", result)
    
    def test_main_function(self):
        """Test main function."""
        result = main_function("a", "b")
        self.assertIn("Result", result)

if __name__ == '__main__':
    unittest.main()

# === examples/example_usage.py ===

"""
Example usage of the package.
"""

from mypackage import MainClass, main_function
from mypackage.utils import helper_function

# Create instance
obj = MainClass(config={'setting': 'value'})

# Use functionality
result = obj.process("sample data")
print(result)

# Use function
output = main_function("hello", "world")
print(output)

# Use utility
value = helper_function(10)
print(value)

print("Package structure examples completed!")

# Configuration Files and Metadata

# === setup.py (Traditional approach) ===

"""
setup.py - Package configuration using setuptools.
"""

from setuptools import setup, find_packages
import os

# Read README for long description
with open('README.md', 'r', encoding='utf-8') as f:
    long_description = f.read()

# Read version from package
with open('mypackage/__init__.py', 'r') as f:
    for line in f:
        if line.startswith('__version__'):
            version = line.split('=')[1].strip().strip('"\'')
            break

setup(
    # Basic metadata
    name='mypackage',
    version=version,
    author='Your Name',
    author_email='[email protected]',
    description='A short description of your package',
    long_description=long_description,
    long_description_content_type='text/markdown',
    url='https://github.com/username/mypackage',
    
    # Package discovery
    packages=find_packages(exclude=['tests*', 'docs*']),
    
    # Dependencies
    install_requires=[
        'requests>=2.25.0',
        'numpy>=1.20.0',
        'pandas>=1.2.0'
    ],
    
    # Optional dependencies
    extras_require={
        'dev': [
            'pytest>=6.0',
            'black>=21.0',
            'flake8>=3.9'
        ],
        'docs': [
            'sphinx>=4.0',
            'sphinx-rtd-theme>=1.0'
        ]
    },
    
    # Python version requirement
    python_requires='>=3.7',
    
    # Classifiers
    classifiers=[
        'Development Status :: 4 - Beta',
        'Intended Audience :: Developers',
        'Topic :: Software Development :: Libraries :: Python Modules',
        'License :: OSI Approved :: MIT License',
        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3.10',
        'Programming Language :: Python :: 3.11',
    ],
    
    # Keywords for PyPI search
    keywords='data processing, utilities, example',
    
    # License
    license='MIT',
    
    # Entry points for command-line scripts
    entry_points={
        'console_scripts': [
            'mypackage=mypackage.cli:main',
        ],
    },
    
    # Include additional files
    include_package_data=True,
    
    # Project URLs
    project_urls={
        'Bug Reports': 'https://github.com/username/mypackage/issues',
        'Documentation': 'https://mypackage.readthedocs.io',
        'Source': 'https://github.com/username/mypackage',
    },
)

# === pyproject.toml (Modern approach) ===

"""
# pyproject.toml - Modern package configuration

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

[project]
name = "mypackage"
version = "1.0.0"
description = "A short description of your package"
readme = "README.md"
authors = [
    {name = "Your Name", email = "[email protected]"}
]
license = {text = "MIT"}
requires-python = ">=3.7"
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.7",
    "Programming Language :: Python :: 3.8",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]
keywords = ["data", "processing", "utilities"]
dependencies = [
    "requests>=2.25.0",
    "numpy>=1.20.0",
    "pandas>=1.2.0"
]

[project.optional-dependencies]
dev = [
    "pytest>=6.0",
    "black>=21.0",
    "flake8>=3.9"
]
docs = [
    "sphinx>=4.0",
    "sphinx-rtd-theme>=1.0"
]

[project.urls]
Homepage = "https://github.com/username/mypackage"
Documentation = "https://mypackage.readthedocs.io"
Repository = "https://github.com/username/mypackage"
"Bug Tracker" = "https://github.com/username/mypackage/issues"

[project.scripts]
mypackage = "mypackage.cli:main"

[tool.setuptools.packages.find]
where = ["."]
exclude = ["tests*", "docs*"]

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = "test_*.py"

[tool.black]
line-length = 88
target-version = ['py37', 'py38', 'py39', 'py310', 'py311']
"""

# === setup.cfg (Static configuration) ===

"""
# setup.cfg - Static configuration alternative

[metadata]
name = mypackage
version = attr: mypackage.__version__
author = Your Name
author_email = [email protected]
description = A short description of your package
long_description = file: README.md
long_description_content_type = text/markdown
url = https://github.com/username/mypackage
license = MIT
classifiers =
    Development Status :: 4 - Beta
    Intended Audience :: Developers
    License :: OSI Approved :: MIT License
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.7
    Programming Language :: Python :: 3.8
    Programming Language :: Python :: 3.9
keywords = data, processing, utilities

[options]
packages = find:
python_requires = >=3.7
install_requires =
    requests>=2.25.0
    numpy>=1.20.0
    pandas>=1.2.0

[options.packages.find]
exclude =
    tests*
    docs*

[options.extras_require]
dev =
    pytest>=6.0
    black>=21.0
    flake8>=3.9

[options.entry_points]
console_scripts =
    mypackage = mypackage.cli:main
"""

# === MANIFEST.in (Include additional files) ===

"""
# MANIFEST.in - Specify additional files to include

include README.md
include LICENSE
include CHANGELOG.md
include requirements.txt
recursive-include mypackage *.json *.yaml
recursive-include docs *.md *.rst
recursive-exclude * __pycache__
recursive-exclude * *.py[co]
"""

# === requirements.txt (Development dependencies) ===

"""
# requirements.txt - Development dependencies

# Testing
pytest>=6.0
pytest-cov>=2.12

# Code quality
black>=21.0
flake8>=3.9
mypy>=0.910

# Documentation
sphinx>=4.0
sphinx-rtd-theme>=1.0

# Build tools
build>=0.7
twine>=3.4
"""

# === README.md (Project documentation) ===

"""
# MyPackage

A comprehensive Python package for data processing and utilities.

## Installation

```bash
pip install mypackage
```

## Quick Start

```python
from mypackage import MainClass, main_function

# Create instance
obj = MainClass()
result = obj.process("data")

# Use function
output = main_function("arg1", "arg2")
```

## Features

- Feature 1: Data processing
- Feature 2: Utility functions
- Feature 3: Easy integration

## Documentation

Full documentation available at: https://mypackage.readthedocs.io

## Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

## License

MIT License - see LICENSE file for details.
"""

print("Configuration examples completed!")

# Building and Publishing Packages

"""
Building and Publishing Workflow
"""

# === Step 1: Prepare package ===

# Install build tools
# pip install build twine

# === Step 2: Build distributions ===

# Modern approach using build module
# python -m build

# Creates:
# - dist/mypackage-1.0.0.tar.gz (source distribution)
# - dist/mypackage-1.0.0-py3-none-any.whl (wheel)

# Legacy approach using setup.py
# python setup.py sdist bdist_wheel

# === Step 3: Check distribution ===

# Verify distribution with twine
# twine check dist/*

# === Step 4: Upload to Test PyPI (testing) ===

# Register on test.pypi.org first
# twine upload --repository testpypi dist/*

# Test installation from Test PyPI
# pip install --index-url https://test.pypi.org/simple/ mypackage

# === Step 5: Upload to PyPI (production) ===

# Register on pypi.org
# twine upload dist/*

# === Version management ===

"""
Semantic Versioning: MAJOR.MINOR.PATCH

- MAJOR: Incompatible API changes
- MINOR: Backward-compatible functionality additions
- PATCH: Backward-compatible bug fixes

Examples:
- 1.0.0: Initial release
- 1.0.1: Bug fix
- 1.1.0: New feature
- 2.0.0: Breaking changes
"""

# Update version in __init__.py
# __version__ = "1.1.0"

# === .pypirc configuration ===

"""
# ~/.pypirc - PyPI credentials configuration

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-YOUR-API-TOKEN

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-YOUR-TEST-API-TOKEN
"""

# === Build script ===

import subprocess
import shutil
import os

def clean_build_artifacts():
    """Remove old build artifacts."""
    dirs_to_remove = ['build', 'dist', '*.egg-info']
    
    for pattern in dirs_to_remove:
        for item in os.listdir('.'):
            if pattern.replace('*', '') in item:
                if os.path.isdir(item):
                    shutil.rmtree(item)
                    print(f"Removed {item}")

def build_package():
    """Build package distributions."""
    print("Building package...")
    
    # Clean old builds
    clean_build_artifacts()
    
    # Build using build module
    result = subprocess.run(
        ['python', '-m', 'build'],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print("Build successful!")
        print(result.stdout)
    else:
        print("Build failed!")
        print(result.stderr)
        return False
    
    return True

def check_distributions():
    """Check distribution files."""
    print("\nChecking distributions...")
    
    result = subprocess.run(
        ['twine', 'check', 'dist/*'],
        capture_output=True,
        text=True,
        shell=True
    )
    
    print(result.stdout)
    
    if result.returncode != 0:
        print("Distribution check failed!")
        print(result.stderr)
        return False
    
    return True

def upload_to_testpypi():
    """Upload to Test PyPI."""
    print("\nUploading to Test PyPI...")
    
    result = subprocess.run(
        ['twine', 'upload', '--repository', 'testpypi', 'dist/*'],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print("Upload to Test PyPI successful!")
        print(result.stdout)
    else:
        print("Upload failed!")
        print(result.stderr)

def upload_to_pypi():
    """Upload to PyPI."""
    print("\nUploading to PyPI...")
    
    # Confirmation
    confirm = input("Upload to production PyPI? (yes/no): ")
    
    if confirm.lower() != 'yes':
        print("Upload cancelled")
        return
    
    result = subprocess.run(
        ['twine', 'upload', 'dist/*'],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print("Upload to PyPI successful!")
        print(result.stdout)
    else:
        print("Upload failed!")
        print(result.stderr)

def main():
    """Main build and publish workflow."""
    print("=== Package Build and Publish Workflow ===")
    
    # Build
    if not build_package():
        return
    
    # Check
    if not check_distributions():
        return
    
    # Choose upload destination
    print("\nUpload options:")
    print("1. Test PyPI (testing)")
    print("2. PyPI (production)")
    print("3. Skip upload")
    
    choice = input("Choose option (1/2/3): ")
    
    if choice == '1':
        upload_to_testpypi()
    elif choice == '2':
        upload_to_pypi()
    else:
        print("Skipping upload")

# === Release checklist script ===

def release_checklist():
    """Pre-release checklist."""
    print("=== Release Checklist ===")
    
    checks = [
        "Updated version number in __init__.py",
        "Updated CHANGELOG.md with changes",
        "All tests passing (pytest)",
        "Code formatted (black)",
        "Linting passed (flake8)",
        "Documentation updated",
        "README.md reviewed",
        "License file included",
        "Git tag created for version",
        "Build artifacts cleaned"
    ]
    
    print("\nPlease confirm the following:")
    for i, check in enumerate(checks, 1):
        print(f"{i}. {check}")
    
    confirm = input("\nAll items completed? (yes/no): ")
    return confirm.lower() == 'yes'

# === Version bumping ===

import re

def bump_version(version_type='patch'):
    """Bump version number."""
    
    # Read current version
    with open('mypackage/__init__.py', 'r') as f:
        content = f.read()
    
    # Extract current version
    match = re.search(r'__version__\s*=\s*["\']([^"\']*)["\'']', content)
    if not match:
        print("Version not found!")
        return
    
    current = match.group(1)
    major, minor, patch = map(int, current.split('.'))
    
    # Bump version
    if version_type == 'major':
        major += 1
        minor = 0
        patch = 0
    elif version_type == 'minor':
        minor += 1
        patch = 0
    else:  # patch
        patch += 1
    
    new_version = f"{major}.{minor}.{patch}"
    
    # Update version
    new_content = re.sub(
        r'__version__\s*=\s*["\'][^"\']*["\']',
        f'__version__ = "{new_version}"',
        content
    )
    
    with open('mypackage/__init__.py', 'w') as f:
        f.write(new_content)
    
    print(f"Version bumped: {current} -> {new_version}")

# Example usage (commented)
# if __name__ == '__main__':
#     if release_checklist():
#         main()
#     else:
#         print("Please complete all checklist items first")

print("Build and publish examples completed!")