Rename ParallelStoreReader to BlockStoreReader (#44)

* Rename ParallelStoreReader to BlockStoreReader

* Rename ParallelStoreReader to BlockStoreReader

Author: maxrjones

docs/api/readers.md

@@ -1,3 +1,3 @@
 ::: obspec_utils.readers.BufferedStoreReader
 ::: obspec_utils.readers.EagerStoreReader
-::: obspec_utils.readers.ParallelStoreReader
+::: obspec_utils.readers.BlockStoreReader

docs/design/caching.md

@@ -75,7 +75,7 @@ During data access:
 
 **Store-level caching is appropriate here because:**
 
-- Chunks may be re-read by different computations
+- Blocks may be re-read by different computations
 - Cache should be shared across all consumers of the store
 - Lifecycle is independent of any single reader
 
@@ -102,7 +102,7 @@ reader.close()
 
 **Characteristics:**
 
-- Fetches file using parallel `get_ranges()` for speed
+- Fetches file using concurrent `get_ranges()` for speed
 - Caches in `BytesIO` buffer
 - Cache is isolated to this reader instance
 - Memory freed on `close()` or context manager exit
@@ -113,26 +113,26 @@ reader.close()
 - Small-to-medium files that fit in memory
 - When you'll read most of the file anyway
 
-### Reader-Level: ParallelStoreReader
+### Reader-Level: BlockStoreReader
 
-`ParallelStoreReader` uses chunk-based LRU caching:
+`BlockStoreReader` uses block-based LRU caching:
 
 ```python
-from obspec_utils.readers import ParallelStoreReader
+from obspec_utils.readers import BlockStoreReader
 
-reader = ParallelStoreReader(
+reader = BlockStoreReader(
     store, "file.nc",
-    chunk_size=256 * 1024,      # 256 KB chunks
-    max_cached_chunks=64,       # Up to 64 chunks cached
+    block_size=256 * 1024,      # 256 KB blocks
+    max_cached_blocks=64,       # Up to 64 blocks cached
 )
 
-# Chunks fetched on demand via get_ranges()
+# Blocks fetched on demand via get_ranges()
 data = reader.read(1000)
 ```
 
 **Characteristics:**
 
-- Bounded memory usage: `chunk_size * max_cached_chunks`
+- Bounded memory usage: `block_size * max_cached_blocks`
 - LRU eviction when cache is full
 - Good for sparse/random access patterns
 
@@ -152,8 +152,8 @@ from obspec_utils.readers import BufferedStoreReader
 reader = BufferedStoreReader(store, "file.nc", buffer_size=1024 * 1024)
 
 # Sequential reads benefit from buffering
-while chunk := reader.read(4096):
-    process(chunk)
+while block := reader.read(4096):
+    process(block)
 ```
 
 **Characteristics:**
@@ -354,8 +354,8 @@ results = dask.compute(*tasks)
 |---------------|-------------------|
 | Parse HDF5/NetCDF file | `EagerStoreReader` |
 | Sequential streaming | `BufferedStoreReader` |
-| Sparse random access | `ParallelStoreReader` |
-| Unknown pattern, large file | `ParallelStoreReader` |
+| Sparse random access | `BlockStoreReader` |
+| Unknown pattern, large file | `BlockStoreReader` |
 | Small file, repeated access | `EagerStoreReader` |
 
 ### Should I use store-level caching?
@@ -372,7 +372,7 @@ results = dask.compute(*tasks)
 
 ### SplittingReadableStore
 
-`SplittingReadableStore` accelerates `get()` by splitting large requests into parallel `get_ranges()`:
+`SplittingReadableStore` accelerates `get()` by splitting large requests into concurrent `get_ranges()`:
 
 ```python
 from obspec_utils.wrappers import SplittingReadableStore
@@ -384,25 +384,25 @@ fast_store = SplittingReadableStore(
 )
 ```
 
-This extracts the parallel fetching logic from `EagerStoreReader` into a composable wrapper. It composes naturally with `CachingReadableStore`:
+This extracts the concurrent fetching logic from `EagerStoreReader` into a composable wrapper. It composes naturally with `CachingReadableStore`:
 
 ```python
 from obspec_utils.wrappers import CachingReadableStore, SplittingReadableStore
 
-# Compose: fast parallel fetches + caching
+# Compose: fast concurrent fetches + caching
 store = S3Store(bucket="my-bucket")
 store = SplittingReadableStore(store)  # Split large fetches
 store = CachingReadableStore(store)    # Cache results
 
-# First get(): parallel fetch -> cache
+# First get(): concurrent fetch -> cache
 # Second get(): served from cache
 ```
 
 **Characteristics:**
 
 - Only affects `get()` and `get_async()` - range requests pass through unchanged
 - Requires `head()` support to determine file size (falls back to single request otherwise)
-- Tuned for cloud storage (12 MB chunks, 18 concurrent requests by default)
+- Tuned for cloud storage (12 MB blocks, 18 concurrent requests by default)
 
 ## Summary
 

docs/index.md

@@ -9,10 +9,10 @@ Utilities for interacting with object storage, based on [obspec](https://github.
 - **`obspec_utils.protocols`**: Minimal protocols ([`ReadableStore`][obspec_utils.protocols.ReadableStore],
     [`ReadableFile`][obspec_utils.protocols.ReadableFile]) defining read-only interfaces for object storage access
 - **`obspec_utils.readers`**: File-like interfaces ([`BufferedStoreReader`][obspec_utils.readers.BufferedStoreReader],
-    [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader], [`ParallelStoreReader`][obspec_utils.readers.ParallelStoreReader])
+    [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader], [`BlockStoreReader`][obspec_utils.readers.BlockStoreReader])
     for reading from object stores
 - **`obspec_utils.stores`**: Alternative store implementations (e.g., [`AiohttpStore`][obspec_utils.stores.AiohttpStore] for generic HTTP access)
-- **`obspec_utils.wrappers`**: Composable store wrappers for caching, tracing, and parallel fetching
+- **`obspec_utils.wrappers`**: Composable store wrappers for caching, tracing, and concurrent fetching
 - **`obspec_utils.registry`**: [`ObjectStoreRegistry`][obspec_utils.registry.ObjectStoreRegistry] for managing multiple stores and resolving URLs
 
 ## Design Philosophy
@@ -84,7 +84,7 @@ data = await store.get_range_async(path, start=0, end=1000)
 The file handlers provide file-like interfaces (read, seek, tell) for reading from object stores. They work with **any** [`ReadableStore`][obspec_utils.protocols.ReadableStore] implementation:
 
 ```python
-from obspec_utils.readers import BufferedStoreReader, EagerStoreReader, ParallelStoreReader
+from obspec_utils.readers import BufferedStoreReader, EagerStoreReader, BlockStoreReader
 
 # Works with obstore
 from obstore.store import S3Store
@@ -104,9 +104,9 @@ reader.seek(0)           # Seek back to start
 eager_reader = EagerStoreReader(store, "file.bin")
 data = eager_reader.readall()
 
-# Parallel reader uses get_ranges() for efficient multi-chunk fetching with LRU cache
-parallel_reader = ParallelStoreReader(store, "file.bin", chunk_size=256*1024)
-data = parallel_reader.read(1000)
+# Block reader uses get_ranges() for efficient multi-chunk fetching with LRU cache
+block_reader = BlockStoreReader(store, "file.bin", chunk_size=256*1024)
+data = block_reader.read(1000)
 ```
 
 ## Contributing

src/obspec_utils/obspec.py

@@ -2,13 +2,14 @@
 
 New code should import from:
 - `obspec_utils.protocols` for ReadableStore, ReadableFile
-- `obspec_utils.readers` for BufferedStoreReader, EagerStoreReader, ParallelStoreReader
+- `obspec_utils.readers` for BufferedStoreReader, EagerStoreReader, BlockStoreReader
 """
 
 import warnings
 
 from obspec_utils.protocols import ReadableFile, ReadableStore
 from obspec_utils.readers import (
+    BlockStoreReader,
     BufferedStoreReader,
     EagerStoreReader,
     ParallelStoreReader,
@@ -17,15 +18,16 @@
 warnings.warn(
     "Importing from obspec_utils.obspec is deprecated. "
     "Please use 'from obspec_utils.protocols import ReadableStore, ReadableFile' "
-    "and 'from obspec_utils.readers import BufferedStoreReader, EagerStoreReader, ParallelStoreReader' instead.",
+    "and 'from obspec_utils.readers import BufferedStoreReader, EagerStoreReader, BlockStoreReader' instead.",
     DeprecationWarning,
     stacklevel=2,
 )
 
 __all__ = [
-    "ReadableFile",
-    "ReadableStore",
+    "BlockStoreReader",
     "BufferedStoreReader",
     "EagerStoreReader",
     "ParallelStoreReader",
+    "ReadableFile",
+    "ReadableStore",
 ]

src/obspec_utils/protocols/_protocols.py

@@ -61,7 +61,7 @@ class ReadableFile(Protocol):
 
     The `obspec_utils` readers ([`BufferedStoreReader`][obspec_utils.readers.BufferedStoreReader],
     [`EagerStoreReader`][obspec_utils.readers.EagerStoreReader],
-    [`ParallelStoreReader`][obspec_utils.readers.EagerStoreReader]) all implement this protocol,
+    [`BlockStoreReader`][obspec_utils.readers.BlockStoreReader]) all implement this protocol,
     allowing them to be used interchangeably wherever a [`ReadableFile`][obspec_utils.protocols.ReadableFile] is expected.
 
     !!! Warning

src/obspec_utils/readers/__init__.py

@@ -6,9 +6,10 @@
 
 from obspec_utils.readers._buffered import BufferedStoreReader
 from obspec_utils.readers._eager import EagerStoreReader
-from obspec_utils.readers._parallel import ParallelStoreReader
+from obspec_utils.readers._block import BlockStoreReader, ParallelStoreReader
 
 __all__ = [
+    "BlockStoreReader",
     "BufferedStoreReader",
     "EagerStoreReader",
     "ParallelStoreReader",