relative-import-context 0.1.0

A Jupyter/IPython extension for clean, scoped project imports in notebooks.

relative-import-context

A Python utility and Jupyter/IPython extension for fixing notebook import issues without messy global sys.path hacks.

The problem

In Jupyter notebooks, this often fails:

from app.db import SessionLocal

Even when your project is structured correctly:

project/
  app/
    __init__.py
    db.py
  notebooks/
    explore.ipynb

That happens because notebooks run inside an already-started Python interpreter. They do not behave like:

python -m app.module

#For regular apps, the better long-term fix is usually:
python -m app.module

or:

pip install -e .

But inside notebooks, developers often still need a clean way to add the project root temporarily.

Pip Install

From PyPI:

pip install relative-import-context

For local development:

pip install -e .

Jupyter usage

Load the extension:

%load_ext relative_import_context

Add your project root:

%relimport .

or from inside a notebooks/ folder:

%relimport ..

Then import normally:

from app.db import SessionLocal

Magic commands

%relimport .                 # Add one path
%relimports . ./libs         # Add multiple paths
%relpaths                    # Show paths added by this extension
%relremove .                 # Remove one path
%relclear                    # Remove all paths added by this extension
%unload_ext relative_import_context

Context manager usage

You can also use it without Jupyter magic commands:

from relative_import_context import RelativeImportContext

with RelativeImportContext("."):
    from app.db import SessionLocal

Capture logs during imports

import logging
from relative_import_context import RelativeImportContext

logger = logging.getLogger("my_app")

with RelativeImportContext(".", logger_name="my_app") as ctx:
    logger.info("Importing app modules")
    from app.db import SessionLocal

print(ctx.get_logs())

Why not just sys.path.append()?

sys.path.append() works, but it is global and easy to forget about. This package gives you either:

• notebook-friendly magic commands for path management
• a scoped context manager that restores sys.path afterward

Development

Test relative-import-context

git clone https://github.com/moyarich/relative-import-context.git
cd relative-import-context
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -s -v

License

MIT