Docs and type hints disagree with runtime for several public APIs

Description

Several public docs / type annotations disagree with the actual runtime behavior on current master (TinyDB 4.9.0, 4aa5311). These look like documentation/typing fixes rather than behavior changes — listing them together for triage. Happy to split into separate PRs if preferred.

Verified against code + existing tests (no behavior change proposed unless noted).

1. Query.test type annotation / docstring vs runtime

Annotation (tinydb/queries.py): func: Callable[[Mapping], bool]
Docstring: “passing the dict as the first argument”

Runtime: path is resolved first; func is called on the field value, with *args:

# docs/usage.rst style — works at runtime today
User = Query()
User.name.test(lambda s: s == 'John')
User.age.test(lambda v, mn, mx: mn <= v <= mx, 0, 21)

Covered by tests/test_queries.py (test_custom, test_custom_with_params).

Suggestion: annotate something closer to Callable[..., bool] (or a more precise overload) and fix the docstring to say “field value”, matching usage.rst.

2. operations.add excludes str in the type hint

Annotation (tinydb/operations.py): n: Union[int, float]
Docs (docs/usage.rst): “also works for strings”
Tests (tests/test_operations.py): add('char', 'xyz')
Runtime: 'a' + 'xyz' → 'axyz'

Suggestion: widen the annotation (e.g. include str) to match docs/tests.

3. Broken update_multiple example in docs/usage.rst

>>> db.update_multiple([
...     ({'int': 2}, where('char') == 'a'),
...     ({delete('int'), where('char') == 'b'),
... ])

The second tuple has mismatched braces ({delete('int'), where(...))). Correct form is a 2-tuple like the tests use: (delete('int'), where('char') == 'b').

4. Package docstring invents an _id field

tinydb/__init__.py example shows search results like [{'data': 5, '_id': 1}].
Runtime documents expose the ID as Document.doc_id, not an _id key in the mapping (tinydb/table.py).

5. Table.get docstring vs doc_ids= return

Docstring says the document doesn’t exist → None / “exactly one document”.
For doc_ids=..., implementation (and overloads) return list[Document], including [] when nothing matches (tests/test_tinydb.py asserts db.get(doc_ids=[99]) == []).

6. Query.search docstring says re.match, code uses re.search

Param docs: “regex flags to pass to re.match”
Implementation calls re.search(...). (Query.matches correctly documents re.match.)

7. usage.rst: get “probably a random” match

Docs say if multiple documents match, “probably a random one” is returned.
Implementation returns the first match in dict.items() order (insertion-ordered on modern Python), not random.

Suggested tests / checks for a fix PR

• Keep existing runtime tests; adjust annotations so mypy accepts the documented Query.test(..., *args) and add(field, 'str') shapes
• Fix the doctest/example for update_multiple
• Optionally a tiny docs smoke check that the package docstring example matches .doc_id usage

Happy to send a docs/typing-only PR once this looks correct to you.