feat: adds Request and Response Hooks

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds new `RequestHook` and `ResponseHook` events. (un)subscribe to them with the new `subscribe_to_request_hook`, `subscribe_to_response_hook`, `unsubscribe_from_request_hook`, or `unsubscribe_from_response_hook` methods of an `EasyPostClient`
+
 ## v8.0.0 (2023-06-06)
 
 See our [Upgrade Guide](UPGRADE_GUIDE.md#upgrading-from-7x-to-80) for more details.

Makefile

@@ -20,9 +20,9 @@ black-check:
 build:
 	$(VIRTUAL_BIN)/python -m build
 
-## clean - Remove the virtual environment and clear out .pyc files
+## clean - Clean the project
 clean:
-	rm -rf $(VIRTUAL_ENV) dist/ build/ *.egg-info/ .pytest_cache .mypy_cache
+	rm -rf $(VIRTUAL_ENV) dist/ *.egg-info/ .*cache htmlcov *.lcov .coverage
 	find . -name '*.pyc' -delete
 
 ## coverage - Test the project and generate an HTML coverage report

README.md

@@ -62,6 +62,24 @@ bought_shipment = client.shipment.buy(shipment.id, rate=shipment.lowest_rate())
 print(bought_shipment)
 ```
 
+### HTTP Hooks
+
+Users can subscribe to HTTP requests and responses via the `RequestHook` and `ResponseHook` objects. To do so, pass a function to the `subscribe_to_request_hook` or `subscribe_to_response_hook` methods of an `EasyPostClient` object:
+
+```python
+def custom_function(**kwargs):
+    """Pass your code here, data about the request/response is contained within `kwargs`."""
+    print(f"Received a request with the status code of: {kwargs.get('http_status')}")
+
+client = easypost.EasyPostClient(os.getenv('EASYPOST_API_KEY'))
+
+client.subscribe_to_response_hook(custom_function)
+
+# Make your API calls here, your custom_function will trigger once a response is received
+```
+
+You can also unsubscribe your functions in a similar manner by using the `unsubscribe_from_request_hook` and `unsubscribe_from_response_hook` methods of a client object.
+
 ## Documentation
 
 API documentation can be found at: <https://easypost.com/docs/api>.

easypost/easypost_client.py

@@ -5,6 +5,10 @@
     SUPPORT_EMAIL,
     TIMEOUT,
 )
+from easypost.hooks import (
+    RequestHook,
+    ResponseHook,
+)
 from easypost.services import (
     AddressService,
     BatchService,
@@ -75,6 +79,10 @@ def __init__(
         self.user = UserService(self)
         self.webhook = WebhookService(self)
 
+        # Hooks
+        self._request_event = RequestHook()
+        self._response_event = ResponseHook()
+
         # use urlfetch as request_lib on google app engine, otherwise use requests
         self._request_lib = None
         try:
@@ -105,3 +113,19 @@ def __init__(
             else:
                 if major_version < 1:
                     raise ImportError(INVALID_REQUESTS_VERSION_ERROR.format(SUPPORT_EMAIL))
+
+    def subscribe_to_request_hook(self, function):
+        """Subscribe functions to run when a request event occurs."""
+        self._request_event += function
+
+    def unsubscribe_from_request_hook(self, function):
+        """Unsubscribe functions from running when a request even occurs."""
+        self._request_event -= function
+
+    def subscribe_to_response_hook(self, function):
+        """Subscribe functions to run when a response event occurs."""
+        self._response_event += function
+
+    def unsubscribe_from_response_hook(self, function):
+        """Unsubscribe functions from running when a response even occurs."""
+        self._response_event -= function

easypost/hooks/__init__.py

@@ -0,0 +1,4 @@
+# flake8: noqa
+from easypost.hooks.event_hook import EventHook
+from easypost.hooks.request_hook import RequestHook
+from easypost.hooks.response_hook import ResponseHook

easypost/hooks/event_hook.py

@@ -0,0 +1,17 @@
+class EventHook:
+    """The parent event that occurs when a hook is triggered."""
+
+    def __init__(self):
+        self._event_handlers = []
+
+    def __iadd__(self, handler):
+        self._event_handlers.append(handler)
+        return self
+
+    def __isub__(self, handler):
+        self._event_handlers.remove(handler)
+        return self
+
+    def __call__(self, *args, **kwargs):
+        for event_handler in self._event_handlers:
+            event_handler(*args, **kwargs)

easypost/hooks/request_hook.py

@@ -0,0 +1,7 @@
+from easypost.hooks import EventHook
+
+
+class RequestHook(EventHook):
+    """An event that gets triggered when an HTTP request begins."""
+
+    pass

easypost/hooks/response_hook.py

@@ -0,0 +1,7 @@
+from easypost.hooks import EventHook
+
+
+class ResponseHook(EventHook):
+    """An event that gets triggered when an HTTP response is returned."""
+
+    pass

easypost/requestor.py

@@ -2,6 +2,7 @@
 import json
 import platform
 import time
+import uuid
 from enum import Enum
 from json import JSONDecodeError
 from typing import (
@@ -200,17 +201,40 @@ def request_raw(
             "User-Agent": user_agent,
         }
 
+        request_timestamp = datetime.datetime.now(datetime.timezone.utc)
+        request_uuid = uuid.uuid4()
+        self._client._request_event(
+            method=method,
+            path=abs_url,
+            headers=headers,
+            data=params,
+            request_timestamp=request_timestamp,
+            request_uuid=request_uuid,
+        )
+
         if self._client._request_lib == "urlfetch":
-            http_body, http_status = self.urlfetch_request(
+            http_body, http_status, http_headers = self.urlfetch_request(
                 method=method, abs_url=abs_url, headers=headers, params=params
             )
         elif self._client._request_lib == "requests":
-            http_body, http_status = self.requests_request(
+            http_body, http_status, http_headers = self.requests_request(
                 method=method, abs_url=abs_url, headers=headers, params=params
             )
         else:
             raise EasyPostError(INVALID_REQUEST_LIB_ERROR.format(self._client._request_lib, SUPPORT_EMAIL))
 
+        response_timestamp = datetime.datetime.now(datetime.timezone.utc)
+        self._client._response_event(
+            http_status=http_status,
+            method=method,
+            path=abs_url,
+            headers=http_headers,
+            response_body=http_body,
+            request_timestamp=request_timestamp,
+            response_timestamp=response_timestamp,
+            request_uuid=request_uuid,
+        )
+
         return http_body, http_status
 
     def interpret_response(self, http_body: str, http_status: int) -> Dict[str, Any]:
@@ -235,7 +259,7 @@ def requests_request(
         abs_url: str,
         headers: Dict[str, Any],
         params: Dict[str, Any],
-    ) -> Tuple[str, int]:
+    ) -> Tuple[str, int, Dict[str, Any]]:
         """Make a request by using the `request` library."""
         if method in [RequestMethod.GET, RequestMethod.DELETE]:
             url_params = params
@@ -261,20 +285,21 @@ def requests_request(
             )
             http_body = result.text
             http_status = result.status_code
+            http_headers = result.headers
         except requests.exceptions.Timeout:
             raise TimeoutError(TIMEOUT_ERROR)
         except Exception as e:
             raise HttpError(COMMUNICATION_ERROR.format(SUPPORT_EMAIL, e))
 
-        return http_body, http_status
+        return http_body, http_status, http_headers
 
     def urlfetch_request(
         self,
         method: RequestMethod,
         abs_url: str,
         headers: Dict[str, Any],
         params: Dict[str, Any],
-    ) -> Tuple[str, int]:
+    ) -> Tuple[str, int, Dict[str, Any]]:
         """Make a request by using the `urlfetch` library."""
         fetch_args = {
             "method": method.value,
@@ -300,7 +325,7 @@ def urlfetch_request(
         except Exception as e:
             raise HttpError(COMMUNICATION_ERROR.format(SUPPORT_EMAIL, e))
 
-        return result.content, result.status_code
+        return result.content, result.status_code, result.headers
 
     def handle_api_error(self, http_status: int, http_body: str, response: Dict[str, Any]) -> None:
         """Handles API errors returned from the EasyPost API."""
@@ -318,7 +343,11 @@ def handle_api_error(self, http_status: int, http_body: str, response: Dict[str,
 
         error_type = STATUS_CODE_TO_ERROR_MAPPING.get(http_status, UnknownApiError)
 
-        raise error_type(message=error.get("message", ""), http_status=http_status, http_body=http_body)
+        raise error_type(
+            message=error.get("message", ""),
+            http_status=http_status,
+            http_body=http_body,
+        )
 
     def _utf8(self, value: Union[str, bytes]) -> str:
         # Python3's str(bytestring) returns "b'bytestring'" so we use .decode instead