tlc.discovery¶

Public discovery-invalidation API.

tlc.discovery is the call-site opt-in for announcing a 3LC object mutation that happened outside the indexer’s view — a table written by an external tool, a run directory deleted from a script. notify_write and notify_delete take just the object’s URL; the affected discovery scopes (the locations a scanner polls) are deduced from the URL’s shape, so a running indexer here revisits immediately and indexers in other processes pick the change up on their next scan.

This is discovery freshness — keeping 3LC’s knowledge of which objects exist current. The indexing mechanism that consumes it is internal.

Module Contents¶

Functions¶

Function

Description

defer_notifications

Coalesce auto-path discovery notifications, flushing the deduped set once on outermost exit.

mute_notifications

Suppress the auto-path discovery notifications emitted within this block.

notify_delete

Announce that content was deleted at url.

notify_write

Announce that content was written at url.

API¶

defer_notifications() → Generator[None, None, None]¶

Coalesce auto-path discovery notifications, flushing the deduped set once on outermost exit.

Object writes/deletes inside the block are recorded rather than fired; on exit of the outermost defer_notifications block the deduplicated set is flushed in insertion order. Nested blocks coalesce into the single outermost flush. The flush runs in a finally, so coalesced notifications are not lost if the block raises. Affects only the auto path; the explicit tlc.discovery calls always fire immediately.

mute_notifications() → Generator[None, None, None]¶

Suppress the auto-path discovery notifications emitted within this block.

Object writes/deletes inside the block announce nothing. Mute wins over defer_notifications() — a muted block nested inside a deferred one drops its notifications entirely rather than coalescing them. The explicit tlc.discovery.notify_write() / tlc.discovery.notify_delete() calls are unaffected: they always fire immediately.

notify_delete(
url: str | Url,
) → None¶

Announce that content was deleted at url.

Parameters:

url – The URL of the 3LC object that was removed. Tables and runs in the canonical project layout (…/<project>/datasets/<dataset>/tables/<table> or …/<project>/runs/<run>) refresh their enclosing project directory and the scan root above it; any other location (configs included) refreshes the object’s containing directory. The layout is deduced from the URL.

Raises:

  • RuntimeError – If no authentication is active — notifications write change markers, so the library must be activated (see tlc.auth).

  • OSError – If a change marker cannot be written (for example a read-only or unreachable location). Scopes marked before the failure stay marked, and a running indexer in this process is still notified.

  • ValueError – If url is a relative URL — it has no addressable discovery scope; pass an absolute URL.

notify_write(
url: str | Url,
) → None¶

Announce that content was written at url.

Parameters:

url – The URL of the 3LC object that was created or updated. Tables and runs in the canonical project layout (…/<project>/datasets/<dataset>/tables/<table> or …/<project>/runs/<run>) refresh their enclosing project directory and the scan root above it; any other location (configs included) refreshes the object’s containing directory. The layout is deduced from the URL.

Raises:

  • RuntimeError – If no authentication is active — notifications write change markers, so the library must be activated (see tlc.auth).

  • OSError – If a change marker cannot be written (for example a read-only or unreachable location). Scopes marked before the failure stay marked, and a running indexer in this process is still notified.

  • ValueError – If url is a relative URL — it has no addressable discovery scope; pass an absolute URL.