blob: Add basic read/write/remove operations

[scotttrinh]

Note: This is based on a feature branch that is unreviewed and not currently opened as a PR. That branch is a noisy bootstrapping effort that removes the old API and adds all of the necessary plumbing for the new vercel-blob package to live in the aggregate package. This keeps this PR focused on just this feature.

---

As the first slice of the Blob work, this PR adds the most basic modes for read/write, stat, and remove. Here's the basic usage:

try:
    async with blob.open(pathname, "w", content_type="text/plain") as writer:
        await writer.write("Hello from vercel-blob.\n")

    metadata = await blob.stat(pathname)
    async with blob.open(pathname) as reader:
        print(f"{metadata.pathname} ({metadata.size} bytes): {await reader.read()}", end="")
finally:
    await blob.remove(pathname, missing_ok=True)

It's intended to be congruent with both Python stdlib-like API and the existing Sandbox fs interface to allow streaming bytes/text around to different places with a mostly-consistent API.

---

Since Copilot brought this up, I figured it was worth adding this quick note. We're intentionally deferring lazy, bounded reads and the related text-offset performance optimization to a separate PR focused on range-backed readers. The current basic reader downloads and buffers the complete object, so both eager memory use and the text offset performance issue stem from the same temporary buffered design. That later work will introduce lazy range requests, bounded read-ahead, incremental text decoding across range boundaries, seeking, and proper response lifecycle management for both async and sync readers. Addressing these concerns now would optimize or partially replace an implementation we already plan to remove. I wanted to focus on the public API, which will not change when we later optimize and deliver the simplest implementation first.

[Copilot]

Pull request overview

This PR introduces the first functional slice of the new vercel-blob package by adding a file-oriented API for basic async and sync Blob operations (open/read/write, stat, and remove), implemented on top of the shared session/transport plumbing in the aggregate SDK.

Changes:

• Add async vercel.blob public surface with deferred open operations and file-like reader/writer facades.
• Add sync mirror API (vercel.blob.sync) implemented as thin wrappers over async-shaped internals via iter_coroutine.
• Add internal HTTP client, credentials/options/validation, plus comprehensive unit tests, live tests, and runnable examples/docs.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
uv.lock	Updates lockfile metadata/markers and adds editable vercel-blob dependency entries.
src/vercel-blob/vercel/blob/sync/init.py	Removes the prior placeholder sync package init.
src/vercel-blob/vercel/blob/sync.py	Adds synchronous Blob file API (open, stat, remove) and re-exports.
src/vercel-blob/vercel/blob/errors.py	Defines public exception types (including response-carrying errors).
src/vercel-blob/vercel/blob/_internal/validation.py	Adds pathname normalization and open-option validation.
src/vercel-blob/vercel/blob/_internal/sync_runtime.py	Implements sync IO facades for read/write streams and open wiring.
src/vercel-blob/vercel/blob/_internal/streams.py	Introduces transport-agnostic reader/writer cores and text decoding/offset logic.
src/vercel-blob/vercel/blob/_internal/service.py	Adds session-scoped BlobService and sync/async service factories.
src/vercel-blob/vercel/blob/_internal/options.py	Adds async/sync service option dataclasses and env-defaulting.
src/vercel-blob/vercel/blob/_internal/models.py	Adds shared credential/result models and type aliases.
src/vercel-blob/vercel/blob/_internal/credentials.py	Implements credential discovery/validation for RW token and OIDC flows.
src/vercel-blob/vercel/blob/_internal/async_runtime.py	Implements async IO facades, deferred open operation, and open wiring.
src/vercel-blob/vercel/blob/_internal/api_client.py	Adds HTTP request logic, response parsing, and error mapping.
src/vercel-blob/vercel/blob/_internal/init.py	Defines internal package marker/docstring.
src/vercel-blob/vercel/blob/init.py	Replaces placeholder async surface with full API and re-exports.
src/vercel-blob/tests/test_imports.py	Removes old placeholder import-surface test.
src/vercel-blob/tests/test_blob_public_flow.py	Adds unit tests covering async+sync lifecycle, validation, and error mapping.
src/vercel-blob/tests/live/test_examples.py	Adds live example execution test harness scoped by Poe args/credentials.
src/vercel-blob/tests/live/test_blob_live.py	Adds a live lifecycle test against real Blob credentials.
src/vercel-blob/README.md	Updates package documentation and adds async/sync usage guidance and examples.
src/vercel-blob/pyproject.toml	Declares package dependencies and configures pytest/live markers and Poe tasks.
src/vercel-blob/examples/blob_sync_binary.py	Adds runnable sync binary lifecycle example.
src/vercel-blob/examples/blob_sandbox_streaming.py	Adds end-to-end streaming example via Blob + Sandbox.
src/vercel-blob/examples/blob_async_text.py	Adds runnable async text lifecycle example.
changes/vercel-blob/basic-file-api.feature.md	Adds a news fragment describing the new basic Blob file APIs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.