python-package-api-interface-design

Python Package API Interface Design

Summary

Design and document a well-structured Python package API that exposes utility functions through organized subpackages (e.g., cooltools.lib) with clear imports, stable interfaces, and comprehensive Sphinx documentation. This skill ensures that scientific computation libraries are discoverable, testable, and maintainable across versions.

When to use

You are building or refactoring a scientific Python library and need to decide how to organize and expose utility functions (e.g., adaptive coarse-graining, filtering, analysis routines) so that end users can import and call them reliably. Use this skill when you have a set of related functions that should live in a logical subpackage (lib, utils, analysis) and you want to document the API surface, enforce code quality, and validate that the interface works as intended.

When NOT to use

• Your package is a single-file script or does not need to expose a public API to other projects.
• You are working with unstable, experimental code that is not ready for external consumption (the article notes: 'New functionality for smoothing P(s) and derivatives (API is not yet stable)').
• Your primary goal is rapid prototyping; formal API design and documentation overhead may not justify the effort until the library is stabilized.

Inputs

• Python source files with utility functions (e.g., .py modules)
• Package structure with init.py files defining public exports
• Docstrings in Numpy or similar parseable format
• Configuration files (setup.py, setup.cfg, pyproject.toml, Sphinx conf.py)

Outputs

• Organized subpackage (e.g., cooltools.lib) with importable public API
• Sphinx-generated HTML API reference documentation
• pytest unit test suite confirming importability and function behavior
• Code coverage and style reports (pytest-cov, pytest-flake8 output)
• Formatted source code passing black or autopep8 checks

How to apply

Organize utility functions into a dedicated subpackage (e.g., cooltools.lib) with explicit init.py imports that expose the public API. Write each function with Numpy-style docstrings so that Sphinx can automatically generate API reference documentation. Install the package in editable (development) mode using pip install -e . to allow rapid testing of changes. Run pytest with code-coverage extensions (pytest-cov) and style checks (pytest-flake8, flake8) to ensure functions meet quality standards. Apply a code formatter like black or autopep8 to maintain consistent style. Build the Sphinx documentation locally with make docs and verify that the function appears in the API reference with correct signatures and docstrings. Confirm via pytest that the function is importable from the intended path (e.g., from cooltools.lib import adaptive_coarsegrain) and behaves as expected in unit tests.