Merge pull request #25 from bellingcat/4.0/beta

4.0/beta

Author: ritchiemwewa

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "octosuite"
-version = "4.0.0beta1"
+version = "4.0.0beta2"
 description = "TUI-based toolkit for GitHub data analysis."
 readme = "README.md"
 license = "MIT"

src/octosuite/__init__.py

@@ -1,2 +1,2 @@
 __pkg__ = "octosuite"
-__version__ = "4.0.0beta1"
+__version__ = "4.0.0beta2"

src/octosuite/core/cache.py

@@ -8,30 +8,59 @@ class ResponseCache:
     """Simple in-memory cache for API responses."""
 
     def __init__(self):
+        """Initialise the ResponseCache with an empty cache dictionary."""
+
         self._cache = {}
 
     @staticmethod
     def _generate_key(url: str, params: dict = None) -> str:
-        """Generate a unique cache key from URL and params."""
+        """
+        Generate a unique cache key from URL and parameters.
+
+        :param url: The URL to generate a key for.
+        :param params: Optional dictionary of parameters to include in the key.
+        :return: MD5 hash string representing the unique cache key.
+        """
+
         cache_data = f"{url}:{json.dumps(params or {}, sort_keys=True)}"
         return hashlib.md5(cache_data.encode()).hexdigest()
 
     def get(self, url: str, params: dict = None):
-        """Get cached response."""
+        """
+        Retrieve a cached response if it exists.
+
+        :param url: The URL to retrieve cached data for.
+        :param params: Optional dictionary of parameters used in the original request.
+        :return: Cached response data if found, None otherwise.
+        """
+
         key = self._generate_key(url, params)
         return self._cache.get(key)
 
     def set(self, url: str, data, params: dict = None):
-        """Cache a response."""
+        """
+        Store a response in the cache.
+
+        :param url: The URL to cache data for.
+        :param data: The response data to cache.
+        :param params: Optional dictionary of parameters used in the request.
+        """
+
         key = self._generate_key(url, params)
         self._cache[key] = data
 
     def clear(self):
-        """Clear all cached responses."""
+        """Clear all cached responses from memory."""
         self._cache.clear()
 
     def remove(self, url: str, params: dict = None):
-        """Remove a specific cached response."""
+        """
+        Remove a specific cached response.
+
+        :param url: The URL to remove cached data for.
+        :param params: Optional dictionary of parameters used in the original request.
+        """
+
         key = self._generate_key(url, params)
         self._cache.pop(key, None)
 
@@ -40,5 +69,6 @@ def remove(self, url: str, params: dict = None):
 
 
 def clear_cache():
-    """Clear all cached API responses."""
+    """Clear all cached API responses from the global cache instance."""
+
     cache.clear()

src/octosuite/core/github.py

@@ -14,6 +14,8 @@
 
 
 class GitHub:
+    """Handles GitHub API requests with caching and response sanitisation."""
+
     def __init__(
         self,
         user_agent: str = (
@@ -22,6 +24,12 @@ def __init__(
             f"https://github.com/bellingcat/octosuite) requests/{requests.__version__}"
         ),
     ):
+        """
+        Initialise the GitHub API client.
+
+        :param user_agent: Custom User-Agent string for API requests.
+        """
+
         self.user_agent = user_agent
         self.cache = cache
 
@@ -32,6 +40,16 @@ def get(
         return_response: bool = False,
         use_cache: bool = True,
     ) -> t.Union[dict, list, Response]:
+        """
+        Make a GET request to the GitHub API.
+
+        :param url: The API endpoint URL.
+        :param params: Optional query parameters for the request.
+        :param return_response: If True, return the raw Response object instead of JSON data.
+        :param use_cache: If True, use cached responses when available.
+        :return: Dictionary, list, or Response object depending on the request and parameters.
+        """
+
         if use_cache and not return_response:
             cached = self.cache.get(url, params)
             if cached is not None:
@@ -58,7 +76,14 @@ def get(
     def is_valid_entity(
         self, _type: t.Literal["user", "org", "repo"], **kwargs
     ) -> bool:
-        """Validate if a GitHub entity exists."""
+        """
+        Validate whether a GitHub entity exists.
+
+        :param _type: Type of entity to validate ("user", "org", or "repo").
+        :param kwargs: Entity identifiers (username for user/org, repo_owner and repo_name for repo).
+        :return: True if the entity exists, False otherwise.
+        """
+
         try:
             type_map = {
                 "user": f"https://api.github.com/users/{kwargs.get('username')}",
@@ -86,6 +111,13 @@ def is_valid_entity(
             return False
 
     def sanitise_response(self, response: t.Union[dict, list]) -> t.Union[dict, list]:
+        """
+        Remove API URLs and null values from response data recursively.
+
+        :param response: The response data to sanitise (dict or list).
+        :return: Sanitised response with API URLs and null values removed.
+        """
+
         pattern = re.compile(r"https://api\.github\.com")
 
         if isinstance(response, list):