feat: deprecate datacenters (#656)

The API endpoints `GET /v1/datacenters` and `GET /v1/datacenters/{id}`
are now deprecated and will be removed after 1 Oct. 2026. After this
date, requests to these endpoints will return `HTTP 410 Gone`.

See
https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.

Author: jooola

hcloud/_client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import time
+import warnings
 from http import HTTPStatus
 from random import uniform
 from typing import Any, Protocol
@@ -181,11 +182,10 @@ def __init__(
             timeout=timeout,
         )
 
-        self.datacenters = DatacentersClient(self)
-        """DatacentersClient Instance
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            self.datacenters = DatacentersClient(self)
 
-        :type: :class:`DatacentersClient <hcloud.datacenters.client.DatacentersClient>`
-        """
         self.locations = LocationsClient(self)
         """LocationsClient Instance
 
@@ -303,6 +303,28 @@ def request(  # type: ignore[no-untyped-def]
         """
         return self._client.request(method, url, **kwargs)
 
+    @property
+    def datacenters(self) -> DatacentersClient:
+        """DatacentersClient Instance
+
+        .. deprecated:: 2.22.0
+            The datacenters client is deprecated and will be removed after the 2026-10-01.
+            See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+
+        :type: :class:`DatacentersClient <hcloud.datacenters.client.DatacentersClient>`
+        """
+        warnings.warn(
+            "The datacenters client is deprecated and will be removed after the 2026-10-01. "
+            "See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._datacenters
+
+    @datacenters.setter
+    def datacenters(self, value: DatacentersClient) -> None:
+        self._datacenters = value
+
 
 class ClientBase:
     def __init__(

hcloud/core/client.py

@@ -109,7 +109,10 @@ def __init__(
         """
         self._client = client
         self.complete = complete
-        self.data_model: Domain = self.model.from_dict(data)
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            self.data_model: Domain = self.model.from_dict(data)
 
     def __getattr__(self, name: str):  # type: ignore[no-untyped-def]
         """Allow magical access to the properties of the model

hcloud/datacenters/client.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
-from typing import Any, NamedTuple
+import warnings
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from ..core import BoundModelBase, Meta, ResourceClientBase
 from ..locations import BoundLocation
 from ..server_types import BoundServerType
 from .domain import Datacenter, DatacenterServerTypes
 
+if TYPE_CHECKING:
+    from .._client import Client
+
 __all__ = [
     "BoundDatacenter",
     "DatacentersPageResult",
@@ -15,6 +19,12 @@
 
 
 class BoundDatacenter(BoundModelBase[Datacenter], Datacenter):
+    """
+    .. deprecated:: 2.22.0
+        The bound datacenter class is deprecated and will be removed after the 2026-10-01.
+        See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+    """
+
     _client: DatacentersClient
 
     model = Datacenter
@@ -54,13 +64,34 @@ def __init__(self, client: DatacentersClient, data: dict[str, Any]):
 
 
 class DatacentersPageResult(NamedTuple):
+    """
+    .. deprecated:: 2.22.0
+        The datacenters page result class is deprecated and will be removed after the 2026-10-01.
+        See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+    """
+
     datacenters: list[BoundDatacenter]
     meta: Meta
 
 
 class DatacentersClient(ResourceClientBase):
+    """
+    .. deprecated:: 2.22.0
+        The datacenters client class is deprecated and will be removed after the 2026-10-01.
+        See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+    """
+
     _base_url = "/datacenters"
 
+    def __init__(self, client: Client):
+        warnings.warn(
+            "The datacenters client class is deprecated and will be removed after the 2026-10-01. "
+            "See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(client)
+
     def get_by_id(self, id: int) -> BoundDatacenter:
         """Get a specific datacenter by its ID.
 

hcloud/datacenters/domain.py

@@ -18,6 +18,10 @@
 class Datacenter(BaseDomain, DomainIdentityMixin):
     """Datacenter Domain
 
+    .. deprecated:: 2.22.0
+        The datacenters domain class is deprecated and will be removed after the 2026-10-01.
+        See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+
     :param id: int ID of Datacenter
     :param name: str Name of Datacenter
     :param description: str Description of Datacenter
@@ -37,6 +41,12 @@ def __init__(
         location: Location | None = None,
         server_types: DatacenterServerTypes | None = None,
     ):
+        warnings.warn(
+            "The datacenter domain class is deprecated and will be removed after the 2026-10-01. "
+            "See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.id = id
         self.name = name
         self.description = description
@@ -69,6 +79,10 @@ def server_types(self, value: DatacenterServerTypes | None) -> None:
 class DatacenterServerTypes(BaseDomain):
     """DatacenterServerTypes Domain
 
+    .. deprecated:: 2.22.0
+        The datacenters domain class is deprecated and will be removed after the 2026-10-01.
+        See https://docs.hetzner.cloud/changelog#2026-06-02-datacenters-deprecated.
+
     :param available: List[:class:`BoundServerTypes <hcloud.server_types.client.BoundServerTypes>`]
            All available server types for this datacenter
     :param supported: List[:class:`BoundServerTypes <hcloud.server_types.client.BoundServerTypes>`]

hcloud/primary_ips/client.py

@@ -44,7 +44,9 @@ def __init__(
 
         raw = data.get("datacenter", {})
         if raw:
-            data["datacenter"] = BoundDatacenter(client._parent.datacenters, raw)
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=DeprecationWarning)
+                data["datacenter"] = BoundDatacenter(client._parent.datacenters, raw)
 
         raw = data.get("location", {})
         if raw:

hcloud/servers/client.py

@@ -77,7 +77,9 @@ def __init__(
     ):
         raw = data.get("datacenter")
         if raw:
-            data["datacenter"] = BoundDatacenter(client._parent.datacenters, raw)
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=DeprecationWarning)
+                data["datacenter"] = BoundDatacenter(client._parent.datacenters, raw)
 
         raw = data.get("location")
         if raw:

tests/unit/actions/test_client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import inspect
+import warnings
 from unittest import mock
 
 import pytest
@@ -47,10 +48,15 @@ def test_resources_with_actions(client: Client):
     """
     Ensure that the list of resource clients above is up to date.
     """
-    members = inspect.getmembers(
-        client,
-        predicate=lambda p: isinstance(p, ResourceClientBase) and hasattr(p, "actions"),
-    )
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+        members = inspect.getmembers(
+            client,
+            predicate=lambda p: isinstance(p, ResourceClientBase)
+            and hasattr(p, "actions"),
+        )
+
     for name, member in members:
         assert name in resources_with_actions
 

tests/unit/datacenters/test_client.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from unittest import mock  # noqa: F401
 
 import pytest  # noqa: F401
@@ -8,6 +9,8 @@
 from hcloud.datacenters import BoundDatacenter, DatacentersClient, DatacenterServerTypes
 from hcloud.locations import BoundLocation
 
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
 
 class TestBoundDatacenter:
     def test_bound_datacenter_init(self, datacenter_response):
@@ -64,7 +67,9 @@ def test_bound_datacenter_init(self, datacenter_response):
 class TestDatacentersClient:
     @pytest.fixture()
     def datacenters_client(self, client: Client):
-        return DatacentersClient(client)
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=DeprecationWarning)
+            return DatacentersClient(client)
 
     def test_get_by_id(
         self,

tests/unit/datacenters/test_domain.py

@@ -1,9 +1,13 @@
 from __future__ import annotations
 
+import warnings
+
 import pytest
 
 from hcloud.datacenters import Datacenter, DatacenterServerTypes
 
+warnings.filterwarnings("ignore", category=DeprecationWarning)
+
 
 @pytest.mark.parametrize(
     "value",