clear cache

Author: Carreau

tools/last_user_activity.py

@@ -1,5 +1,7 @@
-"""
-This tools find all users in multiple organizations and print their last activity date.
+"""GitHub Organization Activity Tracker
+
+This module tracks and reports the last activity of members across GitHub organizations.
+It implements disk-based caching to minimize API requests and respect rate limits.
 """
 
 import os
@@ -13,7 +15,8 @@
 import diskcache
 import json
 import pathlib
-from typing import Optional
+from typing import Optional, List, Dict
+import argparse
 
 orgs = [
     "binder-examples",
@@ -48,8 +51,30 @@
 CACHE_DIR = "github_cache"
 cache = diskcache.Cache(CACHE_DIR)
 
-async def get_org_members(session: aiohttp.ClientSession, org: str) -> list[dict]:
-    """Get all members for an organization with persistent caching"""
+async def get_org_members(session: aiohttp.ClientSession, org: str) -> List[Dict]:
+    """Fetch all members of a GitHub organization with caching.
+
+    Parameters
+    ----------
+    session : aiohttp.ClientSession
+        The HTTP session to use for requests
+    org : str
+        The name of the GitHub organization
+
+    Returns
+    -------
+    List[Dict]
+        A list of dictionaries containing member information.
+        Each dictionary contains at least:
+        - 'login': str, the username
+        - 'id': int, the user ID
+        - 'type': str, usually 'User'
+
+    Notes
+    -----
+    Results are cached for 24 hours to minimize API requests.
+    Pagination is handled automatically (100 items per page).
+    """
     cache_key = f"org_members_{org}"
     if cache_key in cache:
         return cache[cache_key]
@@ -68,11 +93,30 @@ async def get_org_members(session: aiohttp.ClientSession, org: str) -> list[dict
 
             members.extend(page_members)
 
-    cache.set(cache_key, members, expire=3600 * 24)  # Cache for 24 hours
+    cache.set(cache_key, members, expire=3600 * 24)
     return members
 
 async def get_user_activity(session: aiohttp.ClientSession, username: str) -> Optional[datetime]:
-    """Get the last activity date for a user with persistent caching"""
+    """Fetch the last public activity date for a GitHub user.
+
+    Parameters
+    ----------
+    session : aiohttp.ClientSession
+        The HTTP session to use for requests
+    username : str
+        The GitHub username to check
+
+    Returns
+    -------
+    Optional[datetime]
+        The datetime of the user's last public activity,
+        or None if no activity was found or an error occurred
+
+    Notes
+    -----
+    Results are cached for 24 hours to minimize API requests.
+    Only public events are considered for activity tracking.
+    """
     cache_key = f"user_activity_{username}"
     if cache_key in cache:
         return cache[cache_key]
@@ -83,14 +127,42 @@ async def get_user_activity(session: aiohttp.ClientSession, username: str) -> Op
             events = await response.json()
             if events:
                 last_activity = datetime.fromisoformat(events[0]["created_at"].replace('Z', '+00:00'))
-                cache.set(cache_key, last_activity, expire=3600 * 24)  # Cache for 24 hours
+                cache.set(cache_key, last_activity, expire=3600 * 24)
                 return last_activity
     return None
 
+def clear_cache() -> None:
+    """Clear the disk cache.
+    
+    Removes all cached data, forcing fresh API requests on next run.
+    
+    Notes
+    -----
+    This is useful when you want to ensure you're getting the latest data
+    or if the cache becomes corrupted.
+    """
+    if pathlib.Path(CACHE_DIR).exists():
+        cache.clear()
+        print("[green]Cache cleared successfully[/green]")
+    else:
+        print("[yellow]No cache directory found[/yellow]")
+
 async def main():
+    """Main execution function.
+    
+    Fetches and displays the last activity for all members across specified organizations.
+    Uses disk caching to minimize API requests and handles GitHub API rate limits.
+
+    Notes
+    -----
+    The results are displayed organization by organization, with members sorted
+    by their last activity date (most recent first).
+    """
     # Add cache info at start
-    if pathlib.Path(CACHE_DIR).exists():
-        print(f"[blue]Using cache directory: {CACHE_DIR}[/blue]")
+    cache_path = pathlib.Path(CACHE_DIR)
+    if cache_path.exists():
+        cache_size = sum(f.stat().st_size for f in cache_path.rglob('*') if f.is_file())
+        print(f"[blue]Using cache directory: {CACHE_DIR} ({cache_size / 1024 / 1024:.1f} MB)[/blue]")
     else:
         print("[yellow]Creating new cache directory[/yellow]")
 
@@ -139,4 +211,11 @@ async def main():
             print(f"{username:<20}: Last activity {last_activity_ago} in orgs: {orgs_str}")
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="GitHub Organization Activity Tracker")
+    parser.add_argument('--clear-cache', action='store_true', help='Clear the cache before running')
+    args = parser.parse_args()
+
+    if args.clear_cache:
+        clear_cache()
+    
     asyncio.run(main())