new: Add event polling functionality (#293)

## 📝 Description

This change introduces various event-polling-related methods and classes
to be reused across both official and unofficial Linode API
integrations. Additionally, this change adds documentation and guide for
using the new event polling system.

This event polling system is derived from the event polling system
implemented in the Linode Ansible Collection, but is _not_ backwards
compatbile.

Author: lgarber-akamai

docs/guides/event_polling.rst

@@ -0,0 +1,104 @@
+Polling for Events
+==================
+
+There are often situations where an API request will trigger a
+long-running operation (e.g. Instance shutdown) that will run
+after the request has been made. These operations are tracked
+through `Linode Account Events`_ which reflect the target entity,
+progress, and status of these operations.
+
+.. _Linode Account Events: https://www.linode.com/docs/api/account/#events-list
+
+There are often cases where you would like for your application to
+halt until these operations have succeeded. The most reliable and
+efficient way to achieve this is by using the :py:class:`EventPoller`
+object.
+
+Polling on Basic Operations
+---------------------------
+
+In order to poll for an operation, we must create an :py:class:`EventPoller`
+object *before* the endpoint that triggers the operation has been called.
+
+Assuming a :py:class:`LinodeClient` object has already been created with the name
+"client" and an :py:class:`Instance` object has already been created with the name "my_instance",
+an :py:class:`EventPoller` can be created using the
+:meth:`LinodeClient.polling.event_poller_create(...) <PollingGroup.event_poller_create>`
+method::
+
+    poller = client.polling.event_poller_create(
+        "linode",  # The type of the target entity
+        "linode_shutdown",  # The action to poll for
+        entity_id=my_instance.id,  # The ID of your Linode Instance
+    )
+
+Valid values for the `type` and `action` fields can be found in the `Events Response Documentation`_.
+
+.. _Events Response Documentation: https://www.linode.com/docs/api/account/#events-list__responses
+
+From here, we can send the request to trigger the long-running operation::
+
+    my_instance.shutdown()
+
+To wait for this operation to finish, we can call the
+:meth:`poller.wait_for_next_event_finished(...) <EventPoller.wait_for_next_event_finished>`
+method::
+
+    poller.wait_for_next_event_finished()
+
+The :py:class:`timeout` (default 240) and :py:class:`interval` (default 5) arguments can optionally be used to configure the timeout
+and poll frequency for this operation.
+
+Bringing this together, we get the following::
+
+    from linode_api4 import LinodeClient, Instance
+
+    # Construct a client
+    client = LinodeClient("MY_LINODE_TOKEN")
+
+    # Fetch an existing Linode Instance
+    my_instance = client.load(Instance, 12345)
+
+    # Create the event poller
+    poller = client.polling.event_poller_create(
+        "linode",  # The type of the target entity
+        "linode_shutdown",  # The action to poll for
+        entity_id=my_instance.id,  # The ID of your Linode Instance
+    )
+
+    # Shutdown the Instance
+    my_instance.shutdown()
+
+    # Wait until the event has finished
+    poller.wait_for_next_event_finished()
+
+    print("Linode has been successfully shutdown!")
+
+Polling for an Entity to be Free
+--------------------------------
+
+In many cases, certain operations cannot be run until any other operations running on a resource have
+been completed. To ensure these operation are run reliably and do not encounter conflicts,
+you can use the
+:meth:`LinodeClient.polling.wait_for_entity_free(...) <PollingGroup.wait_for_entity_free>` method
+to wait until a resource has no running or queued operations.
+
+For example::
+
+    # Construct a client
+    client = LinodeClient("MY_LINODE_TOKEN")
+
+    # Load an existing instance
+    my_instance = client.load(Instance, 12345)
+
+    # Wait until the Linode is not busy
+    client.polling.wait_for_entity_free(
+        "linode",
+        my_instance.id
+    )
+
+    # Boot the Instance
+    my_instance.boot()
+
+The :py:class:`timeout` (default 240) and :py:class:`interval` (default 5) arguments can optionally be used to configure the timeout
+and poll frequency for this operation.

docs/index.rst

@@ -32,9 +32,11 @@ Table of Contents
 
    guides/getting_started
    guides/core_concepts
+   guides/event_polling
    guides/oauth
    linode_api4/linode_client
    linode_api4/login_client
    linode_api4/objects/models
+   linode_api4/polling
    linode_api4/paginated_list
    linode_api4/objects/filtering

docs/linode_api4/linode_client.rst

@@ -146,6 +146,15 @@ with buckets and objects, use the s3 API directly with a library like `boto3`_.
 
 .. _boto3: https://github.com/boto/boto3
 
+PollingGroup
+^^^^^^^^^^^^
+
+Includes methods related to account event polling.
+
+.. autoclass:: linode_api4.linode_client.PollingGroup
+   :members:
+   :special-members:
+
 ProfileGroup
 ^^^^^^^^^^^^
 

docs/linode_api4/objects/models.rst

@@ -139,4 +139,3 @@ Volume Models
    :exclude-members: api_endpoint, properties, derived_url_path, id_attribute, parent_id_name
    :undoc-members:
    :inherited-members:
-

docs/linode_api4/polling.rst

@@ -0,0 +1,12 @@
+Event Polling
+==========
+
+This project exposes a framework for dynamically polling on long-running Linode Events.
+
+See the :doc:`Event Polling Guide<../guides/event_polling>` for more details.
+
+EventPoller class
+-------------------
+
+.. autoclass:: linode_api4.EventPoller
+   :members:

linode_api4/__init__.py

@@ -4,3 +4,4 @@
 from linode_api4.linode_client import LinodeClient
 from linode_api4.login_client import LinodeLoginClient, OAuthScopes
 from linode_api4.paginated_list import PaginatedList
+from linode_api4.polling import EventPoller

linode_api4/groups/__init__.py

@@ -11,6 +11,7 @@
 from .networking import *
 from .nodebalancer import *
 from .object_storage import *
+from .polling import *
 from .profile import *
 from .region import *
 from .support import *

linode_api4/groups/polling.py

@@ -0,0 +1,90 @@
+import polling
+
+from linode_api4.groups import Group
+from linode_api4.objects.account import Event
+from linode_api4.polling import EventPoller, TimeoutContext
+
+
+class PollingGroup(Group):
+    """
+    This group contains various helper functions for polling on Linode events.
+    """
+
+    def event_poller_create(
+        self,
+        entity_type: str,
+        action: str,
+        entity_id: int = None,
+    ) -> EventPoller:
+        """
+        Creates a new instance of the EventPoller class.
+
+        :param entity_type: The type of the entity to poll for events on.
+                            Valid values for this field can be found here: https://www.linode.com/docs/api/account/#events-list__responses
+        :type entity_type: str
+        :param action: The action that caused the Event to poll for.
+                       Valid values for this field can be found here: https://www.linode.com/docs/api/account/#events-list__responses
+        :type action: str
+        :param entity_id: The ID of the entity to poll for.
+        :type entity_id: int
+        :param poll_interval: The interval in seconds to wait between polls.
+        :type poll_interval: int
+
+        :returns: The new EventPoller object.
+        :rtype: EventPoller
+        """
+
+        return EventPoller(
+            self.client,
+            entity_type,
+            action,
+            entity_id=entity_id,
+        )
+
+    def wait_for_entity_free(
+        self,
+        entity_type: str,
+        entity_id: int,
+        timeout: int = 240,
+        interval: int = 5,
+    ):
+        """
+        Waits for all events relevant events to not be scheduled or in-progress.
+
+        :param entity_type: The type of the entity to poll for events on.
+                            Valid values for this field can be found here: https://www.linode.com/docs/api/account/#events-list__responses
+        :type entity_type: str
+        :param entity_id: The ID of the entity to poll for.
+        :type entity_id: int
+        :param timeout: The timeout in seconds for this polling operation.
+        :type timeout: int
+        :param interval: The interval in seconds to wait between polls.
+        :type interval: int
+        """
+
+        timeout_ctx = TimeoutContext(timeout_seconds=timeout)
+
+        api_filter = {
+            "+order": "desc",
+            "+order_by": "created",
+            "entity.id": entity_id,
+            "entity.type": entity_type,
+        }
+
+        def poll_func():
+            events = self.client.get("/account/events", filters=api_filter)[
+                "data"
+            ]
+            return all(
+                event["status"] not in ("scheduled", "started")
+                for event in events
+            )
+
+        if poll_func():
+            return
+
+        polling.poll(
+            poll_func,
+            step=interval,
+            timeout=timeout_ctx.seconds_remaining,
+        )

linode_api4/linode_client.py

@@ -168,6 +168,9 @@ def __init__(
         #: Access methods related to Images - See :any:`ImageGroup` for more information.
         self.images = ImageGroup(self)
 
+        #: Access methods related to Event polling - See :any:`PollingGroup` for more information.
+        self.polling = PollingGroup(self)
+
     @property
     def _user_agent(self):
         return "{}python-linode_api4/{} {}".format(