linode-api4 5.42.0__tar.gz → 5.43.0__tar.gz

{linode_api4-5.42.0/linode_api4.egg-info → linode_api4-5.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linode_api4
-Version: 5.42.0
+Version: 5.43.0
 Summary: The official Python SDK for Linode API v4
 Author-email: Linode <devs@linode.com>
 License: BSD-3-Clause

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/groups/linode.py

@@ -322,7 +322,6 @@ class LinodeGroup(Group):
         :param firewall: The firewall to attach this Linode to.
         :type firewall: int or Firewall
         :param disk_encryption: The disk encryption policy for this Linode.
-                                NOTE: Disk encryption may not currently be available to all users.
         :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.

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/groups/monitor.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any, Optional, Union
 
 from linode_api4 import PaginatedList
 from linode_api4.errors import UnexpectedResponseError
@@ -6,6 +6,8 @@ from linode_api4.groups import Group
 from linode_api4.objects import (
     AlertChannel,
     AlertDefinition,
+    AlertDefinitionEntity,
+    AlertScope,
     MonitorDashboard,
     MonitorMetricsDefinition,
     MonitorService,
@@ -202,7 +204,7 @@ class MonitorGroup(Group):
 
         .. note:: This endpoint is in beta and requires using the v4beta base URL.
 
-        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-alert-channels
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-notification-channels
 
         :param filters: Optional filter expressions to apply to the collection.
                         See :doc:`Filtering Collections</linode_api4/objects/filtering>` for details.
@@ -221,6 +223,8 @@ class MonitorGroup(Group):
         trigger_conditions: dict,
         entity_ids: Optional[list[str]] = None,
         description: Optional[str] = None,
+        scope: Optional[Union[AlertScope, str]] = None,
+        regions: Optional[list[str]] = None,
     ) -> AlertDefinition:
         """
         Create a new alert definition for a given service type.
@@ -252,6 +256,10 @@ class MonitorGroup(Group):
         :type entity_ids: Optional[list[str]]
         :param description: (Optional) Longer description for the alert definition.
         :type description: Optional[str]
+        :param scope: (Optional) Alert scope (for example: `account`, `entity`, or `region`). Defaults to `entity`.
+        :type scope: Optional[Union[AlertScope, str]]
+        :param regions: (Optional) Regions to monitor.
+        :type regions: Optional[list[str]]
 
         :returns: The newly created :class:`AlertDefinition`.
         :rtype: AlertDefinition
@@ -267,10 +275,15 @@ class MonitorGroup(Group):
             "rule_criteria": rule_criteria,
             "trigger_conditions": trigger_conditions,
         }
-        if description is not None:
-            params["description"] = description
+
         if entity_ids is not None:
             params["entity_ids"] = entity_ids
+        if description is not None:
+            params["description"] = description
+        if scope is not None:
+            params["scope"] = scope
+        if regions is not None:
+            params["regions"] = regions
 
         # API will validate service_type and return an error if missing
         result = self.client.post(
@@ -284,3 +297,38 @@ class MonitorGroup(Group):
             )
 
         return AlertDefinition(self.client, result["id"], service_type, result)
+
+    def alert_definition_entities(
+        self,
+        service_type: str,
+        id: int,
+        *filters,
+    ) -> PaginatedList:
+        """
+        List entities associated with a specific alert definition.
+
+        This endpoint supports pagination fields (`page`, `page_size`) in the API.
+
+        .. note:: This endpoint is in beta and requires using the v4beta base URL.
+
+        API Documentation: TODO
+
+        :param service_type: Service type for the alert definition (e.g. `dbaas`).
+        :type service_type: str
+        :param id: Alert definition identifier.
+        :type id: int
+        :param filters: Optional filter expressions to apply to the collection.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`.
+
+        :returns: A paginated list of entities associated with the alert definition.
+        :rtype: PaginatedList[AlertDefinitionEntity]
+        """
+
+        endpoint = (
+            f"/monitor/services/{service_type}/alert-definitions/{id}/entities"
+        )
+        return self.client._get_and_filter(
+            AlertDefinitionEntity,
+            *filters,
+            endpoint=endpoint,
+        )

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/groups/volume.py

@@ -48,7 +48,6 @@ class VolumeGroup(Group):
         :type tags: list[str]
         :param encryption: Whether the new Volume should opt in or out of disk encryption.
         :type encryption: str
-            Note: Block Storage Disk Encryption is not currently available to all users.
         :returns: The new Volume.
         :rtype: Volume
         """

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/objects/linode.py

@@ -1448,7 +1448,6 @@ class Instance(Base):
                                  should already be set up, see :any:`ProfileGroup.ssh_keys`
                                  for details.
         :param disk_encryption: The disk encryption policy for this Linode.
-                                NOTE: Disk encryption may not currently be available to all users.
         :type disk_encryption: InstanceDiskEncryptionType or str
         :param stackscript: A StackScript object, or the ID of one, to deploy to this
                             disk.  Requires deploying a compatible image.
@@ -1642,7 +1641,6 @@ class Instance(Base):
                                 the key.
         :type authorized_keys: list or str
         :param disk_encryption: The disk encryption policy for this Linode.
-                                NOTE: Disk encryption may not currently be available to all users.
         :type disk_encryption: InstanceDiskEncryptionType or str
 
         :returns: The newly generated password, if one was not provided

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/objects/monitor.py

@@ -7,11 +7,13 @@ from linode_api4.objects.serializable import JSONObject, StrEnum
 
 __all__ = [
     "AggregateFunction",
-    "Alert",
     "AlertChannel",
     "AlertDefinition",
+    "AlertDefinitionChannel",
+    "AlertDefinitionEntity",
+    "AlertEntities",
+    "AlertScope",
     "AlertType",
-    "Alerts",
     "MonitorDashboard",
     "MonitorMetricsDefinition",
     "MonitorService",
@@ -341,15 +343,15 @@ class RuleCriteria(JSONObject):
 
 
 @dataclass
-class Alert(JSONObject):
+class AlertDefinitionChannel(JSONObject):
     """
-    Represents an alert definition reference within an AlertChannel.
+    Represents the notification channel set up for use with an alert.
 
     Fields:
-      - id: int - Unique identifier of the alert definition.
-      - label: str - Human-readable name for the alert definition.
-      - type: str - Type of the alert (e.g., 'alerts-definitions').
-      - url: str - API URL for the alert definition.
+      - id: int - Unique identifier for this notification channel.
+      - label: str - Human-readable name for the alert channel.
+      - type: str - Type of notification used with the channel. For a user alert definition, only `email` is supported.
+      - url: str - URL for the channel that ends in the channel's id.
     """
 
     id: int = 0
@@ -358,18 +360,6 @@ class Alert(JSONObject):
     url: str = ""
 
 
-@dataclass
-class Alerts(JSONObject):
-    """
-    Represents a collection of alert definitions within an AlertChannel.
-
-    Fields:
-      - items: List[Alert] - List of alert definitions.
-    """
-
-    items: List[Alert] = field(default_factory=list)
-
-
 class AlertType(StrEnum):
     """
     Enumeration of alert origin types used by alert definitions.
@@ -387,6 +377,43 @@ class AlertType(StrEnum):
     user = "user"
 
 
+class AlertScope(StrEnum):
+    """
+    Scope values supported for alert definitions.
+    """
+
+    entity = "entity"
+    region = "region"
+    account = "account"
+
+
+@dataclass
+class AlertEntities(JSONObject):
+    """
+    Represents entity metadata for an alert definition.
+
+    For entity scoped alerts, `entities` envelope contains the URL to list entities,
+    a count, and a has_more_resources flag.
+    For region/account scoped alerts, the `entities` are returned as an empty object.
+    """
+
+    url: str = ""
+    count: int = 0
+    has_more_resources: bool = False
+
+
+@dataclass
+class AlertDefinitionEntity(JSONObject):
+    """
+    Represents an entity associated with an alert definition.
+    """
+
+    id: str = ""
+    label: str = ""
+    url: str = ""
+    _type: str = field(default="", metadata={"json_key": "type"})
+
+
 class AlertDefinition(DerivedBase):
     """
     Represents an alert definition for a monitor service.
@@ -406,12 +433,12 @@ class AlertDefinition(DerivedBase):
         "severity": Property(mutable=True),
         "type": Property(mutable=True),
         "status": Property(mutable=True),
-        "has_more_resources": Property(mutable=True),
+        "has_more_resources": Property(),  # Deprecated; use entities.has_more_resources.
         "rule_criteria": Property(mutable=True, json_object=RuleCriteria),
         "trigger_conditions": Property(
             mutable=True, json_object=TriggerConditions
         ),
-        "alert_channels": Property(mutable=True, json_object=Alerts),
+        "alert_channels": Property(json_object=AlertDefinitionChannel),
         "created": Property(is_datetime=True),
         "updated": Property(is_datetime=True),
         "updated_by": Property(),
@@ -419,28 +446,12 @@ class AlertDefinition(DerivedBase):
         "entity_ids": Property(mutable=True),
         "description": Property(mutable=True),
         "service_class": Property(alias_of="class"),
+        "scope": Property(AlertScope),
+        "regions": Property(mutable=True),
+        "entities": Property(json_object=AlertEntities),
     }
 
 
-@dataclass
-class EmailChannelContent(JSONObject):
-    """
-    Represents the content for an email alert channel.
-    """
-
-    email_addresses: Optional[List[str]] = None
-
-
-@dataclass
-class ChannelContent(JSONObject):
-    """
-    Represents the content block for an AlertChannel, which varies by channel type.
-    """
-
-    email: Optional[EmailChannelContent] = None
-    # Other channel types like 'webhook', 'slack' could be added here as Optional fields.
-
-
 @dataclass
 class EmailDetails(JSONObject):
     """
@@ -481,7 +492,7 @@ class AlertChannel(Base):
     fire. Alert channels define a destination and configuration for
     notifications (for example: email lists, webhooks, PagerDuty, Slack, etc.).
 
-    API Documentation: https://techdocs.akamai.com/linode-api/reference/get-alert-channels
+    API Documentation: https://techdocs.akamai.com/linode-api/reference/get-notification-channels
 
     This class maps to the Monitor API's `/monitor/alert-channels` resource
     and is used by the SDK to list, load, and inspect channels.
@@ -499,7 +510,6 @@ class AlertChannel(Base):
         "channel_type": Property(),
         "details": Property(mutable=False, json_object=ChannelDetails),
         "alerts": Property(mutable=False, json_object=AlertInfo),
-        "content": Property(mutable=False, json_object=ChannelContent),
         "created": Property(is_datetime=True),
         "updated": Property(is_datetime=True),
         "created_by": Property(),

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4/version.py

@@ -2,4 +2,4 @@
 The version of this linode_api4 package.
 """
 
-__version__ = "v5.42.0"
+__version__ = "v5.43.0"

{linode_api4-5.42.0 → linode_api4-5.43.0/linode_api4.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linode_api4
-Version: 5.42.0
+Version: 5.43.0
 Summary: The official Python SDK for Linode API v4
 Author-email: Linode <devs@linode.com>
 License: BSD-3-Clause

{linode_api4-5.42.0 → linode_api4-5.43.0}/linode_api4.egg-info/SOURCES.txt

@@ -188,6 +188,7 @@ test/fixtures/longview_plan.json
 test/fixtures/longview_subscriptions.json
 test/fixtures/maintenance_policies.json
 test/fixtures/mongodb.json
+test/fixtures/monitor_alert-channels.json
 test/fixtures/monitor_alert-definitions.json
 test/fixtures/monitor_dashboards.json
 test/fixtures/monitor_dashboards_1.json
@@ -195,6 +196,7 @@ test/fixtures/monitor_services.json
 test/fixtures/monitor_services_dbaas.json
 test/fixtures/monitor_services_dbaas_alert-definitions.json
 test/fixtures/monitor_services_dbaas_alert-definitions_12345.json
+test/fixtures/monitor_services_dbaas_alert-definitions_12345_entities.json
 test/fixtures/monitor_services_dbaas_dashboards.json
 test/fixtures/monitor_services_dbaas_metric-definitions.json
 test/fixtures/monitor_services_dbaas_metrics.json

linode_api4-5.43.0/test/fixtures/monitor_alert-channels.json

@@ -0,0 +1,31 @@
+{
+    "data": [
+        {
+            "id": 123,
+            "label": "alert notification channel",
+            "type": "user",
+            "channel_type": "email",
+            "details": {
+                "email": {
+                    "usernames": [
+                        "admin-user1",
+                        "admin-user2"
+                    ],
+                    "recipient_type": "user"
+                }
+            },
+            "alerts": {
+                "url": "/monitor/alert-channels/123/alerts",
+                "type": "alerts-definitions",
+                "alert_count": 0
+            },
+            "created": "2024-01-01T00:00:00",
+            "updated": "2024-01-01T00:00:00",
+            "created_by": "tester",
+            "updated_by": "tester"
+        }
+    ],
+    "page": 1,
+    "pages": 1,
+    "results": 1
+}

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/fixtures/monitor_alert-definitions.json

@@ -7,13 +7,26 @@
       "severity": 1,
       "type": "user",
       "description": "A test alert for dbaas service",
+      "scope": "entity",
+      "regions": [],
       "entity_ids": ["13217"],
-      "alert_channels": [],
+      "entities": {
+        "url": "/monitor/services/dbaas/alert-definitions/12345/entities",
+        "count": 1,
+        "has_more_resources": false
+      },
+      "alert_channels": [
+        {
+          "id": 10000,
+          "label": "Read-Write Channel",
+          "type": "email",
+          "url": "/monitor/alert-channels/10000"
+        }
+      ],
       "has_more_resources": false,
       "rule_criteria": null,
       "trigger_conditions": null,
       "class": "alert",
-      "notification_groups": [],
       "status": "active",
       "created": "2024-01-01T00:00:00",
       "updated": "2024-01-01T00:00:00",

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/fixtures/monitor_services_dbaas_alert-definitions.json

@@ -7,10 +7,24 @@
       "severity": 1,
       "type": "user",
       "description": "A test alert for dbaas service",
+      "scope": "entity",
+      "regions": [],
       "entity_ids": [
         "13217"
       ],
-      "alert_channels": [],
+      "entities": {
+        "url": "/monitor/services/dbaas/alert-definitions/12345/entities",
+        "count": 1,
+        "has_more_resources": false
+      },
+      "alert_channels": [
+        {
+          "id": 10000,
+          "label": "Read-Write Channel",
+          "type": "email",
+          "url": "/monitor/alert-channels/10000"
+        }
+      ],
       "has_more_resources": false,
       "rule_criteria": {
         "rules": [
@@ -39,7 +53,6 @@
         "trigger_occurrences": 3
       },
       "class": "alert",
-      "notification_groups": [],
       "status": "active",
       "created": "2024-01-01T00:00:00",
       "updated": "2024-01-01T00:00:00",

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/fixtures/monitor_services_dbaas_alert-definitions_12345.json

@@ -5,10 +5,24 @@
   "severity": 1,
   "type": "user",
   "description": "A test alert for dbaas service",
+  "scope": "entity",
+  "regions": [],
   "entity_ids": [
     "13217"
   ],
-  "alert_channels": [],
+  "entities": {
+    "url": "/monitor/services/dbaas/alert-definitions/12345/entities",
+    "count": 1,
+    "has_more_resources": false
+  },
+  "alert_channels": [
+    {
+      "id": 10000,
+      "label": "Read-Write Channel",
+      "type": "email",
+      "url": "/monitor/alert-channels/10000"
+    }
+  ],
   "has_more_resources": false,
   "rule_criteria": {
     "rules": [

linode_api4-5.43.0/test/fixtures/monitor_services_dbaas_alert-definitions_12345_entities.json

@@ -0,0 +1,25 @@
+{
+  "data": [
+    {
+      "id": "1",
+      "label": "mydatabase-1",
+      "url": "/v4/databases/mysql/instances/1",
+      "type": "dbaas"
+    },
+    {
+      "id": "2",
+      "label": "mydatabase-2",
+      "url": "/v4/databases/mysql/instances/2",
+      "type": "dbaas"
+    },
+    {
+      "id": "3",
+      "label": "mydatabase-3",
+      "url": "/v4/databases/mysql/instances/3",
+      "type": "dbaas"
+    }
+  ],
+  "page": 1,
+  "pages": 1,
+  "results": 3
+}

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/integration/conftest.py

@@ -16,7 +16,6 @@ import requests
 from requests.exceptions import ConnectionError, RequestException
 
 from linode_api4 import (
-    ExplicitNullValue,
     InterfaceGeneration,
     LinodeInterfaceDefaultRouteOptions,
     LinodeInterfaceOptions,
@@ -645,7 +644,7 @@ def linode_with_linode_interfaces(
                 public=LinodeInterfacePublicOptions(),
             ),
             LinodeInterfaceOptions(
-                firewall_id=ExplicitNullValue,
+                firewall_id=e2e_test_firewall.id,
                 vpc=LinodeInterfaceVPCOptions(
                     subnet_id=subnet.id,
                 ),

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/integration/models/monitor/test_monitor.py

@@ -7,9 +7,10 @@ from test.integration.helpers import (
 
 import pytest
 
-from linode_api4 import LinodeClient
+from linode_api4 import LinodeClient, PaginatedList
 from linode_api4.objects import (
     AlertDefinition,
+    AlertDefinitionEntity,
     ApiError,
     MonitorDashboard,
     MonitorMetricsDefinition,
@@ -256,12 +257,14 @@ def test_integration_create_get_update_delete_alert_definition(
 
         assert created.id
         assert getattr(created, "label", None) == label
+        assert getattr(created, "entities", None) is not None
 
         created = wait_for_alert_ready(created.id, service_type)
 
         updated = client.load(AlertDefinition, created.id, service_type)
         updated.label = f"{label}-updated"
         updated.save()
+        assert getattr(updated, "entities", None) is not None
 
         updated = wait_for_alert_ready(updated.id, service_type)
 
@@ -275,3 +278,36 @@ def test_integration_create_get_update_delete_alert_definition(
                 AlertDefinition, created.id, service_type
             )
             delete_alert.delete()
+
+
+def test_alert_definition_entities(test_linode_client):
+    """Test listing entities associated with an alert definition.
+
+    This test first retrieves alert definitions for a service type, then lists entities for the first alert definition.
+    It asserts that the returned entities have expected fields.
+    """
+    client = test_linode_client
+    service_type = "dbaas"
+
+    alert_definitions = client.monitor.alert_definitions(
+        service_type=service_type
+    )
+
+    if len(alert_definitions) == 0:
+        pytest.fail("No alert definitions available for dbaas service type")
+
+    assert getattr(alert_definitions[0], "entities", None) is not None
+
+    alert_def = alert_definitions[0]
+    entities = client.monitor.alert_definition_entities(
+        service_type, alert_def.id
+    )
+
+    assert isinstance(entities, PaginatedList)
+    if len(entities) > 0:
+        entity = entities[0]
+        assert isinstance(entity, AlertDefinitionEntity)
+        assert entity.id
+        assert entity.label
+        assert entity.url
+        assert entity._type == service_type

{linode_api4-5.42.0 → linode_api4-5.43.0}/test/unit/groups/monitor_api_test.py

@@ -4,6 +4,8 @@ from linode_api4 import PaginatedList
 from linode_api4.objects import (
     AggregateFunction,
     AlertDefinition,
+    AlertDefinitionChannel,
+    AlertDefinitionEntity,
     EntityMetricOptions,
 )
 
@@ -71,6 +73,20 @@ class MonitorAlertDefinitionsTest(ClientBaseCase):
             # assert collection and element types
             assert isinstance(alert, PaginatedList)
             assert isinstance(alert[0], AlertDefinition)
+            assert alert[0].scope == "entity"
+            assert alert[0].regions == []
+            assert alert[0].entities.url.endswith(
+                "/alert-definitions/12345/entities"
+            )
+            assert alert[0].entities.count == 1
+            assert alert[0].entities.has_more_resources is False
+            assert isinstance(alert[0].alert_channels, list)
+            assert len(alert[0].alert_channels) == 1
+            assert isinstance(
+                alert[0].alert_channels[0], AlertDefinitionChannel
+            )
+            assert alert[0].alert_channels[0].id == 10000
+            assert alert[0].alert_channels[0]._type == "email"
 
             # fetch the raw JSON from the client and assert its fields
             raw = self.client.get(url)
@@ -90,6 +106,11 @@ class MonitorAlertDefinitionsTest(ClientBaseCase):
             "service_type": service_type,
             "severity": 1,
             "status": "active",
+            "entities": {
+                "url": f"/monitor/services/dbaas/alert-definitions/67890/entities",
+                "count": 1,
+                "has_more_resources": False,
+            },
         }
 
         with self.mock_post(result) as mock_post:
@@ -100,6 +121,8 @@ class MonitorAlertDefinitionsTest(ClientBaseCase):
                 channel_ids=[1, 2],
                 rule_criteria={"rules": []},
                 trigger_conditions={"criteria_condition": "ALL"},
+                scope="entity",
+                regions=[],
                 entity_ids=["13217"],
                 description="created via test",
             )
@@ -109,10 +132,51 @@ class MonitorAlertDefinitionsTest(ClientBaseCase):
             assert mock_post.call_data["label"] == "Created Alert"
             assert mock_post.call_data["severity"] == 1
             assert "channel_ids" in mock_post.call_data
+            assert mock_post.call_data["scope"] == "entity"
+            assert mock_post.call_data["regions"] == []
 
             assert isinstance(alert, AlertDefinition)
             assert alert.id == 67890
+            assert alert.entities.url.endswith(
+                "/alert-definitions/67890/entities"
+            )
+            assert alert.entities.count == 1
+            assert alert.entities.has_more_resources is False
 
             # fetch the same response from the client and assert
             resp = self.client.post(url, data={})
             assert resp["label"] == "Created Alert"
+
+    def test_alert_definition_entities(self):
+        service_type = "dbaas"
+        id = 12345
+        url = (
+            f"/monitor/services/{service_type}/alert-definitions/{id}/entities"
+        )
+
+        with self.mock_get(url) as mock_get:
+            entities = self.client.monitor.alert_definition_entities(
+                service_type, id
+            )
+
+            assert mock_get.call_url == url
+            assert isinstance(entities, PaginatedList)
+            assert len(entities) == 3
+
+            assert isinstance(entities[0], AlertDefinitionEntity)
+            assert entities[0].id == "1"
+            assert entities[0].label == "mydatabase-1"
+            assert entities[0].url == "/v4/databases/mysql/instances/1"
+            assert entities[0]._type == "dbaas"
+
+            assert isinstance(entities[1], AlertDefinitionEntity)
+            assert entities[1].id == "2"
+            assert entities[1].label == "mydatabase-2"
+            assert entities[1].url == "/v4/databases/mysql/instances/2"
+            assert entities[1]._type == "dbaas"
+
+            assert isinstance(entities[2], AlertDefinitionEntity)
+            assert entities[2].id == "3"
+            assert entities[2].label == "mydatabase-3"
+            assert entities[2].url == "/v4/databases/mysql/instances/3"
+            assert entities[2]._type == "dbaas"