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

Tom Preston

Null

Tim Schilling

Charlie Denton

Christopher Clarke

Construction

This package was created with Cookiecutter and the simplicity project template.