https://github.com/disqus/django-bitfield

A BitField extension for Django Models
https://github.com/disqus/django-bitfield

Last synced: 3 days ago
JSON representation

A BitField extension for Django Models

• Host: GitHub
• URL: https://github.com/disqus/django-bitfield
• Owner: disqus
• License: apache-2.0
• Created: 2010-12-28T02:07:35.000Z (almost 14 years ago)
• Default Branch: master
• Last Pushed: 2024-01-20T11:01:09.000Z (10 months ago)
• Last Synced: 2024-05-22T15:09:08.269Z (6 months ago)
• Language: Python
• Homepage: http://code.disqus.com
• Size: 188 KB
• Stars: 374
• Watchers: 25
• Forks: 147
• Open Issues: 26
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

        
django-bitfield

---------------

.. image:: https://github.com/disqus/django-bitfield/actions/workflows/ci.yml/badge.svg

    :target: https://github.com/disqus/django-bitfield/actions

Provides a BitField like class (using a BigIntegerField) for your Django models.

Requirements

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

* Django >= 1.11 (a newer version with current security support is

  highly recommended).

* PostgreSQL (see notes)

**Notes:**

- SQLite does not support save operations using a ``Bit`` (per the example under Usage).

- MySQL fails on most queries related to BitField's.

Installation

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

Install it with pip (or easy_install)::

	pip install django-bitfield

Usage

=====

First you'll need to attach a BitField to your class. This acts as a BigIntegerField (BIGINT) in your database::

	from bitfield import BitField

	class MyModel(models.Model):

	    flags = BitField(flags=(

	        'awesome_flag',

	        'flaggy_foo',

	        'baz_bar',

	    ))

Flags can also be defined with labels::

	class MyModel(models.Model):

	    flags = BitField(flags=(

	        ('awesome_flag', 'Awesome Flag!'),

	        ('flaggy_foo', 'Flaggy Foo'),

	        ('baz_bar', 'Baz (bar)'),

	    ))

Now you can use the field using very familiar Django operations::

	# Create the model

	o = MyModel.objects.create(flags=0)

	# Add awesome_flag (does not work in SQLite)

	MyModel.objects.filter(pk=o.pk).update(flags=F('flags').bitor(MyModel.flags.awesome_flag))

	# Set flags manually to [awesome_flag, flaggy_foo]

	MyModel.objects.filter(pk=o.pk).update(flags=MyModel.flags.awesome_flag | MyModel.flags.flaggy_foo)

	# Remove awesome_flag (does not work in SQLite)

	MyModel.objects.filter(pk=o.pk).update(flags=F('flags').bitand(~MyModel.flags.awesome_flag))

	# Find by awesome_flag

	MyModel.objects.filter(flags=MyModel.flags.awesome_flag)

	# Exclude by awesome_flag

	MyModel.objects.filter(flags=~MyModel.flags.awesome_flag)

	# Test awesome_flag

	if o.flags.awesome_flag:

	    print "Happy times!"

	# List all flags on the field

	for f in o.flags:

	    print f

	# Get a flag label

	print o.flags.get_label('awesome_flag')

Enjoy!

Admin

=====

To use the widget in the admin, you'll need to import the classes and then update or create

a ModelAdmin with these formfield_overrides lines in your admin.py::

    from bitfield import BitField

    from bitfield.forms import BitFieldCheckboxSelectMultiple

    class MyModelAdmin(admin.ModelAdmin):

	formfield_overrides = {

		BitField: {'widget': BitFieldCheckboxSelectMultiple},

	}

	

    admin.site.register(MyModel, MyModelAdmin)

There is also a ``BitFieldListFilter`` list filter (Django 1.4 or newer).

To use it set ``list_filter`` ModelAdmin option::

    list_filter = (

            ('flags', BitFieldListFilter,)

            )

BitFieldListFilter is in ``bitfield.admin`` module::

    from bitfield.admin import BitFieldListFilter

Changelog

=========

2.2.0 - 2022-07-11:

- Add support for Django 4.0.

- Drop support for Django versions older than 1.11.29.

- Drop support for Python 2.7.

2.1.0 - 2021-05-25:

- Add support for Django 3.1, 3.2 (No changes needed).

- Add support for Python 3.8, 3.9.

- Fixed multiple bugs with use in the Django admin.

- Removed dead compatibility code.

2.0.1 - 2020-01-25:

- Add support for Django 3.0.

2.0.0 - 2020-01-24:

- Drop support for Django versions below 1.10.

- Use _meta.private_fields instead of deprecated _meta.virtual_fields in CompositeBitField.

- Add testing with python 3.6, 3.7 and Django 2.x to travis configuration.