Install & Compatibility
Where this runs
tested against v0.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 20.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.1s · import 0.000s · 21MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ShardDataset
✓ from iden import ShardDataset
Commonly used for defining and interacting with a sharded dataset.
ShardLoader
✓ from iden import ShardLoader
The primary class for lazy loading and iterating over data shards for model training.
The quickstart demonstrates initializing a `ShardDataset` with paths to data shards and then using a `ShardLoader` to iterate over these shards in batches. The `ShardLoader` implements lazy loading, fetching data only as required, which is crucial for training machine learning models on large datasets. The example includes a dummy shard creation for demonstration purposes.
import os
from iden import ShardDataset, ShardLoader
# Placeholder for creating dummy shards
def create_dummy_shards(base_path, num_shards=3, items_per_shard=10):
os.makedirs(base_path, exist_ok=True)
for i in range(num_shards):
shard_file = os.path.join(base_path, f'shard_{i}.txt')
with open(shard_file, 'w') as f:
for j in range(items_per_shard):
f.write(f'data_item_from_shard_{i}_idx_{j}\n')
print(f'Created {num_shards} dummy shards in {base_path}')
# Setup (replace with your actual shard paths)
SHARD_BASE_PATH = './iden_data_shards'
create_dummy_shards(SHARD_BASE_PATH)
# 1. Initialize ShardDataset with paths to your data shards
# In a real scenario, this list would come from your data storage system
shard_paths = [os.path.join(SHARD_BASE_PATH, f'shard_{i}.txt') for i in range(3)]
dataset = ShardDataset(shard_paths)
# 2. Initialize ShardLoader for lazy loading
# batch_size and num_workers are typical parameters for data loading
loader = ShardLoader(dataset, batch_size=2, shuffle=True, num_workers=0)
# 3. Iterate through the data in batches
print("\nLoading data using ShardLoader:")
for epoch in range(2):
print(f"--- Epoch {epoch + 1} ---")
for i, batch in enumerate(loader):
print(f" Batch {i}: {batch}")
if i >= 2: # Limit output for quickstart
break
if epoch == 0: # Ensure cleanup after first epoch for quickstart clarity
import shutil
shutil.rmtree(SHARD_BASE_PATH)
print(f"Cleaned up dummy shards in {SHARD_BASE_PATH}")
break # Exit after one epoch for quickstart
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/non_existent_shard.npy'
The `ShardDataset` was initialized with a path to a shard file that does not exist at the specified location. This often happens due to incorrect path configurations or data movement.
fixVerify all paths passed to `ShardDataset` or `ShardLoader` refer to actual, accessible data files. Use absolute paths or ensure your working directory is correctly set relative to the shard locations.
IndexError: list index out of range (during iteration of ShardLoader)
This error typically occurs if there's a mismatch between the expected number of items in a shard and what's actually available, or an issue with the indexing logic within a custom `ShardDataset` implementation when accessing individual samples.
fixReview the `__len__` and `__getitem__` methods of your `ShardDataset` implementation. Ensure `__len__` accurately reports the total number of samples and `__getitem__` handles all valid indices without going out of bounds for any given shard.
MemoryError: Unable to allocate ... (during batch processing)
Despite lazy loading at the shard level, if individual data samples within a shard are excessively large, or the `batch_size` is too high, the system might still run out of memory when loading a batch into RAM.
fixReduce the `batch_size` in `ShardLoader`. Consider further splitting very large data samples into smaller units or implementing more granular lazy loading within the `ShardDataset`'s `__getitem__` method if samples themselves are huge.
Upgrade
Version history
0.4.1latest on PyPI · released Jun 15, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher.
Resources
No resource links recorded.