Django PostgreSQL Netfields
===========================

.. image:: https://secure.travis-ci.org/jimfunk/django-postgresql-netfields.png

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 a ``CIDR`` and
a ``MACADDR`` field have been added. This library also provides a manager that
allows for advanced IP based lookup 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
field is represented as an EUI type 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
------------

Current version of code is targeting Django >= 1.8 support, as this relies
heavily on ORM internals and supporting multiple versions is especially tricky.

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()
     # ...

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

These correspond with the operators and functions from
http://www.postgresql.org/docs/9.4/interactive/functions-net.html

``CidrAddressField`` includes two extra lookups:

``__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                                       |
+--------------------------------+------------------+----------------------+----------------------------------------------------------------+

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);"
         ),
         # ...
     ]

Errata
------

* In Django < 1.9.6 types returned in ArrayFields are strings and not ipaddress types. See
  https://code.djangoproject.com/ticket/25143

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 :-)
