--functions can take filenames, can be used multiple times (#681)

Closes #659

The --functions option now accepts:
- File paths ending in .py (e.g., --functions my_funcs.py)
- Multiple invocations (e.g., --functions foo.py --functions 'def bar(): ...')
- Inline Python code (existing behavior)

Implementation follows the same pattern as llm's --functions flag
(simonw/llm@a880c123).

Changes:
- Added multiple=True to --functions Click option in query, bulk, and memory commands
- Modified _register_functions() to detect and read .py files
- Updated _maybe_register_functions() to iterate over multiple function sources
- Removed unused bytes/bytearray handling
- Added comprehensive tests for file paths and multiple invocations
- Updated documentation with examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Shorter help for --functions

---------

Co-authored-by: Claude <noreply@anthropic.com>

tests/test_cli.py

@@ -806,6 +806,77 @@ def test_hidden_functions_are_hidden(db_path):
     assert "_two" not in functions
 
 
+def test_query_functions_from_file(db_path, tmp_path):
+    # Create a temporary file with function definitions
+    functions_file = tmp_path / "my_functions.py"
+    functions_file.write_text(TEST_FUNCTIONS)
+
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            db_path,
+            "select zero(), one(1), two(1, 2)",
+            "--functions",
+            str(functions_file),
+        ],
+    )
+    assert result.exit_code == 0
+    assert json.loads(result.output.strip()) == [
+        {"zero()": 0, "one(1)": 1, "two(1, 2)": 3}
+    ]
+
+
+def test_query_functions_file_not_found(db_path):
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            db_path,
+            "select zero()",
+            "--functions",
+            "nonexistent.py",
+        ],
+    )
+    assert result.exit_code == 1
+    assert "File not found: nonexistent.py" in result.output
+
+
+def test_query_functions_multiple_invocations(db_path):
+    # Test using --functions multiple times
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            db_path,
+            "select triple(2), quadruple(2)",
+            "--functions",
+            "def triple(x):\n    return x * 3",
+            "--functions",
+            "def quadruple(x):\n    return x * 4",
+        ],
+    )
+    assert result.exit_code == 0
+    assert json.loads(result.output.strip()) == [{"triple(2)": 6, "quadruple(2)": 8}]
+
+
+def test_query_functions_file_and_inline(db_path, tmp_path):
+    # Test combining file and inline code
+    functions_file = tmp_path / "file_funcs.py"
+    functions_file.write_text("def triple(x):\n    return x * 3")
+
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            db_path,
+            "select triple(2), quadruple(2)",
+            "--functions",
+            str(functions_file),
+            "--functions",
+            "def quadruple(x):\n    return x * 4",
+        ],
+    )
+    assert result.exit_code == 0
+    assert json.loads(result.output.strip()) == [{"triple(2)": 6, "quadruple(2)": 8}]
+
+
 LOREM_IPSUM_COMPRESSED = (
     b"x\x9c\xed\xd1\xcdq\x03!\x0c\x05\xe0\xbb\xabP\x01\x1eW\x91\xdc|M\x01\n\xc8\x8e"
     b"f\xf83H\x1e\x97\x1f\x91M\x8e\xe9\xe0\xdd\x96\x05\x84\xf4\xbek\x9fRI\xc7\xf2J"

tests/test_cli_bulk.py

@@ -45,6 +45,32 @@ def test_cli_bulk(test_db_and_path):
     ] == list(db["example"].rows)
 
 
+def test_cli_bulk_multiple_functions(test_db_and_path):
+    db, db_path = test_db_and_path
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            "bulk",
+            db_path,
+            "insert into example (id, name) values (:id, myupper(mylower(:name)))",
+            "-",
+            "--nl",
+            "--functions",
+            "myupper = lambda s: s.upper()",
+            "--functions",
+            "mylower = lambda s: s.lower()",
+        ],
+        input='{"id": 3, "name": "ThReE"}\n{"id": 4, "name": "FoUr"}\n',
+    )
+    assert result.exit_code == 0, result.output
+    assert [
+        {"id": 1, "name": "One"},
+        {"id": 2, "name": "Two"},
+        {"id": 3, "name": "THREE"},
+        {"id": 4, "name": "FOUR"},
+    ] == list(db["example"].rows)
+
+
 def test_cli_bulk_batch_size(test_db_and_path):
     db, db_path = test_db_and_path
     proc = subprocess.Popen(

tests/test_cli_memory.py

@@ -307,6 +307,22 @@ def test_memory_functions():
     assert result.output.strip() == '[{"hello()": "Hello"}]'
 
 
+def test_memory_functions_multiple():
+    result = CliRunner().invoke(
+        cli.cli,
+        [
+            "memory",
+            "select triple(2), quadruple(2)",
+            "--functions",
+            "def triple(x):\n    return x * 3",
+            "--functions",
+            "def quadruple(x):\n    return x * 4",
+        ],
+    )
+    assert result.exit_code == 0
+    assert result.output.strip() == '[{"triple(2)": 6, "quadruple(2)": 8}]'
+
+
 def test_memory_return_db(tmpdir):
     # https://github.com/simonw/sqlite-utils/issues/643
     from sqlite_utils.cli import cli