Skip to main content

Django + shell_plus + Jupyter notebooks made easy

Project description

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, or another directory of your choosing. 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 you have created your notebook in a different directory, instead do:
# plus = activate(search_dir="/path/to/your/project")

# 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
nmpowell
Nick Powell
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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dj_notebook-0.7.0.tar.gz (28.9 kB view hashes)

Uploaded Source

Built Distribution

dj_notebook-0.7.0-py3-none-any.whl (22.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page