Update doctest env.py (#484)

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

Author: crivetimihai

mcpgateway/alembic/env.py

@@ -64,10 +64,43 @@
 # Create config object - this is the standard way in Alembic
 config = getattr(context, "config", None) or Config()
 
+
 def _inside_alembic() -> bool:
-    """Return True only when this file is running under Alembic CLI."""
+    """Detect if this module is being executed by the Alembic CLI.
+
+    This function checks whether the current execution context is within
+    an Alembic migration environment. It's used to prevent migration code
+    from running when this module is imported for other purposes (e.g.,
+    during testing or when importing models).
+
+    The detection works by checking for the presence of the '_proxy' attribute
+    on the alembic.context object. This attribute is set internally by Alembic
+    when it loads and executes the env.py file during migration operations.
+
+    Returns:
+        bool: True if running under Alembic CLI (e.g., during 'alembic upgrade',
+            'alembic downgrade', etc.), False if imported normally by Python
+            code or during testing.
+
+    Examples:
+        When running migrations::
+
+            $ alembic upgrade head
+            # _inside_alembic() returns True
+
+        When importing in tests or application code::
+
+            from mcpgateway.alembic.env import target_metadata
+            # _inside_alembic() returns False
+
+    Note:
+        This guard is crucial to prevent the migration execution code at the
+        bottom of this module from running during normal imports. Without it,
+        importing this module would attempt to run migrations every time.
+    """
     return getattr(context, "_proxy", None) is not None
 
+
 config.set_main_option("script_location", str(files("mcpgateway").joinpath("alembic")))
 
 # Interpret the config file for Python logging.
@@ -146,8 +179,9 @@ def run_migrations_online() -> None:
         with context.begin_transaction():
             context.run_migrations()
 
+
 if _inside_alembic():
     if context.is_offline_mode():
         run_migrations_offline()
     else:
-        run_migrations_online()
+        run_migrations_online()

mcpgateway/federation/forward.py

@@ -136,8 +136,9 @@ async def forward_request(
             target_gateway_id: Optional specific gateway ID for targeted forwarding
 
         Returns:
-            For targeted requests: Single gateway response
-            For broadcast requests: List of responses from all active gateways
+            Any: Single gateway response for targeted requests (when target_gateway_id
+                is provided), or list of responses from all active gateways for
+                broadcast requests (when target_gateway_id is None).
 
         Raises:
             ForwardingError: If forwarding fails due to network issues,