Debugger-Safe Object Representation#

Problem#

When a Python debugger (debugpy / VS Code) hits a breakpoint, it suspends all Python threads and calls repr() on every local variable in the current frame. If __repr__ triggers async work through the LanceDBBackgroundEventLoop, the representation call blocks waiting for a thread that the debugger has already suspended — causing the debug session to freeze indefinitely. 1 2

The exact failure chain:

1. Debugger stops at a breakpoint and suspends all Python threads.
2. Debugger renders local variables by calling repr().
3. The old LanceDBConnection.__repr__ read the read_consistency_interval property.
4. That property called LOOP.run(...).result().
5. LanceDBBackgroundEventLoop's thread is suspended, so LOOP.run() deadlocks.

The symptom manifests immediately after lancedb.connect() because that is the first point at which a connection object exists as a local variable. The same problem existed in LanceTable.__repr__, which also accessed read_consistency_interval through the connection. 1

An earlier instance of this class of bug: LanceTable.__repr__ previously included version={self.version}, which triggers a round-trip to get the current table version — another property backed by LOOP.run(). 3

Rule: __repr__ Must Be Side-Effect-Free#

The invariant is: __repr__ must never call LOOP.run() or perform any I/O. Debuggers, REPLs, and logging infrastructure all assume repr() is instant and non-blocking.

Current Implementations#

LanceDBConnection.__repr__ 4 — reads only self._conn.uri, a plain string attribute set during construction:

LanceDBConnection(uri='/path/to/db')

LanceTable.__repr__ 5 — reads only self.name and self._conn, both stored as instance attributes:

LanceTable(name='my_table', _conn=LanceDBConnection(uri='...'))

RemoteDBConnection.__repr__ 6 — reads only self.db_name, stored at construction time:

RemoteConnect(name=my-database)

None of these access read_consistency_interval, version, or any other async-backed property.

Key Source Files#

The regression test that enforces the no-LOOP-in-repr contract lives in test_sync_repr_does_not_use_background_loop: it monkeypatches LOOP.run to raise, then asserts that both repr(db) and repr(table) still succeed.

Fix History#

Guidelines When Adding Fields to __repr__#

Only include fields that:

• Are stored as plain attributes at construction time (e.g., self.uri, self.name).
• Do not go through LOOP.run(), any await, network I/O, or file I/O.

If you want to expose a computed/async value in a string representation, add a separate method (e.g., describe()) that callers invoke explicitly — never embed it in __repr__.

Setting PYDEVD_UNBLOCK_THREADS_TIMEOUT=0 in the debugger environment is a workaround that prevents indefinite blocking, but it does not fix the underlying issue. 1