Skip to content

Home

dj-notebook

Django + shell_plus + 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

The ever-growing list of features:

  • Easy Jupyter notebooks with Django
  • Built-in integration with the imported objects from django-extensions shell_plus
  • Saves the state between sessions so you don't need to remember what you did
  • Inheritance diagrams on any object, including ORM models
  • Converts any Django QuerySet to Pandas Dataframe
  • Handy function for displaying MermaidJS charts
  • Generates visual maps of model relations
  • Works in the browser, VSCode, PyCharm, Emacs, Vim, and more!

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

Here's another useful diagram:

plus.model_graph(plus.User)

QuerySet to Dataframe

Want to convert a Django query to a Pandas Dataframe? We got you covered.

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

More things you can do!

dj-notebook official documentation

Contributors

pydanny
Daniel Roy Greenfeld
skyforest
Cody Antunez
geoffbeier
Geoff Beier
specbeck
Saransh Sood
anna-zhydko
Anna Zhydko
Tejoooo
Tejo Kaushal
bloodearnest
Simon Davy
akashverma0786
Null
DaveParr
Dave Parr
syyong
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
  • Stephen Moore for some early work done on the internals of dj-notebook before it was open sourced.
  • django-extensions for providing so many useful tools over the years, and being one of the backbones of this project
prestto
Tom Preston
evieclutton
Null
tim-schilling
Tim Schilling
meshy
Charlie Denton
chrisdev
Christopher Clarke
delfick
Stephen Moore
django-extensions
Django Extensions

Construction

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