Package: django-zen-queries
django-zen-queriesGives you control over which parts of your code are allowed to run queries, and which aren't.Tested against Django 2.2 - 3.1 on Python 3.6 - 3.9.MotivationExplicit is better than implicit(TheZen Of Python)The greatest strength of Django's ORM is also its greatest weakness. By freeing developers from having to think about when database queries are run, the ORM encourages developers tonot think about when database queries are run!This often has great benefits for quick development turnaround, but can have major performance implications in anything other than trivially simple systems.Django's ORM makes queriesimplicit. The Zen of Python tells us thatexplicit is better than implicit, so let's be explicit about which parts of our code are allowed to run queries, and which aren't.Check outthis blog postfor more background.ExampleImagine a pizza restaurant website with the following models:classTopping(models.Model):name=models.CharField(max_length=100)classPizza(models.Model):name=models.CharField(max_length=100)toppings=models.ManyToManyField(Topping)And here's the menu view:defmenu(request):pizzas=Pizza.objects.all()context={'pizzas':pizzas}returnrender(request,'pizzas/menu.html',context)Finally, the template:<h1>Pizza Menu</h1>

<ul>
{% for pizza in pizzas %}
  <li>{{ pizza.name }}</li>
{% endfor %}
</ul>How many queries are run here? Well, the answer is easy to see: it's just one! The query emitted byPizza.objects.all()is all you need to get the information to show on the menu.Now: imagine the client asks for each pizza on the menu to include a count of how many toppings are on the pizza. Easy! Just change the template:<h1>Pizza Menu</h1>

<ul>
{% for pizza in pizzas %}
  <li>{{ pizza.name }} ({{ pizza.toppings.count }})</li>
{% endfor %}
</ul>But how many queries are run now? Well, this is the classicn queries problem. We now have one query to get all our pizzas, and then another queryper pizzato get the toppings count. The more pizzas we have, the slower the app gets.And we probably won't discover this until the website is in production.If you were reading a Django performance tutorial, the next step would be to tell you how to fix this problem (.annotateandCountetc). But that's not the point. The example above is just an illustration of how code in different parts of the codebase, at different levels of abstraction, even possibly (in larger projects) the responsibility of different developers, can interact to result in poor performance. Object-oriented design encourages black-box implementation hiding, but hiding the points at which queries are executed is theworstthing you can do if your aim is to build high-performance web applications. So how do we fix this without breaking all our abstractions?There are two tricks here:Prevent developers from accidentally running queries without realising.Encourage code design that separatesfetching datafromrendering data.This package provides three very simple things:A context manager to allow developers to be explicit about where queries are run.A utility to make querysets less lazy.Some tools to make it easy to use the context manager with Django templates and Django REST framework serializers.To be absolutely clear: this package doesnotgive you any tools to actually improve your query patterns. It just tells you when you need to do it!InstructionsTo demonstrate how to usedjango-zen-queries, let's go back to our example. We want to make it impossible for changes to a template to trigger queries. So, we change our view as follows:defmenu(request):pizzas=Pizza.objects.all()context={'pizzas':pizzas}withqueries_disabled():returnrender(request,'pizzas/menu.html',context)Thequeries_disabledcontext manager here does one very simple thing: it stops any code inside it from running database queries. At all. If they try to run a query, the application will raise aQueriesDisabledErrorexception and blow up.That'salmostenough to give us what we need, but not quite. The code above willalwaysraise aQueriesDisabledError, because the queryset (Pizza.objects.all()) islazy. The database query doesn't actually get run until the queryset is iterated - which happens in the template! So,django-zen-queriesprovides a tiny helper function,fetch, which forces evaluation of a queryset:defmenu(request):pizzas=Pizza.objects.all()context={'pizzas':fetch(pizzas)}withqueries_disabled():returnrender(request,'pizzas/menu.html',context)Now we have exactly what we need: when a developer comes along and adds{{ pizza.toppings.count }}in the template,it justwon't work. They will be forced to figure out how to useannotateandCountin order to get the data they needup front, rather than sometime in the future when customers are complaining that the website is getting slower and slower!DecoratorYou can also usequeries_disabledas a decorator to prohibit database interactions for a whole function or method:@queries_disabled()defvalidate_xyz(pizzas):...This also works with Django'smethod_decoratorutility.Extra toolsAs well as the context managers, the package provides some tools to make it easier to use in common situations:Render shortcutIf you're using the Djangorendershortcut (as in the example above), to avoid having to add the context manager to every view, you can change your importfrom django.shortcuts import rendertofrom zen_queries import render. All the views in that file will automatically be disallowed from running queries during template rendering.TemplateResponse subclassTemplateResponse(andSimpleTemplateResponse) objects are lazy, meaning that template rendering happens on the way "out" of the Django stack.zen_queries.TemplateResponseandzen_queries.SimpleTemplateResponseare subclasses of these withqueries_disabledapplied to therendermethod.You can tell Django's class-based views to use these subclasses instead of the defaultTemplateResponseby setting theresponse_classattribute on the view tozen_queries.TemplateResponse.Django REST framework Serializer and View mixinsDjango REST framework serializers are another major source of unexpected queries. Adding a field to a serializer (perhaps deep within a tree of nested serializers) can very easily cause your application to suddenly start emitting hundreds of queries.zen_queries.rest_framework.QueriesDisabledSerializerMixincan be added to any serializer to wrapqueries_disabledaround the.dataproperty, meaning that the serialization phase is not allowed to execute any queries.You can add this mixin to an existing serializerinstancewithzen_queries.rest_framework.disable_serializer_querieslike this:serializer = disable_serializer_queries(serializer).If you're using REST framework generic views, you can also add a view mixin,zen_queries.rest_framework.QueriesDisabledViewMixin, which overridesget_serializerto mix theQueriesDisabledSerializerMixininto your existing serializer. This is useful because you may want to use the same serializer class between multiple views but only disable queries in some contexts, such as in a list view.  Remember that Python MRO is left-right, so the mixin must come before (to the left of) any base classes that implementget_serializer. The view mixin only disables queries onGETrequests, so can safely be used withListCreateAPIViewand similar.Escape hatchIf you absolutely definitely can't avoid running a query in a part of your codebase that's being executed under aqueries_disabledblock, there is another context manager calledqueries_dangerously_enabledwhich allows you to temporarily re-enable database queries.Template TagsBlock tags for Django's template system are provided which allow you to enable or disable query execution directly in your templates.Important note: In order to use the template libary, you must add"zen_queries"to yourINSTALLED_APPSsetting.Then, use{% load zen_queries %}at the top of your template to load the tag library.The{% queries_disabled}tag is most useful if you wish to applydjango-zen-queriespatterns to a third-party library which provides customisation via overriding templates, such as the Django admin.{% load zen_queries %}

{% queries_disabled %}
<ul>
{% for pizza in pizzas %}
  <li>{{ pizza.name }}</li>
{% endfor %}
</ul>
{% end_queries_disabled %}The{% queries_dangerously_enabled %}tag is handy if you are using therendershortcut orTemplateResponsesubclass (see above) but wish to allow particular parts of your templates to execute queries. This should be used with caution, and you should wrap only the smallest possible sections of your template: the precise line or lines that need to execute the queries.{% load zen_queries %}

{% queries_dangerously_enabled %}
There are {{ pizzas.count }} pizzas.
{% end_queries_dangerously_enabled %}Permissions gotchaAccessing permissions in your templates (via the{{ perms }}template variable) can be a source of queries at template-render time. Fortunately, Django's permission checks arecached by theModelBackend, which can be pre-populated by callingrequest.user.get_all_permissions()in the view, before rendering the template.How does it work?It uses theDatabase Instrumentationfeatures introduced in Django 2.0.InstallationInstall from PyPIpip install django-zen-queriesCode of conductFor guidelines regarding the code of conduct when contributing to this repository please reviewhttps://www.dabapps.com/open-source/code-of-conduct/