feat(cloud)!: use v2 endpoint for floating IPs updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 645
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/gcore%2Fgcore-deca3f038598c9e7614c191a88510b5e50b6a1e482ddeb6e33ce3a226dc05c39.yml
 openapi_spec_hash: 2ee17c1f251ec32cf95b91fb2e643657
-config_hash: 7085751e6bd8f3fd13cfebe04bb99fed
+config_hash: da497b83ee3cacf93b7f67fc7d5b1164

api.md

@@ -414,7 +414,7 @@ from gcore.types.cloud import FloatingIPDetailed
 Methods:
 
 - <code title="post /cloud/v1/floatingips/{project_id}/{region_id}">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">create</a>(\*, project_id, region_id, \*\*<a href="src/gcore/types/cloud/floating_ip_create_params.py">params</a>) -> <a href="./src/gcore/types/cloud/task_id_list.py">TaskIDList</a></code>
-- <code title="patch /cloud/v1/floatingips/{project_id}/{region_id}/{floating_ip_id}">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">update</a>(floating_ip_id, \*, project_id, region_id, \*\*<a href="src/gcore/types/cloud/floating_ip_update_params.py">params</a>) -> <a href="./src/gcore/types/cloud/floating_ip.py">FloatingIP</a></code>
+- <code title="patch /cloud/v2/floatingips/{project_id}/{region_id}/{floating_ip_id}">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">update</a>(floating_ip_id, \*, project_id, region_id, \*\*<a href="src/gcore/types/cloud/floating_ip_update_params.py">params</a>) -> <a href="./src/gcore/types/cloud/task_id_list.py">TaskIDList</a></code>
 - <code title="get /cloud/v1/floatingips/{project_id}/{region_id}">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">list</a>(\*, project_id, region_id, \*\*<a href="src/gcore/types/cloud/floating_ip_list_params.py">params</a>) -> <a href="./src/gcore/types/cloud/floating_ip_detailed.py">SyncOffsetPage[FloatingIPDetailed]</a></code>
 - <code title="delete /cloud/v1/floatingips/{project_id}/{region_id}/{floating_ip_id}">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">delete</a>(floating_ip_id, \*, project_id, region_id) -> <a href="./src/gcore/types/cloud/task_id_list.py">TaskIDList</a></code>
 - <code title="post /cloud/v1/floatingips/{project_id}/{region_id}/{floating_ip_id}/assign">client.cloud.floating_ips.<a href="./src/gcore/resources/cloud/floating_ips.py">assign</a>(floating_ip_id, \*, project_id, region_id, \*\*<a href="src/gcore/types/cloud/floating_ip_assign_params.py">params</a>) -> <a href="./src/gcore/types/cloud/floating_ip.py">FloatingIP</a></code>

src/gcore/resources/cloud/floating_ips.py

@@ -124,24 +124,67 @@ def create(
             cast_to=TaskIDList,
         )
 
-    @typing_extensions.deprecated("deprecated")
     def update(
         self,
         floating_ip_id: str,
         *,
         project_id: int | None = None,
         region_id: int | None = None,
+        fixed_ip_address: Optional[str] | Omit = omit,
+        port_id: Optional[str] | Omit = omit,
         tags: Optional[TagUpdateMapParam] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> FloatingIP:
-        """
-        **Deprecated**: Use PATCH
-        /v2/floatingips/{`project_id`}/{`region_id`}/{`floating_ip_id`} instead
+    ) -> TaskIDList:
+        """This endpoint updates the association and tags of an existing Floating IP.
+
+        The
+        behavior depends on the current association state and the provided fields:
+
+        Parameters:
+
+        `port_id`: The unique identifier of the network interface (port) to which the
+        Floating IP should be assigned. This ID can be retrieved from the "Get instance"
+        or "List network interfaces" endpoints.
+
+        `fixed_ip_address`: The private IP address assigned to the network interface.
+        This must be one of the IP addresses currently assigned to the specified port.
+        You can retrieve available fixed IP addresses from the "Get instance" or "List
+        network interfaces" endpoints.
+
+        When the Floating IP has no port associated (`port_id` is null):
+
+        - Patch with both `port_id` and `fixed_ip_address`: Assign the Floating IP to
+          the specified port and the provided `fixed_ip_address`, if that
+          `fixed_ip_address` exists on the port and is not yet used by another Floating
+          IP.
+        - Patch with `port_id` only (`fixed_ip_address` omitted): Assign the Floating IP
+          to the specified port using the first available IPv4 fixed IP of that port.
+
+        When the Floating IP is already associated with a port:
+
+        - Patch with both `port_id` and `fixed_ip_address`: Re-assign the Floating IP to
+          the specified port and address if all validations pass.
+        - Patch with `port_id` only (`fixed_ip_address` omitted): Re-assign the Floating
+          IP to the specified port using the first available IPv4 fixed IP of that port.
+        - Patch with `port_id` = null: Unassign the Floating IP from its current port.
+
+        Tags:
+
+        - You can update tags alongside association changes. Tags are provided as a list
+          of key-value pairs.
+
+        Idempotency and task creation:
+
+        - No worker task is created if the requested state is already actual, i.e., the
+          requested `port_id` equals the current `port_id` and/or the requested
+          `fixed_ip_address` equals the current `fixed_ip_address`, and the tags already
+          match the current tags. In such cases, the endpoint returns an empty tasks
+          list.
 
         Args:
           project_id: Project ID
@@ -150,6 +193,10 @@ def update(
 
           floating_ip_id: Floating IP ID
 
+          fixed_ip_address: Fixed IP address
+
+          port_id: Port ID
+
           tags: Update key-value tags using JSON Merge Patch semantics (RFC 7386). Provide
               key-value pairs to add or update tags. Set tag values to `null` to remove tags.
               Unspecified tags remain unchanged. Read-only tags are always preserved and
@@ -192,12 +239,19 @@ def update(
         if not floating_ip_id:
             raise ValueError(f"Expected a non-empty value for `floating_ip_id` but received {floating_ip_id!r}")
         return self._patch(
-            f"/cloud/v1/floatingips/{project_id}/{region_id}/{floating_ip_id}",
-            body=maybe_transform({"tags": tags}, floating_ip_update_params.FloatingIPUpdateParams),
+            f"/cloud/v2/floatingips/{project_id}/{region_id}/{floating_ip_id}",
+            body=maybe_transform(
+                {
+                    "fixed_ip_address": fixed_ip_address,
+                    "port_id": port_id,
+                    "tags": tags,
+                },
+                floating_ip_update_params.FloatingIPUpdateParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=FloatingIP,
+            cast_to=TaskIDList,
         )
 
     def list(
@@ -648,24 +702,67 @@ async def create(
             cast_to=TaskIDList,
         )
 
-    @typing_extensions.deprecated("deprecated")
     async def update(
         self,
         floating_ip_id: str,
         *,
         project_id: int | None = None,
         region_id: int | None = None,
+        fixed_ip_address: Optional[str] | Omit = omit,
+        port_id: Optional[str] | Omit = omit,
         tags: Optional[TagUpdateMapParam] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> FloatingIP:
-        """
-        **Deprecated**: Use PATCH
-        /v2/floatingips/{`project_id`}/{`region_id`}/{`floating_ip_id`} instead
+    ) -> TaskIDList:
+        """This endpoint updates the association and tags of an existing Floating IP.
+
+        The
+        behavior depends on the current association state and the provided fields:
+
+        Parameters:
+
+        `port_id`: The unique identifier of the network interface (port) to which the
+        Floating IP should be assigned. This ID can be retrieved from the "Get instance"
+        or "List network interfaces" endpoints.
+
+        `fixed_ip_address`: The private IP address assigned to the network interface.
+        This must be one of the IP addresses currently assigned to the specified port.
+        You can retrieve available fixed IP addresses from the "Get instance" or "List
+        network interfaces" endpoints.
+
+        When the Floating IP has no port associated (`port_id` is null):
+
+        - Patch with both `port_id` and `fixed_ip_address`: Assign the Floating IP to
+          the specified port and the provided `fixed_ip_address`, if that
+          `fixed_ip_address` exists on the port and is not yet used by another Floating
+          IP.
+        - Patch with `port_id` only (`fixed_ip_address` omitted): Assign the Floating IP
+          to the specified port using the first available IPv4 fixed IP of that port.
+
+        When the Floating IP is already associated with a port:
+
+        - Patch with both `port_id` and `fixed_ip_address`: Re-assign the Floating IP to
+          the specified port and address if all validations pass.
+        - Patch with `port_id` only (`fixed_ip_address` omitted): Re-assign the Floating
+          IP to the specified port using the first available IPv4 fixed IP of that port.
+        - Patch with `port_id` = null: Unassign the Floating IP from its current port.
+
+        Tags:
+
+        - You can update tags alongside association changes. Tags are provided as a list
+          of key-value pairs.
+
+        Idempotency and task creation:
+
+        - No worker task is created if the requested state is already actual, i.e., the
+          requested `port_id` equals the current `port_id` and/or the requested
+          `fixed_ip_address` equals the current `fixed_ip_address`, and the tags already
+          match the current tags. In such cases, the endpoint returns an empty tasks
+          list.
 
         Args:
           project_id: Project ID
@@ -674,6 +771,10 @@ async def update(
 
           floating_ip_id: Floating IP ID
 
+          fixed_ip_address: Fixed IP address
+
+          port_id: Port ID
+
           tags: Update key-value tags using JSON Merge Patch semantics (RFC 7386). Provide
               key-value pairs to add or update tags. Set tag values to `null` to remove tags.
               Unspecified tags remain unchanged. Read-only tags are always preserved and
@@ -716,12 +817,19 @@ async def update(
         if not floating_ip_id:
             raise ValueError(f"Expected a non-empty value for `floating_ip_id` but received {floating_ip_id!r}")
         return await self._patch(
-            f"/cloud/v1/floatingips/{project_id}/{region_id}/{floating_ip_id}",
-            body=await async_maybe_transform({"tags": tags}, floating_ip_update_params.FloatingIPUpdateParams),
+            f"/cloud/v2/floatingips/{project_id}/{region_id}/{floating_ip_id}",
+            body=await async_maybe_transform(
+                {
+                    "fixed_ip_address": fixed_ip_address,
+                    "port_id": port_id,
+                    "tags": tags,
+                },
+                floating_ip_update_params.FloatingIPUpdateParams,
+            ),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=FloatingIP,
+            cast_to=TaskIDList,
         )
 
     def list(
@@ -1090,10 +1198,8 @@ def __init__(self, floating_ips: FloatingIPsResource) -> None:
         self.create = to_raw_response_wrapper(
             floating_ips.create,
         )
-        self.update = (  # pyright: ignore[reportDeprecated]
-            to_raw_response_wrapper(
-                floating_ips.update,  # pyright: ignore[reportDeprecated],
-            )
+        self.update = to_raw_response_wrapper(
+            floating_ips.update,
         )
         self.list = to_raw_response_wrapper(
             floating_ips.list,
@@ -1129,10 +1235,8 @@ def __init__(self, floating_ips: AsyncFloatingIPsResource) -> None:
         self.create = async_to_raw_response_wrapper(
             floating_ips.create,
         )
-        self.update = (  # pyright: ignore[reportDeprecated]
-            async_to_raw_response_wrapper(
-                floating_ips.update,  # pyright: ignore[reportDeprecated],
-            )
+        self.update = async_to_raw_response_wrapper(
+            floating_ips.update,
         )
         self.list = async_to_raw_response_wrapper(
             floating_ips.list,
@@ -1168,10 +1272,8 @@ def __init__(self, floating_ips: FloatingIPsResource) -> None:
         self.create = to_streamed_response_wrapper(
             floating_ips.create,
         )
-        self.update = (  # pyright: ignore[reportDeprecated]
-            to_streamed_response_wrapper(
-                floating_ips.update,  # pyright: ignore[reportDeprecated],
-            )
+        self.update = to_streamed_response_wrapper(
+            floating_ips.update,
         )
         self.list = to_streamed_response_wrapper(
             floating_ips.list,
@@ -1207,10 +1309,8 @@ def __init__(self, floating_ips: AsyncFloatingIPsResource) -> None:
         self.create = async_to_streamed_response_wrapper(
             floating_ips.create,
         )
-        self.update = (  # pyright: ignore[reportDeprecated]
-            async_to_streamed_response_wrapper(
-                floating_ips.update,  # pyright: ignore[reportDeprecated],
-            )
+        self.update = async_to_streamed_response_wrapper(
+            floating_ips.update,
         )
         self.list = async_to_streamed_response_wrapper(
             floating_ips.list,

src/gcore/types/cloud/floating_ip_update_params.py

@@ -17,6 +17,12 @@ class FloatingIPUpdateParams(TypedDict, total=False):
     region_id: int
     """Region ID"""
 
+    fixed_ip_address: Optional[str]
+    """Fixed IP address"""
+
+    port_id: Optional[str]
+    """Port ID"""
+
     tags: Optional[TagUpdateMapParam]
     """Update key-value tags using JSON Merge Patch semantics (RFC 7386).