### FsspecStore Example Usage

Source: https://developmentseed.org/obstore/latest/api/fsspec

Demonstrates creating an FsspecStore instance for 'https' protocol and retrieving file content using cat_file. Asserts that the content starts with '# obstore'.

```python
from obstore.fsspec import FsspecStore

store = FsspecStore("https")
resp = store.cat_file("https://raw.githubusercontent.com/developmentseed/obstore/refs/heads/main/README.md")
assert resp.startswith(b"# obstore")


```

--------------------------------

### Install obstore using pip

Source: https://developmentseed.org/obstore/latest

Install the obstore package using pip for Python projects.

```bash
pip install obstore

```

--------------------------------

### If-None-Match Header Examples

Source: https://developmentseed.org/obstore/latest/api/get

Examples of `If-None-Match` header values for conditional GET requests, including specific ETags, multiple ETags, and a wildcard.

```http
If-None-Match: "xyzzy"
If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
If-None-Match: *
```

--------------------------------

### Initialize a MemoryStore

Source: https://developmentseed.org/obstore/latest/blog/2025/02/10/releasing-obstore-04

Basic setup for creating an in-memory store instance.

```python
import os

import obstore as obs
from obstore.store import MemoryStore

# Create an in-memory store
store = MemoryStore()
```

--------------------------------

### Install obstore using conda

Source: https://developmentseed.org/obstore/latest

Install the obstore package from conda-forge using conda, mamba, or pixi.

```bash
conda install -c conda-forge obstore

```

--------------------------------

### Initialize FastAPI Application

Source: https://developmentseed.org/obstore/latest/examples/fastapi

Setup the FastAPI application and import necessary modules from fastapi and obstore.

```python
from fastapi import FastAPI
from fastapi.responses import StreamingResponse

from obstore.store import HTTPStore, S3Store

app = FastAPI()
```

--------------------------------

### If-Match Header Examples

Source: https://developmentseed.org/obstore/latest/api/get

Examples of `If-Match` header values for conditional GET requests, including specific ETags, multiple ETags, and a wildcard.

```http
If-Match: "xyzzy"
If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
If-Match: *
```

--------------------------------

### Initialize S3Store with Custom Provider

Source: https://developmentseed.org/obstore/latest/authentication

Example of passing the custom credential provider instance to the S3Store constructor.

```python
credential_provider = NasaEarthdataCredentialProvider(username="...", password="...")
store = S3Store("bucket_name", credential_provider=credential_provider)
```

--------------------------------

### Construct LocalStore from file URL

Source: https://developmentseed.org/obstore/latest/api/store/local

Demonstrates constructing a LocalStore from a 'file://' URL. Examples show constructing a store pointing to the filesystem root and one with a directory prefix.

```python
url = "file:///";
store = LocalStore.from_url(url)
```

```python
url = "file:///Users/kyle/";
store = LocalStore.from_url(url)
```

--------------------------------

### obstore.GetOptions

Source: https://developmentseed.org/obstore/latest/api/get

Options for a get request. All options are optional.

```APIDOC
## obstore.GetOptions

### head

- **head** (bool) - If true, requests transfer of no content.

### if_match

- **if_match** (str | None) - Requests success if the `ObjectMeta::e_tag` matches, otherwise returns `PreconditionError`.

### if_modified_since

- **if_modified_since** (datetime | None) - Requests success if the object has not been modified since the specified datetime, otherwise returns `PreconditionError`.

### if_none_match

- **if_none_match** (str | None) - Requests success if the `ObjectMeta::e_tag` does not match, otherwise returns `NotModifiedError`.

### if_unmodified_since

- **if_unmodified_since** (datetime | None) - Requests success if the object has been modified since the specified datetime.

### range

- **range** (tuple[int, int] | Sequence[int] | OffsetRange | SuffixRange) - Requests transfer of only the specified range of bytes. Can be a tuple of (start, end), an offset dictionary {'offset': int}, or a suffix dictionary {'suffix': int}.

### version

- **version** (str | None) - Requests a particular object version.
```

--------------------------------

### Example Service Account JSON Content

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Illustrates the expected JSON content for a service account file when using the 'service_account' configuration.

```json
{
   "gcs_base_url": "https://localhost:4443",
   "disable_oauth": true,
   "client_email": "",
   "private_key": ""
}
```

--------------------------------

### Initialize AzureAsyncCredentialProvider

Source: https://developmentseed.org/obstore/latest/api/auth/azure

Instantiate an AzureAsyncCredentialProvider for asynchronous AzureStore operations. Requires `azure-identity` and `aiohttp` to be installed.

```python
import asyncio
import obstore
from obstore.auth.azure import AzureAsyncCredentialProvider
from obstore.store import AzureStore

credential_provider = AzureAsyncCredentialProvider(credential=...)
store = AzureStore("container", credential_provider=credential_provider)

async def fetch_blobs():
    blobs = await obstore.list(store).collect_async()
    print(blobs)

asyncio.run(fetch_blobs())

```

--------------------------------

### Run MinIO locally with Docker

Source: https://developmentseed.org/obstore/latest/examples/minio

Starts a MinIO server container with console access on port 9001 and API access on port 9000.

```bash
docker run -p 9000:9000 -p 9001:9001 \
    quay.io/minio/minio server /data --console-address ":9001"
```

--------------------------------

### Open and Read File with Obstore

Source: https://developmentseed.org/obstore/latest/blog/2025/02/10/releasing-obstore-04

Use `obs.open_reader` to open a file for reading. You can seek to specific positions, read the entire file content, and get the file length.

```python
reader = obs.open_reader(store, "new_file.csv")
file_length = reader.seek(0, os.SEEK_END)
print(file_length) # 43
reader.seek(0)
buf = reader.read()
print(buf)
# Bytes(b"col1,col2,col3\na,1,True\nb,2,False\nc,3,True\n")
```

--------------------------------

### Initialize HTTPStore with URL and Options

Source: https://developmentseed.org/obstore/latest/api/store/http

Constructs a new HTTPStore instance from a URL, optionally configuring client and retry settings. Any path in the URL is used as the store's prefix.

```python
__init__(
    url: str,
    *,
    client_options: ClientConfig | None = None,
    retry_config: RetryConfig | None = None
) -> None

```

--------------------------------

### LocalStore Initialization Parameters

Source: https://developmentseed.org/obstore/latest/api/store/local

Illustrates the parameters for initializing a LocalStore, including prefix, automatic cleanup, and directory creation.

```python
__init__(prefix: str | Path | None = None, *, automatic_cleanup: bool = False, mkdir: bool = False) -> None
```

--------------------------------

### Get a byte range from an object in MemoryStore

Source: https://developmentseed.org/obstore/latest/api/store/memory

Retrieves a specific byte range from the object at the given path in the MemoryStore. Supports specifying start, end, or length.

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

--------------------------------

### Create a store using from_url

Source: https://developmentseed.org/obstore/latest/blog/2025/02/10/releasing-obstore-04

Demonstrates initializing an S3Store from a URL and performing basic file listing and download operations.

```python
import obstore as obs
from obstore.store import from_url

# The base path within the bucket to "mount" to
url = "s3://sentinel-cogs/sentinel-s2-l2a-cogs/12/S/UF/2022/6/S2A_12SUF_20220601_0_L2A"

# Pass in store-specific parameters as keyword arguments
# Here, we pass `skip_signature=True` because it's a public bucket
store = from_url(url, region="us-west-2", skip_signature=True)

# Print filenames in this directory
print([meta["path"] for meta in obs.list_with_delimiter(store)["objects"]])
# ['AOT.tif', 'B01.tif', 'B02.tif', 'B03.tif', 'B04.tif', 'B05.tif', 'B06.tif', 'B07.tif', 'B08.tif', 'B09.tif', 'B11.tif', 'B12.tif', 'B8A.tif', 'L2A_PVI.tif', 'S2A_12SUF_20220601_0_L2A.json', 'SCL.tif', 'TCI.tif', 'WVP.tif', 'granule_metadata.xml', 'thumbnail.jpg', 'tileinfo_metadata.json']

# Download thumbnail
with open("thumbnail.jpg", "wb") as f:
    f.write(obs.get(store, "thumbnail.jpg").bytes())
```

--------------------------------

### Asynchronously get a byte range from an object in MemoryStore

Source: https://developmentseed.org/obstore/latest/api/store/memory

Asynchronously retrieves a specific byte range from the object at the given path in the MemoryStore. Supports specifying start, end, or length.

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

--------------------------------

### Initialize AzureStore with PlanetaryComputerCredentialProvider

Source: https://developmentseed.org/obstore/latest/api/auth/planetary-computer

Demonstrates how to construct an AzureStore using the PlanetaryComputerCredentialProvider for accessing Planetary Computer data. This snippet shows listing items and fetching a thumbnail.

```python
from obstore.store import AzureStore
from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider

url = "https://naipeuwest.blob.core.windows.net/naip/v002/mt/2023/mt_060cm_2023/"

# Construct an AzureStore with this credential provider.
#
# The account, container, and container prefix are passed down to AzureStore
# automatically.
store = AzureStore(credential_provider=PlanetaryComputerCredentialProvider(url))

# List some items in the container
items = next(store.list())

# Fetch a thumbnail
path = "44106/m_4410602_nw_13_060_20230712_20240103.200.jpg"
image_content = store.get(path).bytes()

# Write out the image content to a file in the current directory
with open("thumbnail.jpg", "wb") as f:
    f.write(image_content)

```

--------------------------------

### Async Get Ranges Function Signature

Source: https://developmentseed.org/obstore/latest/api/get

This is the asynchronous function signature for retrieving data ranges from an object store. It allows specifying start and end points, lengths, and a coalesce value for merging ranges.

```python
get_ranges_async(
    store: ObjectStore,
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
    coalesce: int = 1024 * 1024
) -> list[Bytes]
```

--------------------------------

### Accessing Range

Source: https://developmentseed.org/obstore/latest/api/get

Retrieves the byte range (start, stop) of the data returned by the request. Note that this represents the start and end byte indices, not the start and length.

```python
range: tuple[int, int]
```

--------------------------------

### Create LocalStore Instances

Source: https://developmentseed.org/obstore/latest/api/store/local

Demonstrates creating LocalStore instances with and without a directory prefix. The prefix can be a string or a Path object.

```python
from pathlib import Path

store = LocalStore()
store = LocalStore(prefix="/path/to/directory")
store = LocalStore(prefix=Path("."))
```

--------------------------------

### LocalStore Initialization

Source: https://developmentseed.org/obstore/latest/api/store/local

Demonstrates how to initialize a LocalStore, optionally with a directory prefix.

```APIDOC
## LocalStore Initialization

### Description
Initializes a new LocalStore instance. It can be configured with a directory prefix, automatic cleanup of empty directories, and the option to create the prefix directory if it doesn't exist.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pathlib import Path

# Initialize with default settings
store_default = LocalStore()

# Initialize with a string prefix
store_string_prefix = LocalStore(prefix="/path/to/directory")

# Initialize with a Path object prefix
store_path_prefix = LocalStore(prefix=Path("."))

# Initialize with automatic cleanup enabled
store_auto_cleanup = LocalStore(automatic_cleanup=True)

# Initialize with directory creation enabled
store_mkdir = LocalStore(mkdir=True, prefix="./new_directory")
```

### Response
#### Success Response (None)
This method does not return a value.

#### Response Example
None
```

--------------------------------

### Download File Generically with Obspec Get Protocol

Source: https://developmentseed.org/obstore/latest/obspec

Use the `Get` protocol to define a function that downloads a file generically. This function accepts any client implementing the `Get` interface, processing the file in chunks.

```python
from obspec import Get

def download_file(client: Get):
    response = client.get("my-file.txt")
    for buffer in response:
        # Process each buffer chunk as needed
        print(f"Received buffer of size: {len(memoryview(buffer))} bytes")

```

--------------------------------

### HTTPStore.__init__

Source: https://developmentseed.org/obstore/latest/api/store/http

Constructs a new HTTPStore from a URL. Any path on the URL will be assigned as the prefix for the store.

```APIDOC
## HTTPStore.__init__

### Description
Constructs a new HTTPStore from a URL. Any path on the URL will be assigned as the `prefix` for the store. So if you pass `https://example.com/path/to/directory`, the store will be created with a prefix of `path/to/directory`, and all further operations will use paths relative to that prefix.

### Method
`__init__`

### Parameters
#### Path Parameters
* **`url`** (str) - The base URL to use for the store.

#### Other Parameters
* **`client_options`** (ClientConfig | None) - HTTP Client options. Defaults to None.
* **`retry_config`** (RetryConfig | None) - Retry configuration. Defaults to None.

### Returns
* None - HTTPStore
```

--------------------------------

### Open and Read File with FsspecStore

Source: https://developmentseed.org/obstore/latest/integrations/fsspec

Use the `open` method provided on `FsspecStore` to get a readable or writable file-like object. This allows you to read content from a file directly.

```python
from obstore.fsspec import FsspecStore

fs = FsspecStore("s3", region="us-west-2", skip_signature=True)

with fs.open(
    "s3://sentinel-cogs/sentinel-s2-l2a-cogs/12/S/UF/2022/6/S2B_12SUF_20220609_0_L2A/thumbnail.jpg",
) as file:
    content = file.read()


```

--------------------------------

### Asynchronous Get Operation

Source: https://developmentseed.org/obstore/latest/api/get

Use `get_async` to call the `get` operation asynchronously. This is suitable for non-blocking I/O operations.

```python
get_async(
    store: ObjectStore, path: str, *, options: GetOptions | None = None
) -> GetResult
```

--------------------------------

### PlanetaryComputerCredentialProvider Initialization

Source: https://developmentseed.org/obstore/latest/api/auth/planetary-computer

Demonstrates how to initialize the PlanetaryComputerCredentialProvider with a URL and use it with AzureStore.

```APIDOC
## PlanetaryComputerCredentialProvider

### Description
A CredentialProvider for AzureStore for accessing Planetary Computer data resources.
This credential provider uses `requests`, and will error if that cannot be imported.

### __init__
```python
__init__(
    url: str | None = None,
    *,
    account_name: str | None = None,
    container_name: str | None = None,
    session: Session | None = None,
    subscription_key: str | None = None,
    sas_url: str | None = None
) -> None
```

Construct a new PlanetaryComputerCredentialProvider.

**Parameters**:
  * **`url`**(`str | None`, default: `None` ) – 
Either the `https` or `abfs` URL of blob storage to mount to, such as `"https://daymeteuwest.blob.core.windows.net/daymet-zarr/daily"` or `"abfs://daymet-zarr/daily/hi.zarr"`.
For `abfs` URLs, `account_name` must be provided.
For `https` URLs, neither `account_name` nor `container_name` may be provided.
If `url` is not provided, `account_name` and `container_name` must be provided. Defaults to `None`.

**Other Parameters**:
  * **`account_name`**(`str | None`) – 
The Azure storage account name. Must be provided for `abfs` URLs. If `url` is not provided, both this and `container_name` must be provided. Defaults to `None`.
  * **`container_name`**(`str | None`) – 
The Azure storage container name. If `url` is not provided, both this and `account_name` must be provided. Defaults to `None`.
  * **`session`**(`Session | None`) – 
The requests session to use for making requests to the Planetary Computer token API. Defaults to `None`.
  * **`subscription_key`**(`str | None`) – 
A Planetary Computer subscription key.
Precedence is as follows:
    1. Uses the passed-in value if not `None`.
    2. Uses the environment variable `PC_SDK_SUBSCRIPTION_KEY` if set.
    3. Uses the value of `PC_SDK_SUBSCRIPTION_KEY` in `~/.planetarycomputer/settings.env`, if that file exists (requires `python-dotenv` as a dependency).
    4. Defaults to `None`, which may apply request throttling.
  * **`sas_url`**(`str | None`) – 
The URL base for requesting new Planetary Computer SAS tokens.
Precedence is as follows:
    1. Uses the passed-in value if not `None`.
    2. Uses the environment variable `PC_SDK_SAS_URL` if set.
    3. Uses the value of `PC_SDK_SAS_URL` in `~/.planetarycomputer/settings.env`, if that file exists (requires `python-dotenv` as a dependency).
    4. Defaults to `"https://planetarycomputer.microsoft.com/api/sas/v1/token"`.

### Example Usage
```python
from obstore.store import AzureStore
from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider

url = "https://naipeuwest.blob.core.windows.net/naip/v002/mt/2023/mt_060cm_2023/"

# Construct an AzureStore with this credential provider.
#
# The account, container, and container prefix are passed down to AzureStore
# automatically.
store = AzureStore(credential_provider=PlanetaryComputerCredentialProvider(url))

# List some items in the container
items = next(store.list())

# Fetch a thumbnail
path = "44106/m_4410602_nw_13_060_20230712_20240103.200.jpg"
image_content = store.get(path).bytes()

# Write out the image content to a file in the current directory
with open("thumbnail.jpg", "wb") as f:
    f.write(image_content)
```
```

--------------------------------

### Get Object Bytes from HTTPStore

Source: https://developmentseed.org/obstore/latest/api/store/http

Retrieves the bytes stored at the specified location in the HTTPStore. Optional get options can be provided.

```python
get(path: str, *, options: GetOptions | None = None) -> GetResult

```

--------------------------------

### Initialize GoogleCredentialProvider for GCSStore

Source: https://developmentseed.org/obstore/latest/api/auth/google

Use GoogleCredentialProvider for synchronous GCSStore operations. It requires google-auth and requests to be installed. The credentials parameter can be omitted to use application default credentials.

```python
from obstore.auth.google import GoogleCredentialProvider
from obstore.store import GCSStore

credential_provider = GoogleCredentialProvider(credentials=...)
store = GCSStore("bucket_name", credential_provider=credential_provider)
```

--------------------------------

### Get Object from S3 Store

Source: https://developmentseed.org/obstore/latest/api/store/aws

Retrieve the bytes stored at the specified location in the S3 store. Optional get options can be provided.

```python
store.get("path/to/object.txt")
```

```python
store.get("path/to/object.txt", options=GetOptions(...))
```

--------------------------------

### Initialize S3Store

Source: https://developmentseed.org/obstore/latest/api/store/aws

Create a new S3Store instance. Configuration can be provided directly or inferred from environment variables. Supports custom prefixes, client options, retry configurations, and credential providers.

```python
S3Store(
    bucket="my-bucket",
    prefix="my-prefix",
    config=S3Config(...),
    client_options=ClientConfig(...),
    retry_config=RetryConfig(...),
    credential_provider=S3CredentialProvider(...)
)
```

--------------------------------

### Asynchronous Get Object Bytes from HTTPStore

Source: https://developmentseed.org/obstore/latest/api/store/http

Asynchronously retrieves the bytes stored at the specified location in the HTTPStore. Optional get options can be provided.

```python
get_async(path: str, *, options: GetOptions | None = None) -> GetResult

```

--------------------------------

### GCSStore Initialization

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Construct a new GCSStore. All constructors will check for environment variables. Refer to GCSConfig for valid environment variables. If no credentials are explicitly provided, they will be sourced from the environment.

```APIDOC
## __init__ GCSStore

### Description
Construct a new GCSStore.

### Parameters
#### Path Parameters
* **`bucket`** (str | None) - Optional - The GCS bucket to use.

#### Other Parameters
* **`prefix`** (str | None) - Optional - A prefix within the bucket to use for all operations.
* **`config`** (GCSConfig | None) - Optional - GCS Configuration. Values in this config will override values inferred from the environment. Defaults to None.
* **`client_options`** (ClientConfig | None) - Optional - HTTP Client options. Defaults to None.
* **`retry_config`** (RetryConfig | None) - Optional - Retry configuration. Defaults to None.
* **`credential_provider`** (GCSCredentialProvider | None) - Optional - A callback to provide custom Google credentials.
* **`kwargs`** (Unpack[GCSConfig]) - Optional - GCS configuration values. Supports the same values as `config`, but as named keyword args.

### Returns
* None - GCSStore
```

--------------------------------

### Get Object Asynchronously from S3 Store

Source: https://developmentseed.org/obstore/latest/api/store/aws

Asynchronously retrieve the bytes stored at the specified location in the S3 store. Optional get options can be provided.

```python
await store.get_async("path/to/object.txt")
```

```python
await store.get_async("path/to/object.txt", options=GetOptions(...))
```

--------------------------------

### Using NasaEarthdataAsyncCredentialProvider with S3Store

Source: https://developmentseed.org/obstore/latest/api/auth/earthdata

Demonstrates how to obtain S3 credentials and use them with S3Store to download a file from NASA Earthdata. It shows the process of initializing the provider, creating an S3Store, and streaming the file content. Ensure environment variables or netrc are configured for credential lookup if not explicitly provided.

```python
import obstore
from obstore.auth.earthdata import NasaEarthdataAsyncCredentialProvider

# Obtain an S3 credentials URL and an S3 data/download URL, typically
# via metadata returned from a NASA CMR collection or granule query.
credentials_url = "https://data.ornldaac.earthdata.nasa.gov/s3credentials"
data_url = (
    "s3://ornl-cumulus-prod-protected/gedi/GEDI_L4A_AGB_Density_V2_1/data/"
    "GEDI04_A_2024332225741_O33764_03_T01289_02_004_01_V002.h5"
)
data_prefix_url, filename = data_url.rsplit("/", 1)

# Since no NASA Earthdata credentials are specified in this example,
# environment variables or netrc will be used to locate them in order to
# obtain S3 credentials from the URL.
cp = NasaEarthdataAsyncCredentialProvider(credentials_url)

store = obstore.store.from_url(data_prefix_url, credential_provider=cp)

# Download the file by streaming chunks
try:
    result = await store.get(filename)
    with open(filename, "wb") as f:
        async for chunk in aiter(result):
            f.write(chunk)
finally:
    await cp.close()

```

--------------------------------

### Synchronous Get Operation

Source: https://developmentseed.org/obstore/latest/api/get

Use `get` to retrieve the bytes stored at a specified path within an ObjectStore. It takes the ObjectStore instance, the path, and optional GetOptions.

```python
get(
    store: ObjectStore, path: str, *, options: GetOptions | None = None
) -> GetResult
```

--------------------------------

### List objects with obstore

Source: https://developmentseed.org/obstore/latest/cookbook

Demonstrates how to recursively list files under a specific prefix using the list method.

```python
store = ... # store of your choice

# Recursively list all files below the 'data' path.
# 1. On AWS S3 this would be the 'data/' prefix
# 2. On a local filesystem, this would be the 'data' directory
prefix = "data"

# Get a stream of metadata objects:
list_stream = store.list(prefix)

# Print info
for batch in list_stream:
    for meta in batch:
        print(f'Name: {meta["path"]}, size: {meta["size"]}')
```

--------------------------------

### Get Object Metadata (Functional API)

Source: https://developmentseed.org/obstore/latest/api/head

Use this functional API to get the metadata for a specified location within an ObjectStore instance. Requires an ObjectStore instance and the path.

```python
head(store: ObjectStore, path: str) -> ObjectMeta
```

--------------------------------

### Interact with MinIO using S3Store

Source: https://developmentseed.org/obstore/latest/examples/minio

Initializes an S3Store connection to a local MinIO instance and demonstrates basic file lifecycle operations.

```python
from obstore.store import S3Store

store = S3Store(
    "test-bucket",
    endpoint="http://localhost:9000",
    access_key_id="minioadmin",
    secret_access_key="minioadmin",
    virtual_hosted_style_request=False,
    client_options={"allow_http": True},
)

# Add files
store.put("a.txt", b"foo")
store.put("b.txt", b"bar")
store.put("c/d.txt", b"baz")

# List files
files = store.list().collect()
print(files)

# Download a file
resp = store.get("a.txt")
print(resp.bytes())

# Delete a file
store.delete("a.txt")
```

--------------------------------

### Get Object Metadata Asynchronously (Functional API)

Source: https://developmentseed.org/obstore/latest/api/head

Call the head function asynchronously to retrieve object metadata. This provides a non-blocking way to get metadata using the functional API.

```python
head_async(store: ObjectStore, path: str) -> ObjectMeta
```

--------------------------------

### Initialize AzureStore with PlanetaryComputerCredentialProvider

Source: https://developmentseed.org/obstore/latest/authentication

Construct an AzureStore to access data from the Microsoft Planetary Computer. The PlanetaryComputerCredentialProvider handles token access and refresh automatically. The account, container, and prefix are passed down to AzureStore.

```python
from obstore.store import AzureStore
from obstore.auth.planetary_computer import PlanetaryComputerCredentialProvider

url = "https://naipeuwest.blob.core.windows.net/naip/v002/mt/2023/mt_060cm_2023/"

# Construct an AzureStore with this credential provider.
#
# The account, container, and container prefix are passed down to AzureStore
# automatically.
store = AzureStore(credential_provider=PlanetaryComputerCredentialProvider(url))
```

--------------------------------

### GCSStore get_async Method

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Call get asynchronously.

```APIDOC
## get_async GCSStore

### Description
Call `get` asynchronously.

### Parameters
#### Path Parameters
* **`path`** (str) - Required - The path to the object.

#### Other Parameters
* **`options`** (GetOptions | None) - Optional - Options for the get operation.

### Returns
* GetResult
```

--------------------------------

### Initialize AzureStore

Source: https://developmentseed.org/obstore/latest/api/store/azure

Constructs a new AzureStore instance. Environment variables are checked for configuration. Supports overriding values with provided config, client options, retry config, and credential provider.

```python
__init__(
    container_name: str | None = None,
    *, 
    prefix: str | None = None,
    config: AzureConfig | None = None,
    client_options: ClientConfig | None = None,
    retry_config: RetryConfig | None = None,
    credential_provider: AzureCredentialProvider | None = None,
    **kwargs: Unpack[AzureConfig]
) -> None

```

--------------------------------

### Get Object Size

Source: https://developmentseed.org/obstore/latest/api/file

Retrieve the size of the object in bytes.

```python
size: int
```

--------------------------------

### get

Source: https://developmentseed.org/obstore/latest/api/store/azure

Retrieves bytes from a specified location in Azure Blob Storage.

```APIDOC
## get

### Description
Retrieves the bytes that are stored at the specified location.

### Method
GET

### Endpoint
`/path`

### Parameters
#### Path Parameters
- **path** (str) - Required - The path to the object.

#### Query Parameters
- **options** (GetOptions | None) - Optional - Additional options for the get operation.

### Response
#### Success Response (200)
- **result** (GetResult) - The result of the get operation, containing the bytes.

### Response Example
```json
{
  "result": "bytes_data"
}
```
```

--------------------------------

### GCSStore get Method

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Return the bytes that are stored at the specified location.

```APIDOC
## get GCSStore

### Description
Return the bytes that are stored at the specified location.

### Parameters
#### Path Parameters
* **`path`** (str) - Required - The path to the object.

#### Other Parameters
* **`options`** (GetOptions | None) - Optional - Options for the get operation.

### Returns
* GetResult
```

--------------------------------

### S3Store.__init__

Source: https://developmentseed.org/obstore/latest/api/store/aws

Creates a new S3Store instance to interact with an AWS S3 bucket. It allows configuration of the bucket, prefix, and various AWS-specific options like client configuration, retry strategy, and credential provider.

```APIDOC
## __init__

### Description
Create a new S3Store.

### Method
__init__

### Parameters
#### Path Parameters
* **bucket** (str | None) - Required - The AWS bucket to use.

#### Other Parameters
* **prefix** (str | None) - Optional - A prefix within the bucket to use for all operations.
* **config** (S3Config | None) - Optional - AWS configuration. Values in this config will override values inferred from the environment. Defaults to None.
* **client_options** (ClientConfig | None) - Optional - HTTP Client options. Defaults to None.
* **retry_config** (RetryConfig | None) - Optional - Retry configuration. Defaults to None.
* **credential_provider** (S3CredentialProvider | None) - Optional - A callback to provide custom S3 credentials.
* **kwargs** (Unpack[S3Config]) - Optional - AWS configuration values. Supports the same values as `config`, but as named keyword args.

### Returns
* None - S3Store
```

--------------------------------

### BufferedFile.loc

Source: https://developmentseed.org/obstore/latest/api/fsspec

Gets the current file location (offset) within the buffer.

```APIDOC
## BufferedFile.loc

### Description
Get current file location.

### Property
loc: int
```

--------------------------------

### Access store configuration attributes

Source: https://developmentseed.org/obstore/latest/blog/2025/02/10/releasing-obstore-04

Shows how to retrieve and reuse configuration, client options, and retry settings from an existing store instance.

```python
from obstore.store import S3Store

store = S3Store.from_url(
    "s3://ookla-open-data/parquet/performance/type=fixed/year=2024/quarter=1",
    region="us-west-2",
    skip_signature=True,
)
new_store = S3Store(
    config=store.config,
    prefix=store.prefix,
    client_options=store.client_options,
    retry_config=store.retry_config,
)
assert store.config == new_store.config
assert store.prefix == new_store.prefix
assert store.client_options == new_store.client_options
assert store.retry_config == new_store.retry_config
```

--------------------------------

### Get Range Asynchronously

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Call `get_range` asynchronously. Refer to the documentation for get_range_async.

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


```

--------------------------------

### GCSStore from_url Class Method

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Construct a new GCSStore with values populated from a well-known storage URL. Any path on the URL will be assigned as the prefix for the store.

```APIDOC
## from_url GCSStore

### Description
Construct a new GCSStore with values populated from a well-known storage URL. Any path on the URL will be assigned as the `prefix` for the store. So if you pass `gs://<bucket>/path/to/directory`, the store will be created with a prefix of `path/to/directory`, and all further operations will use paths relative to that prefix.

### Parameters
#### Path Parameters
* **`url`** (str) - Required - well-known storage URL.

#### Other Parameters
* **`prefix`** (str | None) - Optional - A prefix within the bucket to use for all operations.
* **`config`** (GCSConfig | None) - Optional - GCS Configuration. Values in this config will override values inferred from the url. Defaults to None.
* **`client_options`** (ClientConfig | None) - Optional - HTTP Client options. Defaults to None.
* **`retry_config`** (RetryConfig | None) - Optional - Retry configuration. Defaults to None.
* **`credential_provider`** (GCSCredentialProvider | None) - Optional - A callback to provide custom Google credentials.
* **`kwargs`** (Unpack[GCSConfig]) - Optional - GCS configuration values. Supports the same values as `config`, but as named keyword args.

### Returns
* Self - GCSStore
```

--------------------------------

### get

Source: https://developmentseed.org/obstore/latest/api/store/memory

Retrieves the bytes of an object stored at a specific path in the in-memory store.

```APIDOC
## get

### Description
Returns the bytes that are stored at the specified location.

### Method
`get(path: str, *, options: GetOptions | None = None) -> GetResult`

### Parameters
- **path** (str) - The path to the object.
- **options** (GetOptions | None) - Optional. Additional options for retrieving the object.
```

--------------------------------

### FsspecStore Initialization for File System

Source: https://developmentseed.org/obstore/latest/api/fsspec

Initializes FsspecStore for the local file system protocol. Does not accept cloud-specific configurations.

```python
__init__(
    protocol: Literal["file"],
    *args: Any,
    config: None = None,
    client_options: None = None,
    retry_config: None = None,
    asynchronous: bool = False,
    max_cache_size: int = 10,
    loop: Any = None,
    batch_size: int | None = None,
    automatic_cleanup: bool = False,
    mkdir: bool = False
) -> None


```

--------------------------------

### Fetch Token

Source: https://developmentseed.org/obstore/latest/api/auth/planetary-computer

Demonstrates how to fetch a new authentication token.

```APIDOC
### __call__
```python
__call__() -> AzureSASToken
```

Fetch a new token.
```

--------------------------------

### Get Data (Asynchronous)

Source: https://developmentseed.org/obstore/latest/api/get

Retrieves data from the store asynchronously. This is useful for non-blocking operations.

```APIDOC
## get_async

### Description
Retrieves an object from the store asynchronously.

### Method API
`async get_async(key: str, options: GetOptions = GetOptions()) -> GetResult`

### Functional API
`async get_async(key: str, options: GetOptions = GetOptions()) -> GetResult`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for GetOptions
- **head** (bool) - If true, only return metadata headers, not the object body.
- **if_match** (str) - Return object only if its entity tag matches the given value. Also called an "If-Match" header.
- **if_modified_since** (str) - Return object only if it has been modified since the specified date. Also called an "If-Modified-Since" header.
- **if_none_match** (str) - Return object only if its entity tag does not match the given value. Also called an "If-None-Match" header.
- **if_unmodified_since** (str) - Return object only if it has not been modified since the specified date. Also called an "If-Unmodified-Since" header.
- **range** (OffsetRange | SuffixRange | str) - Return only a subset of the object. See `OffsetRange` and `SuffixRange`.
- **version** (str) - Return a specific version of the object.

### Response
#### Success Response (200)
- **GetResult** - An object containing the retrieved data and associated metadata.
  - **attributes** (dict) - Metadata attributes of the object.
  - **meta** (dict) - Additional metadata.
  - **range** (OffsetRange | SuffixRange | str) - The range of the data returned.
  - **buffer()** - Returns the object's content as bytes.
  - **buffer_async()** - Asynchronously returns the object's content as bytes.
  - **bytes()** - Returns the object's content as bytes.
  - **bytes_async()** - Asynchronously returns the object's content as bytes.
  - **stream()** - Returns a stream of the object's content.

### Request Example
```python
# Assuming 'store' is an initialized Obstore client
result = await store.get_async("my-object-key")
print(result.attributes)
print(await result.bytes_async())
```

### Response Example
```json
{
  "attributes": {
    "content-type": "application/json"
  },
  "meta": {},
  "range": null,
  "data": "{\"key\": \"value\"}"
}
```
```

--------------------------------

### Wrap synchronous obstore downloads with tqdm

Source: https://developmentseed.org/obstore/latest/examples/tqdm

Use this pattern for standard synchronous file retrieval. Requires the tqdm library and an initialized HTTPStore.

```python
from obstore.store import HTTPStore
from tqdm import tqdm

store = HTTPStore.from_url("https://ookla-open-data.s3.us-west-2.amazonaws.com")
path = "parquet/performance/type=fixed/year=2019/quarter=1/2019-01-01_performance_fixed_tiles.parquet"
response = obs.get(store, path)
file_size = response.meta["size"]
with tqdm(total=file_size) as pbar:
    for bytes_chunk in response:
        # Do something with buffer
        pbar.update(len(bytes_chunk))
```

--------------------------------

### Get Object Metadata Asynchronously

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Call `head` asynchronously. Refer to the documentation for head_async.

```python
head_async(path: str) -> ObjectMeta


```

--------------------------------

### Get Object Metadata

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Return the metadata for the specified location. Refer to the documentation for head.

```python
head(path: str) -> ObjectMeta


```

--------------------------------

### Construct Generic ObjectStore from URL

Source: https://developmentseed.org/obstore/latest/api/store

Constructs an ObjectStore from a URL, with options for automatic cleanup and directory creation. Defaults to no specific configuration.

```python
from_url(
    url: str,
    *,
    config: None = None,
    client_options: None = None,
    retry_config: None = None,
    automatic_cleanup: bool = False,
    mkdir: bool = False
) -> ObjectStore
```

--------------------------------

### Construct FsspecStore and List Items

Source: https://developmentseed.org/obstore/latest/integrations/fsspec

Construct an fsspec-compatible filesystem with `FsspecStore`. This implements `AbstractFileSystem`, so you can use it wherever an API expects an fsspec-compatible filesystem. Use `fs.ls()` to list items in a prefix.

```python
from obstore.fsspec import FsspecStore

fs = FsspecStore("s3", region="us-west-2", skip_signature=True)
prefix = (
    "s3://sentinel-cogs/sentinel-s2-l2a-cogs/12/S/UF/2022/6/S2B_12SUF_20220609_0_L2A/"
)
items = fs.ls(prefix)
# [{'name': 'sentinel-cogs/sentinel-s2-l2a-cogs/12/S/UF/2022/6/S2B_12SUF_20220609_0_L2A/AOT.tif',
#   'size': 80689,
#   'type': 'file',
#   'e_tag': '"c93b0f6b0e2cf8e375968f41161f9df7"'},
#   ...


```

--------------------------------

### Get Multiple Ranges Asynchronously

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Call `get_ranges` asynchronously. Refer to the documentation for get_ranges_async.

```python
get_ranges_async(
    path: str,
    *,
    starts: Sequence[int],
    ends: Sequence[int] | None = None,
    lengths: Sequence[int] | None = None,
    coalesce: int = 1024 * 1024
) -> list[Bytes]


```

--------------------------------

### List Objects in LocalStore (ObjectMeta Format)

Source: https://developmentseed.org/obstore/latest/api/store/local

Lists all objects with a given prefix, returning results as a stream of ObjectMeta sequences. Supports offset and chunk size customization.

```python
list(prefix: str | None = None, *, offset: str | None = None, chunk_size: int = 50, return_arrow: Literal[False] = False) -> ListStream[Sequence[ObjectMeta]]
```

--------------------------------

### Get Current Position in AsyncReadableFile

Source: https://developmentseed.org/obstore/latest/api/file

Return the current byte offset within the stream.

```python
tell() -> int
```

--------------------------------

### Initialize and Use NasaEarthdataCredentialProvider

Source: https://developmentseed.org/obstore/latest/api/auth/earthdata

Demonstrates how to initialize the NasaEarthdataCredentialProvider and use it with S3Store to download a file. Ensure you are in the correct AWS region (us-west-2) for credentials to be valid. The provider will attempt to use environment variables or netrc for authentication if no explicit credentials are provided.

```python
from obstore.store import S3Store
from obstore.auth.earthdata import NasaEarthdataCredentialProvider

# Obtain an S3 credentials URL and an S3 data/download URL, typically
# via metadata returned from a NASA CMR collection or granule query.
credentials_url = "https://data.ornldaac.earthdata.nasa.gov/s3credentials"
data_url = (
    "s3://ornl-cumulus-prod-protected/gedi/GEDI_L4A_AGB_Density_V2_1/data/"
    "GEDI04_A_2024332225741_O33764_03_T01289_02_004_01_V002.h5"
)
data_prefix_url, filename = data_url.rsplit("/", 1)

# Since no NASA Earthdata credentials are specified in this example, 
# environment variables or netrc will be used to locate them in order to
# obtain S3 credentials from the URL.
cp = NasaEarthdataCredentialProvider(credentials_url)

store = S3Store.from_url(data_prefix_url, credential_provider=cp)

# Download the file by streaming chunks
try:
    result = store.get(filename)
    with open(filename, "wb") as f:
        for chunk in iter(result):
            f.write(chunk)
finally:
    cp.close()

```

--------------------------------

### Get Object Metadata from HTTPStore

Source: https://developmentseed.org/obstore/latest/api/store/http

Retrieves the metadata for the object at the specified location in the HTTPStore.

```python
head(path: str) -> ObjectMeta

```

--------------------------------

### obstore.store.ObjectStoreMethods.get_async

Source: https://developmentseed.org/obstore/latest/api/get

Asynchronously retrieves the bytes stored at a specified location. This is the asynchronous counterpart to the `get` method.

```APIDOC
## obstore.store.ObjectStoreMethods.get_async

### Description

Call `get` asynchronously.

### Method

GET (assumed, as it's a retrieval operation)

### Endpoint

`/objects/{path}` (assumed, based on common RESTful patterns for object storage)

### Parameters

#### Path Parameters

- **path** (str) - Required - The path to the object to retrieve.

#### Query Parameters

- **options** (GetOptions | None) - Optional - Additional options for the get operation.

### Response

#### Success Response (200)

- **result** (GetResult) - The result of the asynchronous get operation, likely containing the retrieved bytes.

#### Response Example

```json
{
  "result": "..."
}
```
```

--------------------------------

### GCSStore from_url Class Method

Source: https://developmentseed.org/obstore/latest/api/store/gcs

Constructs a GCSStore from a well-known storage URL (e.g., gs://bucket/path). The path component of the URL is used as the prefix for store operations. Configuration can be overridden via parameters.

```python
from_url(url: str, *, prefix: str | None = None, config: GCSConfig | None = None, client_options: ClientConfig | None = None, retry_config: RetryConfig | None = None, credential_provider: GCSCredentialProvider | None = None, **kwargs: Unpack[GCSConfig]) -> Self
```