This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Django category app with bitwise tree-like structure of primary key.

Project Description

Abstract (and one concrete) Model with tree-like structure using bitwise ID field. This implementation is very simple and super fast! Given a category, you can query for related models (products) to the category and all it’s subcategories by SomeModel.objects.filter(category_id__gte=category.gte,

Technical details

The key idea is to reserve a block of bits in model’s ID for different levels of hierarchy. In the basic setup we expect 32 bit ID (can be changed via ID_BIT_WIDTH) and we give 5 bits for each level (can be changed via LEVEL_BIT_WIDTH). The IDs looks like this:

XXXXX000000000000000000000000000  # mask for the root category
00001000000000000000000000000000  # first root
00010000000000000000000000000000  # second root
00011000000000000000000000000000  # third root

00001000010000000000000000000000  # first child of the first root
00001000100000000000000000000000  # second child of the first root

...and so on

Getting all descendants in all levels is in hierarchical_instance.descendants, but under the hood it is as simple as:


What is included in this app

  • abstract HierarchicalModel which takes care about the magic with IDs
  • abstract BaseCategory which contains the most usual category implementation
  • HierarchicalField which you can use for any custom model
  • HierarchicalWidget which dynamically (via AJAX) creates / deletes select boxes
  • and which contains AJAX magic for form field working

How to make it work

If you just want to use just one of the abstract models then you don’t need to do anything special. Import the abstract model from bitcategory.models import BaseCategory and inherit from it in your concrete Model. Then make a foreign key in your another model which is going to use categories:

# :file:
from django.db import models
from bitcategory.models import BaseCategory

class MyCategory(BaseCategory):
    # BaseCategory already provides fileds name, slug and path
    class Meta:
        abstract = False

class MyProduct(models.Model):
    # some other fields like price, quantity ....
    category = models.ForeignKey('myproject.MyCategory', verbose_name=_("Category"))

That is all to your Model definition. Now, provided you have a concrete instance of MyCategory in variable category, you can query products within the category and all its subcategories by:


or to get products only for the category by:


However, if you want to have the awesome dynamic select boxes in your forms with category in it, you need to do more

  • add the bitcategory into your INSTALLED_APPS

  • add bitcategory.urls into your urls and specify your custom hierarchical model. If you didn’t create your custom hierarchical model, then use our pre-built concrete model bitcategory.models.Category. We do that in order to be able to respond to AJAX requests which are sent by the bitcategory.fields.HierarchicalField. The most simple way looks like:

    # :file:
    from django.conf.urls import patterns, include, url
    from myapp.models import YourHierarchicalModel
    urlpatterns = patterns('',
          url('', include('bitcategory.urls'), {"model": YourHierarchicalModel}),

Now you are ready to show your form with categories in it. First, add bitcategory.fields.HierarchicalField in the form. When rendering the form into a page, don’t forget to include {{}} into your template for javascripts.

Release History

Release History

This version
History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django_bit_category-0.5.2-py2.py3-none-any.whl (13.6 kB) Copy SHA256 Checksum SHA256 3.5 Wheel Oct 28, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting