249 raise doctest (#524)

* Update docstring for wrapper.py

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

* Update cli.py doctest

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

* Update doctest for translate.py

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

* Update doctest for gateway_service.py

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

* Update doctest for retry_manager.py

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

* Update doctest for db.py

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

* Update doctest for resource_cache.py

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

* Cleanup coverage annotated files

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

* Improve coverage for verify_credentials.py

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

---------

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

Author: crivetimihai

Makefile

@@ -38,7 +38,7 @@ FILES_TO_CLEAN := .coverage coverage.xml mcp.prof mcp.pstats \
                   $(DOCS_DIR)/docs/test/sbom.md \
                   $(DOCS_DIR)/docs/test/{unittest,full,index,test}.md \
 				  $(DOCS_DIR)/docs/images/coverage.svg $(LICENSES_MD) $(METRICS_MD) \
-                  *.db *.sqlite *.sqlite3 mcp.db-journal
+                  *.db *.sqlite *.sqlite3 mcp.db-journal *.py,cover
 
 COVERAGE_DIR ?= $(DOCS_DIR)/docs/coverage
 LICENSES_MD  ?= $(DOCS_DIR)/docs/test/licenses.md
@@ -193,6 +193,8 @@ clean:
 	@rm -f $(FILES_TO_CLEAN)
 	@# Delete Python bytecode
 	@find . -name '*.py[cod]' -delete
+	@# Delete coverage annotated files
+	@find . -name '*.py,cover' -delete
 	@echo "✅  Clean complete."
 
 
@@ -202,7 +204,7 @@ clean:
 # help: 🧪 TESTING
 # help: smoketest            - Run smoketest.py --verbose (build container, add MCP server, test endpoints)
 # help: test                 - Run unit tests with pytest
-# help: coverage             - Run tests with coverage, emit md/HTML/XML + badge
+# help: coverage             - Run tests with coverage, emit md/HTML/XML + badge, generate annotated files
 # help: htmlcov              - (re)build just the HTML coverage report into docs
 # help: test-curl            - Smoke-test API endpoints with curl script
 # help: pytest-examples      - Run README / examples through pytest-examples
@@ -243,7 +245,9 @@ coverage:
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage html -d $(COVERAGE_DIR) --include=app/*"
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage xml"
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage-badge -fo $(DOCS_DIR)/docs/images/coverage.svg"
-	@echo "✅  Coverage artefacts: md, HTML in $(COVERAGE_DIR), XML & badge ✔"
+	@echo "🔍  Generating annotated coverage files..."
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage annotate -d ."
+	@echo "✅  Coverage artefacts: md, HTML in $(COVERAGE_DIR), XML, badge & annotated files (.py,cover) ✔"
 
 htmlcov:
 	@echo "📊  Generating HTML coverage report..."

mcpgateway/cache/resource_cache.py

@@ -19,7 +19,7 @@
 >>> cache.get('a')
 1
 >>> import time
->>> time.sleep(1.1)
+>>> time.sleep(1.2)
 >>> cache.get('a') is None
 True
 >>> cache.set('a', 1)
@@ -71,7 +71,7 @@ class ResourceCache:
     >>> cache.get('a')
     1
     >>> import time
-    >>> time.sleep(1.1)
+    >>> time.sleep(1.2)
     >>> cache.get('a') is None
     True
     >>> cache.set('a', 1)

mcpgateway/cli.py

@@ -72,6 +72,14 @@ def _needs_app(arg_list: List[str]) -> bool:
 
     Returns:
         bool: Returns *True* when the CLI invocation has *no* positional APP path
+
+    Examples:
+        >>> _needs_app([])
+        True
+        >>> _needs_app(["--reload"])
+        True
+        >>> _needs_app(["myapp.main:app"])
+        False
     """
 
     return len(arg_list) == 0 or arg_list[0].startswith("-")
@@ -85,6 +93,14 @@ def _insert_defaults(raw_args: List[str]) -> List[str]:
 
     Returns:
         List[str]: List of arguments
+
+    Examples:
+        >>> result = _insert_defaults([])
+        >>> result[0]
+        'mcpgateway.main:app'
+        >>> result = _insert_defaults(["myapp.main:app", "--reload"])
+        >>> result[0]
+        'myapp.main:app'
     """
 
     args = list(raw_args)  # shallow copy - we'll mutate this
@@ -109,7 +125,15 @@ def _insert_defaults(raw_args: List[str]) -> List[str]:
 
 
 def main() -> None:  # noqa: D401 - imperative mood is fine here
-    """Entry point for the *mcpgateway* console script (delegates to Uvicorn)."""
+    """Entry point for the *mcpgateway* console script (delegates to Uvicorn).
+
+    Processes command line arguments, handles version requests, and forwards
+    all other arguments to Uvicorn with sensible defaults injected.
+
+    Environment Variables:
+        MCG_HOST: Default host (default: "127.0.0.1")
+        MCG_PORT: Default port (default: "4444")
+    """
 
     # Check for version flag
     if "--version" in sys.argv or "-V" in sys.argv:

mcpgateway/db.py

@@ -17,6 +17,8 @@
     >>> from mcpgateway.db import connect_args
     >>> isinstance(connect_args, dict)
     True
+    >>> 'keepalives' in connect_args or 'check_same_thread' in connect_args or len(connect_args) == 0
+    True
 """
 
 # Standard
@@ -126,6 +128,10 @@ def utc_now() -> datetime:
         >>> now = utc_now()
         >>> now.tzinfo is not None
         True
+        >>> str(now.tzinfo)
+        'UTC'
+        >>> isinstance(now, datetime)
+        True
     """
     return datetime.now(timezone.utc)
 
@@ -624,6 +630,28 @@ def content(self) -> ResourceContent:
 
         Raises:
             ValueError: If the resource has no content available.
+
+        Examples:
+            >>> resource = Resource(uri="test://example", name="test")
+            >>> resource.text_content = "Hello, World!"
+            >>> content = resource.content
+            >>> content.text
+            'Hello, World!'
+            >>> content.type
+            'resource'
+
+            >>> binary_resource = Resource(uri="test://binary", name="binary")
+            >>> binary_resource.binary_content = b"\\x00\\x01\\x02"
+            >>> binary_content = binary_resource.content
+            >>> binary_content.blob
+            b'\\x00\\x01\\x02'
+
+            >>> empty_resource = Resource(uri="test://empty", name="empty")
+            >>> try:
+            ...     empty_resource.content
+            ... except ValueError as e:
+            ...     str(e)
+            'Resource has no content'
         """
 
         if self.text_content is not None:
@@ -801,6 +829,24 @@ def validate_arguments(self, args: Dict[str, str]) -> None:
         Raises:
             ValueError: If the arguments do not conform to the schema.
 
+        Examples:
+            >>> prompt = Prompt(
+            ...     name="test_prompt",
+            ...     template="Hello {name}",
+            ...     argument_schema={
+            ...         "type": "object",
+            ...         "properties": {
+            ...             "name": {"type": "string"}
+            ...         },
+            ...         "required": ["name"]
+            ...     }
+            ... )
+            >>> prompt.validate_arguments({"name": "Alice"})  # No exception
+            >>> try:
+            ...     prompt.validate_arguments({"age": 25})  # Missing required field
+            ... except ValueError as e:
+            ...     "name" in str(e)
+            True
         """
         try:
             jsonschema.validate(args, self.argument_schema)
@@ -980,6 +1026,18 @@ def failure_rate(self) -> float:
 
         Returns:
             float: The failure rate as a value between 0 and 1.
+
+        Examples:
+            >>> tool = Tool(original_name="test_tool", original_name_slug="test-tool", input_schema={})
+            >>> tool.failure_rate  # No metrics yet
+            0.0
+            >>> tool.metrics = [
+            ...     ToolMetric(tool_id=tool.id, response_time=1.0, is_success=True),
+            ...     ToolMetric(tool_id=tool.id, response_time=2.0, is_success=False),
+            ...     ToolMetric(tool_id=tool.id, response_time=1.5, is_success=True),
+            ... ]
+            >>> tool.failure_rate
+            0.3333333333333333
         """
         total: int = self.execution_count
         if total == 0:
@@ -1225,6 +1283,16 @@ def get_db():
 
     Yields:
         SessionLocal: A SQLAlchemy database session.
+
+    Examples:
+        >>> from mcpgateway.db import get_db
+        >>> gen = get_db()
+        >>> db = next(gen)
+        >>> hasattr(db, 'query')
+        True
+        >>> hasattr(db, 'commit')
+        True
+        >>> gen.close()
     """
     db = SessionLocal()
     try:

mcpgateway/main.py

@@ -267,19 +267,22 @@ async def validation_exception_handler(_request: Request, exc: ValidationError):
                       validation error details.
 
     Examples:
-        >>> # This handler is automatically invoked by FastAPI when a ValidationError occurs
-        >>> # For example, when request data fails Pydantic model validation:
-        >>> # POST /tools with invalid data would trigger this handler
-        >>> # Response format:
-        >>> # {
-        >>> #   "detail": [
-        >>> #     {
-        >>> #       "loc": ["body", "name"],
-        >>> #       "msg": "field required",
-        >>> #       "type": "value_error.missing"
-        >>> #     }
-        >>> #   ]
-        >>> # }
+        >>> from pydantic import ValidationError, BaseModel
+        >>> from fastapi import Request
+        >>> import asyncio
+        >>>
+        >>> class TestModel(BaseModel):
+        ...     name: str
+        ...     age: int
+        >>>
+        >>> # Create a validation error
+        >>> try:
+        ...     TestModel(name="", age="invalid")
+        ... except ValidationError as e:
+        ...     # Test our handler
+        ...     result = asyncio.run(validation_exception_handler(None, e))
+        ...     result.status_code
+        422
     """
     return JSONResponse(status_code=422, content=ErrorFormatter.format_validation_error(exc))
 
@@ -445,6 +448,22 @@ def get_db():
 
     Ensures:
         The database session is closed after the request completes, even in the case of an exception.
+
+    Examples:
+        >>> # Test that get_db returns a generator
+        >>> db_gen = get_db()
+        >>> hasattr(db_gen, '__next__')
+        True
+        >>> # Test cleanup happens
+        >>> try:
+        ...     db = next(db_gen)
+        ...     type(db).__name__
+        ... finally:
+        ...     try:
+        ...         next(db_gen)
+        ...     except StopIteration:
+        ...         pass  # Expected - generator cleanup
+        'Session'
     """
     db = SessionLocal()
     try:
@@ -454,8 +473,7 @@ def get_db():
 
 
 def require_api_key(api_key: str) -> None:
-    """
-    Validates the provided API key.
+    """Validates the provided API key.
 
     This function checks if the provided API key matches the expected one
     based on the settings. If the validation fails, it raises an HTTPException
@@ -466,6 +484,22 @@ def require_api_key(api_key: str) -> None:
 
     Raises:
         HTTPException: If the API key is invalid, a 401 Unauthorized error is raised.
+
+    Examples:
+        >>> from mcpgateway.config import settings
+        >>> settings.auth_required = True
+        >>> settings.basic_auth_user = "admin"
+        >>> settings.basic_auth_password = "secret"
+        >>>
+        >>> # Valid API key
+        >>> require_api_key("admin:secret")  # Should not raise
+        >>>
+        >>> # Invalid API key
+        >>> try:
+        ...     require_api_key("wrong:key")
+        ... except HTTPException as e:
+        ...     e.status_code
+        401
     """
     if settings.auth_required:
         expected = f"{settings.basic_auth_user}:{settings.basic_auth_password}"
@@ -482,6 +516,17 @@ async def invalidate_resource_cache(uri: Optional[str] = None) -> None:
 
     Args:
         uri (Optional[str]): The URI of the resource to invalidate from the cache. If None, the entire cache is cleared.
+
+    Examples:
+        >>> import asyncio
+        >>> # Test with specific URI
+        >>> result = asyncio.run(invalidate_resource_cache("/test/uri"))
+        >>> result is None
+        True
+        >>> # Test with no URI (clear all)
+        >>> result = asyncio.run(invalidate_resource_cache())
+        >>> result is None
+        True
     """
     if uri:
         resource_cache.delete(uri)