Images¶

The shared image pipeline behind the Image and ImageBackground components. Remote sources are downloaded on a background thread with an in-memory LRU cache, a disk cache, and request deduplication (many views asking for the same URL trigger one download). Platform handlers decode the cached file downsampled to the view's bounds, so oversized photos don't pin full-resolution bitmaps in memory.

Most apps never call this module directly; the Image component's placeholder_color, on_load, and on_error props cover the common cases:

import pythonnative as pn

pn.Image(
    source="https://example.com/photo.jpg",
    placeholder_color="#E2E8F0",
    on_load=lambda: print("loaded"),
    on_error=lambda message: print("failed:", message),
    style={"width": 200, "height": 120},
)

Shared image pipeline: async fetch with memory and disk caching.

Every platform's Image handler routes remote sources through this module. The pipeline downloads on a daemon thread (never blocking the UI), stores the raw bytes in a platform-appropriate disk cache keyed by URL hash, deduplicates concurrent requests for the same URL, and keeps a small in-memory LRU of recently fetched byte payloads so scrolling back to an image doesn't touch the filesystem again.

Decoding stays platform-native (BitmapFactory / UIImage / PhotoImage): callbacks receive a local file path, which each handler decodes with its platform's downsampling facilities.

Callbacks are delivered on the platform main thread via call_on_main_thread, so handlers can touch native views directly.

Functions:

Name	Description
`fetch`	Fetch `url` into the cache and deliver a local file path.
`clear_cache`	Empty the memory cache and delete all cached image files.

fetch ¶

fetch(url: str, on_ready: Callable[[str], None], on_error: Optional[Callable[[str], None]] = None) -> None

Fetch url into the cache and deliver a local file path.

Cache hits (memory or disk) still deliver asynchronously-consistent behavior but resolve without a network round trip. Concurrent requests for the same URL share one download. Callbacks run on the platform main thread.

Parameters:

Name	Type	Description	Default
`url`	`str`	The `http(s)` image URL.	required
`on_ready`	`Callable[[str], None]`	Called with the local file path once available.	required
`on_error`	`Optional[Callable[[str], None]]`	Called with an error message if the download fails.	`None`

clear_cache ¶

clear_cache() -> None

Empty the memory cache and delete all cached image files.