new: Support region availability endpoints (#349)

* Add availability object

* Add filter assertion

* Avail docs

Author: lgarber-akamai

linode_api4/groups/region.py

@@ -1,5 +1,6 @@
 from linode_api4.groups import Group
 from linode_api4.objects import Region
+from linode_api4.objects.region import RegionAvailabilityEntry
 
 
 class RegionGroup(Group):
@@ -23,3 +24,22 @@ def __call__(self, *filters):
         """
 
         return self.client._get_and_filter(Region, *filters)
+
+    def availability(self, *filters):
+        """
+        Returns the availability of Linode plans within a Region.
+
+
+        API Documentation: https://www.linode.com/docs/api/regions/#regions-availability-list
+
+        :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 entries describing the availability of a plan in a region.
+        :rtype: PaginatedList of RegionAvailabilityEntry
+        """
+
+        return self.client._get_and_filter(
+            RegionAvailabilityEntry, *filters, endpoint="/regions/availability"
+        )

linode_api4/objects/region.py

@@ -1,4 +1,10 @@
-from linode_api4.objects import Base, Property
+from dataclasses import dataclass
+from typing import List
+
+from linode_api4.errors import UnexpectedResponseError
+from linode_api4.objects.base import Base, JSONObject, Property
+from linode_api4.objects.filtering import FilterableAttribute
+from linode_api4.objects.serializable import JSONFilterableMetaclass
 
 
 class Region(Base):
@@ -17,3 +23,29 @@ class Region(Base):
         "resolvers": Property(),
         "label": Property(),
     }
+
+    @property
+    def availability(self) -> List["RegionAvailabilityEntry"]:
+        result = self._client.get(
+            f"{self.api_endpoint}/availability", model=self
+        )
+
+        if result is None:
+            raise UnexpectedResponseError(
+                "Expected availability data, got None."
+            )
+
+        return [RegionAvailabilityEntry.from_json(v) for v in result]
+
+
+@dataclass
+class RegionAvailabilityEntry(JSONObject):
+    """
+    Represents the availability of a Linode type within a region.
+
+    API Documentation: https://www.linode.com/docs/api/regions/#region-availability-view
+    """
+
+    region: str = None
+    plan: str = None
+    available: bool = False

linode_api4/objects/serializable.py

@@ -1,10 +1,41 @@
 import inspect
 from dataclasses import asdict, dataclass
-from typing import Any, Dict, Optional, get_args, get_origin, get_type_hints
+from types import SimpleNamespace
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    Optional,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from linode_api4.objects.filtering import FilterableAttribute
+
+# Wraps the SimpleNamespace class and allows for
+# SQLAlchemy-style filter generation on JSONObjects.
+JSONFilterGroup = SimpleNamespace
+
+
+class JSONFilterableMetaclass(type):
+    def __init__(cls, name, bases, dct):
+        setattr(
+            cls,
+            "filters",
+            JSONFilterGroup(
+                **{
+                    k: FilterableAttribute(k)
+                    for k in cls.__annotations__.keys()
+                }
+            ),
+        )
+
+        super().__init__(name, bases, dct)
 
 
 @dataclass
-class JSONObject:
+class JSONObject(metaclass=JSONFilterableMetaclass):
     """
     A simple helper class for serializable API objects.
     This is typically used for nested object values.
@@ -13,6 +44,16 @@ class JSONObject:
     fields and static typing.
     """
 
+    filters: ClassVar[JSONFilterGroup] = None
+    """
+    A group containing FilterableAttributes used to create SQLAlchemy-style filters.
+
+    Example usage::
+        self.client.regions.availability(
+            RegionAvailabilityEntry.filters.plan == "premium4096.7"
+        )
+    """
+
     def __init__(self):
         raise NotImplementedError(
             "JSONObject is not intended to be constructed directly"

linode_api4/paginated_list.py

@@ -1,5 +1,7 @@
 import math
 
+from linode_api4.objects.serializable import JSONObject
+
 
 class PaginatedList(object):
     """
@@ -205,6 +207,10 @@ def make_list(json_arr, client, cls, parent_id=None):
 
         for obj in json_arr:
             id_val = None
+            # Special handling for JSON objects
+            if issubclass(cls, JSONObject):
+                result.append(cls.from_json(obj))
+                continue
 
             if "id" in obj:
                 id_val = obj["id"]