Bug: Wrong/Incomplete typing on `Surreal` methods

[Wouterkoorn]

Describe the bug

Most methods return annotations are List[Dict[str, Any]].
This is correct when querying for (potentially) multiple items like Surreal.select("table"), without supplying a specific ID.
This is incorrect when querying with a specific ID, like Surreal.select("table:id"). Instead of a list of dicts, it directly returns a single dict.

Another thing missing in the typing of Optional. When select or delete get supplied a non-existent ID, the method returns None.

These issues only seem to be the case with Surreal (WS/RPC client), and not with SurrealHTTP, which does always return a list.

Steps to reproduce

async def example(db: Surreal) -> None:
    print(type(await db.create("table:id")))
    print(type(await db.update("table:id", {"field": "value"})))
    print(type(await db.select("table:id")))
    print(type(await db.delete("table:id")))
    print(await db.select("table:wrong_id"))
    print(await db.delete("table:wrong_id"))

results in:

<class 'dict'>
<class 'dict'>
<class 'dict'>
<class 'dict'>
None
None

While all methods are typed to return type of <class 'list'>

Expected behaviour

I can see a few options to resolve this, listed below with their pros and cons:

1. Change the typing of the affected methods, e.g. Optional[Union[Dict[str, Any], List[Dict[str, Any]]]]
   + This is a non-breaking change, only affecting type annotations
2. Use type overloading, annotating either list or dict
   - This will only work if the id becomes a separate optional parameter - breaking change
   + More precise typing than Union
3. Only return list, as it is currently typed
   - This would not change the typing, but instead adjust the return value to the existing type - breaking change
   + This would make the Surreal and SurrealHTTP classes more aligned, returning the same types.

My opinion would be to implement idea number 1 now, as it is non-breaking. And keep the other ideas open for a breaking version bump (1.0?)

Please feel free to suggest other ideas as well.

And note, I'm more than happy to create the PR once we've decided on the desired solution.

SurrealDB version

1.3.1 for linux on x86_64

surrealdb.py version

0.3.2 (latest as of 2024-04-02)

Contact Details

Ideally in the issue itself. Otherwise: 6qmf6te8@duck.com

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

[Wouterkoorn]

For the first proposed solution I've created a PR, as it is the most trivial: #98