zipwire 0.3.0__tar.gz → 0.4.0__tar.gz

{zipwire-0.3.0 → zipwire-0.4.0}/.github/dependabot.yml

@@ -8,3 +8,5 @@ updates:
       codeql:
         patterns:
           - "github/codeql-action/*"
+    cooldown:
+      default-days: 7

{zipwire-0.3.0 → zipwire-0.4.0}/.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
         with:
           enable-cache: true
       - run: uvx ruff check src tests
@@ -37,10 +37,10 @@ jobs:
         python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
     continue-on-error: ${{ matrix.python-version == '3.15' }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
         with:
           enable-cache: true
       - run: uv tool install --python ${{ matrix.python-version }} tox --with tox-uv --with tox-gh
@@ -58,10 +58,10 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
         with:
           enable-cache: true
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
@@ -78,10 +78,10 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
         with:
           enable-cache: true
       - run: uv sync --group docs

{zipwire-0.3.0 → zipwire-0.4.0}/.github/workflows/codeql.yml

@@ -16,10 +16,10 @@ jobs:
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1
+      - uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd  # v4.37.7
         with:
           languages: python
-      - uses: github/codeql-action/analyze@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1
+      - uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd  # v4.37.7

{zipwire-0.3.0 → zipwire-0.4.0}/.github/workflows/release.yml

@@ -12,12 +12,12 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990  # v8.3.2
+      - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
         with:
-          enable-cache: true
+          enable-cache: false
       - run: uv build
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:
@@ -36,6 +36,6 @@ jobs:
         with:
           name: dist
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
         with:
           attestations: true

{zipwire-0.3.0 → zipwire-0.4.0}/.github/workflows/scorecard.yml

@@ -15,10 +15,10 @@ jobs:
       security-events: write
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           persist-credentials: false
-      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a  # v2.4.3
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc  # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -28,6 +28,6 @@ jobs:
           name: scorecard-results
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@7188fc363630916deb702c7fdcf4e481b751f97a  # v4.37.1
+      - uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd  # v4.37.7
         with:
           sarif_file: results.sarif

{zipwire-0.3.0 → zipwire-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: zipwire
-Version: 0.3.0
+Version: 0.4.0
 Summary: Read and extract files from remote ZIP archives over HTTP range requests
 Project-URL: Homepage, https://github.com/tiran/zipwire
 Project-URL: Documentation, https://zipwire.readthedocs.io/
@@ -60,8 +60,13 @@ CDNs, object stores, and static file servers do.
   memory usage low even for large entries.
 - **Sync and async** - `SyncRemoteZip` for synchronous code,
   `AsyncRemoteZip` with `await`/`async with` for asyncio.
+- **Wheel metadata** - `SyncRemoteWheel` / `AsyncRemoteWheel` read a Python
+  wheel's `.dist-info` (METADATA, WHEEL, RECORD) straight from PyPI in a single
+  adaptive tail request, without downloading the wheel.
 - **ZIP64** - supports archives and entries larger than 4 GiB.
 - **Pluggable backends** - bring your own HTTP library (see below).
+- **Local files** - `FileReader` / `AsyncFileReader` open an archive on disk
+  through the exact same API, no HTTP server required.
 
 ## Installation and backends
 
@@ -81,11 +86,36 @@ pip install zipwire[httpx2]
 | requests | `RequestsReader`     | sync  | 1.1     | `requests`    |
 | aiohttp  | `AiohttpReader`      | async | 1.1     | `aiohttp`     |
 
-Every backend accepts an optional pre-configured client or session so you can
-share connection pools, authentication, and retry configuration.
+Every HTTP backend accepts an optional pre-configured client or session so you
+can share connection pools, authentication, and retry configuration.
+
+For archives that already live on the local filesystem, `FileReader` and
+`AsyncFileReader` (in `zipwire.backends`, no extra dependency) satisfy the same
+reader protocols - see the local-file example below.
 
 ## Examples
 
+### Read Python wheel metadata without downloading the wheel
+
+A common use case: fetch a wheel's `METADATA`, `WHEEL`, or `RECORD` from PyPI
+without downloading the (often huge) wheel itself. `SyncRemoteWheel` and
+`AsyncRemoteWheel` parse the wheel URL to locate the `.dist-info` directory and
+fetch an adaptive tail, so metadata entries are served from memory without
+extra HTTP requests:
+
+```python
+from zipwire import SyncRemoteWheel
+from zipwire.backends import Urllib3Reader
+
+url = "https://files.pythonhosted.org/.../requests-2.32.3-py3-none-any.whl"
+with SyncRemoteWheel(Urllib3Reader(url)) as whl:
+    print(whl.read(whl.metadata_name).decode())
+```
+
+This optimization relies on the [recommended wheel layout](https://packaging.python.org/en/latest/specifications/binary-distribution-format/#recommended-archiver-features)
+of placing `.dist-info` at the end of the archive; wheels built otherwise still
+work, falling back to a normal range request per entry.
+
 ### Sync - list files and read one
 
 ```python
@@ -130,6 +160,21 @@ async def main():
 asyncio.run(main())
 ```
 
+### Local archive - same API, no HTTP
+
+`FileReader` opens an archive from disk through the same interface, accepting a
+path or a `file://` URI. `AsyncFileReader` is the async counterpart. This lets
+code that already uses zipwire handle local and remote archives the same way,
+without special-casing either.
+
+```python
+from zipwire import SyncRemoteZip
+from zipwire.backends import FileReader
+
+with SyncRemoteZip(FileReader("/path/to/archive.zip")) as rz:
+    data = rz.read("path/to/file.txt")
+```
+
 ## License
 
 Apache-2.0

{zipwire-0.3.0 → zipwire-0.4.0}/README.md

@@ -25,8 +25,13 @@ CDNs, object stores, and static file servers do.
   memory usage low even for large entries.
 - **Sync and async** - `SyncRemoteZip` for synchronous code,
   `AsyncRemoteZip` with `await`/`async with` for asyncio.
+- **Wheel metadata** - `SyncRemoteWheel` / `AsyncRemoteWheel` read a Python
+  wheel's `.dist-info` (METADATA, WHEEL, RECORD) straight from PyPI in a single
+  adaptive tail request, without downloading the wheel.
 - **ZIP64** - supports archives and entries larger than 4 GiB.
 - **Pluggable backends** - bring your own HTTP library (see below).
+- **Local files** - `FileReader` / `AsyncFileReader` open an archive on disk
+  through the exact same API, no HTTP server required.
 
 ## Installation and backends
 
@@ -46,11 +51,36 @@ pip install zipwire[httpx2]
 | requests | `RequestsReader`     | sync  | 1.1     | `requests`    |
 | aiohttp  | `AiohttpReader`      | async | 1.1     | `aiohttp`     |
 
-Every backend accepts an optional pre-configured client or session so you can
-share connection pools, authentication, and retry configuration.
+Every HTTP backend accepts an optional pre-configured client or session so you
+can share connection pools, authentication, and retry configuration.
+
+For archives that already live on the local filesystem, `FileReader` and
+`AsyncFileReader` (in `zipwire.backends`, no extra dependency) satisfy the same
+reader protocols - see the local-file example below.
 
 ## Examples
 
+### Read Python wheel metadata without downloading the wheel
+
+A common use case: fetch a wheel's `METADATA`, `WHEEL`, or `RECORD` from PyPI
+without downloading the (often huge) wheel itself. `SyncRemoteWheel` and
+`AsyncRemoteWheel` parse the wheel URL to locate the `.dist-info` directory and
+fetch an adaptive tail, so metadata entries are served from memory without
+extra HTTP requests:
+
+```python
+from zipwire import SyncRemoteWheel
+from zipwire.backends import Urllib3Reader
+
+url = "https://files.pythonhosted.org/.../requests-2.32.3-py3-none-any.whl"
+with SyncRemoteWheel(Urllib3Reader(url)) as whl:
+    print(whl.read(whl.metadata_name).decode())
+```
+
+This optimization relies on the [recommended wheel layout](https://packaging.python.org/en/latest/specifications/binary-distribution-format/#recommended-archiver-features)
+of placing `.dist-info` at the end of the archive; wheels built otherwise still
+work, falling back to a normal range request per entry.
+
 ### Sync - list files and read one
 
 ```python
@@ -95,6 +125,21 @@ async def main():
 asyncio.run(main())
 ```
 
+### Local archive - same API, no HTTP
+
+`FileReader` opens an archive from disk through the same interface, accepting a
+path or a `file://` URI. `AsyncFileReader` is the async counterpart. This lets
+code that already uses zipwire handle local and remote archives the same way,
+without special-casing either.
+
+```python
+from zipwire import SyncRemoteZip
+from zipwire.backends import FileReader
+
+with SyncRemoteZip(FileReader("/path/to/archive.zip")) as rz:
+    data = rz.read("path/to/file.txt")
+```
+
 ## License
 
 Apache-2.0

{zipwire-0.3.0 → zipwire-0.4.0}/docs/api.rst

@@ -78,6 +78,14 @@ Backends
 .. autoclass:: zipwire.backends._aiohttp.AiohttpReader
    :members:
 
+.. autoclass:: zipwire.backends._file.FileReader
+   :members:
+   :special-members: __enter__, __exit__
+
+.. autoclass:: zipwire.backends._file.AsyncFileReader
+   :members:
+   :special-members: __aenter__, __aexit__
+
 Exceptions
 ----------
 

{zipwire-0.3.0 → zipwire-0.4.0}/docs/backends.rst

@@ -43,6 +43,16 @@ Available backends
      - async
      - 1.1
      - ``aiohttp``
+   * - local files
+     - :class:`~zipwire.backends.FileReader`
+     - sync
+     - --
+     - *(included)*
+   * - local files
+     - :class:`~zipwire.backends.AsyncFileReader`
+     - async
+     - --
+     - *(included)*
 
 Choosing a backend
 ------------------
@@ -60,6 +70,57 @@ Choosing a backend
 - **Requests integration** - use :class:`~zipwire.backends.RequestsReader`
   if your project already uses ``requests`` and you want to share sessions,
   authentication, or retry configuration.
+- **Local archives** - use :class:`~zipwire.backends.FileReader` or
+  :class:`~zipwire.backends.AsyncFileReader` to read a ZIP or wheel that
+  already lives on the local filesystem.  No extra dependency is required.
+
+Reading local files
+-------------------
+
+:class:`~zipwire.backends.FileReader` and
+:class:`~zipwire.backends.AsyncFileReader` back the same
+:class:`~zipwire.SyncRemoteZip` / :class:`~zipwire.AsyncRemoteZip` API with
+local file IO, so identical code opens a local or a remote archive.  Instead
+of an HTTP round-trip, :meth:`~zipwire.backends.FileReader.head` synthesises
+``Content-Length`` / ``Accept-Ranges`` from ``os.fstat`` on the open handle
+(the size is cached, assuming the file does not change), and range reads
+seek into a lazily-opened file handle.  A missing path raises
+:exc:`FileNotFoundError`, mirroring how a network 404 surfaces as
+:exc:`OSError`.
+
+Both accept either a path (``str`` / :class:`os.PathLike`) or a ``file://``
+URI via :meth:`~zipwire.backends.FileReader.from_uri` (percent-decoded, with
+an empty or ``localhost`` host).
+
+.. code-block:: python
+
+   from zipwire import SyncRemoteZip
+   from zipwire.backends import FileReader
+
+   with SyncRemoteZip(FileReader("/path/to/archive.zip")) as rz:
+       data = rz.read("file.txt")
+
+   reader = FileReader.from_uri("file:///path/to/archive.zip")
+
+Regular files do not support true non-blocking IO, so
+:class:`~zipwire.backends.AsyncFileReader` offloads every blocking call to a
+worker thread via :func:`asyncio.to_thread` -- the same approach libraries
+such as ``aiofiles`` use internally, without the extra dependency.
+
+.. code-block:: python
+
+   import asyncio
+
+   from zipwire import AsyncRemoteZip
+   from zipwire.backends import AsyncFileReader
+
+
+   async def main():
+       async with AsyncRemoteZip(AsyncFileReader("/path/to/archive.zip")) as rz:
+           print(await rz.read("file.txt"))
+
+
+   asyncio.run(main())
 
 Passing an existing client
 --------------------------

{zipwire-0.3.0 → zipwire-0.4.0}/docs/quickstart.rst

@@ -46,6 +46,25 @@ entries:
        with open("output.bin", "wb") as f:
            rz.read_into("big-file.bin", f)
 
+Read a local archive
+^^^^^^^^^^^^^^^^^^^^
+
+:class:`~zipwire.backends.FileReader` opens an archive on the local
+filesystem through the same interface, so the same code works for local and
+remote archives.  It accepts a path or a ``file://`` URI and needs no extra
+dependency:
+
+.. code-block:: python
+
+   from zipwire import SyncRemoteZip
+   from zipwire.backends import FileReader
+
+   with SyncRemoteZip(FileReader("/path/to/archive.zip")) as rz:
+       data = rz.read("path/to/file.txt")
+
+   # Or from a file:// URI
+   reader = FileReader.from_uri("file:///path/to/archive.zip")
+
 Asynchronous usage
 ------------------
 
@@ -89,6 +108,27 @@ Async with httpx2
 
    asyncio.run(main())
 
+Async local archive
+^^^^^^^^^^^^^^^^^^^
+
+:class:`~zipwire.backends.AsyncFileReader` reads a local archive and offloads
+blocking file IO to a worker thread so it never stalls the event loop:
+
+.. code-block:: python
+
+   import asyncio
+
+   from zipwire import AsyncRemoteZip
+   from zipwire.backends import AsyncFileReader
+
+
+   async def main():
+       async with AsyncRemoteZip(AsyncFileReader("/path/to/archive.zip")) as rz:
+           print(await rz.read("path/to/file.txt"))
+
+
+   asyncio.run(main())
+
 Async streaming to disk
 ^^^^^^^^^^^^^^^^^^^^^^^^
 

{zipwire-0.3.0 → zipwire-0.4.0}/src/zipwire/__init__.py

@@ -59,6 +59,23 @@ Asynchronous:
   - ``Httpx2AsyncReader`` -- uses *httpx2*, supports HTTP/2
     (``pip install zipwire[httpx2]``)
 
+Local files:
+  - ``FileReader`` / ``AsyncFileReader`` -- read an archive from the local
+    filesystem through the same API (no extra dependency).  Useful for
+    testing or for handling ``file://`` URIs and local paths uniformly
+    with HTTP URLs.
+
+::
+
+    from zipwire import SyncRemoteZip
+    from zipwire.backends import FileReader
+
+    with SyncRemoteZip(FileReader("/path/to/archive.zip")) as rz:
+        data = rz.read("path/inside/archive.txt")
+
+    # From a file:// URI
+    reader = FileReader.from_uri("file:///path/to/archive.zip")
+
 Wheel subclasses
 ----------------
 

{zipwire-0.3.0 → zipwire-0.4.0}/src/zipwire/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.0'
-__version_tuple__ = version_tuple = (0, 3, 0)
+__version__ = version = '0.4.0'
+__version_tuple__ = version_tuple = (0, 4, 0)
 
 __commit_id__ = commit_id = None

{zipwire-0.3.0 → zipwire-0.4.0}/src/zipwire/backends/__init__.py

@@ -14,6 +14,8 @@ from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from zipwire.backends._aiohttp import AiohttpReader as AiohttpReader
+    from zipwire.backends._file import AsyncFileReader as AsyncFileReader
+    from zipwire.backends._file import FileReader as FileReader
     from zipwire.backends._httpx2 import Httpx2AsyncReader as Httpx2AsyncReader
     from zipwire.backends._httpx2 import Httpx2SyncReader as Httpx2SyncReader
     from zipwire.backends._requests import RequestsReader as RequestsReader
@@ -25,6 +27,8 @@ _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "AiohttpReader": ("zipwire.backends._aiohttp", "AiohttpReader"),
     "Urllib3Reader": ("zipwire.backends._urllib3", "Urllib3Reader"),
     "RequestsReader": ("zipwire.backends._requests", "RequestsReader"),
+    "FileReader": ("zipwire.backends._file", "FileReader"),
+    "AsyncFileReader": ("zipwire.backends._file", "AsyncFileReader"),
 }
 
 __all__ = list(_LAZY_IMPORTS)

zipwire-0.4.0/src/zipwire/backends/_file.py

@@ -0,0 +1,206 @@
+"""Local-file readers that satisfy the SyncReader / AsyncReader protocols.
+
+``FileReader`` and ``AsyncFileReader`` back the same
+:class:`~zipwire.SyncRemoteZip` / :class:`~zipwire.AsyncRemoteZip` API with
+local file IO, so an archive on disk opens exactly like a remote one.  They
+are useful for testing, for treating ``file://`` URIs uniformly with HTTP
+URLs, and for reading a wheel or ZIP that already lives on the local
+filesystem without a running HTTP server.
+
+Unlike the HTTP backends there is no network round-trip: :meth:`head`
+synthesises headers from ``os.fstat`` on the open handle (the size is
+cached, assuming the file does not change), and range reads seek into a
+lazily-opened file handle.
+
+Regular files do not support true non-blocking IO (``epoll``/``select`` and
+``O_NONBLOCK`` do not apply to them), so ``AsyncFileReader`` offloads every
+blocking call to a worker thread via :func:`asyncio.to_thread` -- the same
+strategy libraries such as ``aiofiles`` use internally, without the extra
+dependency.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import typing
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+from zipwire._constants import STREAM_CHUNK_SIZE
+
+if typing.TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+
+    from zipwire._types import Headers
+
+
+def _path_from_file_uri(uri: str) -> str:
+    """Convert a ``file://`` URI to a local filesystem path.
+
+    Accepts an empty or ``localhost`` host and percent-decodes the path
+    via :func:`urllib.request.url2pathname`.
+
+    Raises:
+        ValueError: If *uri* is not a ``file://`` URI or names a remote host.
+    """
+    parsed = urlparse(uri)
+    if parsed.scheme != "file":
+        raise ValueError(f"Not a file:// URI: {uri!r}")
+    if parsed.netloc not in ("", "localhost"):
+        raise ValueError(f"Non-local file URI host {parsed.netloc!r} in {uri!r}")
+    return url2pathname(parsed.path)
+
+
+def _stat_headers(size: int) -> dict[str, str]:
+    """Synthesise HTTP-style headers describing a local file of *size* bytes."""
+    return {"content-length": str(size), "accept-ranges": "bytes"}
+
+
+class FileReader:
+    """SyncReader implementation backed by a local file.
+
+    Opens the file lazily on the first read and keeps a single handle
+    open until :meth:`close` (or context-manager exit).  A missing path
+    surfaces as :exc:`FileNotFoundError`, mirroring how an HTTP 404
+    surfaces as :exc:`OSError` in the network backends.
+    """
+
+    def __init__(self, path: str | os.PathLike[str], *, url: str | None = None) -> None:
+        self._path = os.fspath(path)
+        self._url = url if url is not None else self._path
+        self._handle: typing.BinaryIO | None = None
+        self._size: int | None = None
+
+    @classmethod
+    def from_uri(cls, uri: str) -> FileReader:
+        """Create a :class:`FileReader` from a ``file://`` URI."""
+        return cls(_path_from_file_uri(uri), url=uri)
+
+    @property
+    def url(self) -> str:
+        """The original path or ``file://`` URI for this reader."""
+        return self._url
+
+    def _open(self) -> typing.BinaryIO:
+        if self._handle is None:
+            self._handle = open(self._path, "rb")  # noqa: SIM115
+        return self._handle
+
+    def _file_size(self) -> int:
+        # Cached from fstat on the open handle.  We assume the file does
+        # not change for the lifetime of the reader.
+        if self._size is None:
+            self._size = os.fstat(self._open().fileno()).st_size
+        return self._size
+
+    def head(self) -> Headers:
+        return _stat_headers(self._file_size())
+
+    def read_range(self, offset: int, length: int) -> tuple[bytes, Headers]:
+        fh = self._open()
+        fh.seek(offset)
+        data = fh.read(length)
+        return data, _stat_headers(self._file_size())
+
+    def stream_range(self, offset: int, length: int) -> Iterator[bytes]:
+        fh = self._open()
+        fh.seek(offset)
+        remaining = length
+        while remaining > 0:
+            chunk = fh.read(min(STREAM_CHUNK_SIZE, remaining))
+            if not chunk:
+                break
+            remaining -= len(chunk)
+            yield chunk
+
+    def close(self) -> None:
+        if self._handle is not None:
+            self._handle.close()
+            self._handle = None
+        self._size = None
+
+    def __enter__(self) -> FileReader:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncFileReader:
+    """AsyncReader implementation backed by a local file.
+
+    Regular files cannot be read without blocking, so every blocking
+    call is offloaded to a worker thread with :func:`asyncio.to_thread`,
+    keeping the event loop responsive.  A missing path surfaces as
+    :exc:`FileNotFoundError`, mirroring how an HTTP 404 surfaces as
+    :exc:`OSError` in the network backends.
+    """
+
+    def __init__(self, path: str | os.PathLike[str], *, url: str | None = None) -> None:
+        self._path = os.fspath(path)
+        self._url = url if url is not None else self._path
+        self._handle: typing.BinaryIO | None = None
+        self._size: int | None = None
+
+    @classmethod
+    def from_uri(cls, uri: str) -> AsyncFileReader:
+        """Create an :class:`AsyncFileReader` from a ``file://`` URI."""
+        return cls(_path_from_file_uri(uri), url=uri)
+
+    @property
+    def url(self) -> str:
+        """The original path or ``file://`` URI for this reader."""
+        return self._url
+
+    def _open(self) -> typing.BinaryIO:
+        if self._handle is None:
+            self._handle = open(self._path, "rb")  # noqa: SIM115
+        return self._handle
+
+    def _file_size(self) -> int:
+        # Cached from fstat on the open handle.  We assume the file does
+        # not change for the lifetime of the reader.
+        if self._size is None:
+            self._size = os.fstat(self._open().fileno()).st_size
+        return self._size
+
+    async def head(self) -> Headers:
+        size = await asyncio.to_thread(self._file_size)
+        return _stat_headers(size)
+
+    async def read_range(self, offset: int, length: int) -> tuple[bytes, Headers]:
+        def _read() -> tuple[bytes, int]:
+            fh = self._open()
+            fh.seek(offset)
+            return fh.read(length), self._file_size()
+
+        data, size = await asyncio.to_thread(_read)
+        return data, _stat_headers(size)
+
+    async def stream_range(self, offset: int, length: int) -> AsyncIterator[bytes]:
+        def _open_seek() -> typing.BinaryIO:
+            fh = self._open()
+            fh.seek(offset)
+            return fh
+
+        fh = await asyncio.to_thread(_open_seek)
+        remaining = length
+        while remaining > 0:
+            chunk = await asyncio.to_thread(fh.read, min(STREAM_CHUNK_SIZE, remaining))
+            if not chunk:
+                break
+            remaining -= len(chunk)
+            yield chunk
+
+    async def close(self) -> None:
+        if self._handle is not None:
+            await asyncio.to_thread(self._handle.close)
+            self._handle = None
+        self._size = None
+
+    async def __aenter__(self) -> AsyncFileReader:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()