1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
|
Metadata-Version: 2.1
Name: django-netfields
Version: 1.3.2
Summary: Django PostgreSQL netfields implementation
Home-page: https://github.com/jimfunk/django-postgresql-netfields
Author: James Oakley
Author-email: jfunk@funktronics.ca
License: BSD
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Utilities
License-File: LICENSE
License-File: AUTHORS
Django PostgreSQL Netfields
===========================
This project is an attempt at making proper PostgreSQL net related fields for
Django. In Django pre 1.4 the built in ``IPAddressField`` does not support IPv6
and uses an inefficient ``HOST()`` cast in all lookups. As of 1.4 you can use
``GenericIPAddressField`` for IPv6, but the casting problem remains.
In addition to the basic ``IPAddressField`` replacement, ``InetAddressField``,
a ``CidrAddressField`` a ``MACAddressField``, and a ``MACAddress8Field`` have
been added. This library also provides a manager that allows for advanced IP
based lookups directly in the ORM.
In Python, the values of the IP address fields are represented as types from
the ipaddress_ module. In Python 2.x, a backport_ is used. The MAC address
fields are represented as EUI types from the netaddr_ module.
.. _ipaddress: https://docs.python.org/3/library/ipaddress.html
.. _backport: https://pypi.python.org/pypi/ipaddress/
.. _netaddr: http://pythonhosted.org/netaddr/
Dependencies
------------
This module requires ``Django >= 1.11``, ``psycopg2`` or ``psycopg``, and ``netaddr``.
Installation
------------
.. code-block:: bash
$ pip install django-netfields
Getting started
---------------
Make sure ``netfields`` is in your ``PYTHONPATH`` and in ``INSTALLED_APPS``.
``InetAddressField`` will store values in PostgreSQL as type ``INET``. In
Python, the value will be represented as an ``ipaddress.ip_interface`` object
representing an IP address and netmask/prefix length pair unless the
``store_prefix_length`` argument is set to ``False``, in which case the value
will be represented as an ``ipaddress.ip_address`` object.
.. code-block:: python
from netfields import InetAddressField, NetManager
class Example(models.Model):
inet = InetAddressField()
# ...
objects = NetManager()
``CidrAddressField`` will store values in PostgreSQL as type ``CIDR``. In
Python, the value will be represented as an ``ipaddress.ip_network`` object.
.. code-block:: python
from netfields import CidrAddressField, NetManager
class Example(models.Model):
inet = CidrAddressField()
# ...
objects = NetManager()
``MACAddressField`` will store values in PostgreSQL as type ``MACADDR``. In
Python, the value will be represented as a ``netaddr.EUI`` object. Note that
the default text representation of EUI objects is not the same as that of the
``netaddr`` module. It is represented in a format that is more commonly used
in network utilities and by network administrators (``00:11:22:aa:bb:cc``).
.. code-block:: python
from netfields import MACAddressField, NetManager
class Example(models.Model):
inet = MACAddressField()
# ...
``MACAddress8Field`` will store values in PostgreSQL as type ``MACADDR8``. In
Python, the value will be represented as a ``netaddr.EUI`` object. As with
``MACAddressField``, the representation is the common one
(``00:11:22:aa:bb:cc:dd:ee``).
.. code-block:: python
from netfields import MACAddress8Field, NetManager
class Example(models.Model):
inet = MACAddress8Field()
# ...
For ``InetAddressField`` and ``CidrAddressField``, ``NetManager`` is required
for the extra lookups to be available. Lookups for ``INET`` and ``CIDR``
database types will be handled differently than when running vanilla Django.
All lookups are case-insensitive and text based lookups are avoided whenever
possible. In addition to Django's default lookup types the following have been
added:
``__net_contained``
is contained within the given network
``__net_contained_or_equal``
is contained within or equal to the given network
``__net_contains``
contains the given address
``__net_contains_or_equals``
contains or is equal to the given address/network
``__net_overlaps``
contains or contained by the given address
``__family``
matches the given address family
``__host``
matches the host part of an address regardless of prefix length
``__prefixlen``
matches the prefix length part of an address
These correspond with the operators and functions from
http://www.postgresql.org/docs/9.4/interactive/functions-net.html
``CidrAddressField`` includes two extra lookups (these will be depreciated in the future by ``__prefixlen``):
``__max_prefixlen``
Maximum value (inclusive) for ``CIDR`` prefix, does not distinguish between IPv4 and IPv6
``__min_prefixlen``
Minimum value (inclusive) for ``CIDR`` prefix, does not distinguish between IPv4 and IPv6
Database Functions
''''''''''''''''''
`Postgres network address functions <https://www.postgresql.org/docs/11/functions-net.html>`_ are exposed via the ``netfields.functions`` module. They can be used to extract additional information from these fields or to construct complex queries.
.. code-block:: python
from django.db.models import F
from netfields import CidrAddressField, NetManager
from netfields.functions import Family, Masklen
class Example(models.Model):
inet = CidrAddressField()
# ...
ipv4_with_num_ips = (
Example.objects.annotate(
family=Family(F('inet')),
num_ips=2 ** (32 - Masklen(F('inet'))) # requires Django >2.0 to resolve
)
.filter(family=4)
)
**CidrAddressField and InetAddressField Functions**
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| Postgres Function | Django Function | Return Type | Description |
+================================+==================+======================+================================================================+
| abbrev(``T``) | Abbrev | ``TextField`` | abbreviated display format as text |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| broadcast(``T``) | Broadcast | ``InetAddressField`` | broadcast address for network |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| family(``T``) | Family | ``IntegerField`` | extract family of address; 4 for IPv4, 6 for IPv6 |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| host(``T``) | Host | ``TextField`` | extract IP address as text |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| hostmask(``T``) | Hostmask | ``InetAddressField`` | construct host mask for network |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| masklen(``T``) | Masklen | ``IntegerField`` | extract netmask length |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| netmask(``T``) | Netmask | ``InetAddressField`` | construct netmask for network |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| network(``T``) | Network | ``CidrAddressField`` | extract network part of address |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| set_masklen(``T``, int) | SetMasklen | ``T`` | set netmask length for inet value |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| text(``T``) | AsText | ``TextField`` | extract IP address and netmask length as text |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| inet_same_family(``T``, ``T``) | IsSameFamily | ``BooleanField`` | are the addresses from the same family? |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| inet_merge(``T``, ``T``) | Merge | ``CidrAddressField`` | the smallest network which includes both of the given networks |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
**MACAddressField Functions**
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| Postgres Function | Django Function | Return Type | Description |
+================================+==================+======================+================================================================+
| trunc(``T``) | Trunc | ``T`` | set last 3 bytes to zero |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
**MACAddress8Field Functions**
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| Postgres Function | Django Function | Return Type | Description |
+================================+==================+======================+================================================================+
| trunc(``T``) | Trunc | ``T`` | set last 5 bytes to zero |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
| macaddr8_set7bit(``T``) | Macaddr8Set7bit | ``T`` | set 7th bit to one. Used to generate link-local IPv6 addresses |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+
Indexes
'''''''
As of Django 2.2, indexes can be created for ``InetAddressField`` and ``CidrAddressField`` extra lookups directly on the model.
.. code-block:: python
from django.contrib.postgres.indexes import GistIndex
from netfields import CidrAddressField, NetManager
class Example(models.Model):
inet = CidrAddressField()
# ...
class Meta:
indexes = (
GistIndex(
fields=('inet',), opclasses=('inet_ops',),
name='app_example_inet_idx'
),
)
For earlier versions of Django, a custom migration can be used to install an index.
.. code-block:: python
from django.db import migrations
class Migration(migrations.Migration):
# ...
operations = [
# ...
migrations.RunSQL(
"CREATE INDEX app_example_inet_idx ON app_example USING GIST (inet inet_ops);"
),
# ...
]
Related Django bugs
-------------------
* 11442_ - Postgresql backend casts inet types to text, breaks IP operations and IPv6 lookups.
* 811_ - IPv6 address field support.
https://docs.djangoproject.com/en/dev/releases/1.4/#extended-ipv6-support is also relevant
.. _11442: http://code.djangoproject.com/ticket/11442
.. _811: http://code.djangoproject.com/ticket/811
Similar projects
----------------
https://bitbucket.org/onelson/django-ipyfield tries to solve some of the same
issues as this library. However, instead of supporting just postgres via the proper
fields types the ipyfield currently uses a ``VARCHAR(39)`` as a fake unsigned 64 bit
number in its implementation.
History
-------
Main repo was originally kept https://github.com/adamcik/django-postgresql-netfields
Late April 2013 the project was moved to https://github.com/jimfunk/django-postgresql-netfields
to pass the torch on to someone who actually uses this code actively :-)
|
