Merge pull request #1444 from tisnik/lcore-1608-improve-docstrings-in-lcore-repository

LCORE-1608: improve docstrings in LCORE repository

Author: tisnik

dev-tools/mcp-mock-server/test_mock_mcp_server.py

@@ -1,5 +1,4 @@
-"""
-Pytest tests for the MCP Mock Server.
+"""Pytest tests for the MCP Mock Server.
 
 This test suite verifies the mock server functionality without requiring
 the full Lightspeed Stack infrastructure.

src/app/database.py

@@ -72,14 +72,17 @@ def _create_sqlite_engine(config: SQLiteDatabaseConfiguration, **kwargs: Any) ->
     """Create SQLite database engine.
 
     Parameters:
+    ----------
         config (SQLiteDatabaseConfiguration): Configuration containing
         `db_path` for the SQLite file.
         **kwargs: Additional keyword arguments forwarded to SQLAlchemy's create_engine.
 
     Returns:
+    -------
         Engine: A SQLAlchemy Engine bound to the specified SQLite database file.
 
     Raises:
+    ------
         FileNotFoundError: If the parent directory of `config.db_path` does not exist.
         RuntimeError: If engine creation fails.
     """
@@ -107,14 +110,17 @@ def _create_postgres_engine(
     SSL.
 
     Parameters:
+    ----------
         config (PostgreSQLDatabaseConfiguration): Connection and database
         settings (user, password, host, port, db, ssl/gss options, optional
         namespace and ca_cert_path).
 
     Returns:
+    -------
         Engine: A SQLAlchemy Engine connected to the configured PostgreSQL database.
 
     Raises:
+    ------
         RuntimeError: If engine creation fails or if creating the specified schema fails.
     """
     postgres_url = (

src/app/endpoints/feedback.py

@@ -149,10 +149,12 @@ def store_feedback(user_id: str, feedback: dict) -> None:
     configured local storage directory.
 
     Parameters:
+    ----------
         user_id (str): Unique identifier of the user submitting feedback.
         feedback (dict): Feedback data to be stored, merged with user ID and timestamp.
 
     Raises:
+    ------
         HTTPException: If writing the feedback file fails (HTTP 500).
     """
     logger.debug("Storing feedback for user %s", user_id)

src/app/endpoints/query.py

@@ -276,11 +276,13 @@ async def retrieve_response(
     This function processes the prepared request and returns the LLM response.
 
     Parameters:
+    ----------
         client: The AsyncLlamaStackClient to use for the request.
         responses_params: The Responses API parameters.
         moderation_result: The moderation result.
 
     Returns:
+    -------
         TurnSummary: Summary of the LLM response content
     """
     response: Optional[OpenAIResponseObject] = None

src/app/endpoints/rags.py

@@ -112,10 +112,12 @@ def _resolve_rag_id_to_vector_db_id(rag_id: str, byok_rags: list[ByokRag]) -> st
     (assuming it is already a llama-stack vector store ID).
 
     Parameters:
+    ----------
         rag_id: The user-provided RAG identifier.
         byok_rags: List of BYOK RAG config entries.
 
     Returns:
+    -------
         The llama-stack vector_db_id, or the original ID if no mapping found.
     """
     for brag in byok_rags:

src/app/endpoints/stream_interrupt.py

@@ -49,14 +49,17 @@ async def stream_interrupt_endpoint_handler(
     """Interrupt an in-progress streaming query by request identifier.
 
     Parameters:
+    ----------
         interrupt_request: Request payload containing the stream request ID.
         auth: Auth context tuple resolved from the authentication dependency.
         registry: Stream interrupt registry dependency used to cancel streams.
 
     Returns:
+    -------
         StreamingInterruptResponse: Confirmation payload when interruption succeeds.
 
     Raises:
+    ------
         HTTPException: If no active stream for the given request ID can be interrupted.
     """
     user_id, _, _, _ = auth

src/app/endpoints/streaming_query.py

@@ -438,6 +438,7 @@ async def _persist_interrupted_turn(
     and updated when ready.
 
     Parameters:
+    ----------
         context: The response generator context.
         responses_params: The Responses API parameters.
         turn_summary: TurnSummary with llm_response already set to the
@@ -507,11 +508,13 @@ def _register_interrupt_callback(
     both persist the same turn.
 
     Parameters:
+    ----------
         context: The response generator context.
         responses_params: The Responses API parameters.
         turn_summary: TurnSummary populated during streaming.
 
     Returns:
+    -------
         A mutable list ``[False]`` used as a persist-done guard; the
         caller should check ``guard[0]`` before persisting and set
         it to ``True`` afterwards.
@@ -877,6 +880,7 @@ def stream_http_error_event(
     Args:
         error: An AbstractErrorResponse instance representing the error.
         media_type: The media type for the response format. Defaults to MEDIA_TYPE_JSON if None.
+
     Returns:
         str: A Server-Sent Events (SSE) formatted error message containing
             the serialized error details.
@@ -903,9 +907,11 @@ def format_stream_data(d: dict) -> str:
     Create a response generator function for Responses API streaming.
 
     Parameters:
+    ----------
         d (dict): The data to be formatted as an SSE event.
 
     Returns:
+    -------
         str: The formatted SSE data string.
     """
     data = json.dumps(d)
@@ -920,11 +926,13 @@ def stream_start_event(conversation_id: str, request_id: str) -> str:
     use the request ID to issue an interrupt if needed.
 
     Parameters:
+    ----------
         conversation_id (str): Unique identifier for the conversation.
         request_id (str): Unique SUID for this streaming request,
             returned to the client for interrupt support.
 
     Returns:
+    -------
         str: SSE-formatted string representing the start event.
     """
     return format_stream_data(
@@ -946,9 +954,11 @@ def stream_interrupted_event(request_id: str) -> str:
     from an unexpected connection drop.
 
     Parameters:
+    ----------
         request_id (str): Unique identifier for the interrupted request.
 
     Returns:
+    -------
         str: SSE-formatted string representing the interrupted event.
     """
     return format_stream_data(
@@ -974,12 +984,14 @@ def stream_end_event(
     including referenced document metadata and token usage information.
 
     Parameters:
+    ----------
         token_usage (TokenCounter): Token usage information.
         available_quotas (dict[str, int]): Available quotas for the user.
         referenced_documents (list[ReferencedDocument]): List of referenced documents.
         media_type (str): The media type for the response format.
 
     Returns:
+    -------
         str: A Server-Sent Events (SSE) formatted string
         representing the end of the data stream.
     """

src/app/endpoints/tools.py

@@ -43,10 +43,12 @@ def _input_schema_to_parameters(
     the flat parameter list format used by the tools endpoint response.
 
     Parameters:
+    ----------
         schema: JSON Schema dict with ``properties`` and ``required`` keys,
                 or ``None`` if the tool has no parameters.
 
     Returns:
+    -------
         A list of parameter dicts, each containing ``name``, ``description``,
         ``parameter_type``, ``required``, and ``default`` keys.
     """

src/app/routers.py

@@ -41,6 +41,7 @@ def include_routers(app: FastAPI) -> None:
     authorized, metrics) are mounted without a version prefix.
 
     Parameters:
+    ----------
         app (FastAPI): The FastAPI application to which routers will be attached.
     """
     app.include_router(root.router)

src/authentication/__init__.py

@@ -24,14 +24,17 @@ def get_auth_dependency(
     """Select the configured authentication dependency interface.
 
     Parameters:
+    ----------
         virtual_path (str): Virtual path passed to the authentication
                             dependency when it is constructed.
 
     Returns:
+    -------
         AuthInterface: An instance implementing AuthInterface for the
                        configured authentication module.
 
     Raises:
+    ------
         ValueError: If the configured authentication module is not supported.
     """
     try: