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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linode_api4
-Version: 5.42.0
+Version: 5.44.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.44.0}/linode_api4/groups/linode.py

@@ -162,6 +162,10 @@ class LinodeGroup(Group):
         interface_generation: Optional[Union[InterfaceGeneration, str]] = None,
         network_helper: Optional[bool] = None,
         maintenance_policy: Optional[str] = None,
+        root_pass: Optional[str] = None,
+        kernel: Optional[str] = None,
+        boot_size: Optional[int] = None,
+        authorized_users: Optional[List[str]] = None,
         **kwargs,
     ):
         """
@@ -172,27 +176,26 @@ class LinodeGroup(Group):
         To create an Instance from an :any:`Image`, call `instance_create` with
         a :any:`Type`, a :any:`Region`, and an :any:`Image`.  All three of
         these fields may be provided as either the ID or the appropriate object.
-        In this mode, a root password will be generated and returned with the
-        new Instance object.
+        When an Image is provided, at least one of ``root_pass``, ``authorized_users``, or
+        ``authorized_keys`` must also be given.
 
         For example::
 
-           new_linode, password = client.linode.instance_create(
+           new_linode = client.linode.instance_create(
                "g6-standard-2",
                "us-east",
-               image="linode/debian9")
+               image="linode/debian13",
+               root_pass="aComplex@Password123")
 
            ltype = client.linode.types().first()
            region = client.regions().first()
            image = client.images().first()
 
-           another_linode, password = client.linode.instance_create(
+           another_linode = client.linode.instance_create(
                ltype,
                region,
-               image=image)
-
-        To output the password from the above example:
-            print(password)
+               image=image,
+               authorized_keys="ssh-rsa AAAA")
 
         To output the first IPv4 address of the new Linode:
             print(new_linode.ipv4[0])
@@ -210,10 +213,11 @@ class LinodeGroup(Group):
 
            stackscript = StackScript(client, 10079)
 
-           new_linode, password = client.linode.instance_create(
+           new_linode = client.linode.instance_create(
               "g6-standard-2",
               "us-east",
-              image="linode/debian9",
+              image="linode/debian13",
+              root_pass="aComplex@Password123",
               stackscript=stackscript,
               stackscript_data={"gh_username": "example"})
 
@@ -244,10 +248,11 @@ class LinodeGroup(Group):
         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(
+        linode = client.linode.instance_create(
             "g6-standard-1",
             "us-mia",
             image="linode/ubuntu24.04",
+            root_pass="aComplex@Password123",
 
             # This can be configured as an account-wide default
             interface_generation=InterfaceGeneration.LINODE,
@@ -280,10 +285,14 @@ class LinodeGroup(Group):
         :type ltype: str or Type
         :param region: The Region in which we are creating the Instance
         :type region: str or Region
-        :param image: The Image to deploy to this Instance. If this is provided
-                      and no root_pass is given, a password will be generated
-                      and returned along with the new Instance.
+        :param image: The Image to deploy to this Instance. If this is provided,
+                      at least one of root_pass, authorized_users, or authorized_keys must also be
+                      provided.
         :type image: str or Image
+        :param root_pass: The root password for the new Instance. Required when
+                          an image is provided and neither authorized_users nor
+                          authorized_keys are given.
+        :type root_pass: str
         :param stackscript: The StackScript to deploy to the new Instance.  If
                             provided, "image" is required and must be compatible
                             with the chosen StackScript.
@@ -300,6 +309,11 @@ class LinodeGroup(Group):
                                 be a single key, or a path to a file containing
                                 the key.
         :type authorized_keys: list or str
+        :param authorized_users: A list of usernames whose keys should be installed
+                                 as trusted for the root user.  These user's keys
+                                 should already be set up, see :any:`ProfileGroup.ssh_keys`
+                                 for details.
+        :type authorized_users: list[str]
         :param label: The display label for the new Instance
         :type label: str
         :param group: The display group for the new Instance
@@ -322,7 +336,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.
@@ -336,26 +349,39 @@ class LinodeGroup(Group):
         :param maintenance_policy: The slug of the maintenance policy to apply during maintenance.
                                       If not provided, the default policy (linode/migrate) will be applied.
         :type maintenance_policy: str
-
-        :returns: A new Instance object, or a tuple containing the new Instance and
-                  the generated password.
-        :rtype: Instance or tuple(Instance, str)
+        :param kernel: The kernel to boot the Instance with. If provided, this will be used as the
+                       kernel for the default configuration profile.
+        :type kernel: str
+        :param boot_size: The size of the boot disk in MB. If provided, this will be used to create
+                          the boot disk for the Instance.
+        :type boot_size: int
+
+        :returns: A new Instance object
+        :rtype: Instance
         :raises ApiError: If contacting the API fails
         :raises UnexpectedResponseError: If the API response is somehow malformed.
                                          This usually indicates that you are using
                                          an outdated library.
         """
 
-        ret_pass = None
-        if image and not "root_pass" in kwargs:
-            ret_pass = Instance.generate_root_password()
-            kwargs["root_pass"] = ret_pass
+        if (
+            image
+            and not root_pass
+            and not authorized_keys
+            and not authorized_users
+        ):
+            raise ValueError(
+                "When creating an Instance from an Image, at least one of "
+                "root_pass, authorized_users, or authorized_keys must be provided."
+            )
 
         params = {
             "type": ltype,
             "region": region,
             "image": image,
+            "root_pass": root_pass,
             "authorized_keys": load_and_validate_keys(authorized_keys),
+            "authorized_users": authorized_users,
             # These will automatically be flattened below
             "firewall_id": firewall,
             "backup_id": backup,
@@ -373,6 +399,8 @@ class LinodeGroup(Group):
             "interfaces": interfaces,
             "interface_generation": interface_generation,
             "network_helper": network_helper,
+            "kernel": kernel,
+            "boot_size": boot_size,
         }
 
         params.update(kwargs)
@@ -387,10 +415,7 @@ class LinodeGroup(Group):
                 "Unexpected response when creating linode!", json=result
             )
 
-        l = Instance(self.client, result["id"], result)
-        if not ret_pass:
-            return l
-        return l, ret_pass
+        return Instance(self.client, result["id"], result)
 
     @staticmethod
     def build_instance_metadata(user_data=None, encode_user_data=True):
@@ -399,10 +424,11 @@ class LinodeGroup(Group):
         the :any:`instance_create` method. This helper can also be used
         when cloning and rebuilding Instances.
         **Creating an Instance with User Data**::
-            new_linode, password = client.linode.instance_create(
+            new_linode = client.linode.instance_create(
                 "g6-standard-2",
                 "us-east",
                 image="linode/ubuntu22.04",
+                root_pass="aComplex@Password123",
                 metadata=client.linode.build_instance_metadata(user_data="myuserdata")
             )
         :param user_data: User-defined data to provide to the Linode Instance through

{linode_api4-5.42.0 → linode_api4-5.44.0}/linode_api4/groups/lock.py

@@ -24,7 +24,7 @@ class LockGroup(Group):
 
            locks = client.locks()
 
-        API Documentation: TBD
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/get-resource-locks
 
         :param filters: Any number of filters to apply to this query.
                         See :doc:`Filtering Collections</linode_api4/objects/filtering>`
@@ -44,7 +44,7 @@ class LockGroup(Group):
         """
         Creates a new Resource Lock for the specified entity.
 
-        API Documentation: TBD
+        API Documentation: https://techdocs.akamai.com/linode-api/reference/post-resource-lock
 
         :param entity_type: The type of entity to lock (e.g., "linode").
         :type entity_type: str

{linode_api4-5.42.0 → linode_api4-5.44.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.44.0}/linode_api4/groups/networking.py

@@ -452,10 +452,10 @@ class NetworkingGroup(Group):
         :param assignments: Any number of assignments to make.  See
                             :any:`IPAddress.to` for details on how to construct
                             assignments.
-        :type assignments: dct
+        :type assignments: list
         """
 
-        for a in assignments["assignments"]:
+        for a in assignments:
             if not "address" in a or not "linode_id" in a:
                 raise ValueError("Invalid assignment: {}".format(a))
 

{linode_api4-5.42.0 → linode_api4-5.44.0}/linode_api4/groups/object_storage.py

@@ -19,6 +19,7 @@ from linode_api4.objects import (
     ObjectStorageACL,
     ObjectStorageBucket,
     ObjectStorageCluster,
+    ObjectStorageGlobalQuota,
     ObjectStorageKeyPermission,
     ObjectStorageKeys,
     ObjectStorageQuota,
@@ -533,3 +534,18 @@ class ObjectStorageGroup(Group):
         :rtype: PaginatedList of ObjectStorageQuota
         """
         return self.client._get_and_filter(ObjectStorageQuota, *filters)
+
+    def global_quotas(self, *filters):
+        """
+        Lists the active account-level Object Storage quotas applied to your account.
+
+        API Documentation: TBD
+
+        :param filters: Any number of filters to apply to this query.
+                        See :doc:`Filtering Collections</linode_api4/objects/filtering>`
+                        for more details on filtering.
+
+        :returns: A list of account-level Object Storage Quotas that matched the query.
+        :rtype: PaginatedList of ObjectStorageGlobalQuota
+        """
+        return self.client._get_and_filter(ObjectStorageGlobalQuota, *filters)

{linode_api4-5.42.0 → linode_api4-5.44.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.44.0}/linode_api4/objects/database.py

@@ -1,12 +1,7 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
-from linode_api4.objects import (
-    Base,
-    JSONObject,
-    MappedObject,
-    Property,
-)
+from linode_api4.objects import Base, JSONObject, MappedObject, Property
 
 
 class DatabaseType(Base):

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

@@ -1437,29 +1437,36 @@ class Instance(Base):
                            for the image deployed the disk will be used.  Required
                            if creating a disk without an image.
         :param read_only: If True, creates a read-only disk
-        :param image: The Image to deploy to the disk.
+        :param image: The Image to deploy to the disk.  If provided, at least one of
+                      root_pass, authorized_users or authorized_keys must also be given.
         :param root_pass: The password to configure for the root user when deploying an
-                          image to this disk.  Not used if image is not given.  If an
-                          image is given and root_pass is not, a password will be
-                          generated and returned alongside the new disk.
+                          image to this disk.  Not used if image is not given.
         :param authorized_keys: A list of SSH keys to install as trusted for the root user.
         :param authorized_users: A list of usernames whose keys should be installed
                                  as trusted for the root user.  These user's keys
                                  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.
         :param **stackscript_args: Any arguments to pass to the StackScript, as defined
                                    by its User Defined Fields.
+
+        :returns: A new Disk object.
+        :rtype: Disk
         """
 
-        gen_pass = None
-        if image and not root_pass:
-            gen_pass = Instance.generate_root_password()
-            root_pass = gen_pass
+        if (
+            image
+            and not root_pass
+            and not authorized_keys
+            and not authorized_users
+        ):
+            raise ValueError(
+                "When creating a Disk from an Image, at least one of "
+                "root_pass, authorized_users, or authorized_keys must be provided."
+            )
 
         authorized_keys = load_and_validate_keys(authorized_keys)
 
@@ -1506,11 +1513,7 @@ class Instance(Base):
                 "Unexpected response creating disk!", json=result
             )
 
-        d = Disk(self._client, result["id"], self.id, result)
-
-        if gen_pass:
-            return d, gen_pass
-        return d
+        return Disk(self._client, result["id"], self.id, result)
 
     def enable_backups(self):
         """
@@ -1622,6 +1625,7 @@ class Instance(Base):
         disk_encryption: Optional[
             Union[InstanceDiskEncryptionType, str]
         ] = None,
+        authorized_users: Optional[List[str]] = None,
         **kwargs,
     ):
         """
@@ -1633,26 +1637,30 @@ class Instance(Base):
 
         :param image: The Image to deploy to this Instance
         :type image: str or Image
-        :param root_pass: The root password for the newly rebuilt Instance.  If
-                          omitted, a password will be generated and returned.
+        :param root_pass: The root password for the newly rebuilt Instance.  At least
+                          one of root_pass, authorized_users, or authorized_keys must be provided.
         :type root_pass: str
         :param authorized_keys: The ssh public keys to install in the linode's
                                 /root/.ssh/authorized_keys file.  Each entry may
                                 be a single key, or a path to a file containing
                                 the key.
         :type authorized_keys: list or str
+        :param authorized_users: A list of usernames whose keys should be installed
+                                 as trusted for the root user.  These user's keys
+                                 should already be set up, see :any:`ProfileGroup.ssh_keys`
+                                 for details.
+        :type authorized_users: list[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
-                  (otherwise True)
-        :rtype: str or bool
+        :returns: True.
+        :rtype: bool
         """
-        ret_pass = None
-        if not root_pass:
-            ret_pass = Instance.generate_root_password()
-            root_pass = ret_pass
+        if not root_pass and not authorized_keys and not authorized_users:
+            raise ValueError(
+                "When rebuilding an Instance, at least one of "
+                "root_pass, authorized_users, or authorized_keys must be provided."
+            )
 
         authorized_keys = load_and_validate_keys(authorized_keys)
 
@@ -1663,6 +1671,7 @@ class Instance(Base):
             "disk_encryption": (
                 str(disk_encryption) if disk_encryption else None
             ),
+            "authorized_users": authorized_users,
         }
 
         params.update(kwargs)
@@ -1681,10 +1690,7 @@ class Instance(Base):
         # update ourself with the newly-returned information
         self._populate(result)
 
-        if not ret_pass:
-            return True
-        else:
-            return ret_pass
+        return True
 
     def rescue(self, *disks):
         """
@@ -2057,8 +2063,6 @@ class Instance(Base):
         Creates a new interface under this Linode.
         Linode interfaces are not interchangeable with Config interfaces.
 
-        NOTE: Linode interfaces may not currently be available to all users.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/post-linode-interface
 
         Example: Creating a simple public interface for this Linode::
@@ -2134,8 +2138,6 @@ class Instance(Base):
         """
         The settings for all interfaces under this Linode.
 
-        NOTE: Linode interfaces may not currently be available to all users.
-
         :returns: The settings for instance-level interface settings for this Linode.
         :rtype: LinodeInterfacesSettings
         """
@@ -2204,8 +2206,6 @@ class Instance(Base):
         NOTE: If dry_run is True, interfaces in the result will be
               of type MappedObject rather than LinodeInterface.
 
-        NOTE: Linode interfaces may not currently be available to all users.
-
         API Documentation: https://techdocs.akamai.com/linode-api/reference/post-upgrade-linode-interfaces
 
         :param config: The configuration profile the legacy interfaces to