feat: Simplify Store protocol to only define length (#12)

* feat: Simplify GetRangeAsync to only define `length`

* Rename to Store and update readme and tests

Author: kylebarron

README.md

@@ -1,48 +1,18 @@
-# aiopmtiles
+# async-pmtiles
 
-<p align="center">
-  <em>Async Version of Python PMTiles Reader.</em>
-</p>
-<p align="center">
-  <a href="https://github.com/developmentseed/aiopmtiles/actions?query=workflow%3ACI" target="_blank">
-      <img src="https://github.com/developmentseed/aiopmtiles/workflows/CI/badge.svg" alt="Test">
-  </a>
-  <a href="https://codecov.io/gh/developmentseed/aiopmtiles" target="_blank">
-      <img src="https://codecov.io/gh/developmentseed/aiopmtiles/branch/main/graph/badge.svg" alt="Coverage">
-  </a>
-  <a href="https://pypi.org/project/aiopmtiles" target="_blank">
-      <img src="https://img.shields.io/pypi/v/aiopmtiles?color=%2334D058&label=pypi%20package" alt="Package version">
-  </a>
-  <a href="https://pypistats.org/packages/aiopmtiles" target="_blank">
-      <img src="https://img.shields.io/pypi/dm/aiopmtiles.svg" alt="Downloads">
-  </a>
-  <a href="https://github.com/developmentseed/aiopmtiles/blob/main/LICENSE" target="_blank">
-      <img src="https://img.shields.io/github/license/developmentseed/aiopmtiles.svg" alt="Downloads">
-  </a>
-</p>
+An asynchronous [PMTiles] reader for Python.
 
----
+The [PMTiles format] is a cloud-native, compressed, single-file archive for storing tiled vector and raster map data.
 
-**Documentation**: <a href="https://developmentseed.org/aiopmtiles/" target="_blank">https://developmentseed.org/aiopmtiles/</a>
+[PMTiles]: https://docs.protomaps.com/
+[PMTiles format]: https://docs.protomaps.com/pmtiles/
 
-**Source Code**: <a href="https://github.com/developmentseed/aiopmtiles" target="_blank">https://github.com/developmentseed/aiopmtiles</a>
+**Documentation**: <https://developmentseed.org/async-pmtiles/>
 
----
+## Install
 
-`aiopmtiles` is a python `Async I/O` version of the great [PMTiles](https://github.com/protomaps/PMTiles) python reader.
-
-The [**PMTiles**](https://github.com/protomaps/PMTiles) format is a *Cloud-optimized + compressed single-file tile archives for vector and raster maps*.
-
-## Installation
-
-```bash
-$ python -m pip install pip -U
-
-# From Pypi
-$ python -m pip install aiopmtiles
-
-# Or from source
-$ python -m pip install git+http://github.com/developmentseed/aiopmtiles
+```
+pip install async-pmtiles
 ```
 
 ## Example
@@ -74,18 +44,40 @@ src.tile_compression
 data = await src.get_tile(x=0, y=0, z=0)
 ```
 
-## Contribution & Development
-
-See [CONTRIBUTING.md](https://github.com/developmentseed/aiopmtiles/blob/main/CONTRIBUTING.md)
-
-## Authors
-
-See [contributors](https://github.com/developmentseed/aiopmtiles/graphs/contributors)
-
-## Changes
-
-See [CHANGES.md](https://github.com/developmentseed/aiopmtiles/blob/main/CHANGES.md).
-
-## License
-
-See [LICENSE](https://github.com/developmentseed/aiopmtiles/blob/main/LICENSE)
+### Custom Client
+
+Here's an example with using a small wrapper around `aiohttp` to read from arbitrary URLs:
+
+```py
+from dataclasses import dataclass
+from aiohttp import ClientSession
+from async_pmtiles import PMTilesReader, Store
+
+@dataclass
+class AiohttpAdapter(Store):
+    session: ClientSession
+
+    async def get_range_async(
+        self,
+        path: str,
+        *,
+        start: int,
+        length: int,
+    ) -> bytes:
+        inclusive_end = start + length - 1
+        headers = {"Range": f"bytes={start}-{inclusive_end}"}
+        async with self.session.get(path, headers=headers) as response:
+            return await response.read()
+
+
+async def main():
+    async with ClientSession() as session:
+        store = AiohttpAdapter(session)
+        url = "https://r2-public.protomaps.com/protomaps-sample-datasets/cb_2018_us_zcta510_500k.pmtiles"
+        src = await PMTilesReader.open(url, store=store)
+
+        assert src.header
+        assert src.bounds == (-176.684714, -14.37374, 145.830418, 71.341223)
+        assert src.minzoom == 0
+        assert src.maxzoom == 7
+```

docs/usage.md

@@ -26,7 +26,6 @@ extra:
 # Layout
 nav:
   - Home: "index.md"
-  - Usage: "usage.md"
   - API Reference: "api.md"
   - Changelog: "CHANGELOG.md"
   - Contributing: "DEVELOP.md"
@@ -108,14 +107,9 @@ plugins:
               - griffe_inherited_docstrings
 
           inventories:
-            - https://affine.readthedocs.io/en/latest/objects.inv
-            - https://developmentseed.org/async-tiff/latest/objects.inv
-            - https://developmentseed.org/morecantile/objects.inv
+            - https://developmentseed.org/obspec/latest/objects.inv
             - https://developmentseed.org/obstore/latest/objects.inv
             - https://docs.python.org/3/objects.inv
-            - https://numpy.org/doc/stable/objects.inv
-            - https://pyproj4.github.io/pyproj/stable/objects.inv
-            - https://rasterio.readthedocs.io/en/stable/objects.inv
 
 # https://github.com/developmentseed/titiler/blob/50934c929cca2fa8d3c408d239015f8da429c6a8/docs/mkdocs.yml#L115-L140
 markdown_extensions:

mkdocs.yml

@@ -32,6 +32,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "aiohttp>=3.13.3",
     "build>=1.4.0",
     "ipykernel>=7.2.0",
     "obstore>=0.8.2",

pyproject.toml

@@ -1,6 +1,6 @@
 """async-pmtiles: asynchronous interface for reading PMTiles files."""
 
-from ._reader import PMTilesReader
+from ._reader import PMTilesReader, Store
 from ._version import __version__
 
-__all__ = ["PMTilesReader", "__version__"]
+__all__ = ["PMTilesReader", "Store", "__version__"]