Skip to content
Snippets Groups Projects
Commit 09c48cae authored by Michael Fladischer's avatar Michael Fladischer
Browse files

New upstream version 1.3.1

parent cfff6c45
No related branches found
No related tags found
No related merge requests found
Showing
with 696 additions and 281 deletions
- 1.3.1
* Add support for psycopg v3.x in Django 4.2 and above (Clemens Wolff)
- 1.3.0
* Added MACAddress8Field for EUI-64 values Benoît Vinot
* Fix potential MacAddressField crash in DRF (tfromme)
......
include AUTHORS
include CHANGELOG
include LICENSE
include README.rst
include requirements.txt
include manage.py
include testsettings.py
include test/*
include test/tests/*
This diff is collapsed.
......@@ -22,7 +22,7 @@ fields are represented as EUI types from the netaddr_ module.
Dependencies
------------
This module requires ``Django >= 1.11``, ``psycopg2``, and ``netaddr``.
This module requires ``Django >= 1.11``, ``psycopg2`` or ``psycopg``, and ``netaddr``.
Installation
------------
......
Metadata-Version: 2.1
Name: django-netfields
Version: 1.3.1
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 :-)
AUTHORS
CHANGELOG
LICENSE
MANIFEST.in
README.rst
manage.py
requirements.txt
setup.py
testsettings.py
django_netfields.egg-info/PKG-INFO
django_netfields.egg-info/SOURCES.txt
django_netfields.egg-info/dependency_links.txt
django_netfields.egg-info/not-zip-safe
django_netfields.egg-info/requires.txt
django_netfields.egg-info/top_level.txt
netfields/__init__.py
netfields/apps.py
netfields/compat.py
netfields/fields.py
netfields/forms.py
netfields/functions.py
netfields/lookups.py
netfields/mac.py
netfields/managers.py
netfields/models.py
netfields/psycopg2_types.py
netfields/psycopg3_types.py
netfields/rest_framework.py
test/__init__.py
test/__init__.pyc
test/models.py
test/models.pyc
test/tests/__init__.py
test/tests/__init__.pyc
test/tests/test_form_fields.py
test/tests/test_form_fields.pyc
test/tests/test_functions.py
test/tests/test_functions.pyc
test/tests/test_rest_framework_fields.py
test/tests/test_rest_framework_fields.pyc
test/tests/test_sql_fields.py
test/tests/test_sql_fields.pyc
\ No newline at end of file
netaddr
django>=1.8
six
netfields
......@@ -5,6 +5,11 @@ if VERSION[0] < 2:
else:
from django.db.backends.postgresql.base import DatabaseWrapper
try:
from django.db.backends.postgresql.base import is_psycopg3
except ImportError:
is_psycopg3 = False
if VERSION[0] <= 2:
from django.utils.six import with_metaclass, text_type
else:
......
......@@ -5,7 +5,7 @@ from ipaddress import ip_interface, ip_network
from netaddr import EUI
from netaddr.core import AddrFormatError
from netfields.compat import DatabaseWrapper, with_metaclass, text_type
from netfields.compat import DatabaseWrapper, is_psycopg3, with_metaclass, text_type
from netfields.forms import (
InetAddressFormField,
NoPrefixInetAddressFormField,
......@@ -14,7 +14,11 @@ from netfields.forms import (
MACAddress8FormField
)
from netfields.mac import mac_unix_common, mac_eui64
from netfields.psycopg2_types import Inet, Macaddr, Macaddr8
if is_psycopg3:
from netfields.psycopg3_types import Inet, Macaddr, Macaddr8
else:
from netfields.psycopg2_types import Inet, Macaddr, Macaddr8
NET_OPERATORS = DatabaseWrapper.operators.copy()
......
from psycopg.adapt import Dumper, Loader
from psycopg.postgres import adapters
class Inet(str):
def __repr__(self):
return '%s(%s)' % (self.__class__.__name__, self)
class Macaddr(Inet):
pass
class Macaddr8(Inet):
pass
class _MacaddrDumper(Dumper):
oid = adapters.types['macaddr'].oid
def dump(self, obj):
return str(obj).encode()
class _MacaddrLoader(Loader):
def load(self, data):
if isinstance(data, memoryview):
data = bytes(data)
return Macaddr(data.decode())
class _Macaddr8Dumper(Dumper):
oid = adapters.types['macaddr8'].oid
def dump(self, obj):
return str(obj).encode()
class _Macaddr8Loader(Loader):
def load(self, data):
if isinstance(data, memoryview):
data = bytes(data)
return Macaddr8(data.decode())
adapters.register_loader('macaddr', _MacaddrLoader)
adapters.register_loader('macaddr8', _Macaddr8Loader)
adapters.register_dumper(Macaddr, _MacaddrDumper)
adapters.register_dumper(Macaddr8, _Macaddr8Dumper)
[egg_info]
tag_build =
tag_date = 0
......@@ -23,7 +23,7 @@ if sys.version_info.major == 2:
setup(
name='django-netfields',
version='1.3.0',
version='1.3.1',
license='BSD',
description='Django PostgreSQL netfields implementation',
long_description=get_long_description(),
......
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
No preview for this file type
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment