From 527210972e68b11f874289ff5fa5117bd00d15fc Mon Sep 17 00:00:00 2001
From: Leonid Ganeline <leo.gan.57@gmail.com>
Date: Tue, 18 Jul 2023 07:51:44 -0700
Subject: [PATCH] docstrings `output_parsers` (#7859)

Added/updated the docstrings from `output_parsers`
 @baskaryan
---
 langchain/output_parsers/boolean.py          |  8 +++++--
 langchain/output_parsers/combining.py        |  2 +-
 langchain/output_parsers/datetime.py         |  7 ++++--
 langchain/output_parsers/enum.py             |  3 +++
 langchain/output_parsers/fix.py              | 10 ++++++++
 langchain/output_parsers/json.py             |  2 ++
 langchain/output_parsers/list.py             |  4 ++--
 langchain/output_parsers/loading.py          |  9 +++++++-
 langchain/output_parsers/openai_functions.py | 14 ++++++++++++
 langchain/output_parsers/pydantic.py         |  3 +++
 langchain/output_parsers/rail_parser.py      | 24 +++++++++++++++++---
 langchain/output_parsers/regex.py            |  5 +++-
 langchain/output_parsers/regex_dict.py       |  5 +++-
 langchain/output_parsers/retry.py            | 21 +++++++++++++++++
 langchain/output_parsers/structured.py       | 15 ++++++++----
 langchain/schema/output_parser.py            |  4 ++--
 16 files changed, 117 insertions(+), 19 deletions(-)

diff --git a/langchain/output_parsers/boolean.py b/langchain/output_parsers/boolean.py
index 96f61252917..f0990b8e050 100644
--- a/langchain/output_parsers/boolean.py
+++ b/langchain/output_parsers/boolean.py
@@ -2,14 +2,18 @@ from langchain.schema import BaseOutputParser
 
 
 class BooleanOutputParser(BaseOutputParser[bool]):
+    """Parse the output of an LLM call to a boolean."""
+
     true_val: str = "YES"
+    """The string value that should be parsed as True."""
     false_val: str = "NO"
+    """The string value that should be parsed as False."""
 
     def parse(self, text: str) -> bool:
         """Parse the output of an LLM call to a boolean.
 
         Args:
-            text: output of language model
+            text: output of a language model
 
         Returns:
             boolean
@@ -25,5 +29,5 @@ class BooleanOutputParser(BaseOutputParser[bool]):
 
     @property
     def _type(self) -> str:
-        """Snake-case string identifier for output parser type."""
+        """Snake-case string identifier for an output parser type."""
         return "boolean_output_parser"
diff --git a/langchain/output_parsers/combining.py b/langchain/output_parsers/combining.py
index fc24f018fba..511d9398f07 100644
--- a/langchain/output_parsers/combining.py
+++ b/langchain/output_parsers/combining.py
@@ -8,7 +8,7 @@ from langchain.schema import BaseOutputParser
 
 
 class CombiningOutputParser(BaseOutputParser):
-    """Class to combine multiple output parsers into one."""
+    """Combine multiple output parsers into one."""
 
     @property
     def lc_serializable(self) -> bool:
diff --git a/langchain/output_parsers/datetime.py b/langchain/output_parsers/datetime.py
index 658459d2654..bec68bb1cb1 100644
--- a/langchain/output_parsers/datetime.py
+++ b/langchain/output_parsers/datetime.py
@@ -12,9 +12,9 @@ def _generate_random_datetime_strings(
     start_date: datetime = datetime(1, 1, 1),
     end_date: datetime = datetime.now() + timedelta(days=3650),
 ) -> List[str]:
-    """
-    Generates n random datetime strings conforming to the
+    """Generates n random datetime strings conforming to the
     given pattern within the specified date range.
+
     Pattern should be a string containing the desired format codes.
     start_date and end_date should be datetime objects representing
     the start and end of the date range.
@@ -30,7 +30,10 @@ def _generate_random_datetime_strings(
 
 
 class DatetimeOutputParser(BaseOutputParser[datetime]):
+    """Parse the output of an LLM call to a datetime."""
+
     format: str = "%Y-%m-%dT%H:%M:%S.%fZ"
+    """The string value that used as the datetime format."""
 
     def get_format_instructions(self) -> str:
         examples = comma_list(_generate_random_datetime_strings(self.format))
diff --git a/langchain/output_parsers/enum.py b/langchain/output_parsers/enum.py
index fbb8c838f43..ee3daecfeef 100644
--- a/langchain/output_parsers/enum.py
+++ b/langchain/output_parsers/enum.py
@@ -7,7 +7,10 @@ from langchain.schema import BaseOutputParser, OutputParserException
 
 
 class EnumOutputParser(BaseOutputParser):
+    """Parse an output that is one of a set of values."""
+
     enum: Type[Enum]
+    """The enum to parse. Its values must be strings."""
 
     @root_validator()
     def raise_deprecation(cls, values: Dict) -> Dict:
diff --git a/langchain/output_parsers/fix.py b/langchain/output_parsers/fix.py
index 750a0654165..cc8bc30bf67 100644
--- a/langchain/output_parsers/fix.py
+++ b/langchain/output_parsers/fix.py
@@ -27,6 +27,16 @@ class OutputFixingParser(BaseOutputParser[T]):
         parser: BaseOutputParser[T],
         prompt: BasePromptTemplate = NAIVE_FIX_PROMPT,
     ) -> OutputFixingParser[T]:
+        """Create an OutputFixingParser from a language model and a parser.
+
+        Args:
+            llm: llm to use for fixing
+            parser: parser to use for parsing
+            prompt: prompt to use for fixing
+
+        Returns:
+            OutputFixingParser
+        """
         chain = LLMChain(llm=llm, prompt=prompt)
         return cls(parser=parser, retry_chain=chain)
 
diff --git a/langchain/output_parsers/json.py b/langchain/output_parsers/json.py
index 0a64fa348d1..035d8d48987 100644
--- a/langchain/output_parsers/json.py
+++ b/langchain/output_parsers/json.py
@@ -63,6 +63,8 @@ def parse_and_check_json_markdown(text: str, expected_keys: List[str]) -> dict:
 
 
 class SimpleJsonOutputParser(BaseOutputParser[Any]):
+    """Parse the output of an LLM call to a JSON object."""
+
     def parse(self, text: str) -> Any:
         text = text.strip()
         try:
diff --git a/langchain/output_parsers/list.py b/langchain/output_parsers/list.py
index 108d0af6877..c7f94648bf2 100644
--- a/langchain/output_parsers/list.py
+++ b/langchain/output_parsers/list.py
@@ -7,7 +7,7 @@ from langchain.schema import BaseOutputParser
 
 
 class ListOutputParser(BaseOutputParser):
-    """Class to parse the output of an LLM call to a list."""
+    """Parse the output of an LLM call to a list."""
 
     @property
     def _type(self) -> str:
@@ -19,7 +19,7 @@ class ListOutputParser(BaseOutputParser):
 
 
 class CommaSeparatedListOutputParser(ListOutputParser):
-    """Parse out comma separated lists."""
+    """Parse the output of an LLM call to a comma-separated list."""
 
     @property
     def lc_serializable(self) -> bool:
diff --git a/langchain/output_parsers/loading.py b/langchain/output_parsers/loading.py
index 7acd5aa95bb..b25710c1236 100644
--- a/langchain/output_parsers/loading.py
+++ b/langchain/output_parsers/loading.py
@@ -2,7 +2,14 @@ from langchain.output_parsers.regex import RegexParser
 
 
 def load_output_parser(config: dict) -> dict:
-    """Load output parser."""
+    """Load an output parser.
+
+    Args:
+        config: config dict
+
+    Returns:
+        config dict with output parser loaded
+    """
     if "output_parsers" in config:
         if config["output_parsers"] is not None:
             _config = config["output_parsers"]
diff --git a/langchain/output_parsers/openai_functions.py b/langchain/output_parsers/openai_functions.py
index 7d9d8aed860..a6d455825be 100644
--- a/langchain/output_parsers/openai_functions.py
+++ b/langchain/output_parsers/openai_functions.py
@@ -12,7 +12,10 @@ from langchain.schema import (
 
 
 class OutputFunctionsParser(BaseLLMOutputParser[Any]):
+    """Parse an output that is one of sets of values."""
+
     args_only: bool = True
+    """Whether to only return the arguments to the function call."""
 
     def parse_result(self, result: List[Generation]) -> Any:
         generation = result[0]
@@ -32,6 +35,8 @@ class OutputFunctionsParser(BaseLLMOutputParser[Any]):
 
 
 class JsonOutputFunctionsParser(OutputFunctionsParser):
+    """Parse an output as the Json object."""
+
     def parse_result(self, result: List[Generation]) -> Any:
         func = super().parse_result(result)
         if self.args_only:
@@ -41,7 +46,10 @@ class JsonOutputFunctionsParser(OutputFunctionsParser):
 
 
 class JsonKeyOutputFunctionsParser(JsonOutputFunctionsParser):
+    """Parse an output as the element of the Json object."""
+
     key_name: str
+    """The name of the key to return."""
 
     def parse_result(self, result: List[Generation]) -> Any:
         res = super().parse_result(result)
@@ -49,7 +57,10 @@ class JsonKeyOutputFunctionsParser(JsonOutputFunctionsParser):
 
 
 class PydanticOutputFunctionsParser(OutputFunctionsParser):
+    """Parse an output as a pydantic object."""
+
     pydantic_schema: Union[Type[BaseModel], Dict[str, Type[BaseModel]]]
+    """The pydantic schema to parse the output with."""
 
     @root_validator(pre=True)
     def validate_schema(cls, values: Dict) -> Dict:
@@ -77,7 +88,10 @@ class PydanticOutputFunctionsParser(OutputFunctionsParser):
 
 
 class PydanticAttrOutputFunctionsParser(PydanticOutputFunctionsParser):
+    """Parse an output as an attribute of a pydantic object."""
+
     attr_name: str
+    """The name of the attribute to return."""
 
     def parse_result(self, result: List[Generation]) -> Any:
         result = super().parse_result(result)
diff --git a/langchain/output_parsers/pydantic.py b/langchain/output_parsers/pydantic.py
index eacee30e11e..b35943e6e2a 100644
--- a/langchain/output_parsers/pydantic.py
+++ b/langchain/output_parsers/pydantic.py
@@ -11,7 +11,10 @@ T = TypeVar("T", bound=BaseModel)
 
 
 class PydanticOutputParser(BaseOutputParser[T]):
+    """Parse an output using a pydantic model."""
+
     pydantic_object: Type[T]
+    """The pydantic model to parse."""
 
     def parse(self, text: str) -> T:
         try:
diff --git a/langchain/output_parsers/rail_parser.py b/langchain/output_parsers/rail_parser.py
index 491d4b41e97..093b457b91b 100644
--- a/langchain/output_parsers/rail_parser.py
+++ b/langchain/output_parsers/rail_parser.py
@@ -6,10 +6,16 @@ from langchain.schema import BaseOutputParser
 
 
 class GuardrailsOutputParser(BaseOutputParser):
+    """Parse the output of an LLM call using Guardrails."""
+
     guard: Any
+    """The Guardrails object."""
     api: Optional[Callable]
+    """The API to use for the Guardrails object."""
     args: Any
+    """The arguments to pass to the API."""
     kwargs: Any
+    """The keyword arguments to pass to the API."""
 
     @property
     def _type(self) -> str:
@@ -24,10 +30,22 @@ class GuardrailsOutputParser(BaseOutputParser):
         *args: Any,
         **kwargs: Any,
     ) -> GuardrailsOutputParser:
+        """Create a GuardrailsOutputParser from a rail file.
+
+        Args:
+            rail_file: a rail file.
+            num_reasks: number of times to re-ask the question.
+            api: the API to use for the Guardrails object.
+            *args: The arguments to pass to the API
+            **kwargs: The keyword arguments to pass to the API.
+
+        Returns:
+            GuardrailsOutputParser
+        """
         try:
             from guardrails import Guard
         except ImportError:
-            raise ValueError(
+            raise ImportError(
                 "guardrails-ai package not installed. "
                 "Install it by running `pip install guardrails-ai`."
             )
@@ -50,7 +68,7 @@ class GuardrailsOutputParser(BaseOutputParser):
         try:
             from guardrails import Guard
         except ImportError:
-            raise ValueError(
+            raise ImportError(
                 "guardrails-ai package not installed. "
                 "Install it by running `pip install guardrails-ai`."
             )
@@ -73,7 +91,7 @@ class GuardrailsOutputParser(BaseOutputParser):
         try:
             from guardrails import Guard
         except ImportError:
-            raise ValueError(
+            raise ImportError(
                 "guardrails-ai package not installed. "
                 "Install it by running `pip install guardrails-ai`."
             )
diff --git a/langchain/output_parsers/regex.py b/langchain/output_parsers/regex.py
index 8245be202e6..cdddb083992 100644
--- a/langchain/output_parsers/regex.py
+++ b/langchain/output_parsers/regex.py
@@ -7,15 +7,18 @@ from langchain.schema import BaseOutputParser
 
 
 class RegexParser(BaseOutputParser):
-    """Class to parse the output into a dictionary."""
+    """Parse the output of an LLM call using a regex."""
 
     @property
     def lc_serializable(self) -> bool:
         return True
 
     regex: str
+    """The regex to use to parse the output."""
     output_keys: List[str]
+    """The keys to use for the output."""
     default_output_key: Optional[str] = None
+    """The default key to use for the output."""
 
     @property
     def _type(self) -> str:
diff --git a/langchain/output_parsers/regex_dict.py b/langchain/output_parsers/regex_dict.py
index fc1271a7deb..a52b8980f3a 100644
--- a/langchain/output_parsers/regex_dict.py
+++ b/langchain/output_parsers/regex_dict.py
@@ -7,11 +7,14 @@ from langchain.schema import BaseOutputParser
 
 
 class RegexDictParser(BaseOutputParser):
-    """Class to parse the output into a dictionary."""
+    """Parse the output of an LLM call into a Dictionary using a regex."""
 
     regex_pattern: str = r"{}:\s?([^.'\n']*)\.?"  # : :meta private:
+    """The regex pattern to use to parse the output."""
     output_key_to_format: Dict[str, str]
+    """The keys to use for the output."""
     no_update_value: Optional[str] = None
+    """The default key to use for the output."""
 
     @property
     def _type(self) -> str:
diff --git a/langchain/output_parsers/retry.py b/langchain/output_parsers/retry.py
index e4af4b23f65..0f2c4f7ac1c 100644
--- a/langchain/output_parsers/retry.py
+++ b/langchain/output_parsers/retry.py
@@ -45,7 +45,9 @@ class RetryOutputParser(BaseOutputParser[T]):
     """
 
     parser: BaseOutputParser[T]
+    """The parser to use to parse the output."""
     retry_chain: LLMChain
+    """The LLMChain to use to retry the completion."""
 
     @classmethod
     def from_llm(
@@ -58,6 +60,15 @@ class RetryOutputParser(BaseOutputParser[T]):
         return cls(parser=parser, retry_chain=chain)
 
     def parse_with_prompt(self, completion: str, prompt_value: PromptValue) -> T:
+        """Parse the output of an LLM call using a wrapped parser.
+
+        Args:
+            completion: The chain completion to parse.
+            prompt_value: The prompt to use to parse the completion.
+
+        Returns:
+            The parsed completion.
+        """
         try:
             parsed_completion = self.parser.parse(completion)
         except OutputParserException:
@@ -101,6 +112,16 @@ class RetryWithErrorOutputParser(BaseOutputParser[T]):
         parser: BaseOutputParser[T],
         prompt: BasePromptTemplate = NAIVE_RETRY_WITH_ERROR_PROMPT,
     ) -> RetryWithErrorOutputParser[T]:
+        """Create a RetryWithErrorOutputParser from an LLM.
+
+        Args:
+            llm: The LLM to use to retry the completion.
+            parser: The parser to use to parse the output.
+            prompt: The prompt to use to retry the completion.
+
+        Returns:
+            A RetryWithErrorOutputParser.
+        """
         chain = LLMChain(llm=llm, prompt=prompt)
         return cls(parser=parser, retry_chain=chain)
 
diff --git a/langchain/output_parsers/structured.py b/langchain/output_parsers/structured.py
index 40ff75174a8..5733c896f6a 100644
--- a/langchain/output_parsers/structured.py
+++ b/langchain/output_parsers/structured.py
@@ -15,9 +15,14 @@ line_template = '\t"{name}": {type}  // {description}'
 
 
 class ResponseSchema(BaseModel):
+    """A schema for a response from a structured output parser."""
+
     name: str
+    """The name of the schema."""
     description: str
+    """The description of the schema."""
     type: str = "string"
+    """The type of the response."""
 
 
 def _get_sub_string(schema: ResponseSchema) -> str:
@@ -27,7 +32,10 @@ def _get_sub_string(schema: ResponseSchema) -> str:
 
 
 class StructuredOutputParser(BaseOutputParser):
+    """Parse the output of an LLM call to a structured output."""
+
     response_schemas: List[ResponseSchema]
+    """The schemas for the response."""
 
     @classmethod
     def from_response_schemas(
@@ -36,8 +44,7 @@ class StructuredOutputParser(BaseOutputParser):
         return cls(response_schemas=response_schemas)
 
     def get_format_instructions(self, only_json: bool = False) -> str:
-        """
-        Method to get the format instructions for the output parser.
+        """Get format instructions for the output parser.
 
         example:
         ```python
@@ -63,7 +70,7 @@ class StructuredOutputParser(BaseOutputParser):
         print(parser.get_format_instructions())
 
         output:
-        # The output should be a markdown code snippet formatted in the following
+        # The output should be a Markdown code snippet formatted in the following
         # schema, including the leading and trailing "```json" and "```":
         #
         # ```json
@@ -73,7 +80,7 @@ class StructuredOutputParser(BaseOutputParser):
         # }
 
         Args:
-            only_json (bool): If True, only the json in the markdown code snippet
+            only_json (bool): If True, only the json in the Markdown code snippet
                 will be returned, without the introducing text. Defaults to False.
         """
         schema_str = "\n".join(
diff --git a/langchain/schema/output_parser.py b/langchain/schema/output_parser.py
index ba800a667b8..be76baf86f6 100644
--- a/langchain/schema/output_parser.py
+++ b/langchain/schema/output_parser.py
@@ -73,7 +73,7 @@ class BaseOutputParser(BaseLLMOutputParser, ABC, Generic[T]):
         """Parse a single string model output into some structure.
 
         Args:
-            text: String output of language model.
+            text: String output of a language model.
 
         Returns:
             Structured output.
@@ -88,7 +88,7 @@ class BaseOutputParser(BaseLLMOutputParser, ABC, Generic[T]):
         the prompt to do so.
 
         Args:
-            completion: String output of language model.
+            completion: String output of a language model.
             prompt: Input PromptValue.
 
         Returns: