Metadata-Version: 2.4
Name: relative-import-context
Version: 0.1.0
Summary: A Jupyter/IPython extension for clean, scoped project imports in notebooks.
Author: Moya Richards
License: MIT
Project-URL: Homepage, https://github.com/moyarich/relative-import-context
Project-URL: Repository, https://github.com/moyarich/relative-import-context
Project-URL: Issues, https://github.com/moyarich/relative-import-context/issues
Keywords: jupyter,ipython,notebook,imports,sys.path,extension
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: IPython
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipython>=8
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# 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:

```python
from app.db import SessionLocal
```

Even when your project is structured correctly:

```text
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:

```bash
python -m app.module
```

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

or:

```bash
pip install -e .
```

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

## Pip Install

From PyPI:

```bash
pip install relative-import-context
```

For local development:

```bash
pip install -e .
```

## Jupyter usage

Load the extension:

```python
%load_ext relative_import_context
```

Add your project root:

```python
%relimport .
```

or from inside a `notebooks/` folder:

```python
%relimport ..
```

Then import normally:

```python
from app.db import SessionLocal
```

## Magic commands

```python
%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:

```python
from relative_import_context import RelativeImportContext

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

## Capture logs during imports

```python
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

```bash
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
