https://github.com/chrisseto/django-include

ORM extensions for performance-conscious perfectionists.
https://github.com/chrisseto/django-include

Last synced: 3 months ago
JSON representation

ORM extensions for performance-conscious perfectionists.

• Host: GitHub
• URL: https://github.com/chrisseto/django-include
• Owner: chrisseto
• License: mit
• Created: 2017-04-05T14:35:53.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2022-08-03T19:56:37.000Z (over 2 years ago)
• Last Synced: 2024-10-29T22:56:11.441Z (3 months ago)
• Language: Python
• Homepage:
• Size: 69.3 KB
• Stars: 35
• Watchers: 7
• Forks: 4
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGELOG.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
**************

Django Include

**************

.. image:: https://badge.fury.io/py/django-include.svg

    :target: http://badge.fury.io/py/django-include

    :alt: Latest version

.. image:: https://travis-ci.org/chrisseto/django-include.svg?branch=master

    :target: https://travis-ci.org/chrisseto/django-include

ORM extensions for performance-conscious perfectionists.

Django-include provides ``select_related`` functionality for Many-to-X relations.

Requirements

============

Python 2.7 or 3.5+, Django 1.9+, and any SQL server with support for JSON aggregations.

Currently tested against Postgres 9.6. May work with SQLite with the JSON1 extension.

Installation

============

::

  pip install django-include

Usage

=====

Add `include` to `INSTALLED_APPS`.

Attach ``IncludeManager`` to a model:

.. code-block:: python

  from include import IncludeManager

  class BlogPost(models.Model):

      objects = IncludeManager()

Subclass `IncludeQuerySet`:

.. code-block:: python

  from include import IncludeQuerySet

  class CustomQuerySet(IncludeQuerySet):

      def custom_method(self):

          pass

  class BlogPost(models.Model):

      objects = CustomQuerySet.as_manager()

What/Why?

=========

Consider the following:

Given the following models.

.. code-block:: python

  class Email(Model):

      name = CharField()

      user = ForeignKey('User')

  class User(Model):

      emails = ...

  class Contributor(Model):

      role = CharField()

      user = ForeignKey('User')

      project = ForeignKey('Project')

  class Project(Model):

      contributors = ...

There is an endpoint that returns all the users that contributed to a project, their roles, and their email addresses.

If this endpoint were to be implemented using just Django's ORM, it would end up looking something like this:

.. code-block:: python

    project = Project.objects.get(pk=id)  # 1 Query

    for contributor in project.contributors.select_related('users'):  # 1 Query

        [x for x in contributor.user.emails.all()]  # N * M Queries!

        # Some serialization code

At first this solution seems fine, but what happens when a project has an entire college of people, each with a couple email addresses?

Now, there are certainly other tricks that could be done here to reduce the number of queries and runtime.

For instance, dropping down into raw SQL with a couple joins and/or subselects.

Or you could just use `.include`, do a single query, and not have to explain all the *neat* things you did.

.. code-block:: python

    project = Project.objects.include('contributors__user__emails')  # 1 Query

    for contributor in project.contributors.all():  # Already loaded

        [x for x in contributor.user.emails.all()]  # Already loaded

        # Some serialization code

How?

====

Django Include abuses JSON aggregations and Django's `extra`/`annotate` functions to embed related data.

License

=======

MIT licensed. See the bundled `LICENSE `_ file for more details.