feat(python): Account for SurrealDB Python API updates (handle both SurrealDB and AsyncSurrealDB classes) in read_database

[alexander-beedie]

The SurrealDB Python API has been updated (at the end of last year) in conjunction with their latest major release, splitting out SurrealDB and AsyncSurrealDB classes.

This PR updates our SurrealDBCursorProxy shim so that it can handle both the sync and async variants of the client object.

Tested (thoroughly!) locally with the sync and async clients (executing the async loop under both asyncio and uvloop).

Example

Synchronous (SurrealDB):

def surreal_query_to_frame(url: str, query: str):
    with SurrealDB(url) as client:
        client.use(namespace="test", database="test")
        client.sign_in(username="elvis", password="pr3sley")
        return pl.read_database(query=query, connection=client)

surreal_query_to_frame(
    url="http://127.0.0.1:8000",
    query="SELECT * FROM person",
)
# shape: (3, 4)
# ┌─────────────────────────────┬───────────┬─────────────┬──────┐
# │ id                          ┆ pass      ┆ tags        ┆ user │
# │ ---                         ┆ ---       ┆ ---         ┆ ---  │
# │ object                      ┆ str       ┆ list[str]   ┆ str  │
# ╞═════════════════════════════╪═══════════╪═════════════╪══════╡
# │ person:1ck3rnl84dmpvzgoy8bc ┆ more_safe ┆ ["awesome"] ┆ you  │
# │ person:2r90lxkxoezisazaiudl ┆ very_safe ┆ ["polars"]  ┆ me   │
# │ person:hecx1ieleqg3d646x6ia ┆ p4ssw0rd  ┆ ["data"]    ┆ him  │
# └─────────────────────────────┴───────────┴─────────────┴──────┘

Aynchronous (AsyncSurrealDB):

async def surreal_query_to_frame_async(url: str, query: str):
    async with AsyncSurrealDB(url) as client:
        await client.use(namespace="test", database="test")
        await client.sign_in(username="elvis", password="pr3sley")
        return pl.read_database(query=query, connection=client)

import uvloop  # or asyncio

uvloop.run(
  surreal_query_to_frame_async(
    url="http://127.0.0.1:8000",
    query="SELECT * FROM person",
))
# shape: (3, 4)
# ┌─────────────────────────────┬───────────┬─────────────┬──────┐
# │ id                          ┆ pass      ┆ tags        ┆ user │
# │ ---                         ┆ ---       ┆ ---         ┆ ---  │
# │ object                      ┆ str       ┆ list[str]   ┆ str  │
# ╞═════════════════════════════╪═══════════╪═════════════╪══════╡
# │ person:1ck3rnl84dmpvzgoy8bc ┆ more_safe ┆ ["awesome"] ┆ you  │
# │ person:2r90lxkxoezisazaiudl ┆ very_safe ┆ ["polars"]  ┆ me   │
# │ person:hecx1ieleqg3d646x6ia ┆ p4ssw0rd  ┆ ["data"]    ┆ him  │
# └─────────────────────────────┴───────────┴─────────────┴──────┘

[codecov]

Codecov Report

Attention: Patch coverage is 61.53846% with 5 lines in your changes missing coverage. Please review.

Project coverage is 79.77%. Comparing base (3696e53) to head (8493e7e).
Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
py-polars/polars/io/database/_cursor_proxies.py	66.66%	4 Missing ⚠️
py-polars/polars/io/database/functions.py	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #20799      +/-   ##
==========================================
- Coverage   79.78%   79.77%   -0.01%     
==========================================
  Files        1561     1561              
  Lines      222015   222038      +23     
  Branches     2533     2534       +1     
==========================================
+ Hits       177135   177140       +5     
- Misses      44296    44314      +18     
  Partials      584      584              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.