Added doctest to files in mcpgateway folder (#445)

Signed-off-by: Manav Gupta <[email protected]>

Author: manavgup

mcpgateway/config.py

@@ -53,7 +53,7 @@
 import logging
 from pathlib import Path
 import re
-from typing import Annotated, Any, Dict, List, Optional, Set, Union, ClassVar
+from typing import Annotated, Any, ClassVar, Dict, List, Optional, Set, Union
 
 # Third-Party
 from fastapi import HTTPException
@@ -410,7 +410,13 @@ def validate_transport(self) -> None:
             raise ValueError(f"Invalid transport type. Must be one of: {valid_types}")
 
     def validate_database(self) -> None:
-        """Validate database configuration."""
+        """Validate database configuration.
+
+        Examples:
+            >>> from mcpgateway.config import Settings
+            >>> s = Settings(database_url='sqlite:///./test.db')
+            >>> s.validate_database()  # Should create the directory if it does not exist
+        """
         if self.database_url.startswith("sqlite"):
             db_path = Path(self.database_url.replace("sqlite:///", ""))
             db_dir = db_path.parent
@@ -469,6 +475,18 @@ def extract_using_jq(data, jq_filter=""):
 
     Returns:
         The result of applying the jq filter to the input data.
+
+    Examples:
+        >>> extract_using_jq('{"a": 1, "b": 2}', '.a')
+        [1]
+        >>> extract_using_jq({'a': 1, 'b': 2}, '.b')
+        [2]
+        >>> extract_using_jq('[{"a": 1}, {"a": 2}]', '.[].a')
+        [1, 2]
+        >>> extract_using_jq('not a json', '.a')
+        ['Invalid JSON string provided.']
+        >>> extract_using_jq({'a': 1}, '')
+        {'a': 1}
     """
     if jq_filter == "":
         return data
@@ -513,6 +531,16 @@ def jsonpath_modifier(data: Any, jsonpath: str = "$[*]", mappings: Optional[Dict
 
     Raises:
         HTTPException: If there's an error parsing or executing the JSONPath expressions.
+
+    Examples:
+        >>> jsonpath_modifier({'a': 1, 'b': 2}, '$.a')
+        [1]
+        >>> jsonpath_modifier([{'a': 1}, {'a': 2}], '$[*].a')
+        [1, 2]
+        >>> jsonpath_modifier({'a': {'b': 2}}, '$.a.b')
+        [2]
+        >>> jsonpath_modifier({'a': 1}, '$.b')
+        []
     """
     if not jsonpath:
         jsonpath = "$[*]"

mcpgateway/db.py

@@ -63,7 +63,6 @@
 from mcpgateway.utils.db_isready import wait_for_db_ready
 from mcpgateway.validators import SecurityValidator
 
-
 # ---------------------------------------------------------------------------
 # 1. Parse the URL so we can inspect backend ("postgresql", "sqlite", ...)
 #    and the specific driver ("psycopg2", "asyncpg", empty string = default).
@@ -121,6 +120,12 @@ def utc_now() -> datetime:
     Returns:
         datetime: A timezone-aware `datetime` whose `tzinfo` is
         `datetime.timezone.utc`.
+
+    Examples:
+        >>> from mcpgateway.db import utc_now
+        >>> now = utc_now()
+        >>> now.tzinfo is not None
+        True
     """
     return datetime.now(timezone.utc)
 

mcpgateway/schemas.py

@@ -53,9 +53,13 @@ def to_camel_case(s: str) -> str:
     Returns:
         str: The string converted to camelCase.
 
-    Example:
+    Examples:
         >>> to_camel_case("hello_world_example")
         'helloWorldExample'
+        >>> to_camel_case("alreadyCamel")
+        'alreadyCamel'
+        >>> to_camel_case("")
+        ''
     """
     return "".join(word.capitalize() if i else word for i, word in enumerate(s.split("_")))
 
@@ -70,7 +74,8 @@ def encode_datetime(v: datetime) -> str:
     Returns:
         str: The ISO 8601 formatted string representation of the datetime object.
 
-    Example:
+    Examples:
+        >>> from datetime import datetime
         >>> encode_datetime(datetime(2023, 5, 22, 14, 30, 0))
         '2023-05-22T14:30:00'
     """
@@ -107,6 +112,14 @@ def to_dict(self, use_alias: bool = False) -> Dict[str, Any]:
         Returns:
             Dict[str, Any]: A dictionary where keys are field names and values are corresponding field values,
                              with any nested models recursively converted to dictionaries.
+
+        Examples:
+            >>> class ExampleModel(BaseModelWithConfigDict):
+            ...     foo: int
+            ...     bar: str
+            >>> m = ExampleModel(foo=1, bar='baz')
+            >>> m.to_dict()
+            {'foo': 1, 'bar': 'baz'}
         """
         output = {}
         for key, value in self.dict(by_alias=use_alias).items():
@@ -294,6 +307,15 @@ def validate_name(cls, v: str) -> str:
 
         Returns:
             str: Value if validated as safe
+
+        Examples:
+            >>> from mcpgateway.schemas import ToolCreate
+            >>> ToolCreate.validate_name('valid_tool')
+            'valid_tool'
+            >>> ToolCreate.validate_name('Invalid Tool!')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         return SecurityValidator.validate_tool_name(v)
 
@@ -307,6 +329,15 @@ def validate_url(cls, v: str) -> str:
 
         Returns:
             str: Value if validated as safe
+
+        Examples:
+            >>> from mcpgateway.schemas import ToolCreate
+            >>> ToolCreate.validate_url('https://example.com')
+            'https://example.com'
+            >>> ToolCreate.validate_url('ftp://example.com')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         return SecurityValidator.validate_url(v, "Tool URL")
 
@@ -323,6 +354,15 @@ def validate_description(cls, v: Optional[str]) -> Optional[str]:
 
         Raises:
             ValueError: When value is unsafe
+
+        Examples:
+            >>> from mcpgateway.schemas import ToolCreate
+            >>> ToolCreate.validate_description('A safe description')
+            'A safe description'
+            >>> ToolCreate.validate_description('x' * 5000)
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if v is None:
             return v
@@ -340,6 +380,15 @@ def validate_json_fields(cls, v: Dict[str, Any]) -> Dict[str, Any]:
 
         Returns:
             dict: Value if validated as safe
+
+        Examples:
+            >>> from mcpgateway.schemas import ToolCreate
+            >>> ToolCreate.validate_json_fields({'a': 1})
+            {'a': 1}
+            >>> ToolCreate.validate_json_fields({'a': {'b': {'c': {'d': {'e': {'f': {'g': {'h': {'i': {'j': {'k': 1}}}}}}}}}}})
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         SecurityValidator.validate_json_depth(v)
         return v

mcpgateway/validators.py

@@ -112,6 +112,14 @@ def validate_name(cls, value: str, field_name: str = "Name") -> str:
 
         Raises:
             ValueError: When input is not acceptable
+
+        Examples:
+            >>> SecurityValidator.validate_name('valid_name')
+            'valid_name'
+            >>> SecurityValidator.validate_name('Invalid Name!')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if not value:
             raise ValueError(f"{field_name} cannot be empty")
@@ -142,6 +150,14 @@ def validate_identifier(cls, value: str, field_name: str) -> str:
 
         Raises:
             ValueError: When input is not acceptable
+
+        Examples:
+            >>> SecurityValidator.validate_identifier('valid_id', 'ID')
+            'valid_id'
+            >>> SecurityValidator.validate_identifier('Invalid/ID', 'ID')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if not value:
             raise ValueError(f"{field_name} cannot be empty")
@@ -172,6 +188,14 @@ def validate_uri(cls, value: str, field_name: str = "URI") -> str:
 
         Raises:
             ValueError: When input is not acceptable
+
+        Examples:
+            >>> SecurityValidator.validate_uri('/valid/uri', 'URI')
+            '/valid/uri'
+            >>> SecurityValidator.validate_uri('..', 'URI')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if not value:
             raise ValueError(f"{field_name} cannot be empty")
@@ -203,6 +227,14 @@ def validate_tool_name(cls, value: str) -> str:
 
         Raises:
             ValueError: When input is not acceptable
+
+        Examples:
+            >>> SecurityValidator.validate_tool_name('tool_1')
+            'tool_1'
+            >>> SecurityValidator.validate_tool_name('1tool')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if not value:
             raise ValueError("Tool name cannot be empty")
@@ -252,17 +284,25 @@ def validate_template(cls, value: str) -> str:
 
     @classmethod
     def validate_url(cls, value: str, field_name: str = "URL") -> str:
-        """Validate URL format and ensure safe display
+        """Validate URLs for allowed schemes and safe display
 
         Args:
             value (str): Value to validate
-            field_name (str): Name of the field being validated
+            field_name (str): Name of field being validated
 
         Returns:
             str: Value if acceptable
 
         Raises:
             ValueError: When input is not acceptable
+
+        Examples:
+            >>> SecurityValidator.validate_url('https://example.com')
+            'https://example.com'
+            >>> SecurityValidator.validate_url('ftp://example.com')
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
         if not value:
             raise ValueError(f"{field_name} cannot be empty")
@@ -294,17 +334,25 @@ def validate_url(cls, value: str, field_name: str = "URL") -> str:
 
     @classmethod
     def validate_json_depth(cls, obj: Any, max_depth: int = None, current_depth: int = 0) -> None:
-        """Check JSON structure doesn't exceed maximum depth
+        """Validate the maximum depth of a JSON object
 
         Args:
-            obj (Any): JSON object to validate
-            max_depth (int): Max allowed depth for a JSON
-            current_depth (int): Depth of nested structure in JSON
+            obj (Any): The JSON object to check
+            max_depth (int, optional): Maximum allowed depth. Defaults to class setting.
+            current_depth (int): Used for recursion, do not set manually.
 
         Raises:
-            ValueError: When input is not acceptable
+            ValueError: If the object exceeds the maximum allowed depth
+
+        Examples:
+            >>> SecurityValidator.validate_json_depth({'a': {'b': {'c': 1}}}, max_depth=3)
+            >>> SecurityValidator.validate_json_depth({'a': {'b': {'c': {'d': 1}}}}, max_depth=3)
+            Traceback (most recent call last):
+                ...
+            ValueError: ...
         """
-        max_depth = max_depth or cls.MAX_JSON_DEPTH
+        if max_depth is None:
+            max_depth = cls.MAX_JSON_DEPTH
 
         if current_depth > max_depth:
             raise ValueError(f"JSON structure exceeds maximum depth of {max_depth}")