arize 8.0.0a22__py3-none-any.whl → 8.0.0b0__py3-none-any.whl

arize/experiments/functions.py

@@ -1,3 +1,5 @@
+"""Experiment utility functions for task execution and annotation."""
+
 import dataclasses
 import functools
 import inspect
@@ -5,6 +7,7 @@ import json
 import logging
 import traceback
 from binascii import hexlify
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import ExitStack
 from copy import deepcopy
 from datetime import date, datetime, time, timedelta, timezone
@@ -12,16 +15,10 @@ from enum import Enum
 from itertools import product
 from pathlib import Path
 from typing import (
+    TYPE_CHECKING,
     Any,
-    Awaitable,
-    Callable,
-    Dict,
-    List,
     Literal,
-    Mapping,
-    Sequence,
-    Tuple,
-    Type,
+    TypeAlias,
     Union,
     cast,
     get_args,
@@ -37,9 +34,10 @@ from openinference.semconv.trace import (
 )
 from opentelemetry.context import Context
 from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import Span
 from opentelemetry.trace import Status, StatusCode, Tracer
-from typing_extensions import TypeAlias
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk.trace import Span
 
 from arize.experiments.evaluators.base import Evaluator, Evaluators
 from arize.experiments.evaluators.executors import (
@@ -62,9 +60,7 @@ from arize.experiments.types import (
     _TaskSummary,
 )
 
-RateLimitErrors: TypeAlias = Union[
-    Type[BaseException], Sequence[Type[BaseException]]
-]
+RateLimitErrors: TypeAlias = type[BaseException] | Sequence[type[BaseException]]
 
 logger = logging.getLogger(__name__)
 
@@ -81,8 +77,8 @@ def run_experiment(
     concurrency: int = 3,
     exit_on_error: bool = False,
 ) -> pd.DataFrame:
-    """
-    Run an experiment on a dataset.
+    """Run an experiment on a dataset.
+
     Args:
         experiment_name (str): The name for the experiment.
         experiment_id (str): The ID for the experiment.
@@ -94,6 +90,7 @@ def run_experiment(
         evaluators (Optional[Evaluators]): Optional evaluators to assess the task.
         concurrency (int): The number of concurrent tasks to run. Default is 3.
         exit_on_error (bool): Whether to exit on error. Default is False.
+
     Returns:
         pd.DataFrame: The results of the experiment.
     """
@@ -127,25 +124,25 @@ def run_experiment(
             try:
                 bound_task_args = _bind_task_signature(task_signature, example)
                 _output = task(*bound_task_args.args, **bound_task_args.kwargs)
-                if isinstance(_output, Awaitable):
-                    sync_error_message = (
-                        "Task is async and cannot be run within an existing event loop. "
-                        "Consider the following options:\n\n"
-                        "1. Pass in a synchronous task callable.\n"
-                        "2. Use `nest_asyncio.apply()` to allow nesting event loops."
-                    )
-                    raise RuntimeError(sync_error_message)
-                else:
-                    output = _output
             except BaseException as exc:
                 if exit_on_error:
-                    raise exc
+                    raise
                 span.record_exception(exc)
                 status = Status(
                     StatusCode.ERROR, f"{type(exc).__name__}: {exc}"
                 )
                 error = exc
                 _print_experiment_error(exc, example_id=example.id, kind="task")
+            else:
+                if isinstance(_output, Awaitable):
+                    sync_error_message = (
+                        "Task is async and cannot be run within an existing event loop. "
+                        "Consider the following options:\n\n"
+                        "1. Pass in a synchronous task callable.\n"
+                        "2. Use `nest_asyncio.apply()` to allow nesting event loops."
+                    )
+                    raise TypeError(sync_error_message)
+                output = _output
 
             output = jsonify(output)
             if example.input:
@@ -171,25 +168,27 @@ def run_experiment(
             )
             span.set_status(status)
 
-        assert isinstance(
+        if not isinstance(
             output, (dict, list, str, int, float, bool, type(None))
-        ), "Output must be JSON serializable"
+        ):
+            raise TypeError(
+                f"Output must be JSON serializable, got {type(output).__name__}"
+            )
 
-        exp_run = ExperimentRun(
+        return ExperimentRun(
             experiment_id=experiment_name,
             repetition_number=1,
-            start_time=_decode_unix_nano(cast(int, span.start_time)),
+            start_time=_decode_unix_nano(cast("int", span.start_time)),
             end_time=(
-                _decode_unix_nano(cast(int, span.end_time))
+                _decode_unix_nano(cast("int", span.end_time))
                 if span.end_time
-                else datetime.now()
+                else datetime.now(tz=timezone.utc)
             ),
             dataset_example_id=example.id,
             output=output,  # type:ignore
             error=repr(error) if error else None,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type: ignore
         )
-        return exp_run
 
     async def async_run_experiment(example: Example) -> ExperimentRun:
         output = None
@@ -212,7 +211,7 @@ def run_experiment(
                     output = _output
             except BaseException as exc:
                 if exit_on_error:
-                    raise exc
+                    raise
                 span.record_exception(exc)
                 status = Status(
                     StatusCode.ERROR, f"{type(exc).__name__}: {exc}"
@@ -243,27 +242,29 @@ def run_experiment(
             )
             span.set_status(status)
 
-        assert isinstance(
+        if not isinstance(
             output, (dict, list, str, int, float, bool, type(None))
-        ), "Output must be JSON serializable"
+        ):
+            raise TypeError(
+                f"Output must be JSON serializable, got {type(output).__name__}"
+            )
 
-        exp_run = ExperimentRun(
+        return ExperimentRun(
             experiment_id=experiment_name,
             repetition_number=1,
-            start_time=_decode_unix_nano(cast(int, span.start_time)),
+            start_time=_decode_unix_nano(cast("int", span.start_time)),
             end_time=(
-                _decode_unix_nano(cast(int, span.end_time))
+                _decode_unix_nano(cast("int", span.end_time))
                 if span.end_time
-                else datetime.now()
+                else datetime.now(tz=timezone.utc)
             ),
             dataset_example_id=example.id,
             output=output,  # type: ignore
             error=repr(error) if error else None,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type: ignore
         )
-        return exp_run
 
-    _errors: Tuple[Type[BaseException], ...]
+    _errors: tuple[type[BaseException], ...]
     if not isinstance(rate_limit_errors, Sequence):
         _errors = (rate_limit_errors,)  # type: ignore
     else:
@@ -370,9 +371,9 @@ def evaluate_experiment(
     tracer: Tracer | None = None,
     resource: Resource | None = None,
     exit_on_error: bool = False,
-):
-    """
-    Evaluate the results of an experiment using the provided evaluators.
+) -> list[ExperimentEvaluationRun]:
+    """Evaluate the results of an experiment using the provided evaluators.
+
     Args:
         experiment_name (str): The name of the experiment.
         examples (Sequence[Example]): The examples to evaluate.
@@ -383,6 +384,7 @@ def evaluate_experiment(
         tracer (Optional[Tracer]): Optional tracer for tracing the evaluation.
         resource (Optional[Resource]): Optional resource for the evaluation.
         exit_on_error (bool): Whether to exit on error. Default is False.
+
     Returns:
         List[ExperimentEvaluationRun]: The evaluation results.
     """
@@ -409,7 +411,7 @@ def evaluate_experiment(
     md = {"experiment_name": experiment_name}
 
     def sync_eval_run(
-        obj: Tuple[Example, ExperimentRun, Evaluator],
+        obj: tuple[Example, ExperimentRun, Evaluator],
     ) -> ExperimentEvaluationRun:
         example, experiment_run, evaluator = obj
         result: EvaluationResult | None = None
@@ -435,7 +437,7 @@ def evaluate_experiment(
                 )
             except BaseException as exc:
                 if exit_on_error:
-                    raise exc
+                    raise
                 span.record_exception(exc)
                 status = Status(
                     StatusCode.ERROR, f"{type(exc).__name__}: {exc}"
@@ -453,13 +455,13 @@ def evaluate_experiment(
             span.set_attribute(OPENINFERENCE_SPAN_KIND, root_span_kind)
             span.set_status(status)
 
-        eval_run = ExperimentEvaluationRun(
+        return ExperimentEvaluationRun(
             experiment_run_id=experiment_run.id,
-            start_time=_decode_unix_nano(cast(int, span.start_time)),
+            start_time=_decode_unix_nano(cast("int", span.start_time)),
             end_time=(
-                _decode_unix_nano(cast(int, span.end_time))
+                _decode_unix_nano(cast("int", span.end_time))
                 if span.end_time
-                else datetime.now()
+                else datetime.now(tz=timezone.utc)
             ),
             name=evaluator.name,
             annotator_kind=evaluator.kind,
@@ -467,10 +469,9 @@ def evaluate_experiment(
             result=result,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type:ignore
         )
-        return eval_run
 
     async def async_eval_run(
-        obj: Tuple[Example, ExperimentRun, Evaluator],
+        obj: tuple[Example, ExperimentRun, Evaluator],
     ) -> ExperimentEvaluationRun:
         example, experiment_run, evaluator = obj
         result: EvaluationResult | None = None
@@ -496,7 +497,7 @@ def evaluate_experiment(
                 )
             except BaseException as exc:
                 if exit_on_error:
-                    raise exc
+                    raise
                 span.record_exception(exc)
                 status = Status(
                     StatusCode.ERROR, f"{type(exc).__name__}: {exc}"
@@ -513,13 +514,13 @@ def evaluate_experiment(
                 )
             span.set_attribute(OPENINFERENCE_SPAN_KIND, root_span_kind)
             span.set_status(status)
-        eval_run = ExperimentEvaluationRun(
+        return ExperimentEvaluationRun(
             experiment_run_id=experiment_run.id,
-            start_time=_decode_unix_nano(cast(int, span.start_time)),
+            start_time=_decode_unix_nano(cast("int", span.start_time)),
             end_time=(
-                _decode_unix_nano(cast(int, span.end_time))
+                _decode_unix_nano(cast("int", span.end_time))
                 if span.end_time
-                else datetime.now()
+                else datetime.now(tz=timezone.utc)
             ),
             name=evaluator.name,
             annotator_kind=evaluator.kind,
@@ -527,9 +528,8 @@ def evaluate_experiment(
             result=result,
             trace_id=_str_trace_id(span.get_span_context().trace_id),  # type:ignore
         )
-        return eval_run
 
-    _errors: Tuple[Type[BaseException], ...]
+    _errors: tuple[type[BaseException], ...]
     if not isinstance(rate_limit_errors, Sequence):
         _errors = (rate_limit_errors,) if rate_limit_errors is not None else ()
     else:
@@ -563,9 +563,9 @@ def evaluate_experiment(
 
 def _add_metadata_to_output_df(
     output_df: pd.DataFrame,
-    eval_runs: List[ExperimentEvaluationRun],
+    eval_runs: list[ExperimentEvaluationRun],
     evaluator_name: str,
-):
+) -> object:
     for eval_run in eval_runs:
         if eval_run.result is None:
             continue
@@ -589,7 +589,7 @@ def _add_metadata_to_output_df(
     return output_df
 
 
-def _dataframe_to_examples(dataset: pd.DataFrame) -> List[Example]:
+def _dataframe_to_examples(dataset: pd.DataFrame) -> list[Example]:
     for column in dataset.columns:
         if pd.api.types.is_datetime64_any_dtype(dataset[column]):
             dataset[column] = dataset[column].astype(str)
@@ -637,8 +637,7 @@ def _bind_task_signature(
         parameter_name = next(iter(params))
         if parameter_name in parameter_mapping:
             return sig.bind(parameter_mapping[parameter_name])
-        else:
-            return sig.bind(parameter_mapping["dataset_row"])
+        return sig.bind(parameter_mapping["dataset_row"])
     return sig.bind_partial(
         **{
             name: parameter_mapping[name]
@@ -650,7 +649,7 @@ def _bind_task_signature(
 def _evaluators_by_name(
     obj: Evaluators | None,
 ) -> Mapping[EvaluatorName, Evaluator]:
-    evaluators_by_name: Dict[EvaluatorName, Evaluator] = {}
+    evaluators_by_name: dict[EvaluatorName, Evaluator] = {}
     if obj is None:
         return evaluators_by_name
     if isinstance(obj, Mapping):
@@ -676,7 +675,10 @@ def _evaluators_by_name(
                 raise ValueError(f"Two evaluators have the same name: {name}")
             evaluators_by_name[name] = evaluator
     else:
-        assert not isinstance(obj, Mapping) and not isinstance(obj, Sequence)
+        if isinstance(obj, (Mapping, Sequence)):
+            raise TypeError(
+                "Expected a single evaluator, got a mapping or sequence"
+            )
         evaluator = (
             create_evaluator()(obj) if not isinstance(obj, Evaluator) else obj
         )
@@ -688,9 +690,7 @@ def _evaluators_by_name(
 
 
 def get_func_name(fn: Callable[..., Any]) -> str:
-    """
-    Makes a best-effort attempt to get the name of the function.
-    """
+    """Makes a best-effort attempt to get the name of the function."""
     if isinstance(fn, functools.partial):
         return fn.func.__qualname__
     if hasattr(fn, "__qualname__") and not fn.__qualname__.endswith("<lambda>"):
@@ -705,12 +705,8 @@ def _print_experiment_error(
     example_id: str,
     kind: Literal["evaluator", "task"],
 ) -> None:
-    """
-    Prints an experiment error.
-    """
-    display_error = RuntimeError(
-        f"{kind} failed for example id {repr(example_id)}"
-    )
+    """Prints an experiment error."""
+    display_error = RuntimeError(f"{kind} failed for example id {example_id!r}")
     display_error.__cause__ = error
     formatted_exception = "".join(
         traceback.format_exception(
@@ -729,8 +725,7 @@ def _str_trace_id(id_: int) -> str:
 
 
 def get_tqdm_progress_bar_formatter(title: str) -> str:
-    """
-    Returns a progress bar formatter for use with tqdm.
+    """Returns a progress bar formatter for use with tqdm.
 
     Args:
         title (str): The title of the progress bar, displayed as a prefix.
@@ -757,23 +752,32 @@ EVALUATOR = OpenInferenceSpanKindValues.EVALUATOR.value
 JSON = OpenInferenceMimeTypeValues.JSON
 
 
-def get_result_attr(r, attr, default=None):
+def get_result_attr(r: object, attr: str, default: object = None) -> object:
+    """Get an attribute from a result object, with fallback to default.
+
+    Args:
+        r: An object with a `result` attribute.
+        attr: The attribute name to retrieve from the result.
+        default: Value to return if result is None or attribute not found. Defaults to None.
+
+    Returns:
+        The attribute value if found, otherwise the default value.
+    """
     return getattr(r.result, attr, default) if r.result else default
 
 
 def transform_to_experiment_format(
-    experiment_runs: List[Dict[str, Any]] | pd.DataFrame,
+    experiment_runs: list[dict[str, object]] | pd.DataFrame,
     task_fields: ExperimentTaskResultFieldNames,
-    evaluator_fields: Dict[str, EvaluationResultFieldNames] | None = None,
+    evaluator_fields: dict[str, EvaluationResultFieldNames] | None = None,
 ) -> pd.DataFrame:
-    """
-    Transform a DataFrame to match the format returned by run_experiment().
+    """Transform a DataFrame to match the format returned by run_experiment().
 
     Args:
-        df: Input DataFrame containing experiment results
-        task_columns: Column mapping for task results
-        evaluator_columns: Dictionary mapping evaluator names (str)
-            to their column mappings (EvaluationResultColumnNames)
+        experiment_runs: Input list of dictionaries or DataFrame containing experiment results
+        task_fields: Field name mapping for task results
+        evaluator_fields: Dictionary mapping evaluator names (str)
+            to their field name mappings (EvaluationResultFieldNames)
 
     Returns:
         DataFrame in the format matching run_experiment() output
@@ -818,7 +822,7 @@ def _add_evaluator_columns(
     evaluator_name: str,
     column_names: EvaluationResultFieldNames,
 ) -> None:
-    """Helper function to add evaluator columns to output DataFrame"""
+    """Helper function to add evaluator columns to output DataFrame."""
     # Add score if specified
     if column_names.score and column_names.score in input_df.columns:
         output_df[f"eval.{evaluator_name}.score"] = input_df[column_names.score]
@@ -862,10 +866,8 @@ def _add_evaluator_columns(
             output_df[output_col] = output_vals
 
 
-def jsonify(obj: Any) -> Any:
-    """
-    Coerce object to be json serializable.
-    """
+def jsonify(obj: object) -> object:
+    """Coerce object to be json serializable."""
     if isinstance(obj, Enum):
         return jsonify(obj.value)
     if isinstance(obj, (str, int, float, bool)) or obj is None:
@@ -901,20 +903,20 @@ def jsonify(obj: Any) -> Any:
     if hasattr(obj, "model_dump") and callable(obj.model_dump):
         # pydantic v2
         try:
-            d = obj
-            assert isinstance(d, dict)
-        except BaseException:
+            d = obj.model_dump()
+            if isinstance(d, dict):
+                return jsonify(d)
+        except Exception:  # noqa: S110
+            # If model_dump fails or returns non-dict, fall through to next handler
             pass
-        else:
-            return jsonify(d)
     if hasattr(obj, "dict") and callable(obj.dict):
         # pydantic v1
         try:
             d = obj.dict()
-            assert isinstance(d, dict)
-        except BaseException:
+            if isinstance(d, dict):
+                return jsonify(d)
+        except Exception:  # noqa: S110
+            # If dict fails or returns non-dict, fall through to next handler
             pass
-        else:
-            return jsonify(d)
     cls = obj.__class__
     return f"<{cls.__module__}.{cls.__name__} object>"

arize/experiments/tracing.py

@@ -1,44 +1,46 @@
+"""Experiment tracing functionality for capturing execution context."""
+
 from __future__ import annotations
 
 import inspect
 import json
+from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
 from contextlib import contextmanager
 from contextvars import ContextVar
 from threading import Lock
 from typing import (
+    TYPE_CHECKING,
     Any,
-    Callable,
-    Iterable,
-    Iterator,
-    List,
-    Mapping,
-    Sequence,
     cast,
 )
 
 import numpy as np
 from openinference.semconv import trace
 from openinference.semconv.trace import DocumentAttributes, SpanAttributes
-from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.trace import INVALID_TRACE_ID
 from typing_extensions import assert_never
 from wrapt import apply_patch, resolve_path, wrap_function_wrapper
 
+if TYPE_CHECKING:
+    from opentelemetry.sdk.resources import Resource
+
 
 class SpanModifier:
-    """
-    A class that modifies spans with the specified resource attributes.
-    """
+    """A class that modifies spans with the specified resource attributes."""
 
     __slots__ = ("_resource",)
 
     def __init__(self, resource: Resource) -> None:
+        """Initialize the span modifier with resource attributes.
+
+        Args:
+            resource: OpenTelemetry Resource containing attributes to merge.
+        """
         self._resource = resource
 
     def modify_resource(self, span: ReadableSpan) -> None:
-        """
-        Takes a span and merges in the resource attributes specified in the constructor.
+        """Takes a span and merges in the resource attributes specified in the constructor.
 
         Args:
           span: ReadableSpan: the span to modify
@@ -55,8 +57,16 @@ _ACTIVE_MODIFIER: ContextVar[SpanModifier | None] = ContextVar(
 
 
 def override_span(
-    init: Callable[..., None], span: ReadableSpan, args: Any, kwargs: Any
+    init: Callable[..., None], span: ReadableSpan, args: object, kwargs: object
 ) -> None:
+    """Override span initialization to apply active span modifiers.
+
+    Args:
+        init: The original span initialization function.
+        span: The span being initialized.
+        args: Positional arguments for the init function.
+        kwargs: Keyword arguments for the init function.
+    """
     init(*args, **kwargs)
     if isinstance(span_modifier := _ACTIVE_MODIFIER.get(None), SpanModifier):
         span_modifier.modify_resource(span)
@@ -91,8 +101,7 @@ def _monkey_patch_span_init() -> Iterator[None]:
 
 @contextmanager
 def capture_spans(resource: Resource) -> Iterator[SpanModifier]:
-    """
-    A context manager that captures spans and modifies them with the specified resources.
+    """A context manager that captures spans and modifies them with the specified resources.
 
     Args:
       resource: Resource: The resource to merge into the spans created within the context.
@@ -139,10 +148,10 @@ JSON_STRING_ATTRIBUTES = (
     TOOL_PARAMETERS,
 )
 
-SEMANTIC_CONVENTIONS: List[str] = sorted(
+SEMANTIC_CONVENTIONS: list[str] = sorted(
     # e.g. "input.value", "llm.token_count.total", etc.
     (
-        cast(str, getattr(klass, attr))
+        cast("str", getattr(klass, attr))
         for name in dir(trace)
         if name.endswith("Attributes")
         and inspect.isclass(klass := getattr(trace, name))
@@ -162,14 +171,13 @@ def flatten(
     recurse_on_sequence: bool = False,
     json_string_attributes: Sequence[str] | None = None,
 ) -> Iterator[tuple[str, Any]]:
-    """
-    Flatten a nested dictionary or a sequence of dictionaries into a list of
-    key value pairs. If `recurse_on_sequence` is True, then the function will
-    also recursively flatten nested sequences of dictionaries. If
-    `json_string_attributes` is provided, then the function will interpret the
-    attributes in the list as JSON strings and convert them into dictionaries.
-    The `prefix` argument is used to prefix the keys in the output list, but
-    it's mostly used internally to facilitate recursion.
+    """Flatten a nested dictionary or a sequence of dictionaries into a list of key value pairs.
+
+    If `recurse_on_sequence` is True, then the function will also recursively flatten
+    nested sequences of dictionaries. If `json_string_attributes` is provided, then the
+    function will interpret the attributes in the list as JSON strings and convert them
+    into dictionaries. The `prefix` argument is used to prefix the keys in the output list,
+    but it's mostly used internally to facilitate recursion.
     """
     if isinstance(obj, Mapping):
         yield from _flatten_mapping(
@@ -192,11 +200,11 @@ def flatten(
 
 
 def has_mapping(sequence: Iterable[Any]) -> bool:
-    """
-    Check if a sequence contains a dictionary. We don't flatten sequences that
-    only contain primitive types, such as strings, integers, etc. Conversely,
-    we'll only un-flatten digit sub-keys if it can be interpreted the index of
-    an array of dictionaries.
+    """Check if a sequence contains a dictionary.
+
+    We don't flatten sequences that only contain primitive types, such as strings,
+    integers, etc. Conversely, we'll only un-flatten digit sub-keys if it can be
+    interpreted the index of an array of dictionaries.
     """
     return any(isinstance(item, Mapping) for item in sequence)
 
@@ -209,13 +217,13 @@ def _flatten_mapping(
     json_string_attributes: Sequence[str] | None = None,
     separator: str = ".",
 ) -> Iterator[tuple[str, Any]]:
-    """
-    Flatten a nested dictionary into a list of key value pairs. If `recurse_on_sequence`
-    is True, then the function will also recursively flatten nested sequences of dictionaries.
-    If `json_string_attributes` is provided, then the function will interpret the attributes
-    in the list as JSON strings and convert them into dictionaries. The `prefix` argument is
-    used to prefix the keys in the output list, but it's mostly used internally to facilitate
-    recursion.
+    """Flatten a nested dictionary into a list of key value pairs.
+
+    If `recurse_on_sequence` is True, then the function will also recursively flatten
+    nested sequences of dictionaries. If `json_string_attributes` is provided, then the
+    function will interpret the attributes in the list as JSON strings and convert them
+    into dictionaries. The `prefix` argument is used to prefix the keys in the output list,
+    but it's mostly used internally to facilitate recursion.
     """
     for key, value in mapping.items():
         prefixed_key = f"{prefix}{separator}{key}" if prefix else key
@@ -254,13 +262,13 @@ def _flatten_sequence(
     json_string_attributes: Sequence[str] | None = None,
     separator: str = ".",
 ) -> Iterator[tuple[str, Any]]:
-    """
-    Flatten a sequence of dictionaries into a list of key value pairs. If `recurse_on_sequence`
-    is True, then the function will also recursively flatten nested sequences of dictionaries.
-    If `json_string_attributes` is provided, then the function will interpret the attributes
-    in the list as JSON strings and convert them into dictionaries. The `prefix` argument is
-    used to prefix the keys in the output list, but it's mostly used internally to facilitate
-    recursion.
+    """Flatten a sequence of dictionaries into a list of key value pairs.
+
+    If `recurse_on_sequence` is True, then the function will also recursively flatten
+    nested sequences of dictionaries. If `json_string_attributes` is provided, then the
+    function will interpret the attributes in the list as JSON strings and convert them
+    into dictionaries. The `prefix` argument is used to prefix the keys in the output list,
+    but it's mostly used internally to facilitate recursion.
     """
     if isinstance(sequence, str) or not has_mapping(sequence):
         yield prefix, sequence