Enhanced Interfaces: Add support for Linode-related endpoints and fields (#533)

* Add support for Linode-related endpoints and fields

* oops

* tiny fixes

* fix docsa

* Add docs examples

* Docs fixes

* oops

* Remove irrelevant test

* Add LA notices

* Fill in API documentation URLs

* Add return types

Author: lgarber-akamai

linode_api4/groups/linode.py

@@ -1,13 +1,11 @@
 import base64
 import os
-from collections.abc import Iterable
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
 from linode_api4.common import load_and_validate_keys
 from linode_api4.errors import UnexpectedResponseError
 from linode_api4.groups import Group
 from linode_api4.objects import (
-    ConfigInterface,
     Firewall,
     Instance,
     InstanceDiskEncryptionType,
@@ -21,8 +19,13 @@
 from linode_api4.objects.linode import (
     Backup,
     InstancePlacementGroupAssignment,
+    InterfaceGeneration,
+    NetworkInterface,
     _expand_placement_group_assignment,
 )
+from linode_api4.objects.linode_interfaces import (
+    LinodeInterfaceOptions,
+)
 from linode_api4.util import drop_null_keys
 
 
@@ -153,6 +156,13 @@ def instance_create(
                 int,
             ]
         ] = None,
+        interfaces: Optional[
+            List[
+                Union[LinodeInterfaceOptions, NetworkInterface, Dict[str, Any]],
+            ]
+        ] = None,
+        interface_generation: Optional[Union[InterfaceGeneration, str]] = None,
+        network_helper: Optional[bool] = None,
         **kwargs,
     ):
         """
@@ -230,6 +240,30 @@ def instance_create(
                "us-east",
                backup=snapshot)
 
+        **Create an Instance with explicit interfaces:**
+
+        To create a new Instance with explicit interfaces, provide list of
+        LinodeInterfaceOptions objects or dicts to the "interfaces" field::
+
+        linode, password = client.linode.instance_create(
+            "g6-standard-1",
+            "us-mia",
+            image="linode/ubuntu24.04",
+
+            # This can be configured as an account-wide default
+            interface_generation=InterfaceGeneration.LINODE,
+
+            interfaces=[
+                LinodeInterfaceOptions(
+                    default_route=LinodeInterfaceDefaultRouteOptions(
+                        ipv4=True,
+                        ipv6=True
+                    ),
+                    public=LinodeInterfacePublicOptions
+                )
+            ]
+        )
+
         **Create an empty Instance**
 
         If you want to create an empty Instance that you will configure manually,
@@ -293,9 +327,13 @@ def instance_create(
         :type disk_encryption: InstanceDiskEncryptionType or str
         :param interfaces: An array of Network Interfaces to add to this Linode’s Configuration Profile.
                            At least one and up to three Interface objects can exist in this array.
-        :type interfaces: list[ConfigInterface] or list[dict[str, Any]]
+        :type interfaces: List[LinodeInterfaceOptions], List[NetworkInterface], or List[dict[str, Any]]
         :param placement_group: A Placement Group to create this Linode under.
         :type placement_group: Union[InstancePlacementGroupAssignment, PlacementGroup, Dict[str, Any], int]
+        :param interface_generation: The generation of network interfaces this Linode uses.
+        :type interface_generation: InterfaceGeneration or str
+        :param network_helper: Whether this instance should have Network Helper enabled.
+        :type network_helper: bool
 
         :returns: A new Instance object, or a tuple containing the new Instance and
                   the generated password.
@@ -311,13 +349,6 @@ def instance_create(
             ret_pass = Instance.generate_root_password()
             kwargs["root_pass"] = ret_pass
 
-        interfaces = kwargs.get("interfaces", None)
-        if interfaces is not None and isinstance(interfaces, Iterable):
-            kwargs["interfaces"] = [
-                i._serialize() if isinstance(i, ConfigInterface) else i
-                for i in interfaces
-            ]
-
         params = {
             "type": ltype,
             "region": region,
@@ -336,6 +367,9 @@ def instance_create(
                 if placement_group
                 else None
             ),
+            "interfaces": interfaces,
+            "interface_generation": interface_generation,
+            "network_helper": network_helper,
         }
 
         params.update(kwargs)

linode_api4/groups/networking.py

@@ -119,7 +119,7 @@ def firewall_templates(self, *filters):
         """
         Returns a list of Firewall Templates available to the current user.
 
-        API Documentation: Not yet available.
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-firewall-templates
 
         NOTE: This feature may not currently be available to all users.
 
@@ -135,7 +135,9 @@ def firewall_templates(self, *filters):
     def firewall_settings(self) -> FirewallSettings:
         """
         Returns an object representing the Linode Firewall settings for the current user.
-        API Documentation: Not yet available.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-firewall-settings
+
         NOTE: This feature may not currently be available to all users.
         :returns: An object representing the Linode Firewall settings for the current user.
         :rtype: FirewallSettings
@@ -180,6 +182,64 @@ def ipv6_ranges(self, *filters):
         """
         return self.client._get_and_filter(IPv6Range, *filters)
 
+    def ipv6_range_allocate(
+        self,
+        prefix_length: int,
+        route_target: Optional[str] = None,
+        linode: Optional[Union[Instance, int]] = None,
+        **kwargs,
+    ) -> IPv6Range:
+        """
+        Creates an IPv6 Range and assigns it based on the provided Linode or route target IPv6 SLAAC address.
+
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-ipv6-range
+
+        Create an IPv6 range assigned to a Linode by ID::
+
+            range = client.networking.ipv6_range_allocate(64, linode_id=123)
+
+
+        Create an IPv6 range assigned to a Linode by SLAAC::
+
+            range = client.networking.ipv6_range_allocate(
+                64,
+                route_target=instance.ipv6.split("/")[0]
+            )
+
+        :param prefix_length: The prefix length of the IPv6 range.
+        :type prefix_length: int
+        :param route_target: The IPv6 SLAAC address to assign this range to. Required if linode is not specified.
+        :type route_target: str
+        :param linode: The ID of the Linode to assign this range to.
+                       The SLAAC address for the provided Linode is used as the range's route_target.
+                       Required if linode is not specified.
+        :type linode: Instance or int
+
+        :returns: The new IPAddress.
+        :rtype: IPAddress
+        """
+
+        params = {
+            "prefix_length": prefix_length,
+            "route_target": route_target,
+            "linode_id": linode,
+        }
+
+        params.update(**kwargs)
+
+        result = self.client.post(
+            "/networking/ipv6/ranges",
+            data=drop_null_keys(_flatten_request_body_recursive(params)),
+        )
+
+        if not "range" in result:
+            raise UnexpectedResponseError(
+                "Unexpected response when allocating IPv6 range!", json=result
+            )
+
+        result = IPv6Range(self.client, result["range"], result)
+        return result
+
     def ipv6_pools(self, *filters):
         """
         Returns a list of IPv6 pools on this account.

linode_api4/objects/__init__.py

@@ -6,6 +6,7 @@
 from .region import Region
 from .image import Image
 from .linode import *
+from .linode_interfaces import *
 from .volume import *
 from .domain import *
 from .account import *

linode_api4/objects/base.py

@@ -239,6 +239,7 @@ def __setattr__(self, name, value):
         """
         Enforces allowing editing of only Properties defined as mutable
         """
+
         if name in type(self).properties.keys():
             if not type(self).properties[name].mutable:
                 raise AttributeError(