library-module-organization-and-accessibility

library-module-organization-and-accessibility

Summary

Organizing a scientific Python library into well-documented subpackages and utilities ensures that functions are discoverable, importable, and properly integrated into the published API. This skill covers how to structure cooltools so that utilities like adaptive_coarsegrain are accessible via established import paths (e.g., cooltools.lib) and appear in generated documentation.

When to use

You are building or extending a multi-module Python library for scientific computation (e.g., Hi-C analysis, image processing) and need to ensure that new utility functions are discoverable by end-users through stable import paths, appear in auto-generated API documentation, and pass code coverage and style linting checks as part of the library's continuous integration.

When NOT to use

• The function is a private internal utility that should not be exposed to end-users; keep it in a private module without exporting it in init.py.
• The library uses lazy importing or plugin discovery mechanisms that do not rely on explicit init.py registration; follow the library's established pattern instead of forcing standard module organization.
• Documentation is generated by an alternative system (e.g., MkDocs, pdoc) that does not use Sphinx; adapt the documentation build step accordingly.

Inputs

• Python source file containing a new utility function (e.g., adaptive_coarsegrain.py)
• cooltools library repository with setup.py or pyproject.toml
• Existing cooltools.lib subpackage init.py
• Pytest configuration (pytest.ini or pyproject.toml [tool.pytest.ini_options])
• Sphinx configuration (conf.py) and documentation source files

Outputs

• Function callable via stable import path (cooltools.lib.adaptive_coarsegrain)
• Function entry in cooltools.lib API reference documentation (HTML/PDF from Sphinx)
• pytest test report with coverage metrics and style compliance
• Updated module docstring reflecting new utilities