Django + Jupyter notebooks made easy

A Jupyter notebook with access to objects from the Django ORM is a powerful tool to introspect data and run ad-hoc queries.

Full documentation available at dj-notebook

Features

Easy ipython notebooks with Django
Built-in integration with the imported objects from django-extensions
Inheritance diagrams on any object, including ORM models
Converts any Django QuerySet to Pandas Dataframe
Handy function for displaying mermaid charts in
Generates visual maps of model relations

Installation

Use your installation tool of choice, here we use venv and pip:

python -m venv venv
source venv/bin/activate
pip install dj_notebook

Usage

First, find your project's manage.py file and open it. Copy whatever is being set to DJANGO_SETTINGS_MODULE into your clipboard.

Create an ipython notebook in the same directory as manage.py. In VSCode, simply add a new .ipynb file. If using Jupyter Lab, use the File -> New -> Notebook menu option.

Then in the first cell enter:

from dj_notebook import activate

plus = activate()

# If that throws an error, try one of the following:

# DJANGO_SETTINGS_MODULE_VALUE aka "book_store.settings"
# plus = activate("DJANGO_SETTINGS_MODULE_VALUE")

# Point to location of dotenv file with Django settings
# plus = activate(dotenv_file='.env')

In future cells, you can now load and run Django objects, including the ORM. This three line snippet should give an idea of what you can now do:

from django.contrib.auth import get_user_model
User = get_user_model()
User.objects.all()

Usage Plus

But wait, it gets better!

When you activated the Django environment, you instantiated a variable called 'plus'. The 'plus' variable is an object that contains everything loaded from django-extensions' shell_plus. Here's a demonstration, try running this snippet:

plus.User.objects.all()

We also provide a utility for introspection of classes, which can be useful in sophisticated project architectures. Running this code in a Jupyter notebook shell:

plus.diagram(plus.User)

Generates this image

QuerySet to Dataframe

plus.read_frame(plus.User.objects.all())

Check out the official documentation for more things you can do!

dj-notebook official documentation

Contributors

_{Daniel Roy Greenfeld}	_{Cody Antunez}	_{Geoff Beier}	_{Saransh Sood}	_{Anna Zhydko}	_{Tejo Kaushal}
_{Simon Davy}	_Null	_{Dave Parr}	_{Siew-Yit Yong}

Special thanks

These are people who aren't in our formal git history but should be.

Tom Preston did seminal work on Python paths that later became the foundation of dj-notebook
Evie Clutton was co-author of a pull request and they don't show up in the contributor list above
Tim Schilling assisted with the model_graph method
Charlie Denton is responsible for django-schema-graph, which we leverage as part of the model_graph feature
Christopher Clarke built django-pandas, which dj-notebook uses