Monorepo Path Management Library

Common errors

• ModuleNotFoundError: No module named 'my_monorepo_package'

  cause `monorepo.setup()` was not called, or the `root` path was configured incorrectly, preventing Python from finding modules in your monorepo.
  fix Ensure `Monorepo.setup(root=...)` is called early in your application's lifecycle, typically in `__init__.py` or the main entry point, and that the `root` argument correctly points to the absolute path of your monorepo's top-level directory.

• TypeError: Monorepo.setup() missing 1 required keyword-only argument: 'root'

  cause The `root` argument was omitted when calling `Monorepo.setup()`, which is a mandatory parameter.
  fix Provide the `root` argument with the absolute path to your monorepo's root directory, e.g., `Monorepo.setup(root=Path(__file__).parent.parent.parent)`.

Warnings

• gotcha Incorrect `root` path specified for `Monorepo.setup()`.
  Fix: Ensure `root` points to the absolute path of your monorepo's root directory, where all top-level packages/services are located. Use `Path(__file__).parent.parent.parent` or similar for robust relative pathing from within a sub-package.
• gotcha Conflicts with existing `PYTHONPATH` environment variable or other programmatic `sys.path` modifications.
  Fix: Be aware that `monorepo` modifies `sys.path`. If you're also using `PYTHONPATH` or other `sys.path.insert()` calls, carefully test the order of operations. `monorepo` inserts its path at the beginning of `sys.path`, giving it high precedence.
• gotcha IDE/Linter issues with recognizing monorepo paths.
  Fix: IDEs like VS Code or PyCharm might not immediately pick up the `sys.path` modifications from `Monorepo.setup()` for static analysis. Configure your IDE's Python interpreter paths or source roots to include the monorepo root manually for correct linting and autocompletion.

Install

• pip install monorepo Install stable version

Imports

• Monorepo

  from monorepo import Monorepo

Quickstart

This quickstart demonstrates how to initialize `monorepo` by calling `Monorepo.setup()` with the absolute path to your monorepo's root directory. Once set up, you can perform direct imports of packages located anywhere under the specified root, such as `from service_b import my_module`, regardless of the current working directory's depth. The example creates a temporary monorepo structure for demonstration.

from pathlib import Path
from monorepo import Monorepo
import sys

# Simulate a monorepo structure for demonstration
# In a real monorepo, __file__ would be inside a sub-package
# For this example, let's create a dummy structure

# Create a dummy monorepo root and a sub-package
monorepo_root = Path('./my_monorepo_root')
monorepo_root.mkdir(exist_ok=True)
(monorepo_root / 'service_a').mkdir(exist_ok=True)
(monorepo_root / 'service_b').mkdir(exist_ok=True)

# Create a dummy module in service_b
(monorepo_root / 'service_b' / '__init__.py').touch(exist_ok=True)
(monorepo_root / 'service_b' / 'my_module.py').write_text("MY_VALUE = 'Hello from service_b!'")

# Now, simulate being inside 'service_a/main.py'
# The 'root' should point to 'my_monorepo_root'
Monorepo.setup(root=monorepo_root.absolute())

# Now you can import from other services/packages in the monorepo root
# This would typically be 'from service_b import my_module'
# We need to ensure 'service_b' is discoverable, which Monorepo.setup does.
# If running from a different directory, adjust sys.path for the quickstart

try:
    from service_b import my_module
    print(f"Successfully imported my_module: {my_module.MY_VALUE}")
except ModuleNotFoundError as e:
    print(f"Failed to import module: {e}")
finally:
    # Clean up dummy files
    import shutil
    if monorepo_root.exists():
        shutil.rmtree(monorepo_root)