Add file level comments - better logging

Author: fileames

libs/oracledb/langchain_oracledb/document_loaders/oracleadb_loader.py

@@ -1,5 +1,11 @@
-# Copyright (c) 2025 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+oracleadb_loader.py
+
+Contains OracleAutonomousDatabaseLoader for connecting to 
+Oracle Autonomous Database (ADB).
+"""
 
 from typing import Any, Dict, List, Optional, Union
 

libs/oracledb/langchain_oracledb/document_loaders/oracleai.py

@@ -1,13 +1,15 @@
-# Copyright (c) 2025 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+oracleai.py
 
-# Authors:
-#   Harichandan Roy (hroy)
-#   David Jiang (ddjiang)
-#
-# -----------------------------------------------------------------------------
-# oracleai.py
-# -----------------------------------------------------------------------------
+Defines OracleDocLoader and OracleTextSplitter for loading 
+and splitting documents using Oracle AI Vector Search.
+
+Authors:
+    - Harichandan Roy (hroy)
+    - David Jiang (ddjiang)
+"""
 
 from __future__ import annotations
 

libs/oracledb/langchain_oracledb/embeddings/oracleai.py

@@ -1,14 +1,15 @@
-# Copyright (c) 2025 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+oracleai.py
 
-# Authors:
-#   Harichandan Roy (hroy)
-#   David Jiang (ddjiang)
-#
-# -----------------------------------------------------------------------------
-# oracleai.py
-# -----------------------------------------------------------------------------
+Implements OracleEmbeddings for generating and handling 
+vector embeddings with Oracle AI Vector Search.
 
+Authors:
+    - Harichandan Roy (hroy)
+    - David Jiang (ddjiang)
+"""
 from __future__ import annotations
 
 import json

libs/oracledb/langchain_oracledb/utilities/oracleai.py

@@ -1,14 +1,14 @@
-# Copyright (c) 2025 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+oracleai.py
 
-# Authors:
-#   Harichandan Roy (hroy)
-#   David Jiang (ddjiang)
-#
-# -----------------------------------------------------------------------------
-# oracleai.py
-# -----------------------------------------------------------------------------
+Implements OracleSummary with Oracle AI Vector Search support.
 
+Authors:
+    - Harichandan Roy (hroy)
+    - David Jiang (ddjiang)
+"""
 from __future__ import annotations
 
 import json

libs/oracledb/langchain_oracledb/vectorstores/oraclevs.py

@@ -1,6 +1,11 @@
-# Copyright (c) 2025 Oracle and/or its affiliates.
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+oraclevs.py
 
+Provides integration between Oracle Vector Database and 
+LangChain for vector storage and search.
+"""
 from __future__ import annotations
 
 import array
@@ -328,9 +333,9 @@ def _create_table(connection: Connection, table_name: str, embedding_dim: int) -
             )
             ddl = f"CREATE TABLE {table_name} ({ddl_body})"
             cursor.execute(ddl)
-        logger.info("Table created successfully...")
+        logger.info(f"Table {table_name} created successfully...")
     else:
-        logger.info("Table already exists...")
+        logger.info(f"Table {table_name} already exists...")
 
 
 async def _acreate_table(
@@ -345,9 +350,9 @@ async def _acreate_table(
             )
             ddl = f"CREATE TABLE {table_name} ({ddl_body})"
             await cursor.execute(ddl)
-        logger.info("Table created successfully...")
+        logger.info(f"Table {table_name} created successfully...")
     else:
-        logger.info("Table already exists...")
+        logger.info(f"Table {table_name} already exists...")
 
 
 @_handle_exceptions
@@ -477,9 +482,9 @@ def _create_hnsw_index(
     if not _index_exists(connection, idx_name, table_name):
         with connection.cursor() as cursor:
             cursor.execute(ddl)
-            logger.info("Index created successfully...")
+            logger.info(f"Index {idx_name} created successfully...")
     else:
-        logger.info("Index already exists...")
+        logger.info(f"Index {idx_name} already exists...")
 
 
 def _get_ivf_index_ddl(
@@ -559,9 +564,9 @@ def _create_ivf_index(
     if not _index_exists(connection, idx_name, table_name):
         with connection.cursor() as cursor:
             cursor.execute(ddl)
-        logger.info("Index created successfully...")
+        logger.info(f"Index {idx_name} created successfully...")
     else:
-        logger.info("Index already exists...")
+        logger.info(f"Index {idx_name} already exists...")
 
 
 @_ahandle_exceptions
@@ -618,9 +623,9 @@ async def _acreate_hnsw_index(
     if not await _aindex_exists(connection, idx_name, table_name):
         with connection.cursor() as cursor:
             await cursor.execute(ddl)
-            logger.info("Index created successfully...")
+            logger.info(f"Index {idx_name} created successfully...")
     else:
-        logger.info("Index already exists...")
+        logger.info(f"Index {idx_name} already exists...")
 
 
 async def _acreate_ivf_index(
@@ -635,9 +640,9 @@ async def _acreate_ivf_index(
     if not await _aindex_exists(connection, idx_name, table_name):
         with connection.cursor() as cursor:
             await cursor.execute(ddl)
-        logger.info("Index created successfully...")
+        logger.info(f"Index {idx_name} created successfully...")
     else:
-        logger.info("Index already exists...")
+        logger.info(f"Index {idx_name} already exists...")
 
 
 @_handle_exceptions
@@ -658,9 +663,9 @@ def drop_table_purge(client: Any, table_name: str) -> None:
         with connection.cursor() as cursor:
             ddl = f"DROP TABLE {table_name} PURGE"
             cursor.execute(ddl)
-        logger.info("Table dropped successfully...")
+        logger.info(f"Table {table_name} dropped successfully...")
     else:
-        logger.info("Table not found...")
+        logger.info(f"Table {table_name} not found...")
     return
 
 
@@ -681,9 +686,9 @@ async def context(connection: Any) -> None:
             with connection.cursor() as cursor:
                 ddl = f"DROP TABLE {table_name} PURGE"
                 await cursor.execute(ddl)
-            logger.info("Table dropped successfully...")
+            logger.info(f"Table {table_name} dropped successfully...")
         else:
-            logger.info("Table not found...")
+            logger.info(f"Table {table_name} not found...")
 
     await _handle_context(client, context)
     return

libs/oracledb/tests/__init__.py

@@ -1,2 +1,2 @@
-# Copyright (c) 2023 Oracle and/or its affiliates.
+# Copyright (c) 2025 Oracle and/or its affiliates.
 # Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/

libs/oracledb/tests/integration_tests/document_loaders/test_oracleds.py

@@ -1,9 +1,13 @@
-# Authors:
-#   Sudhir Kumar (sudhirkk)
-#
-# -----------------------------------------------------------------------------
-# test_oracleds.py
-# -----------------------------------------------------------------------------
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+test_oracleds.py
+
+Unit tests for OracleDocLoader and OracleTextSplitter.
+
+Authors: 
+    - Sudhir Kumar (sudhirkk)
+"""
 import sys
 
 from langchain_oracledb.document_loaders.oracleai import (

libs/oracledb/tests/integration_tests/vectorstores/test_oraclevs.py

@@ -1,9 +1,15 @@
-"""Test Oracle AI Vector Search functionality."""
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+test_oraclevs.py
+
+Test Oracle AI Vector Search functionality integration 
+with OracleVS.
+"""
 
 # import required modules
 import asyncio
 import logging
-import os
 import sys
 import threading
 
@@ -2321,19 +2327,19 @@ def test_index_table_case(caplog: pytest.LogCaptureFixture) -> None:
     with caplog.at_level(logging.INFO):
         vs_obj = OracleVS(connection, model, "TB1", DistanceStrategy.EUCLIDEAN_DISTANCE)
 
-    assert "Table created successfully..." in caplog.text
+    assert "Table TB1 created successfully..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         OracleVS(connection, model, "Tb1", DistanceStrategy.EUCLIDEAN_DISTANCE)
 
-    assert "Table already exists..." in caplog.text
+    assert "Table Tb1 already exists..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         vs_obj2 = OracleVS(
             connection, model, "TB2", DistanceStrategy.EUCLIDEAN_DISTANCE
         )
 
-    assert "Table created successfully..." in caplog.text
+    assert "Table TB2 created successfully..." in caplog.text
 
     vs_obj.add_texts(texts, metadata)
 
@@ -2342,14 +2348,14 @@ def test_index_table_case(caplog: pytest.LogCaptureFixture) -> None:
             connection, vs_obj, params={"idx_name": "hnsw_idx2", "idx_type": "HNSW"}
         )
 
-    assert "Index created successfully..." in caplog.text
+    assert "Index hnsw_idx2 created successfully..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         create_index(
             connection, vs_obj, params={"idx_name": "HNSW_idx2", "idx_type": "HNSW"}
         )
 
-    assert "Index already exists..." in caplog.text
+    assert "Index HNSW_idx2 already exists..." in caplog.text
 
     with pytest.raises(
         RuntimeError, match="name is already used by an existing object"
@@ -2365,7 +2371,7 @@ def test_index_table_case(caplog: pytest.LogCaptureFixture) -> None:
             connection, vs_obj, params={"idx_name": '"hnsw_idx2"', "idx_type": "HNSW"}
         )
 
-    assert "Index created successfully..." in caplog.text
+    assert 'Index "hnsw_idx2" created successfully...' in caplog.text
 
     with pytest.raises(RuntimeError, match="such column list already indexed"):
         create_index(
@@ -2377,7 +2383,7 @@ def test_index_table_case(caplog: pytest.LogCaptureFixture) -> None:
 
 
 @pytest.mark.asyncio
-async def test_insdex_table_case_async(caplog: pytest.LogCaptureFixture) -> None:
+async def test_index_table_case_async(caplog: pytest.LogCaptureFixture) -> None:
     try:
         connection = await oracledb.connect_async(
             user=username, password=password, dsn=dsn
@@ -2402,21 +2408,21 @@ async def test_insdex_table_case_async(caplog: pytest.LogCaptureFixture) -> None
             connection, model, "TB1", DistanceStrategy.EUCLIDEAN_DISTANCE
         )
 
-    assert "Table created successfully..." in caplog.text
+    assert "Table TB1 created successfully..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         await OracleVS.acreate(
             connection, model, "Tb1", DistanceStrategy.EUCLIDEAN_DISTANCE
         )
 
-    assert "Table already exists..." in caplog.text
+    assert "Table Tb1 already exists..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         vs_obj2 = await OracleVS.acreate(
             connection, model, "TB2", DistanceStrategy.EUCLIDEAN_DISTANCE
         )
 
-    assert "Table created successfully..." in caplog.text
+    assert "Table TB2 created successfully..." in caplog.text
 
     await vs_obj.aadd_texts(texts, metadata)
 
@@ -2425,14 +2431,14 @@ async def test_insdex_table_case_async(caplog: pytest.LogCaptureFixture) -> None
             connection, vs_obj, params={"idx_name": "hnsw_idx2", "idx_type": "HNSW"}
         )
 
-    assert "Index created successfully..." in caplog.text
+    assert "Index hnsw_idx2 created successfully..." in caplog.text
 
     with caplog.at_level(logging.INFO):
         await acreate_index(
             connection, vs_obj, params={"idx_name": "HNSW_idx2", "idx_type": "HNSW"}
         )
 
-    assert "Index already exists..." in caplog.text
+    assert "Index HNSW_idx2 already exists..." in caplog.text
 
     with pytest.raises(
         RuntimeError, match="name is already used by an existing object"
@@ -2448,7 +2454,7 @@ async def test_insdex_table_case_async(caplog: pytest.LogCaptureFixture) -> None
             connection, vs_obj, params={"idx_name": '"hnsw_idx2"', "idx_type": "HNSW"}
         )
 
-    assert "Index created successfully..." in caplog.text
+    assert 'Index "hnsw_idx2" created successfully...' in caplog.text
 
     with pytest.raises(RuntimeError, match="such column list already indexed"):
         await acreate_index(

libs/oracledb/tests/unit_tests/document_loaders/test_oracleadb.py

@@ -1,3 +1,10 @@
+# Copyright (c) 2024, 2025 Oracle and/or its affiliates.
+# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/
+"""
+test_oracleadb.py
+
+Unit tests for OracleAutonomousDatabaseLoader.
+"""
 from typing import Dict, List
 from unittest.mock import MagicMock, patch