Merge branch 'master' into ruff-core-preview-2

Author: cbornet

.github/workflows/api_doc_build.yml

@@ -72,7 +72,7 @@ jobs:
           done
 
       - name: '🐍 Setup Python ${{ env.PYTHON_VERSION }}'
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         id: setup-python
         with:
           python-version: ${{ env.PYTHON_VERSION }}

.github/workflows/check_diffs.yml

@@ -35,7 +35,7 @@ jobs:
       - name: '📋 Checkout Code'
         uses: actions/checkout@v5
       - name: '🐍 Setup Python 3.11'
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
       - name: '📂 Get Changed Files'

.github/workflows/check_new_docs.yml

@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.10'
       - id: files

.github/workflows/codspeed.yml

@@ -44,7 +44,7 @@ jobs:
         with:
           python-version: "3.12"
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

libs/cli/langchain_cli/dev_scripts.py

@@ -14,7 +14,19 @@ def create_demo_server(
     config_keys: Sequence[str] = (),
     playground_type: Literal["default", "chat"] = "default",
 ) -> FastAPI:
-    """Create a demo server for the current template."""
+    """Create a demo server for the current template.
+
+    Args:
+        config_keys: Optional sequence of config keys to expose in the playground.
+        playground_type: The type of playground to use. Can be `'default'` or `'chat'`.
+
+    Returns:
+        The demo server.
+
+    Raises:
+        KeyError: If the `pyproject.toml` file is missing required fields.
+        ImportError: If the module defined in `pyproject.toml` cannot be imported.
+    """
     app = FastAPI()
     package_root = get_package_root()
     pyproject = package_root / "pyproject.toml"
@@ -41,10 +53,18 @@ def create_demo_server(
 
 
 def create_demo_server_configurable() -> FastAPI:
-    """Create a configurable demo server."""
+    """Create a configurable demo server.
+
+    Returns:
+        The configurable demo server.
+    """
     return create_demo_server(config_keys=["configurable"])
 
 
 def create_demo_server_chat() -> FastAPI:
-    """Create a chat demo server."""
+    """Create a chat demo server.
+
+    Returns:
+        The chat demo server.
+    """
     return create_demo_server(playground_type="chat")

libs/cli/langchain_cli/namespaces/migrate/generate/generic.py

@@ -11,7 +11,16 @@ def generate_raw_migrations(
     to_package: str,
     filter_by_all: bool = False,  # noqa: FBT001, FBT002
 ) -> list[tuple[str, str]]:
-    """Scan the `langchain` package and generate migrations for all modules."""
+    """Scan the `langchain` package and generate migrations for all modules.
+
+    Args:
+        from_package: The package to migrate from.
+        to_package: The package to migrate to.
+        filter_by_all: Whether to only consider items in `__all__`.
+
+    Returns:
+        A list of tuples containing the original import path and the new import path.
+    """
     package = importlib.import_module(from_package)
 
     items = []
@@ -84,6 +93,13 @@ def generate_top_level_imports(pkg: str) -> list[tuple[str, str]]:
     and the second tuple will contain the path
     to importing it from the top level namespaces
     (e.g., ``langchain_community.chat_models.XYZ``)
+
+    Args:
+        pkg: The package to scan.
+
+    Returns:
+        A list of tuples containing the fully qualified path and the top-level
+        import path.
     """
     package = importlib.import_module(pkg)
 
@@ -130,7 +146,17 @@ def generate_simplified_migrations(
     to_package: str,
     filter_by_all: bool = True,  # noqa: FBT001, FBT002
 ) -> list[tuple[str, str]]:
-    """Get all the raw migrations, then simplify them if possible."""
+    """Get all the raw migrations, then simplify them if possible.
+
+    Args:
+        from_package: The package to migrate from.
+        to_package: The package to migrate to.
+        filter_by_all: Whether to only consider items in `__all__`.
+
+    Returns:
+        A list of tuples containing the original import path and the simplified
+        import path.
+    """
     raw_migrations = generate_raw_migrations(
         from_package,
         to_package,

libs/cli/langchain_cli/namespaces/migrate/generate/grit.py

@@ -2,13 +2,28 @@
 
 
 def split_package(package: str) -> tuple[str, str]:
-    """Split a package name into the containing package and the final name."""
+    """Split a package name into the containing package and the final name.
+
+    Args:
+        package: The full package name.
+
+    Returns:
+        A tuple of `(containing_package, final_name)`.
+    """
     parts = package.split(".")
     return ".".join(parts[:-1]), parts[-1]
 
 
 def dump_migrations_as_grit(name: str, migration_pairs: list[tuple[str, str]]) -> str:
-    """Dump the migration pairs as a Grit file."""
+    """Dump the migration pairs as a Grit file.
+
+    Args:
+        name: The name of the migration.
+        migration_pairs: A list of tuples `(from_module, to_module)`.
+
+    Returns:
+        The Grit file as a string.
+    """
     remapped = ",\n".join(
         [
             f"""

libs/cli/langchain_cli/namespaces/migrate/generate/utils.py

@@ -59,7 +59,15 @@ def visit_ClassDef(self, node: ast.ClassDef) -> None:
 
 
 def is_subclass(class_obj: type, classes_: list[type]) -> bool:
-    """Check if the given class object is a subclass of any class in list classes."""
+    """Check if the given class object is a subclass of any class in list classes.
+
+    Args:
+        class_obj: The class to check.
+        classes_: A list of classes to check against.
+
+    Returns:
+        True if `class_obj` is a subclass of any class in `classes_`, False otherwise.
+    """
     return any(
         issubclass(class_obj, kls)
         for kls in classes_
@@ -68,7 +76,15 @@ def is_subclass(class_obj: type, classes_: list[type]) -> bool:
 
 
 def find_subclasses_in_module(module: ModuleType, classes_: list[type]) -> list[str]:
-    """Find all classes in the module that inherit from one of the classes."""
+    """Find all classes in the module that inherit from one of the classes.
+
+    Args:
+        module: The module to inspect.
+        classes_: A list of classes to check against.
+
+    Returns:
+        A list of class names that are subclasses of any class in `classes_`.
+    """
     subclasses = []
     # Iterate over all attributes of the module that are classes
     for _name, obj in inspect.getmembers(module, inspect.isclass):
@@ -91,7 +107,15 @@ def identify_all_imports_in_file(
     *,
     from_package: Optional[str] = None,
 ) -> list[tuple[str, str]]:
-    """Let's also identify all the imports in the given file."""
+    """Identify all the imports in the given file.
+
+    Args:
+        file: The file to analyze.
+        from_package: If provided, only return imports from this package.
+
+    Returns:
+        A list of tuples `(module, name)` representing the imports found in the file.
+    """
     code = Path(file).read_text(encoding="utf-8")
     return find_imports_from_package(code, from_package=from_package)
 
@@ -106,6 +130,9 @@ def identify_pkg_source(pkg_root: str) -> pathlib.Path:
     Returns:
         Returns the path to the source code for the package.
 
+    Raises:
+        ValueError: If there is not exactly one directory starting with `'langchain_'`
+            in the package root.
     """
     dirs = [d for d in Path(pkg_root).iterdir() if d.is_dir()]
     matching_dirs = [d for d in dirs if d.name.startswith("langchain_")]
@@ -116,7 +143,15 @@ def identify_pkg_source(pkg_root: str) -> pathlib.Path:
 
 
 def list_classes_by_package(pkg_root: str) -> list[tuple[str, str]]:
-    """List all classes in a package."""
+    """List all classes in a package.
+
+    Args:
+        pkg_root: the root of the package.
+
+    Returns:
+        A list of tuples `(module, class_name)` representing all classes found in the
+        package, excluding test files.
+    """
     module_classes = []
     pkg_source = identify_pkg_source(pkg_root)
     files = list(pkg_source.rglob("*.py"))
@@ -130,7 +165,15 @@ def list_classes_by_package(pkg_root: str) -> list[tuple[str, str]]:
 
 
 def list_init_imports_by_package(pkg_root: str) -> list[tuple[str, str]]:
-    """List all the things that are being imported in a package by module."""
+    """List all the things that are being imported in a package by module.
+
+    Args:
+        pkg_root: the root of the package.
+
+    Returns:
+        A list of tuples `(module, name)` representing the imports found in
+        `__init__.py` files.
+    """
     imports = []
     pkg_source = identify_pkg_source(pkg_root)
     # Scan all the files in the package
@@ -150,7 +193,15 @@ def find_imports_from_package(
     *,
     from_package: Optional[str] = None,
 ) -> list[tuple[str, str]]:
-    """Find imports in code."""
+    """Find imports in code.
+
+    Args:
+        code: The code to analyze.
+        from_package: If provided, only return imports from this package.
+
+    Returns:
+        A list of tuples `(module, name)` representing the imports found.
+    """
     # Parse the code into an AST
     tree = ast.parse(code)
     # Create an instance of the visitor

libs/cli/langchain_cli/utils/events.py

@@ -22,7 +22,14 @@ class EventDict(TypedDict):
 
 
 def create_events(events: list[EventDict]) -> Optional[dict[str, Any]]:
-    """Create events."""
+    """Create events.
+
+    Args:
+        events: A list of event dictionaries.
+
+    Returns:
+        The response from the event tracking service, or None if there was an error.
+    """
     try:
         data = {
             "events": [

libs/cli/langchain_cli/utils/find_replace.py

@@ -4,7 +4,15 @@
 
 
 def find_and_replace(source: str, replacements: dict[str, str]) -> str:
-    """Find and replace text in a string."""
+    """Find and replace text in a string.
+
+    Args:
+        source: The source string.
+        replacements: A dictionary of `{find: replace}` pairs.
+
+    Returns:
+        The modified string.
+    """
     rtn = source
 
     # replace keys in deterministic alphabetical order