editable-development-mode-installation-and-verification

editable-development-mode-installation-and-verification

Summary

Install a Python package in editable (development) mode and verify correctness through import, unit testing, code coverage, style linting, and documentation generation. This workflow enables rapid iteration on package code while ensuring all components remain functional and compliant.

When to use

When you are developing or contributing to a Python package (like cooltools) and need to test changes to utility functions, library integrations, or API implementations without reinstalling the package after each modification. Apply this when you must verify that a new function (e.g., adaptive_coarsegrain) is correctly exposed in the package namespace, passes all unit tests, meets code style standards, and is properly documented.

When NOT to use

• Package is already installed in production mode and users should not modify source code; use standard installation (pip install package_name) instead.
• You are running a pre-compiled or binary package with no Python source; editable mode requires a setuptools-compatible source tree.
• Development environment lacks build tools (gcc, Make, Sphinx) or permission to modify the installation directory; fall back to virtual environment isolation or containerization.

Inputs

• Git repository containing Python package source code (e.g., open2c/cooltools)
• Python environment with pip and build tools available
• Package setup.py or pyproject.toml with dependency specifications

Outputs

• Installed package in editable mode with symlink to source directory
• Unit test execution report (passed/failed counts, coverage metrics)
• Code style lint report (flake8 compliance check)
• Built Sphinx HTML documentation with API reference
• Confirmation that target function/utility is importable and callable

How to apply

Begin by cloning the target repository and installing it in editable mode using pip install -e . from the repository root; this creates a symlink to the development directory so changes are immediately reflected without reinstallation. Next, import the function or module of interest in a Python session to confirm it is callable and accessible from the intended namespace (e.g., from cooltools.lib import adaptive_coarsegrain). Then run the full pytest suite with pytest to execute unit tests and verify behavioral correctness. Extend pytest with the pytest-cov extension to measure code coverage and ensure the new code paths are exercised; also run pytest-flake8 to enforce code style compliance using flake8 linting rules. Finally, build the Sphinx documentation using make docs and inspect the generated API reference to confirm the function appears with its docstring and signature intact. Success is indicated when all tests pass, coverage is satisfactory, no style violations are reported, and the function is discoverable in the built documentation.