From 0db34a890fe0bd5e9ac87bb7a5710f563df87033 Mon Sep 17 00:00:00 2001
From: David Montague <35119617+dmontagu@users.noreply.github.com>
Date: Mon, 14 Aug 2023 10:16:55 -0600
Subject: [PATCH] Add a docstring to the tuple_schema function

---
 python/pydantic_core/core_schema.py | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/python/pydantic_core/core_schema.py b/python/pydantic_core/core_schema.py
index f766674f3..d03853a0b 100644
--- a/python/pydantic_core/core_schema.py
+++ b/python/pydantic_core/core_schema.py
@@ -1456,7 +1456,7 @@ def tuple_variable_schema(
         min_length: The value must be a tuple with at least this many items
         max_length: The value must be a tuple with at most this many items
         strict: The value must be a tuple with exactly this many items
-        ref: optional unique identifier of the schema, used to reference the schema in other places
+        ref: Optional unique identifier of the schema, used to reference the schema in other places
         metadata: Any other information you want to include with the schema, not used by pydantic-core
         serialization: Custom serialization schema
     """
@@ -1495,6 +1495,30 @@ def tuple_schema(
     metadata: Any = None,
     serialization: IncExSeqOrElseSerSchema | None = None,
 ) -> TuplePositionalSchema:
+    """
+    Returns a schema that matches a tuple of schemas, with an optional variadic item, e.g.:
+
+    ```py
+    from pydantic_core import SchemaValidator, core_schema
+
+    schema = core_schema.tuple_schema(
+        [core_schema.int_schema(), core_schema.str_schema(), core_schema.float_schema()],
+        variadic_item_index=1
+    )
+    v = SchemaValidator(schema)
+    assert v.validate_python((1, 'hello', 'world', 1.5)) == (1, 'hello', 'world', 1.5)
+    ```
+
+    Args:
+        items_schema: The value must be a tuple with items that match these schemas
+        variadic_item_index: The index of the schema in `items_schema` to be treated as variadic (following PEP 646)
+        min_length: The value must be a tuple with at least this many items
+        max_length: The value must be a tuple with at most this many items
+        strict: The value must be a tuple with exactly this many items
+        ref: Optional unique identifier of the schema, used to reference the schema in other places
+        metadata: Any other information you want to include with the schema, not used by pydantic-core
+        serialization: Custom serialization schema
+    """
     return _dict_not_none(
         type='tuple',
         items_schema=items_schema,