duck.utils.fileio.test_fileio

Tests for FileIOStream and AsyncFileIOStream.

Run directly: python test_fileio.py

No external test runner or duck installation required — all duck dependencies are stubbed inline before the module is imported.

Module Contents

Functions

assert_eq	Raises AssertionError when a != b.
fresh_cache	Clears the shared FILE_CACHE so each test starts clean.
make_temp_file	Writes content to a named temporary file and returns its path.
run	Runs a single test function and records the outcome.
test_async_context_manager	AsyncFileIOStream works as an async context manager.
test_async_hook_on_read	Async hooks registered with hook() are awaited on AsyncFileIOStream reads.
test_async_hook_on_write	Async hooks registered with hook() are awaited on AsyncFileIOStream writes.
test_async_read_after_write_served_from_cache	A read of the exact written slice immediately after an async write is served from cache without a disk round-trip.
test_async_seeked_full_read_independent_slot	AsyncFileIOStream: a seeked full read is cached under its own pos key.
test_async_seeked_write_patches_cache	AsyncFileIOStream: a seeked write patches overlapping cache entries.
test_async_write_updates_cache	AsyncFileIOStream.write caches the written slice under (write_pos, len(data)).
test_hook_invalid_event_raises	hook() raises ValueError for unknown event names.
test_is_modified_false_after_read_unchanged	is_modified returns False immediately after a read with no external changes.
test_is_modified_false_before_read	is_modified returns False before any read or write has taken place.
test_is_modified_true_after_external_write	is_modified returns True when another process modifies the file after a read.
test_lru_eviction	When maxkeys is exceeded the least-recently-used entry is evicted.
test_mixed_sync_and_async_hooks	Sync and async hooks can both be registered on the same event and both fire in registration order.
test_multiple_seek_positions_all_cached	Repeated reads at multiple offsets are all individually cached and served on a second pass without touching the disk.
test_on_read_and_write_hooks_independent	on_read hooks do not fire on writes and vice versa.
test_on_read_hook_fires_on_cache_hit	on_read hook fires even when data is served from cache.
test_on_read_hook_fires_on_cache_miss	on_read hook is called when data is read fresh from disk.
test_on_read_multiple_hooks	Multiple on_read hooks all fire in registration order.
test_on_write_hook_fires	on_write hook is called after a successful write.
test_on_write_hook_receives_correct_stream	The stream argument passed to the hook is the stream that fired it.
test_read_raises_if_not_open	read() raises ValueError when called before open().
test_seek_and_tell	seek moves the file pointer; tell reports the new position.
test_seeked_full_read_uses_own_cache_slot	A full read after seek() is cached under its own (pos, size) key so the same data is returned on a second read without touching the disk.
test_seeked_partial_read_independent_slot	A partial read from a seeked position occupies its own cache slot and does not collide with a pos-0 read of the same size.
test_seeked_write_evicts_boundary_partial_overlaps	A write that partially overlaps a cached entry at a boundary evicts that entry rather than storing corrupted data.
test_seeked_write_patches_overlapping_cached_entries	A seeked write patches cached entries in memory without a disk re-read.
test_sync_cache_miss_on_mtime_change	When the file changes on disk, cache_get returns None (stale eviction).
test_sync_cache_mtime_updated_on_write	_cache_mtime on the stream is updated after a write so is_modified is accurate without requiring a subsequent read.
test_sync_open_and_read	FileIOStream opens a file and reads the correct bytes.
test_sync_read_after_write_served_from_cache	A read of the exact written slice immediately after a write is served from the cache without a disk round-trip.
test_sync_read_populates_cache	After a sync read, the result is stored in FILE_CACHE.
test_sync_read_serves_cache_hit	A second read returns the cached bytes without touching the descriptor.
test_sync_write_cache_entry_has_fresh_mtime	The mtime stored in cache entries after a write matches the post-flush mtime.
test_sync_write_updates_cache	Writing stores the written slice in the cache under (write_pos, len(data)) and patches any overlapping entries in memory.
test_to_async_preserves_hooks	to_async_fileio_stream copies hooks to the new stream.
test_total_read_bytes_accumulates	_total_read_bytes grows correctly across reads with different sizes.

Data

FAIL
PASS
_results

API

duck.utils.fileio.test_fileio.FAIL

‘\x1b[91mFAIL\x1b[0m’

duck.utils.fileio.test_fileio.PASS

‘\x1b[92mPASS\x1b[0m’

duck.utils.fileio.test_fileio._results: list[tuple[str, bool, str]]

[]

duck.utils.fileio.test_fileio.assert_eq(a, b, msg='')

Raises AssertionError when a != b.

Parameters:

• a – Actual value.

• b – Expected value.

• msg – Optional context shown on failure.

duck.utils.fileio.test_fileio.fresh_cache()

Clears the shared FILE_CACHE so each test starts clean.

duck.utils.fileio.test_fileio.make_temp_file(content: bytes = b'Hello, Duck!') → str

Writes content to a named temporary file and returns its path.

Parameters:

content – Bytes to write into the file.

Returns:

Absolute path to the temporary file.

duck.utils.fileio.test_fileio.run(name: str, fn)

Runs a single test function and records the outcome.

Parameters:

• name – Human-readable test name shown in the summary.

• fn – Zero-argument callable or async coroutine function.

async duck.utils.fileio.test_fileio.test_async_context_manager()

AsyncFileIOStream works as an async context manager.

async duck.utils.fileio.test_fileio.test_async_hook_on_read()

Async hooks registered with hook() are awaited on AsyncFileIOStream reads.

async duck.utils.fileio.test_fileio.test_async_hook_on_write()

Async hooks registered with hook() are awaited on AsyncFileIOStream writes.

async duck.utils.fileio.test_fileio.test_async_read_after_write_served_from_cache()

A read of the exact written slice immediately after an async write is served from cache without a disk round-trip.

async duck.utils.fileio.test_fileio.test_async_seeked_full_read_independent_slot()

AsyncFileIOStream: a seeked full read is cached under its own pos key.

async duck.utils.fileio.test_fileio.test_async_seeked_write_patches_cache()

AsyncFileIOStream: a seeked write patches overlapping cache entries.

async duck.utils.fileio.test_fileio.test_async_write_updates_cache()

AsyncFileIOStream.write caches the written slice under (write_pos, len(data)).

duck.utils.fileio.test_fileio.test_hook_invalid_event_raises()

hook() raises ValueError for unknown event names.

duck.utils.fileio.test_fileio.test_is_modified_false_after_read_unchanged()

is_modified returns False immediately after a read with no external changes.

duck.utils.fileio.test_fileio.test_is_modified_false_before_read()

is_modified returns False before any read or write has taken place.

duck.utils.fileio.test_fileio.test_is_modified_true_after_external_write()

is_modified returns True when another process modifies the file after a read.

duck.utils.fileio.test_fileio.test_lru_eviction()

When maxkeys is exceeded the least-recently-used entry is evicted.

async duck.utils.fileio.test_fileio.test_mixed_sync_and_async_hooks()

Sync and async hooks can both be registered on the same event and both fire in registration order.

duck.utils.fileio.test_fileio.test_multiple_seek_positions_all_cached()

Repeated reads at multiple offsets are all individually cached and served on a second pass without touching the disk.

This is the key benefit of pos-keyed caching: high-seek workloads accumulate warm entries across many positions.

duck.utils.fileio.test_fileio.test_on_read_and_write_hooks_independent()

on_read hooks do not fire on writes and vice versa.

duck.utils.fileio.test_fileio.test_on_read_hook_fires_on_cache_hit()

on_read hook fires even when data is served from cache.

duck.utils.fileio.test_fileio.test_on_read_hook_fires_on_cache_miss()

on_read hook is called when data is read fresh from disk.

duck.utils.fileio.test_fileio.test_on_read_multiple_hooks()

Multiple on_read hooks all fire in registration order.

duck.utils.fileio.test_fileio.test_on_write_hook_fires()

on_write hook is called after a successful write.

duck.utils.fileio.test_fileio.test_on_write_hook_receives_correct_stream()

The stream argument passed to the hook is the stream that fired it.

duck.utils.fileio.test_fileio.test_read_raises_if_not_open()

read() raises ValueError when called before open().

duck.utils.fileio.test_fileio.test_seek_and_tell()

seek moves the file pointer; tell reports the new position.

duck.utils.fileio.test_fileio.test_seeked_full_read_uses_own_cache_slot()

A full read after seek() is cached under its own (pos, size) key so the same data is returned on a second read without touching the disk.

duck.utils.fileio.test_fileio.test_seeked_partial_read_independent_slot()

A partial read from a seeked position occupies its own cache slot and does not collide with a pos-0 read of the same size.

duck.utils.fileio.test_fileio.test_seeked_write_evicts_boundary_partial_overlaps()

A write that partially overlaps a cached entry at a boundary evicts that entry rather than storing corrupted data.

duck.utils.fileio.test_fileio.test_seeked_write_patches_overlapping_cached_entries()

A seeked write patches cached entries in memory without a disk re-read.

Cached entries that overlap the written region are updated in place; non-overlapping entries are left untouched.

duck.utils.fileio.test_fileio.test_sync_cache_miss_on_mtime_change()

When the file changes on disk, cache_get returns None (stale eviction).

duck.utils.fileio.test_fileio.test_sync_cache_mtime_updated_on_write()

_cache_mtime on the stream is updated after a write so is_modified is accurate without requiring a subsequent read.

duck.utils.fileio.test_fileio.test_sync_open_and_read()

FileIOStream opens a file and reads the correct bytes.

duck.utils.fileio.test_fileio.test_sync_read_after_write_served_from_cache()

A read of the exact written slice immediately after a write is served from the cache without a disk round-trip.

duck.utils.fileio.test_fileio.test_sync_read_populates_cache()

After a sync read, the result is stored in FILE_CACHE.

duck.utils.fileio.test_fileio.test_sync_read_serves_cache_hit()

A second read returns the cached bytes without touching the descriptor.

duck.utils.fileio.test_fileio.test_sync_write_cache_entry_has_fresh_mtime()

The mtime stored in cache entries after a write matches the post-flush mtime.

duck.utils.fileio.test_fileio.test_sync_write_updates_cache()

Writing stores the written slice in the cache under (write_pos, len(data)) and patches any overlapping entries in memory.

duck.utils.fileio.test_fileio.test_to_async_preserves_hooks()

to_async_fileio_stream copies hooks to the new stream.

duck.utils.fileio.test_fileio.test_total_read_bytes_accumulates()

_total_read_bytes grows correctly across reads with different sizes.