README.rst
1django-bitfield
2---------------
3
4.. image:: https://api.travis-ci.org/disqus/django-bitfield.png?branch=master
5 :target: https://travis-ci.org/disqus/django-bitfield
6
7Provides a BitField like class (using a BigIntegerField) for your Django models.
8
9(If you're upgrading from a version before 1.2 the API has changed greatly and is backwards incompatible!)
10
11Requirements
12============
13
14* Django >= 1.10.8
15* PostgreSQL (see notes)
16
17**Notes:**
18
19- SQLite does not support save operations using a ``Bit`` (per the example under Usage).
20- MySQL fails on most queries related to BitField's.
21
22Installation
23============
24
25Install it with pip (or easy_install)::
26
27 pip install django-bitfield
28
29Usage
30=====
31
32First you'll need to attach a BitField to your class. This acts as a BigIntegerField (BIGINT) in your database::
33
34 from bitfield import BitField
35
36 class MyModel(models.Model):
37 flags = BitField(flags=(
38 'awesome_flag',
39 'flaggy_foo',
40 'baz_bar',
41 ))
42
43Flags can also be defined with labels::
44
45 class MyModel(models.Model):
46 flags = BitField(flags=(
47 ('awesome_flag', 'Awesome Flag!'),
48 ('flaggy_foo', 'Flaggy Foo'),
49 ('baz_bar', 'Baz (bar)'),
50 ))
51
52Now you can use the field using very familiar Django operations::
53
54 # Create the model
55 o = MyModel.objects.create(flags=0)
56
57 # Add awesome_flag (does not work in SQLite)
58 MyModel.objects.filter(pk=o.pk).update(flags=F('flags').bitor(MyModel.flags.awesome_flag))
59
60 # Set flags manually to [awesome_flag, flaggy_foo]
61 MyModel.objects.filter(pk=o.pk).update(flags=MyModel.flags.awesome_flag | MyModel.flags.flaggy_foo)
62
63 # Remove awesome_flag (does not work in SQLite)
64 MyModel.objects.filter(pk=o.pk).update(flags=F('flags').bitand(~MyModel.flags.awesome_flag))
65
66 # Find by awesome_flag
67 MyModel.objects.filter(flags=MyModel.flags.awesome_flag)
68
69 # Exclude by awesome_flag
70 MyModel.objects.filter(flags=~MyModel.flags.awesome_flag)
71
72 # Test awesome_flag
73 if o.flags.awesome_flag:
74 print "Happy times!"
75
76 # List all flags on the field
77 for f in o.flags:
78 print f
79
80 # Get a flag label
81 print o.flags.get_label('awesome_flag')
82
83Enjoy!
84
85Admin
86=====
87
88To use the widget in the admin, you'll need to import the classes and then update or create
89a ModelAdmin with these formfield_overrides lines in your admin.py::
90
91 from bitfield import BitField
92 from bitfield.forms import BitFieldCheckboxSelectMultiple
93
94 class MyModelAdmin(admin.ModelAdmin):
95 formfield_overrides = {
96 BitField: {'widget': BitFieldCheckboxSelectMultiple},
97 }
98
99 admin.site.register(MyModel, MyModelAdmin)
100
101
102There is also a ``BitFieldListFilter`` list filter (Django 1.4 or newer).
103To use it set ``list_filter`` ModelAdmin option::
104
105 list_filter = (
106 ('flags', BitFieldListFilter,)
107 )
108
109BitFieldListFilter is in ``bitfield.admin`` module::
110
111 from bitfield.admin import BitFieldListFilter
112
113Changelog
114=========
115
1162.1.0 - 2020-05-25:
117
118- Add support for Django 3.1, 3.2 (No changes needed).
119- Add support for Python 3.8, 3.9.
120- Fixed multiple bugs with use in the Django admin.
121- Removed dead compatibility code.
122
1232.0.1 - 2020-01-25:
124
125- Add support for Django 3.0.
126
1272.0.0 - 2020-01-24:
128
129- Drop support for Django versions below 1.10.
130- Use _meta.private_fields instead of deprecated _meta.virtual_fields in CompositeBitField.
131- Add testing with python 3.6, 3.7 and Django 2.x to travis configuration.
132
