From ecabd9e0c5f7e356c056f44f016d192d61d8caeb Mon Sep 17 00:00:00 2001 From: Simon Willison Date: Sun, 23 Nov 2025 11:49:44 -0800 Subject: [PATCH] Documentation for new list/tuple mode Refs #672 --- docs/python-api.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/python-api.rst b/docs/python-api.rst index 47cb30b..bb2b3ee 100644 --- a/docs/python-api.rst +++ b/docs/python-api.rst @@ -810,6 +810,35 @@ You can delete all the existing rows in the table before inserting the new recor Pass ``analyze=True`` to run ``ANALYZE`` against the table after inserting the new records. +.. _python_api_insert_lists: + +Inserting data from a list or tuple iterator +-------------------------------------------- + +As an alternative to passing an iterator of dictionaries, you can pass an iterator of lists or tuples. The first item yielded by the iterator must be a list or tuple of string column names, and subsequent items should be lists or tuples of values: + +.. code-block:: python + + db["creatures"].insert_all([ + ["name", "species"], + ["Cleo", "dog"], + ["Lila", "chicken"], + ["Bants", "chicken"], + ]) + +This also works with generators: + +.. code-block:: python + + def creatures(): + yield "id", "name", "city" + yield 1, "Cleo", "San Francisco" + yield 2, "Lila", "Los Angeles" + + db["creatures"].insert_all(creatures()) + +Tuples and lists are both supported. + .. _python_api_insert_replace: Insert-replacing data