Django PostgreSQL Netfields 使用与技术文档

1. 安装指南

要安装 Django PostgreSQL Netfields，请确保您的环境中已经安装了 Django（版本大于等于1.11），psycopg2 或 psycopg，以及 netaddr。然后使用以下命令进行安装：

pip install django-netfields

2. 项目的使用说明

在使用 Django PostgreSQL Netfields 时，您需要确保 netfields 已经被添加到您的 PYTHONPATH 以及 Django 项目的 INSTALLED_APPS 中。

以下是如何在模型中使用不同字段的示例：

• InetAddressField：用于存储 IP 地址和子网掩码/前缀长度对，以 PostgreSQL 的 INET 类型存储。在 Python 中，该字段值以 ipaddress.ip_interface 对象的形式表示。

from netfields import InetAddressField, NetManager

class Example(models.Model):
    inet = InetAddressField()
    # ...

    objects = NetManager()

• CidrAddressField：用于存储 CIDR 值，以 PostgreSQL 的 CIDR 类型存储。在 Python 中，该字段值以 ipaddress.ip_network 对象的形式表示。

from netfields import CidrAddressField, NetManager

class Example(models.Model):
    inet = CidrAddressField()
    # ...

    objects = NetManager()

• MACAddressField 和 MACAddress8Field：用于存储 MAC 地址，分别以 PostgreSQL 的 MACADDR 和 MACADDR8 类型存储。在 Python 中，这些字段值以 netaddr.EUI 对象的形式表示。

from netfields import MACAddressField, MACAddress8Field, NetManager

class Example(models.Model):
    inet_mac = MACAddressField()
    inet_mac8 = MACAddress8Field()
    # ...

    objects = NetManager()

NetManager 管理器提供了额外的 IP 相关查找功能。

3. 项目API使用文档

Django PostgreSQL Netfields 提供了多种数据库函数，可以通过 netfields.functions 模块使用，以下是一些示例：

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')))  # 需要 Django >2.0 来解析
    )
    .filter(family=4)
)

具体的函数列表和说明如下：

CidrAddressField 和 InetAddressField 函数

PostgreSQL 函数	Django 函数	返回类型	描述
abbrev(T)	Abbrev	TextField	显示地址的缩写格式
broadcast(T)	Broadcast	InetAddressField	网络的广播地址
family(T)	Family	IntegerField	提取地址的家族；4 表示 IPv4，6 表示 IPv6
host(T)	Host	TextField	提取地址的 IP 部分
hostmask(T)	Hostmask	InetAddressField	构建网络的主机掩码
masklen(T)	Masklen	IntegerField	提取网络掩码长度
netmask(T)	Netmask	InetAddressField	构建网络掩码
network(T)	Network	CidrAddressField	提取地址的网络部分
set_masklen(T, int)	SetMasklen	T	设置 inet 值的掩码长度
text(T)	AsText	TextField	提取地址和子网掩码长度为文本
inet_same_family(T, T)	IsSameFamily	BooleanField	地址是否属于相同的家族？
inet_merge(T, T)	Merge	CidrAddressField	包含两个给定网络的最小网络

MACAddressField 函数

PostgreSQL 函数	Django 函数	返回类型	描述
trunc(T)	Trunc	T	将最后 3 字节置零

MACAddress8Field 函数

（与 MACAddressField 类似，此处省略）

4. 项目安装方式

请参照“安装指南”中的步骤进行安装。确保环境中已安装所需依赖，然后通过 pip 命令安装 Django PostgreSQL Netfields。