Refactor: improve sub-module organization (#40)

* Refactor: improve sub-module organization

* Improve cross-references

Author: maxrjones

docs/api/aiohttp.md

@@ -1 +1 @@
-::: obspec_utils.aiohttp.AiohttpStore
+::: obspec_utils.stores.AiohttpStore

docs/api/cache.md

@@ -1 +1 @@
-::: obspec_utils.cache.CachingReadableStore
+::: obspec_utils.wrappers.CachingReadableStore

docs/api/obspec.md

@@ -0,0 +1,2 @@
+::: obspec_utils.protocols.ReadableStore
+::: obspec_utils.protocols.ReadableFile

docs/api/protocols.md

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

docs/api/readers.md

@@ -1 +1 @@
-::: obspec_utils.splitting.SplittingReadableStore
+::: obspec_utils.wrappers.SplittingReadableStore

docs/api/splitting.md

@@ -1,3 +1,3 @@
-::: obspec_utils.tracing.TracingReadableStore
-::: obspec_utils.tracing.RequestTrace
-::: obspec_utils.tracing.RequestRecord
+::: obspec_utils.wrappers.TracingReadableStore
+::: obspec_utils.wrappers.RequestTrace
+::: obspec_utils.wrappers.RequestRecord

docs/api/tracing.md

@@ -86,7 +86,7 @@ During data access:
 `EagerStoreReader` loads the entire file into memory on construction:
 
 ```python
-from obspec_utils.obspec import EagerStoreReader
+from obspec_utils.readers import EagerStoreReader
 
 # File is fully loaded into memory
 reader = EagerStoreReader(store, "file.nc")
@@ -118,7 +118,7 @@ reader.close()
 `ParallelStoreReader` uses chunk-based LRU caching:
 
 ```python
-from obspec_utils.obspec import ParallelStoreReader
+from obspec_utils.readers import ParallelStoreReader
 
 reader = ParallelStoreReader(
     store, "file.nc",
@@ -147,7 +147,7 @@ data = reader.read(1000)
 `BufferedStoreReader` provides read-ahead buffering for sequential access:
 
 ```python
-from obspec_utils.obspec import BufferedStoreReader
+from obspec_utils.readers import BufferedStoreReader
 
 reader = BufferedStoreReader(store, "file.nc", buffer_size=1024 * 1024)
 
@@ -173,7 +173,7 @@ while chunk := reader.read(4096):
 `CachingReadableStore` wraps any store to cache full objects:
 
 ```python
-from obspec_utils.cache import CachingReadableStore
+from obspec_utils.wrappers import CachingReadableStore
 
 # Wrap the store with caching
 cached_store = CachingReadableStore(
@@ -241,7 +241,7 @@ For workloads requiring cross-worker cache sharing, consider:
 
 ```python
 import pickle
-from obspec_utils.cache import CachingReadableStore
+from obspec_utils.wrappers import CachingReadableStore
 
 # Main process: create and populate cache
 cached_store = CachingReadableStore(store, max_size=256 * 1024 * 1024)
@@ -291,7 +291,7 @@ When each worker processes a distinct set of files, per-worker caching works wel
 
 ```python
 from concurrent.futures import ProcessPoolExecutor
-from obspec_utils.cache import CachingReadableStore
+from obspec_utils.wrappers import CachingReadableStore
 
 def process_files(cached_store, file_paths):
     """Each worker gets its own cache, processes its own files."""
@@ -327,7 +327,7 @@ With Dask, the cached store is serialized to each worker:
 ```python
 import dask
 from dask.distributed import Client
-from obspec_utils.cache import CachingReadableStore
+from obspec_utils.wrappers import CachingReadableStore
 
 client = Client()
 
@@ -375,7 +375,7 @@ results = dask.compute(*tasks)
 `SplittingReadableStore` accelerates `get()` by splitting large requests into parallel `get_ranges()`:
 
 ```python
-from obspec_utils.splitting import SplittingReadableStore
+from obspec_utils.wrappers import SplittingReadableStore
 
 fast_store = SplittingReadableStore(
     store,
@@ -387,8 +387,7 @@ fast_store = SplittingReadableStore(
 This extracts the parallel fetching logic from `EagerStoreReader` into a composable wrapper. It composes naturally with `CachingReadableStore`:
 
 ```python
-from obspec_utils.splitting import SplittingReadableStore
-from obspec_utils.cache import CachingReadableStore
+from obspec_utils.wrappers import CachingReadableStore, SplittingReadableStore
 
 # Compose: fast parallel fetches + caching
 store = S3Store(bucket="my-bucket")

docs/design/caching.md

@@ -4,27 +4,31 @@ Utilities for interacting with object storage, based on [obspec](https://github.
 
 ## Background
 
-`obspec-utils` provides helpful utilities for working with object storage in Python, built on top of obspec and obstore. The library includes:
+`obspec-utils` provides helpful utilities for working with object storage in Python, built on top of obspec and obstore. The library is organized into subpackages:
 
-1. **ObjectStoreRegistry**: A registry for managing multiple object stores, allowing you to resolve URLs to the appropriate store and path. This is particularly useful when working with datasets that span multiple storage backends or buckets.
-
-2. **ReadableStore Protocol**: A minimal protocol defining the read-only interface required for object storage access. This allows alternative backends (like aiohttp) to be used instead of obstore.
-
-3. **File Handlers**: Wrappers around obstore's file reading capabilities that provide a familiar file-like interface.
+- **`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])
+    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.registry`**: [`ObjectStoreRegistry`][obspec_utils.registry.ObjectStoreRegistry] for managing multiple stores and resolving URLs
 
 ## Design Philosophy
 
 The library is designed around **protocols rather than concrete classes**. The `ObjectStoreRegistry` accepts any object that implements the `ReadableStore` protocol, which means:
 
-- **obstore classes** (S3Store, HTTPStore, GCSStore, etc.) work out of the box
-- **Custom implementations** (like the included `AiohttpStore`) can be used as alternatives
+- **obstore classes** ([S3Store][obstore.store.S3Store], [HTTPStore][obstore.store.HTTPStore],
+    [GCSStore][obstore.store.GCSStore], etc.) work out of the box
+- **Custom implementations** (like the included [`AiohttpStore`][obspec_utils.stores.AiohttpStore]) can be used as alternatives
 - **The Zarr/VirtualiZarr layer doesn't care** which backend you use - it just needs something satisfying the protocol
 
 This is particularly useful when:
 
-- obstore's HTTPStore (designed for WebDAV/S3-like semantics) isn't ideal for your use case
+- obstore's [HTTPStore][obstore.store.HTTPStore] (designed for WebDAV/S3-like semantics) isn't ideal for your use case
 - You need generic HTTPS access to THREDDS, NASA data servers, or other HTTP endpoints
-- You want to use a different HTTP library like aiohttp
+- You want to use a different HTTP library like [aiohttp](https://docs.aiohttp.org/en/stable/)
 
 ## Getting started
 
@@ -38,7 +42,7 @@ python -m pip install obspec-utils
 
 ### ObjectStoreRegistry
 
-The `ObjectStoreRegistry` allows you to register object stores and resolve URLs to the appropriate store:
+The [`ObjectStoreRegistry`][obspec_utils.registry.ObjectStoreRegistry] allows you to register object stores and resolve URLs to the appropriate store:
 
 ```python
 from obstore.store import S3Store
@@ -55,11 +59,11 @@ store, path = registry.resolve("s3://my-bucket/my-data/file.nc")
 
 ### Using Alternative HTTP Backends
 
-For generic HTTPS access where obstore's HTTPStore may not be ideal, you can use the `AiohttpStore`:
+For generic HTTPS access where obstore's HTTPStore may not be ideal, you can use the [`AiohttpStore`][obspec_utils.stores.AiohttpStore]:
 
 ```python
 from obspec_utils.registry import ObjectStoreRegistry
-from obspec_utils.aiohttp import AiohttpStore
+from obspec_utils.stores import AiohttpStore
 
 # Create an aiohttp-based store for a THREDDS server
 store = AiohttpStore(
@@ -77,18 +81,18 @@ data = await store.get_range_async(path, start=0, end=1000)
 
 ### File Handlers
 
-The file handlers provide file-like interfaces (read, seek, tell) for reading from object stores. They work with **any** ReadableStore implementation:
+The file handlers provide file-like interfaces (read, seek, tell) for reading from object stores. They work with **any** [`ReadableStore`][obspec_utils.readers.ReadableStore] implementation:
 
 ```python
-from obspec_utils.obspec import BufferedStoreReader, EagerStoreReader, ParallelStoreReader
+from obspec_utils.readers import BufferedStoreReader, EagerStoreReader, ParallelStoreReader
 
 # Works with obstore
 from obstore.store import S3Store
 store = S3Store(bucket="my-bucket")
 reader = BufferedStoreReader(store, "path/to/file.bin", buffer_size=1024*1024)
 
 # Also works with AiohttpStore or any ReadableStore
-from obspec_utils.aiohttp import AiohttpStore
+from obspec_utils.stores import AiohttpStore
 store = AiohttpStore("https://example.com/data")
 reader = BufferedStoreReader(store, "file.bin")
 

docs/index.md

@@ -18,13 +18,16 @@ nav:
     - "Protocols": "design/protocols.md"
     - "Caching": "design/caching.md"
   - "API":
+      - Protocols: "api/protocols.md"
+      - Readers: "api/readers.md"
+      - Stores:
+          - AiohttpStore: "api/aiohttp.md"
+      - Wrappers:
+          - Caching: "api/cache.md"
+          - Splitting: "api/splitting.md"
+          - Tracing: "api/tracing.md"
+      - Registry: "api/registry.md"
       - Typing: "api/typing.md"
-      - Aiohttp Store Adapters: "api/aiohttp.md"
-      - Caching: "api/cache.md"
-      - Splitting: "api/splitting.md"
-      - Obspec File Readers: "api/obspec.md"
-      - Store Registries: "api/registry.md"
-      - Tracing: "api/tracing.md"
 
 watch:
   - src/obspec_utils