feat: implement resource actions clients (#252)

This implements the new per resources actions endpoints.

Related to https://docs.hetzner.cloud/changelog#2023-06-29-resource-action-endpoints

```py
# Existing API
client.actions.get_by_id() # /actions/{id}
client.<resource>.get_actions_all() # /<resource>/{resource_id}/actions
client.<resource>.get_actions_list() # /<resource>/{resource_id}/actions

# New API
client.<resource>.actions.get_all() # /<resource>/actions 
client.<resource>.actions.get_list() # /<resource>/actions
client.<resource>.actions.get_by_id() # /<resource>/actions/{id}

# Not planned
client.<resource>.get_action_by_id() # /<resource>/{resource_id}/actions/{id}

# Deprecated
client.actions.get_all() # /actions
client.actions.get_list() # /actions
```

One exception is the primary IPs client, it doesn't include calls to `/<resource>/{resource_id}/actions` or `/<resource>/{resource_id}/actions/{id}`: https://docs.hetzner.cloud/#primary-ip-actions

* test: improve existing actions tests

* feat: create ResourceActionsClient

* feat: deprecated /actions endpoint

* test: add tests for ResourceActionsClient

* feat: spread ResourceActionsClient to all clients

* test: add tests for all ResourceActionsClient

* docs: improve reference docs

* docs: add link to deprecation changelog

Author: jooola

docs/api.clients.actions.rst

@@ -1,9 +1,12 @@
 ActionsClient
 ==================
 
+.. autoclass:: hcloud.actions.client.ResourceActionsClient
+    :members:
 
 .. autoclass:: hcloud.actions.client.ActionsClient
     :members:
+    :inherited-members:
 
 .. autoclass:: hcloud.actions.client.BoundAction
     :members:

hcloud/actions/__init__.py

@@ -1,6 +1,11 @@
 from __future__ import annotations
 
-from .client import ActionsClient, ActionsPageResult, BoundAction  # noqa: F401
+from .client import (  # noqa: F401
+    ActionsClient,
+    ActionsPageResult,
+    BoundAction,
+    ResourceActionsClient,
+)
 from .domain import (  # noqa: F401
     Action,
     ActionException,

hcloud/actions/client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+import warnings
 from typing import TYPE_CHECKING, Any, NamedTuple
 
 from ..core import BoundModelBase, ClientEntityBase, Meta
@@ -40,18 +41,24 @@ class ActionsPageResult(NamedTuple):
     meta: Meta | None
 
 
-class ActionsClient(ClientEntityBase):
-    _client: Client
+class ResourceActionsClient(ClientEntityBase):
+    _resource: str
+
+    def __init__(self, client: Client, resource: str | None):
+        super().__init__(client)
+        self._resource = resource or ""
 
     def get_by_id(self, id: int) -> BoundAction:
         """Get a specific action by its ID.
 
         :param id: int
         :return: :class:`BoundAction <hcloud.actions.client.BoundAction>`
         """
-
-        response = self._client.request(url=f"/actions/{id}", method="GET")
-        return BoundAction(self, response["action"])
+        response = self._client.request(
+            url=f"{self._resource}/actions/{id}",
+            method="GET",
+        )
+        return BoundAction(self._client.actions, response["action"])
 
     def get_list(
         self,
@@ -60,7 +67,7 @@ def get_list(
         page: int | None = None,
         per_page: int | None = None,
     ) -> ActionsPageResult:
-        """Get a list of actions from this account
+        """Get a list of actions.
 
         :param status: List[str] (optional)
                Response will have only actions with specified statuses. Choices: `running` `success` `error`
@@ -82,9 +89,14 @@ def get_list(
         if per_page is not None:
             params["per_page"] = per_page
 
-        response = self._client.request(url="/actions", method="GET", params=params)
+        response = self._client.request(
+            url=f"{self._resource}/actions",
+            method="GET",
+            params=params,
+        )
         actions = [
-            BoundAction(self, action_data) for action_data in response["actions"]
+            BoundAction(self._client.actions, action_data)
+            for action_data in response["actions"]
         ]
         return ActionsPageResult(actions, Meta.parse_meta(response))
 
@@ -93,7 +105,7 @@ def get_all(
         status: list[str] | None = None,
         sort: list[str] | None = None,
     ) -> list[BoundAction]:
-        """Get all actions of the account
+        """Get all actions.
 
         :param status: List[str] (optional)
                Response will have only actions with specified statuses. Choices: `running` `success` `error`
@@ -102,3 +114,52 @@ def get_all(
         :return: List[:class:`BoundAction <hcloud.actions.client.BoundAction>`]
         """
         return self._iter_pages(self.get_list, status=status, sort=sort)
+
+
+class ActionsClient(ResourceActionsClient):
+    def __init__(self, client: Client):
+        super().__init__(client, None)
+
+    def get_list(
+        self,
+        status: list[str] | None = None,
+        sort: list[str] | None = None,
+        page: int | None = None,
+        per_page: int | None = None,
+    ) -> ActionsPageResult:
+        """
+        .. deprecated:: 1.28
+        Use :func:`client.<resource>.actions.get_list` instead,
+        e.g. using :attr:`hcloud.certificates.client.CertificatesClient.actions`.
+
+        `Starting 1 October 2023, it will no longer be available. <https://docs.hetzner.cloud/changelog#2023-07-20-actions-list-endpoint-is-deprecated>`_
+        """
+        warnings.warn(
+            "The 'client.actions.get_list' method is deprecated, please use the "
+            "'client.<resource>.actions.get_list' method instead (e.g. "
+            "'client.certificates.actions.get_list').",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return super().get_list(status=status, sort=sort, page=page, per_page=per_page)
+
+    def get_all(
+        self,
+        status: list[str] | None = None,
+        sort: list[str] | None = None,
+    ) -> list[BoundAction]:
+        """
+        .. deprecated:: 1.28
+        Use :func:`client.<resource>.actions.get_all` instead,
+        e.g. using :attr:`hcloud.certificates.client.CertificatesClient.actions`.
+
+        `Starting 1 October 2023, it will no longer be available. <https://docs.hetzner.cloud/changelog#2023-07-20-actions-list-endpoint-is-deprecated>`_
+        """
+        warnings.warn(
+            "The 'client.actions.get_all' method is deprecated, please use the "
+            "'client.<resource>.actions.get_all' method instead (e.g. "
+            "'client.certificates.actions.get_all').",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return super().get_all(status=status, sort=sort)

hcloud/certificates/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import (
     Certificate,
@@ -106,6 +106,16 @@ class CertificatesPageResult(NamedTuple):
 class CertificatesClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Certificates scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/certificates")
+
     def get_by_id(self, id: int) -> BoundCertificate:
         """Get a specific certificate by its ID.
 

hcloud/firewalls/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import (
     CreateFirewallResponse,
@@ -161,6 +161,16 @@ class FirewallsPageResult(NamedTuple):
 class FirewallsClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Firewalls scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/firewalls")
+
     def get_actions_list(
         self,
         firewall: Firewall | BoundFirewall,

hcloud/floating_ips/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from ..locations import BoundLocation
 from .domain import CreateFloatingIPResponse, FloatingIP
@@ -141,6 +141,16 @@ class FloatingIPsPageResult(NamedTuple):
 class FloatingIPsClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Floating IPs scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/floating_ips")
+
     def get_actions_list(
         self,
         floating_ip: FloatingIP | BoundFloatingIP,

hcloud/images/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import Image
 
@@ -113,6 +113,16 @@ class ImagesPageResult(NamedTuple):
 class ImagesClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Images scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/images")
+
     def get_actions_list(
         self,
         image: Image | BoundImage,

hcloud/load_balancers/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..certificates import BoundCertificate
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from ..load_balancer_types import BoundLoadBalancerType
@@ -331,6 +331,16 @@ class LoadBalancersPageResult(NamedTuple):
 class LoadBalancersClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Load Balancers scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/load_balancers")
+
     def get_by_id(self, id: int) -> BoundLoadBalancer:
         """Get a specific Load Balancer
 

hcloud/networks/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import ActionsPageResult, BoundAction
+from ..actions import ActionsPageResult, BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import Network, NetworkRoute, NetworkSubnet
 
@@ -168,6 +168,16 @@ class NetworksPageResult(NamedTuple):
 class NetworksClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Networks scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/networks")
+
     def get_by_id(self, id: int) -> BoundNetwork:
         """Get a specific network
 

hcloud/primary_ips/client.py

@@ -2,7 +2,7 @@
 
 from typing import TYPE_CHECKING, Any, NamedTuple
 
-from ..actions import BoundAction
+from ..actions import BoundAction, ResourceActionsClient
 from ..core import BoundModelBase, ClientEntityBase, Meta
 from .domain import CreatePrimaryIPResponse, PrimaryIP
 
@@ -99,6 +99,16 @@ class PrimaryIPsPageResult(NamedTuple):
 class PrimaryIPsClient(ClientEntityBase):
     _client: Client
 
+    actions: ResourceActionsClient
+    """Primary IPs scoped actions client
+
+    :type: :class:`ResourceActionsClient <hcloud.actions.client.ResourceActionsClient>`
+    """
+
+    def __init__(self, client: Client):
+        super().__init__(client)
+        self.actions = ResourceActionsClient(client, "/primary_ips")
+
     def get_by_id(self, id: int) -> BoundPrimaryIP:
         """Returns a specific Primary IP object.