From 284d40b7af2641cce687b79ba192c167dd21c3a0 Mon Sep 17 00:00:00 2001
From: Leonid Ganeline <leo.gan.57@gmail.com>
Date: Thu, 6 Jul 2023 23:42:28 -0700
Subject: [PATCH] docstrings top level update (#7173)

Updated docstrings so, that [API
Reference](https://api.python.langchain.com/en/latest/api_reference.html)
page has text in the second column (class/function/... description.
---
 langchain/base_language.py                    |  3 ++-
 langchain/callbacks/comet_ml_callback.py      |  1 +
 langchain/callbacks/flyte_callback.py         |  1 +
 langchain/callbacks/infino_callback.py        |  1 +
 .../callbacks/streamlit/mutable_expander.py   |  4 ++++
 .../streamlit/streamlit_callback_handler.py   | 16 ++++++++++++++++
 langchain/callbacks/tracers/langchain.py      |  1 +
 langchain/chains/query_constructor/base.py    |  4 ++--
 langchain/client/__init__.py                  |  2 +-
 .../parsers/language/code_segmenter.py        |  2 ++
 .../parsers/language/javascript.py            |  2 ++
 .../parsers/language/python.py                |  2 ++
 langchain/evaluation/loading.py               |  9 ++++++++-
 langchain/llms/openllm.py                     |  2 ++
 langchain/llms/vertexai.py                    |  7 +++++++
 langchain/load/load.py                        | 11 +++++++++++
 langchain/retrievers/kendra.py                | 19 +++++++++++++++++++
 .../retrievers/weaviate_hybrid_search.py      |  9 +++++++++
 langchain/text_splitter.py                    |  2 ++
 langchain/tools/playwright/utils.py           |  4 ++--
 langchain/utilities/openapi.py                |  2 +-
 langchain/utils.py                            |  3 +++
 langchain/vectorstores/vectara.py             |  5 ++++-
 23 files changed, 103 insertions(+), 9 deletions(-)

diff --git a/langchain/base_language.py b/langchain/base_language.py
index 4059dc8c47..5e97366d6a 100644
--- a/langchain/base_language.py
+++ b/langchain/base_language.py
@@ -1,4 +1,3 @@
-"""Base class for all language models."""
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -30,6 +29,8 @@ def _get_token_ids_default_method(text: str) -> List[int]:
 
 
 class BaseLanguageModel(Serializable, ABC):
+    """Base class for all language models."""
+
     @abstractmethod
     def generate_prompt(
         self,
diff --git a/langchain/callbacks/comet_ml_callback.py b/langchain/callbacks/comet_ml_callback.py
index 877a8f9037..8ede8c6dd0 100644
--- a/langchain/callbacks/comet_ml_callback.py
+++ b/langchain/callbacks/comet_ml_callback.py
@@ -18,6 +18,7 @@ LANGCHAIN_MODEL_NAME = "langchain-model"
 
 
 def import_comet_ml() -> Any:
+    """Import comet_ml and raise an error if it is not installed."""
     try:
         import comet_ml  # noqa: F401
     except ImportError:
diff --git a/langchain/callbacks/flyte_callback.py b/langchain/callbacks/flyte_callback.py
index d806f0a3d9..5d80682383 100644
--- a/langchain/callbacks/flyte_callback.py
+++ b/langchain/callbacks/flyte_callback.py
@@ -23,6 +23,7 @@ logger = logging.getLogger(__name__)
 
 
 def import_flytekit() -> Tuple[flytekit, renderer]:
+    """Import flytekit and flytekitplugins-deck-standard."""
     try:
         import flytekit  # noqa: F401
         from flytekitplugins.deck import renderer  # noqa: F401
diff --git a/langchain/callbacks/infino_callback.py b/langchain/callbacks/infino_callback.py
index f8a01d6573..1eb75d087d 100644
--- a/langchain/callbacks/infino_callback.py
+++ b/langchain/callbacks/infino_callback.py
@@ -6,6 +6,7 @@ from langchain.schema import AgentAction, AgentFinish, LLMResult
 
 
 def import_infino() -> Any:
+    """Import the infino client."""
     try:
         from infinopy import InfinoClient
     except ImportError:
diff --git a/langchain/callbacks/streamlit/mutable_expander.py b/langchain/callbacks/streamlit/mutable_expander.py
index e58398b109..7de1e9873f 100644
--- a/langchain/callbacks/streamlit/mutable_expander.py
+++ b/langchain/callbacks/streamlit/mutable_expander.py
@@ -9,11 +9,15 @@ if TYPE_CHECKING:
 
 
 class ChildType(Enum):
+    """The enumerator of the child type."""
+
     MARKDOWN = "MARKDOWN"
     EXCEPTION = "EXCEPTION"
 
 
 class ChildRecord(NamedTuple):
+    """The child record as a NamedTuple."""
+
     type: ChildType
     kwargs: Dict[str, Any]
     dg: DeltaGenerator
diff --git a/langchain/callbacks/streamlit/streamlit_callback_handler.py b/langchain/callbacks/streamlit/streamlit_callback_handler.py
index e86e4e0de1..87cc4e058f 100644
--- a/langchain/callbacks/streamlit/streamlit_callback_handler.py
+++ b/langchain/callbacks/streamlit/streamlit_callback_handler.py
@@ -27,6 +27,8 @@ EXCEPTION_EMOJI = "⚠️"
 
 
 class LLMThoughtState(Enum):
+    """Enumerator of the LLMThought state."""
+
     # The LLM is thinking about what to do next. We don't know which tool we'll run.
     THINKING = "THINKING"
     # The LLM has decided to run a tool. We don't have results from the tool yet.
@@ -36,6 +38,8 @@ class LLMThoughtState(Enum):
 
 
 class ToolRecord(NamedTuple):
+    """The tool record as a NamedTuple."""
+
     name: str
     input_str: str
 
@@ -100,6 +104,8 @@ class LLMThoughtLabeler:
 
 
 class LLMThought:
+    """A thought in the LLM's thought stream."""
+
     def __init__(
         self,
         parent_container: DeltaGenerator,
@@ -107,6 +113,14 @@ class LLMThought:
         expanded: bool,
         collapse_on_complete: bool,
     ):
+        """Initialize the LLMThought.
+
+        Args:
+            parent_container: The container we're writing into.
+            labeler: The labeler to use for this thought.
+            expanded: Whether the thought should be expanded by default.
+            collapse_on_complete: Whether the thought should be collapsed.
+        """
         self._container = MutableExpander(
             parent_container=parent_container,
             label=labeler.get_initial_label(),
@@ -213,6 +227,8 @@ class LLMThought:
 
 
 class StreamlitCallbackHandler(BaseCallbackHandler):
+    """A callback handler that writes to a Streamlit app."""
+
     def __init__(
         self,
         parent_container: DeltaGenerator,
diff --git a/langchain/callbacks/tracers/langchain.py b/langchain/callbacks/tracers/langchain.py
index 165eedea41..6e3d7da312 100644
--- a/langchain/callbacks/tracers/langchain.py
+++ b/langchain/callbacks/tracers/langchain.py
@@ -31,6 +31,7 @@ def log_error_once(method: str, exception: Exception) -> None:
 
 
 def wait_for_all_tracers() -> None:
+    """Wait for all tracers to finish."""
     global _TRACERS
     for tracer in _TRACERS:
         tracer.wait_for_futures()
diff --git a/langchain/chains/query_constructor/base.py b/langchain/chains/query_constructor/base.py
index 6111ca46a8..67afc16b5b 100644
--- a/langchain/chains/query_constructor/base.py
+++ b/langchain/chains/query_constructor/base.py
@@ -123,8 +123,8 @@ def load_query_constructor_chain(
     enable_limit: bool = False,
     **kwargs: Any,
 ) -> LLMChain:
-    """
-    Load a query constructor chain.
+    """Load a query constructor chain.
+
     Args:
         llm: BaseLanguageModel to use for the chain.
         document_contents: The contents of the document to be queried.
diff --git a/langchain/client/__init__.py b/langchain/client/__init__.py
index b66b4808c9..bcab76f594 100644
--- a/langchain/client/__init__.py
+++ b/langchain/client/__init__.py
@@ -1,4 +1,4 @@
-"""LangChain+ Client."""
+"""LangChain + Client."""
 from langchain.client.runner_utils import (
     arun_on_dataset,
     arun_on_examples,
diff --git a/langchain/document_loaders/parsers/language/code_segmenter.py b/langchain/document_loaders/parsers/language/code_segmenter.py
index 9a189d761b..6264e40428 100644
--- a/langchain/document_loaders/parsers/language/code_segmenter.py
+++ b/langchain/document_loaders/parsers/language/code_segmenter.py
@@ -3,6 +3,8 @@ from typing import List
 
 
 class CodeSegmenter(ABC):
+    """The abstract class for the code segmenter."""
+
     def __init__(self, code: str):
         self.code = code
 
diff --git a/langchain/document_loaders/parsers/language/javascript.py b/langchain/document_loaders/parsers/language/javascript.py
index 304c59b963..cb53bfb420 100644
--- a/langchain/document_loaders/parsers/language/javascript.py
+++ b/langchain/document_loaders/parsers/language/javascript.py
@@ -4,6 +4,8 @@ from langchain.document_loaders.parsers.language.code_segmenter import CodeSegme
 
 
 class JavaScriptSegmenter(CodeSegmenter):
+    """The code segmenter for JavaScript."""
+
     def __init__(self, code: str):
         super().__init__(code)
         self.source_lines = self.code.splitlines()
diff --git a/langchain/document_loaders/parsers/language/python.py b/langchain/document_loaders/parsers/language/python.py
index bd6a0f5b83..4446b4a21a 100644
--- a/langchain/document_loaders/parsers/language/python.py
+++ b/langchain/document_loaders/parsers/language/python.py
@@ -5,6 +5,8 @@ from langchain.document_loaders.parsers.language.code_segmenter import CodeSegme
 
 
 class PythonSegmenter(CodeSegmenter):
+    """The code segmenter for Python."""
+
     def __init__(self, code: str):
         super().__init__(code)
         self.source_lines = self.code.splitlines()
diff --git a/langchain/evaluation/loading.py b/langchain/evaluation/loading.py
index 27b8b79abd..c5ce94ddc5 100644
--- a/langchain/evaluation/loading.py
+++ b/langchain/evaluation/loading.py
@@ -12,7 +12,14 @@ from langchain.evaluation.schema import EvaluatorType, LLMEvalChain
 
 
 def load_dataset(uri: str) -> List[Dict]:
-    """Load a dataset from the LangChainDatasets HuggingFace org."""
+    """Load a dataset from the LangChainDatasets HuggingFace org.
+
+    Args:
+        uri: The uri of the dataset to load.
+
+    Returns:
+        A list of dictionaries, each representing a row in the dataset.
+    """
     try:
         from datasets import load_dataset
     except ImportError:
diff --git a/langchain/llms/openllm.py b/langchain/llms/openllm.py
index d772047281..3b08ded337 100644
--- a/langchain/llms/openllm.py
+++ b/langchain/llms/openllm.py
@@ -32,6 +32,8 @@ ServerType = Literal["http", "grpc"]
 
 
 class IdentifyingParams(TypedDict):
+    """Parameters for identifying a model as a typed dict."""
+
     model_name: str
     model_id: Optional[str]
     server_url: Optional[str]
diff --git a/langchain/llms/vertexai.py b/langchain/llms/vertexai.py
index 14ce8dbbee..312b3ae44b 100644
--- a/langchain/llms/vertexai.py
+++ b/langchain/llms/vertexai.py
@@ -23,6 +23,13 @@ if TYPE_CHECKING:
 
 
 def is_codey_model(model_name: str) -> bool:
+    """Returns True if the model name is a Codey model.
+
+    Args:
+        model_name: The model name to check.
+
+    Returns: True if the model name is a Codey model.
+    """
     return "code" in model_name
 
 
diff --git a/langchain/load/load.py b/langchain/load/load.py
index b4b8ce5f7a..5cd8bb5e34 100644
--- a/langchain/load/load.py
+++ b/langchain/load/load.py
@@ -7,6 +7,8 @@ from langchain.load.serializable import Serializable
 
 
 class Reviver:
+    """Reviver for JSON objects."""
+
     def __init__(self, secrets_map: Optional[Dict[str, str]] = None) -> None:
         self.secrets_map = secrets_map or dict()
 
@@ -65,4 +67,13 @@ class Reviver:
 
 
 def loads(text: str, *, secrets_map: Optional[Dict[str, str]] = None) -> Any:
+    """Load a JSON object from a string.
+
+    Args:
+        text: The string to load.
+        secrets_map: A map of secrets to load.
+
+    Returns:
+
+    """
     return json.loads(text, object_hook=Reviver(secrets_map))
diff --git a/langchain/retrievers/kendra.py b/langchain/retrievers/kendra.py
index 8008694001..7d0e2084ac 100644
--- a/langchain/retrievers/kendra.py
+++ b/langchain/retrievers/kendra.py
@@ -12,6 +12,15 @@ from langchain.schema import BaseRetriever
 
 
 def clean_excerpt(excerpt: str) -> str:
+    """Cleans an excerpt from Kendra.
+
+    Args:
+        excerpt: The excerpt to clean.
+
+    Returns:
+        The cleaned excerpt.
+
+    """
     if not excerpt:
         return excerpt
     res = re.sub("\s+", " ", excerpt).replace("...", "")
@@ -19,6 +28,16 @@ def clean_excerpt(excerpt: str) -> str:
 
 
 def combined_text(title: str, excerpt: str) -> str:
+    """Combines a title and an excerpt into a single string.
+
+    Args:
+        title: The title of the document.
+        excerpt: The excerpt of the document.
+
+    Returns:
+        The combined text.
+
+    """
     if not title or not excerpt:
         return ""
     return f"Document Title: {title} \nDocument Excerpt: \n{excerpt}\n"
diff --git a/langchain/retrievers/weaviate_hybrid_search.py b/langchain/retrievers/weaviate_hybrid_search.py
index 84a5c7e963..fe2601c835 100644
--- a/langchain/retrievers/weaviate_hybrid_search.py
+++ b/langchain/retrievers/weaviate_hybrid_search.py
@@ -16,13 +16,22 @@ from langchain.schema import BaseRetriever
 
 
 class WeaviateHybridSearchRetriever(BaseRetriever):
+    """Retriever that uses Weaviate's hybrid search to retrieve documents."""
+
     client: Any
+    """keyword arguments to pass to the Weaviate client."""
     index_name: str
+    """The name of the index to use."""
     text_key: str
+    """The name of the text key to use."""
     alpha: float = 0.5
+    """The weight of the text key in the hybrid search."""
     k: int = 4
+    """The number of results to return."""
     attributes: List[str]
+    """The attributes to return in the results."""
     create_schema_if_missing: bool = True
+    """Whether to create the schema if it doesn't exist."""
 
     @root_validator(pre=True)
     def validate_client(
diff --git a/langchain/text_splitter.py b/langchain/text_splitter.py
index 6d2ea2e873..0cbe9e4ed8 100644
--- a/langchain/text_splitter.py
+++ b/langchain/text_splitter.py
@@ -561,6 +561,8 @@ class SentenceTransformersTokenTextSplitter(TextSplitter):
 
 
 class Language(str, Enum):
+    """Enum of the programming languages."""
+
     CPP = "cpp"
     GO = "go"
     JAVA = "java"
diff --git a/langchain/tools/playwright/utils.py b/langchain/tools/playwright/utils.py
index 6bbb62f03c..eb874f2eb4 100644
--- a/langchain/tools/playwright/utils.py
+++ b/langchain/tools/playwright/utils.py
@@ -52,7 +52,7 @@ def get_current_page(browser: SyncBrowser) -> SyncPage:
 
 def create_async_playwright_browser(headless: bool = True) -> AsyncBrowser:
     """
-    Create a async playwright browser.
+    Create an async playwright browser.
 
     Args:
         headless: Whether to run the browser in headless mode. Defaults to True.
@@ -86,7 +86,7 @@ T = TypeVar("T")
 
 
 def run_async(coro: Coroutine[Any, Any, T]) -> T:
-    """
+    """Run an async coroutine.
 
     Args:
         coro: The coroutine to run. Coroutine[Any, Any, T]
diff --git a/langchain/utilities/openapi.py b/langchain/utilities/openapi.py
index 82421dd285..06d0f66632 100644
--- a/langchain/utilities/openapi.py
+++ b/langchain/utilities/openapi.py
@@ -26,7 +26,7 @@ logger = logging.getLogger(__name__)
 
 
 class HTTPVerb(str, Enum):
-    """HTTP verbs."""
+    """Enumerator of the HTTP verbs."""
 
     GET = "get"
     PUT = "put"
diff --git a/langchain/utils.py b/langchain/utils.py
index 0416b42d56..fd03fa6248 100644
--- a/langchain/utils.py
+++ b/langchain/utils.py
@@ -108,12 +108,15 @@ def comma_list(items: List[Any]) -> str:
 @contextlib.contextmanager
 def mock_now(dt_value):  # type: ignore
     """Context manager for mocking out datetime.now() in unit tests.
+
     Example:
     with mock_now(datetime.datetime(2011, 2, 3, 10, 11)):
         assert datetime.datetime.now() == datetime.datetime(2011, 2, 3, 10, 11)
     """
 
     class MockDateTime(datetime.datetime):
+        """Mock datetime.datetime.now() with a fixed datetime."""
+
         @classmethod
         def now(cls):  # type: ignore
             # Create a copy of dt_value.
diff --git a/langchain/vectorstores/vectara.py b/langchain/vectorstores/vectara.py
index 36fffe35d8..05dabac4e4 100644
--- a/langchain/vectorstores/vectara.py
+++ b/langchain/vectorstores/vectara.py
@@ -16,7 +16,10 @@ from langchain.vectorstores.base import VectorStore, VectorStoreRetriever
 
 
 class Vectara(VectorStore):
-    """Implementation of Vector Store using Vectara (https://vectara.com).
+    """Implementation of Vector Store using Vectara.
+
+     See (https://vectara.com).
+
     Example:
         .. code-block:: python