autopypath

Table of Contents

• Usage
• Configuration
• Public API
• Contributing
• Code of Conduct

What is autopypath?

autopypath is a library that simplifies the management of the Python module search path (sys.path) for testing and development environments.

It automatically detects your project root (via .git, pyproject.toml, etc.) and intelligently adds source directories to sys.path at runtime.

It does not read .env files to derive PYTHONPATH because the semantics cannot be consistently interpreted across different operating systems.

For example, consider PYTHONPATH=src:test;lib:

• On POSIX, PYTHONPATH is separated by : → ["src", "test;lib"]
• On Windows, PYTHONPATH is separated by ; → ["src:test", "lib"]
• And the intent may have been ["src", "test", "lib"]

All of those interpretations are "reasonable", so autopypath avoids guessing what was meant and instead uses pyproject.toml or autopypath.toml for configuration.

The Problem it Solves

In active development, builds are often broken. Standard test runners (like pytest or tox) often refuse to start if they cannot import the entire package, or if the package hasn't been re-installed into the virtual environment after a structural change.

autopypath allows you to run individual tests or scripts in isolation, even if:

• The project build is currently broken.
• The package is not installed in the current environment.
• Other parts of the test suite are failing due to ongoing refactoring.

It is not a replacement for virtual environments, but a resilience tool. It mitigates path-related ModuleNotFoundError errors, allowing you to debug a specific file without needing the entire project ecosystem to be in a perfect, deployable state.

Installation

Installing from PyPI

pip install autopypath

Installing from Source

git clone https://github.com/JerilynFranz/python-autopypath.git
cd python-autopypath
pip install .

Development Installation

For development purposes, you can install autopypath in editable mode. To make this easier, a bootstrap.py script is provided.

git clone https://github.com/JerilynFranz/python-autopypath.git
cd python-autopypath
python3 bootstrap.py
source .venv/bin/activate  # On Windows use .venv\Scripts\activate

This script will:

1. Set up the development environment (uv sync --all-groups).
2. Install autopypath in editable mode.
3. Install Git hooks for pre-commit checks.
4. Install development tools like tox, sphinx, and ruff.

Usage

Simply import autopypath at the top of your test script. It will automatically detect the project root and adjust sys.path accordingly (by default adding src, lib, src/tests, and tests directories if they exist).

It does not add . to sys.path by default to avoid conflicts with subdirectories that are NOT intended to be packages, but if you want to include the repo root directory, you can configure it via pyproject.toml or autopypath.toml.

Here is an example:

import autopypath  # <--- This line adjusts the sys.path
import pytest

# Now these imports work without installing the package
import mypackage.my_module

if __name__ == '__main__':
   pytest.main([__file__])

You can now run this file directly:

python tests/my_test_script.py

Configuration

autopypath automatically detects pyproject.toml. You can configure it by adding a [tool.autopypath] section.

Example `pyproject.toml`:

[tool.autopypath]
paths = ["lib", "src/tests", ".", "src"]

If you do not use pyproject.toml, you can create an autopypath.toml file either in your root directory or in subdirectories such as src or tests and it will be detected automatically. This can be useful for monorepos or multi-package repositories and allows customization of sys.path per sub-project or for detection of the project root in non-standard layouts.

Example `autopypath.toml`:

[tool.autopypath]
paths = ["src", "src/lib", "tests"]
repo_markers = {".git" = "dir"}

This file can be placed in the root of your project or in any directory that is a parent of your test scripts (but still inside the repo).