AiohttpStore

obspec_utils.stores.AiohttpStore

Bases: ReadableStore

An aiohttp-based object store implementation.

This provides a lightweight alternative to obstore's HTTPStore for generic HTTP/HTTPS access. It's particularly useful for:

• THREDDS data servers
• NASA data access from outside AWS regions
• Any generic HTTP endpoint that doesn't need S3-like semantics

The store should be used as an async context manager to efficiently reuse a single HTTP session across multiple requests.

Parameters:

• base_url (str) –

  The base URL for this store. All paths are resolved relative to this URL.

• headers (dict[str, str] | None, default: None ) –

  Optional HTTP headers to include in all requests (e.g., authentication).

• timeout (float, default: 30.0 ) –

  Request timeout in seconds. Default is 30.

Examples:

Recommended usage with async context manager:

async with AiohttpStore("https://example.com/data") as store:
    # All requests share the same session
    result = await store.get_async("file.nc")
    data = await result.buffer_async()

    # Byte range requests
    chunk = await store.get_range_async("file.nc", start=0, end=1000)

Synchronous usage (creates a session per request):

store = AiohttpStore("https://example.com/data")
result = store.get("file.nc")
data = result.buffer()

With authentication:

async with AiohttpStore(
    "https://api.example.com/data",
    headers={"Authorization": "Bearer <token>"}
) as store:
    result = await store.get_async("protected/file.nc")

__aenter__ async

__aenter__() -> 'AiohttpStore'

Enter the async context manager, creating a reusable session.

__aexit__ async

__aexit__(exc_type, exc_val, exc_tb) -> None

Exit the async context manager, closing the session.

__del__

__del__() -> None

Clean up on garbage collection.

close

close() -> None

Close the store and release resources.

get

get(path: str, *, options: GetOptions | None = None) -> AiohttpGetResult

Download a file synchronously.

This wraps the async implementation for convenience.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• options (GetOptions | None, default: None ) –

  Optional get options.

Returns:

• AiohttpGetResult –

  Result object with buffer() method and metadata.

get_async async

get_async(
    path: str, *, options: GetOptions | None = None
) -> AiohttpGetResultAsync

Download a file asynchronously.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• options (GetOptions | None, default: None ) –

  Optional get options (range, conditionals, etc.).

Returns:

• AiohttpGetResultAsync –

  Result object with buffer_async() method and metadata.

get_range

get_range(
    path: str, *, start: int, end: int | None = None, length: int | None = None
) -> bytes

Download a byte range synchronously.

This wraps the async implementation for convenience.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• start (int) –

  Start byte offset.

• end (int | None, default: None ) –

  End byte offset (exclusive).

• length (int | None, default: None ) –

  Number of bytes to read.

Returns:

• bytes –

  The requested byte range.

get_range_async async

get_range_async(
    path: str, *, start: int, end: int | None = None, length: int | None = None
) -> bytes

Download a byte range asynchronously.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• start (int) –

  Start byte offset.

• end (int | None, default: None ) –

  End byte offset (exclusive). Either end or length must be provided.

• length (int | None, default: None ) –

  Number of bytes to read. Either end or length must be provided.

Returns:

• bytes –

  The requested byte range.

get_ranges

get_ranges(
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
) -> Sequence[bytes]

Download multiple byte ranges synchronously.

This wraps the async implementation for convenience.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• starts (Sequence[int]) –

  Sequence of start byte offsets.

• ends (Sequence[int] | None, default: None ) –

  Sequence of end byte offsets (exclusive).

• lengths (Sequence[int] | None, default: None ) –

  Sequence of lengths.

Returns:

• Sequence[bytes] –

  The requested byte ranges.

get_ranges_async async

get_ranges_async(
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
) -> Sequence[bytes]

Download multiple byte ranges asynchronously.

Parameters:

• path (str) –

  Path to the file relative to base_url.

• starts (Sequence[int]) –

  Sequence of start byte offsets.

• ends (Sequence[int] | None, default: None ) –

  Sequence of end byte offsets (exclusive).

• lengths (Sequence[int] | None, default: None ) –

  Sequence of lengths. Either ends or lengths must be provided.

Returns:

• Sequence[bytes] –

  The requested byte ranges.

head

head(path: str) -> ObjectMeta

Get file metadata synchronously via HEAD request.

This wraps the async implementation for convenience.

Parameters:

• path (str) –

  Path to the file relative to base_url.

Returns:

• ObjectMeta –

  File metadata including size, last_modified, e_tag, etc.

head_async async

head_async(path: str) -> ObjectMeta

Get file metadata asynchronously via HEAD request.

Parameters:

• path (str) –

  Path to the file relative to base_url.

Returns:

• ObjectMeta –

  File metadata including size, last_modified, e_tag, etc.