feat(extras): Add range_contains ORM lookup

Introduce a generic lookup for ArrayField(RangeField) that matches rows
where a scalar value is contained by any range in the array
(e.g. VLANGroup.vid_ranges).
Replace the raw-SQL helper in the VLANGroup FilterSet (`contains_vid`)
with the ORM lookup for better maintainability.
Add tests for the lookup and the FilterSet behavior.

Closes #20497

netbox/extras/lookups.py

@@ -1,9 +1,39 @@
+from django.contrib.postgres.fields import ArrayField
+from django.contrib.postgres.fields.ranges import RangeField
 from django.db.models import CharField, JSONField, Lookup
 from django.db.models.fields.json import KeyTextTransform
 
 from .fields import CachedValueField
 
 
+class RangeContains(Lookup):
+    """
+    Filter ArrayField(RangeField) columns where ANY element-range contains the scalar RHS.
+
+    Usage (ORM):
+        Model.objects.filter(<range_array_field>__range_contains=<scalar>)
+
+    Works with int4range[], int8range[], daterange[], tstzrange[], etc.
+    """
+
+    lookup_name = 'range_contains'
+
+    def as_sql(self, compiler, connection):
+        # Compile LHS (the array-of-ranges column/expression) and RHS (scalar)
+        lhs, lhs_params = self.process_lhs(compiler, connection)
+        rhs, rhs_params = self.process_rhs(compiler, connection)
+
+        # Guard: only allow ArrayField whose base_field is a PostgreSQL RangeField
+        field = getattr(self.lhs, 'output_field', None)
+        if not (isinstance(field, ArrayField) and isinstance(field.base_field, RangeField)):
+            raise TypeError('range_contains is only valid for ArrayField(RangeField) columns')
+
+        # Range-contains-element using EXISTS + UNNEST keeps the range on the LHS: r @> value
+        sql = f"EXISTS (SELECT 1 FROM unnest({lhs}) AS r WHERE r @> {rhs})"
+        params = lhs_params + rhs_params
+        return sql, params
+
+
 class Empty(Lookup):
     """
     Filter on whether a string is empty.
@@ -25,7 +55,7 @@ class JSONEmpty(Lookup):
 
     A key is considered empty if it is "", null, or does not exist.
     """
-    lookup_name = "empty"
+    lookup_name = 'empty'
 
     def as_sql(self, compiler, connection):
         # self.lhs.lhs is the parent expression (could be a JSONField or another KeyTransform)
@@ -69,6 +99,7 @@ class NetContainsOrEquals(Lookup):
         return 'CAST(%s AS INET) >>= %s' % (lhs, rhs), params
 
 
+ArrayField.register_lookup(RangeContains)
 CharField.register_lookup(Empty)
 JSONField.register_lookup(JSONEmpty)
 CachedValueField.register_lookup(NetHost)