249 raise doctest v2 (#525)

* Improve doctest coverage

Signed-off-by: Mihai Criveti <[email protected]>

* Improve doctest coverage

Signed-off-by: Mihai Criveti <[email protected]>

---------

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

mcpgateway/cache/resource_cache.py

@@ -11,28 +11,27 @@
 - Maximum size limit with LRU eviction
 - Thread-safe operations
 
-Doctest examples
-----------------
->>> from mcpgateway.cache.resource_cache import ResourceCache
->>> cache = ResourceCache(max_size=2, ttl=1)
->>> cache.set('a', 1)
->>> cache.get('a')
-1
->>> import time
->>> time.sleep(1.2)
->>> cache.get('a') is None
-True
->>> cache.set('a', 1)
->>> cache.set('b', 2)
->>> cache.set('c', 3)  # LRU eviction
->>> sorted(cache._cache.keys())
-['b', 'c']
->>> cache.delete('b')
->>> cache.get('b') is None
-True
->>> cache.clear()
->>> cache.get('a') is None
-True
+Examples:
+    >>> from mcpgateway.cache.resource_cache import ResourceCache
+    >>> cache = ResourceCache(max_size=2, ttl=1)
+    >>> cache.set('a', 1)
+    >>> cache.get('a')
+    1
+    >>> import time
+    >>> time.sleep(1.2)
+    >>> cache.get('a') is None
+    True
+    >>> cache.set('a', 1)
+    >>> cache.set('b', 2)
+    >>> cache.set('c', 3)  # LRU eviction
+    >>> sorted(cache._cache.keys())
+    ['b', 'c']
+    >>> cache.delete('b')
+    >>> cache.get('b') is None
+    True
+    >>> cache.clear()
+    >>> cache.get('a') is None
+    True
 """
 
 # Standard
@@ -64,27 +63,27 @@ class ResourceCache:
         _cache: Cache storage
         _lock: Async lock for thread safety
 
-    Doctest:
-    >>> from mcpgateway.cache.resource_cache import ResourceCache
-    >>> cache = ResourceCache(max_size=2, ttl=1)
-    >>> cache.set('a', 1)
-    >>> cache.get('a')
-    1
-    >>> import time
-    >>> time.sleep(1.2)
-    >>> cache.get('a') is None
-    True
-    >>> cache.set('a', 1)
-    >>> cache.set('b', 2)
-    >>> cache.set('c', 3)  # LRU eviction
-    >>> sorted(cache._cache.keys())
-    ['b', 'c']
-    >>> cache.delete('b')
-    >>> cache.get('b') is None
-    True
-    >>> cache.clear()
-    >>> cache.get('a') is None
-    True
+    Examples:
+        >>> from mcpgateway.cache.resource_cache import ResourceCache
+        >>> cache = ResourceCache(max_size=2, ttl=1)
+        >>> cache.set('a', 1)
+        >>> cache.get('a')
+        1
+        >>> import time
+        >>> time.sleep(1.2)
+        >>> cache.get('a') is None
+        True
+        >>> cache.set('a', 1)
+        >>> cache.set('b', 2)
+        >>> cache.set('c', 3)  # LRU eviction
+        >>> sorted(cache._cache.keys())
+        ['b', 'c']
+        >>> cache.delete('b')
+        >>> cache.get('b') is None
+        True
+        >>> cache.clear()
+        >>> cache.get('a') is None
+        True
     """
 
     def __init__(self, max_size: int = 1000, ttl: int = 3600):
@@ -120,7 +119,7 @@ def get(self, key: str) -> Optional[Any]:
         Returns:
             Cached value or None if not found/expired
 
-        Example:
+        Examples:
             >>> from mcpgateway.cache.resource_cache import ResourceCache
             >>> cache = ResourceCache(max_size=2, ttl=1)
             >>> cache.set('a', 1)
@@ -132,7 +131,7 @@ def get(self, key: str) -> Optional[Any]:
             >>> short_cache.get('b')
             2
             >>> import time
-            >>> time.sleep(1)
+            >>> time.sleep(1.2)
             >>> short_cache.get('b') is None
             True
         """
@@ -159,12 +158,12 @@ def set(self, key: str, value: Any) -> None:
             key: Cache key
             value: Value to cache
 
-        Doctest:
-        >>> from mcpgateway.cache.resource_cache import ResourceCache
-        >>> cache = ResourceCache(max_size=2, ttl=1)
-        >>> cache.set('a', 1)
-        >>> cache.get('a')
-        1
+        Examples:
+            >>> from mcpgateway.cache.resource_cache import ResourceCache
+            >>> cache = ResourceCache(max_size=2, ttl=1)
+            >>> cache.set('a', 1)
+            >>> cache.get('a')
+            1
         """
         now = time.time()
 
@@ -184,27 +183,27 @@ def delete(self, key: str) -> None:
         Args:
             key: Cache key to delete
 
-        Doctest:
-        >>> from mcpgateway.cache.resource_cache import ResourceCache
-        >>> cache = ResourceCache()
-        >>> cache.set('a', 1)
-        >>> cache.delete('a')
-        >>> cache.get('a') is None
-        True
+        Examples:
+            >>> from mcpgateway.cache.resource_cache import ResourceCache
+            >>> cache = ResourceCache()
+            >>> cache.set('a', 1)
+            >>> cache.delete('a')
+            >>> cache.get('a') is None
+            True
         """
         self._cache.pop(key, None)
 
     def clear(self) -> None:
         """
         Clear all cached entries.
 
-        Doctest:
-        >>> from mcpgateway.cache.resource_cache import ResourceCache
-        >>> cache = ResourceCache()
-        >>> cache.set('a', 1)
-        >>> cache.clear()
-        >>> cache.get('a') is None
-        True
+        Examples:
+            >>> from mcpgateway.cache.resource_cache import ResourceCache
+            >>> cache = ResourceCache()
+            >>> cache.set('a', 1)
+            >>> cache.clear()
+            >>> cache.get('a') is None
+            True
         """
         self._cache.clear()
 

mcpgateway/main.py

@@ -306,13 +306,18 @@ async def database_exception_handler(_request: Request, exc: IntegrityError):
         JSONResponse: A 409 Conflict response with formatted database error details.
 
     Examples:
-        >>> # This handler is automatically invoked when database constraints are violated
-        >>> # For example, trying to create a duplicate tool name:
-        >>> # POST /tools with duplicate name would trigger this handler
-        >>> # Response format:
-        >>> # {
-        >>> #   "detail": "Unique constraint violation: Key (name)=(existing_tool) already exists"
-        >>> # }
+        >>> from sqlalchemy.exc import IntegrityError
+        >>> from fastapi import Request
+        >>> import asyncio
+        >>>
+        >>> # Create a mock integrity error
+        >>> mock_error = IntegrityError("statement", {}, Exception("duplicate key"))
+        >>> result = asyncio.run(database_exception_handler(None, mock_error))
+        >>> result.status_code
+        409
+        >>> # Verify ErrorFormatter.format_database_error is called
+        >>> hasattr(result, 'body')
+        True
     """
     return JSONResponse(status_code=409, content=ErrorFormatter.format_database_error(exc))
 
@@ -519,13 +524,19 @@ async def invalidate_resource_cache(uri: Optional[str] = None) -> None:
 
     Examples:
         >>> import asyncio
-        >>> # Test with specific URI
-        >>> result = asyncio.run(invalidate_resource_cache("/test/uri"))
-        >>> result is None
+        >>> # Test clearing specific URI from cache
+        >>> resource_cache.set("/test/resource", {"content": "test data"})
+        >>> resource_cache.get("/test/resource") is not None
+        True
+        >>> asyncio.run(invalidate_resource_cache("/test/resource"))
+        >>> resource_cache.get("/test/resource") is None
         True
-        >>> # Test with no URI (clear all)
-        >>> result = asyncio.run(invalidate_resource_cache())
-        >>> result is None
+        >>>
+        >>> # Test clearing entire cache
+        >>> resource_cache.set("/resource1", {"content": "data1"})
+        >>> resource_cache.set("/resource2", {"content": "data2"})
+        >>> asyncio.run(invalidate_resource_cache())
+        >>> resource_cache.get("/resource1") is None and resource_cache.get("/resource2") is None
         True
     """
     if uri: