Merge pull request #73 from anomaly/alpha-8

alpha-8 urgent release

Author: devraj

README.md

@@ -44,6 +44,10 @@ from gallagher import cc
 from gallagher.dto.summary import CardholderSummary
 from gallagher.cc.cardholders import Cardholder
 
+# Optionally provide a client certificate and key
+cert_path = os.path.join(os.getcwd(), "client.pem")
+key_path = os.path.join(os.getcwd(), "client.key")
+
 # Set the API key from the environment
 api_key = os.environ.get("GACC_API_KEY")
 cc.api_key = api_key

docs/docs/python-sdk.md

@@ -297,11 +297,11 @@ async def main():
     cc.api_key = api_key
 
     # Used to control the event loop
-    event = asyncio.Event()
-    event.set()
+    asyncio_event = asyncio.Event()
+    asyncio_event.set()
 
     async for updates in Alarms.follow(
-        event=event,
+        asyncio_event=asyncio_event,
     ):
 
         for update in updates.updates:
@@ -310,7 +310,7 @@ async def main():
         # Examples of stopping the loop if
         # we got no updates
         if len(updates.updates) == 0:
-            event.clear()
+            asyncio_event.clear()
 
 if __name__ == "__main__":
     asyncio.run(main())

examples/alarm.py

@@ -18,7 +18,7 @@ async def main():
     event.set()
 
     async for updates in Alarms.follow(
-        event=event,
+        asyncio_event=event,
     ):
 
         for update in updates.updates:

examples/events.py

@@ -49,7 +49,7 @@ async def main():
     event.set()
 
     async for updates in Event.follow(
-        event=event,
+        asyncio_event=event,
     ):
         for update_event in updates.events:
             print("Processing event")

gallagher/cc/alarms/events.py

@@ -22,8 +22,6 @@
 
 class Event(APIEndpoint):
     """Event
-
-
     
     How updates differ from GET:
 

gallagher/cc/core.py

@@ -22,7 +22,7 @@
 from datetime import datetime
 from dataclasses import dataclass
 
-from asyncio import Event
+from asyncio import Event as AsyncioEvent  # Used for signalling events
 
 from http import HTTPStatus  # Provides constants for HTTP status codes
 
@@ -486,11 +486,15 @@ async def previous(cls, response):
     @classmethod
     async def follow(
         cls,
-        event: Event,
+        asyncio_event: AsyncioEvent, # Not to be confused with Gallagher event
         params: dict[str, Any] = {},
     ):
         """Fetches update and follows next to get the next set of results
 
+        parameters:
+        - event: asyncio.Event object to signal when to stop
+        - params: dictionary of parameters to pass to the endpoint
+
         Long poll behaviour in the Gallagher API uses the following pattern:
         - The request will wait until there's a new set of changes
         - If no changes are detected in 30 seconds then the server returns
@@ -516,7 +520,7 @@ async def follow(
                 verify=cls._ssl_context(),
             ) as _httpx_async:
 
-            while event.is_set():
+            while asyncio_event.is_set():
                 try:
                     response = await _httpx_async.get(
                         f"{url}",  # required to turn pydantic object to str

gallagher/const.py

@@ -23,9 +23,9 @@ class IP_ADDR:
     https://gallaghersecurity.github.io/commandcentre-cloud-api-gateway.html
     """
 
-    CLOUD_GATEWAY_AU = ["3.106.1.6", "3.106.100.112"]
+    CLOUD_GATEWAY_AU: list[str] = ["3.106.1.6", "3.106.100.112"]
 
-    CLOUD_GATEWAY_US = ["44.193.42.111", "3.209.194.103"]
+    CLOUD_GATEWAY_US: list[str] = ["44.193.42.111", "3.209.194.103"]
 
 
 class TRANSPORT:

gallagher/decorators.py

@@ -0,0 +1,79 @@
+""" Decorators for annotating functions for behaviours.
+
+    All decorators are defined here and are referenced across the codebase.
+    Note that some of them reference the bootstrapped environment where
+    information is discovered from the live Command Centre the instance
+    is connected to.
+
+    See Also:
+        https://github.com/anomaly/gallagher/issues/69
+"""
+
+def deprecated(func):
+    """Decorator to indicate that a function is deprecated.
+
+    This decorator is used to indicate that a function is deprecated and
+    should not be used. It will raise a warning when the function is called.
+
+    Args:
+        func (Callable): The function to be deprecated.
+
+    Returns:
+        Callable: The wrapped function.
+
+    Examples:
+        >>> @deprecated
+        ... def old_function():
+        ...     pass
+
+    """
+    import warnings
+    import functools
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        warnings.warn(
+            f"Call to deprecated function {func.__name__}.", 
+            category=DeprecationWarning
+        )
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def available(version_string):
+    """Decorator to indicate that a function is available in a specific version.
+
+    This decorator is used to indicate that a function is available in a specific
+    version of the Command Centre API. It will raise an error if the function is
+    called in a version that does not support it.
+
+    Args:
+        version_string (str): The version string the function is available in.
+
+    Returns:
+        Callable: The wrapped function.
+
+    Examples:
+        >>> @available("1.0.0")
+        ... def new_function():
+        ...     pass
+
+    """
+    import functools
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            from .cc.core import Capabilities
+
+            if Capabilities.CURRENT.version < version_string:
+                raise RuntimeError(
+                    f"Function {func.__name__} is not available in version {Capabilities.CURRENT.version}."
+                )
+
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

gallagher/dto/ref/cardholder.py

@@ -2,15 +2,14 @@
 
 from ..utils import (
     AppBaseModel,
-    HrefMixin,
     IdentityMixin,
     OptionalHrefMixin,
 )
 
 
 class CardholderRef(
     AppBaseModel,
-    HrefMixin,
+    OptionalHrefMixin,
 ):
     """Reference to a Cardholder"""
 

gallagher/dto/summary/card_type.py

@@ -2,7 +2,7 @@
 
 from ..utils import (
     AppBaseModel,
-    IdentityMixin,
+    OptionalIdentityMixin,
 )
 
 class CardExpiryTypeSummary(AppBaseModel):
@@ -11,7 +11,7 @@ class CardExpiryTypeSummary(AppBaseModel):
 
 class CardSummary(
     AppBaseModel,
-    IdentityMixin,
+    OptionalIdentityMixin,
 ):
     """Card summary as sent by the Event objects