vercel-blob-bundle 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vercel, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,498 @@
1
+ Metadata-Version: 2.5
2
+ Name: vercel-blob-bundle
3
+ Version: 0.5.0
4
+ Summary: Python SDK for Vercel Blob
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Requires-Python: >=3.10
8
+ Requires-Dist: anyio<5,>=4.0.0
9
+ Requires-Dist: pydantic<3,>=2.7.0
10
+ Requires-Dist: vercel-internal-core-bundle<0.3.0,>=0.2.2
11
+ Requires-Dist: vercel-internal-shared-vendored-deps>=0.1.4
12
+ Requires-Dist: vercel-oidc-bundle>=0.10.0
13
+ Description-Content-Type: text/markdown
14
+
15
+ # vercel-blob-bundle
16
+
17
+ This is a version of `vercel-blob` with third-party dependencies bundled. For normal use, install the unbundled `vercel-blob` package instead: https://pypi.org/project/vercel-blob/
18
+
19
+ # Vercel Blob Python SDK
20
+
21
+ `vercel-blob` provides async object operations through `vercel.blob` and matching
22
+ sync operations through `vercel.blob.sync`.
23
+
24
+ ```sh
25
+ pip install vercel-blob
26
+ ```
27
+
28
+ ## Object lifecycle
29
+
30
+ Set `BLOB_READ_WRITE_TOKEN` to a read-write token for your store. On Vercel, you
31
+ can instead use OIDC credentials with `BLOB_STORE_ID`.
32
+
33
+ Use `access="public"` for a public store or `access="private"` for a private store.
34
+ The access value must match the store.
35
+
36
+ ```python
37
+ from vercel import blob
38
+
39
+ async def round_trip() -> None:
40
+ uploaded = await blob.put_blob("hello.txt", b"hello, Blob!", access="public")
41
+ try:
42
+ result = await blob.get_blob(uploaded.url, access="public")
43
+ print(result.metadata.content_type)
44
+ print(result.body)
45
+ async with blob.stream_blob(uploaded.url, access="public") as download:
46
+ async for chunk in download:
47
+ print(chunk)
48
+ metadata = await blob.head_blob(uploaded.url)
49
+ print(metadata.size)
50
+ finally:
51
+ await blob.delete_blob(uploaded.url)
52
+ ```
53
+
54
+ The sync API needs no event loop:
55
+
56
+ ```python
57
+ from vercel.blob import sync as blob
58
+
59
+ uploaded = blob.put_blob("hello.txt", b"hello, Blob!", access="public")
60
+ try:
61
+ result = blob.get_blob(uploaded.url, access="public")
62
+ print(result.metadata.content_type)
63
+ print(result.body)
64
+ with blob.stream_blob(uploaded.url, access="public") as download:
65
+ for chunk in download:
66
+ print(chunk)
67
+ print(blob.head_blob(uploaded.url).size)
68
+ finally:
69
+ blob.delete_blob(uploaded.url)
70
+ ```
71
+
72
+ ## Operations
73
+
74
+ | Operation | Input | Result |
75
+ | --- | --- | --- |
76
+ | `put_blob` | Pathname, `bytes` or streaming body, required `access` | `PutResult` from the upload response |
77
+ | `get_blob` | Pathname or Blob delivery URL, required `access` | `GetResult` with download metadata and the complete body as `bytes` |
78
+ | `stream_blob` | Pathname or Blob delivery URL, required `access` | Context manager yielding an iterable byte download |
79
+ | `head_blob` | Pathname or Blob delivery URL | `HeadResult` with size, upload time, and object metadata |
80
+ | `delete_blob` | One target or a sequence of 1–1,000 pathnames or Blob delivery URLs | `None` |
81
+ | `query_blobs` | Optional prefix, page size, and starting cursor | Iterator of `ListBlob` entries that follows pagination automatically |
82
+ | `query_blob_entries` | Optional directory prefix, page size, and starting cursor | Iterator of `ListBlob \| BlobPrefix` at one directory level |
83
+ | `copy_blob` | Source pathname or Blob delivery URL, destination pathname, required `access` | `CopyResult` from the copy response |
84
+ | `multipart_upload_blob` | Pathname, required `access`, upload options | Context yielding a sequential part uploader; `result: PutResult` after successful exit |
85
+
86
+ `put_blob`, `get_blob`, `head_blob`, `copy_blob`, and `delete_blob` are awaited in
87
+ the async API. Iterate over `query_blobs` or `query_blob_entries` with `async for`,
88
+ without awaiting the call. Enter
89
+ `stream_blob` with `async with`. The sync API uses ordinary calls, iterates over
90
+ `query_blobs` with `for`, and enters `stream_blob` with `with`.
91
+
92
+ Pathnames are relative to the store. One leading slash is removed. Empty paths,
93
+ control characters, invalid Unicode, `//`, and `.` or `..` path segments are
94
+ rejected. `put_blob` and copy destinations accept at most 950 UTF-16 code units in
95
+ the original pathname, matching the TypeScript SDK. Characters outside the Unicode Basic Multilingual
96
+ Plane count as two units. Reads do not inherit this upload limit.
97
+
98
+ Pathnames are literal object names, not URL-encoded strings or local file paths.
99
+ Characters such as `?`, `#`, and `%` are preserved and encoded when constructing
100
+ a delivery URL. Delivery URLs must use HTTPS and a standard
101
+ `<store>.<access>.blob.vercel-storage.com` host. Their path is checked after one
102
+ UTF-8 percent-decode, including for control characters and dot segments. The
103
+ encoded path is preserved, queries are retained, and fragments are removed.
104
+ Private URL downloads must belong to the credential's store. Redirects are not
105
+ followed. Custom delivery domains are not supported.
106
+
107
+ The SDK does not execute object names or write downloads to local files. Pathname
108
+ validation is not a shell-escaping or filesystem-safety guarantee. Applications
109
+ must not use untrusted object names as commands or unchecked local file paths.
110
+
111
+ ### Upload options
112
+
113
+ | Keyword | Default | Behavior |
114
+ | --- | --- | --- |
115
+ | `access` | Required | `"public"` or `"private"` |
116
+ | `content_length` | `None` | Byte length; optional for buffers, required for streaming bodies |
117
+ | `content_type` | `None` | Explicit media type; otherwise the service determines it |
118
+ | `add_random_suffix` | `False` | Set to `True` to add a random suffix and avoid pathname collisions |
119
+ | `allow_overwrite` | `False` | Permit replacement of an existing object when enabled |
120
+ | `cache_control_max_age` | `None` | Cache lifetime in whole seconds; otherwise use the service default |
121
+
122
+ `put_blob` accepts in-memory buffers (`bytes`, `bytearray`, `memoryview`) and streaming
123
+ sources with a known length. It infers content length for buffers and snapshots them
124
+ at call time. Uploads use a stable pathname by default, matching the TypeScript SDK.
125
+ To replace an existing object, set `allow_overwrite=True`. To create distinct objects with
126
+ random suffixes, set `add_random_suffix=True` and use the returned `pathname` or
127
+ `url` when referring to each upload.
128
+
129
+ `PutResult` contains `url`, `download_url`, `pathname`, `content_type`,
130
+ `content_disposition`, and `etag`. It does not contain size or upload time.
131
+ `head_blob` returns those additional fields without downloading the object's content.
132
+ No extra metadata request runs after `put_blob`.
133
+
134
+ ### Streaming uploads
135
+
136
+ `put_blob` also accepts byte readers and byte iterables when `content_length` is provided.
137
+ Each API accepts only sources of its own shape:
138
+
139
+ - **Async API**: `AsyncByteReader` (an object with `async def read`) or
140
+ `AsyncIterable[bytes]`.
141
+ - **Sync API**: `SyncByteReader` (an object with a blocking `read`) or `Iterable[bytes]`.
142
+
143
+ The async API does not run blocking reads on worker threads for you. It rejects sync
144
+ readers and sync iterables with a `TypeError`; adapt them as shown below.
145
+
146
+ Streaming uploads require an explicit `content_length` in bytes. Unknown-length streams
147
+ and spooling to temporary files are not supported. The SDK validates that the uploaded
148
+ stream matches the declared length:
149
+
150
+ - If the source ends before `content_length` bytes, `BlobContentLengthError` is raised.
151
+ - If the source yields more than `content_length` bytes, `BlobContentLengthError` is
152
+ raised and the excess data is never sent.
153
+ - Uploads send an explicit `Content-Length` header without chunked transfer encoding.
154
+
155
+ Sources remain caller-owned. The SDK does not close, seek, or retry caller sources. If
156
+ an upload fails, the source's stream position is unspecified.
157
+
158
+ Upload a local file with the sync API:
159
+
160
+ ```python
161
+ from pathlib import Path
162
+ from vercel.blob import sync as blob
163
+
164
+ path = Path("report.pdf")
165
+ size = path.stat().st_size
166
+ with path.open("rb") as file:
167
+ uploaded = blob.put_blob("report.pdf", file, access="public", content_length=size)
168
+ ```
169
+
170
+ In async code, open the file with `anyio.open_file`:
171
+
172
+ ```python
173
+ import anyio
174
+ from vercel import blob
175
+
176
+ async def upload_report() -> blob.PutResult:
177
+ path = anyio.Path("report.pdf")
178
+ size = (await path.stat()).st_size
179
+ async with await anyio.open_file(path, "rb") as file:
180
+ return await blob.put_blob("report.pdf", file, access="public", content_length=size)
181
+ ```
182
+
183
+ Wrap a sync file object you already have with `anyio.wrap_file(file)`. Adapt a sync
184
+ iterator into an async iterable. An async generator is enough for in-memory chunks;
185
+ if producing a chunk can block, pull each chunk on a worker thread:
186
+
187
+ ```python
188
+ from collections.abc import AsyncIterator, Iterable, Iterator
189
+
190
+ import anyio
191
+
192
+ async def from_memory(chunks: Iterable[bytes]) -> AsyncIterator[bytes]:
193
+ for chunk in chunks:
194
+ yield chunk
195
+
196
+ async def from_blocking(chunks: Iterator[bytes]) -> AsyncIterator[bytes]:
197
+ while (chunk := await anyio.to_thread.run_sync(next, chunks, None)) is not None:
198
+ yield chunk
199
+ ```
200
+
201
+ ### Multipart uploads
202
+
203
+ Use `multipart_upload_blob` when you want to choose complete parts explicitly. It
204
+ accepts the same metadata, suffix, and overwrite options as `put_blob`. Enter the
205
+ context with `async with` (or `with` for `blob.sync`); do not await its creation.
206
+
207
+ ```python
208
+ from collections.abc import AsyncIterator
209
+ from vercel import blob
210
+
211
+ async def first_part() -> AsyncIterator[bytes]:
212
+ for _ in range(80):
213
+ yield b"x" * (64 * 1024)
214
+
215
+ async def upload_parts() -> blob.PutResult:
216
+ async with blob.multipart_upload_blob("parts.bin", access="public") as upload:
217
+ await upload.upload_part(first_part(), content_length=5 * 1024 * 1024)
218
+ await upload.upload_part(b"tail")
219
+ return upload.result
220
+ ```
221
+
222
+ The sync API accepts sync readers and iterables:
223
+
224
+ ```python
225
+ from vercel.blob import sync as blob
226
+
227
+ with blob.multipart_upload_blob("parts.bin", access="public") as upload:
228
+ upload.upload_part(
229
+ (b"x" * (64 * 1024) for _ in range(80)), content_length=5 * 1024 * 1024
230
+ )
231
+ upload.upload_part(b"tail")
232
+ print(upload.result.url)
233
+ ```
234
+
235
+ `upload_part` returns `None`. The SDK assigns consecutive numbers starting at 1
236
+ and retains successful ETags internally. There is no part-number argument,
237
+ receipt list, or manual completion step. Upload one part at a time; overlapping
238
+ calls fail the handle. There is no background scheduling or automatic retry.
239
+
240
+ Parts accept the same sources and exact-length checks as `put_blob`: buffer lengths
241
+ are inferred, streaming lengths are required, and sources stay caller-owned.
242
+ Each part must contain 1 byte through 5 GiB, with at most 10,000 parts. Every
243
+ part except the last must be at least 5 MiB. After a smaller part, a further
244
+ part is rejected before consuming its source or sending its request. An empty
245
+ scope raises without completing; use `put_blob(pathname, b"", ...)` for an empty object.
246
+
247
+ A successful context exit publishes the object and makes `upload.result`
248
+ available. Normal early `return` or `break` is a successful exit and publishes
249
+ the uploaded parts. Exceptions and cancellation prevent completion. A failed
250
+ part, including a validation or source error caught inside the block, permanently
251
+ fails that handle; normal exit then raises `BlobError` instead of publishing a
252
+ prefix. Result access before successful exit raises `BlobError`, as do part
253
+ uploads before entry or after exit.
254
+ Keep the multipart context inside its session scope.
255
+
256
+ Completion errors propagate from context exit and leave `result` unavailable.
257
+ A lost completion response can leave publication uncertain; the SDK does not
258
+ retry completion. The backend has no multipart abort action. Local cleanup does
259
+ not delete remote parts or roll back an object that may already have published.
260
+
261
+ ### Collections
262
+
263
+ Both runtimes expose `query_blobs`, `query_blob_entries`, `copy_blob`, and batch
264
+ `delete_blob`. Like Sandbox's `query_*` APIs, `query_blobs` lazily yields
265
+ individual objects and automatically
266
+ follows pagination cursors. Each `ListBlob` includes URL, download URL, pathname,
267
+ size, upload date, and ETag.
268
+
269
+ ```python
270
+ async for item in blob.query_blobs(prefix="reports/", page_size=100):
271
+ print(item.pathname, item.size)
272
+
273
+ # Synchronous iteration needs no event loop.
274
+ for item in blob.sync.query_blobs(prefix="reports/", page_size=100):
275
+ print(item.pathname, item.size)
276
+ ```
277
+
278
+ `page_size` is the maximum number of objects fetched per API request, an integer
279
+ from 1 to 1,000 (the service defaults to 1,000). It does not limit the total number
280
+ of objects yielded. `prefix` is a literal pathname prefix. The optional opaque
281
+ `cursor` specifies where to begin iteration; subsequent cursors are followed
282
+ internally.
283
+
284
+ Creating an iterator sends no HTTP request. Validation and the first request
285
+ happen when iteration begins. The iterator retains one page at a time and fetches
286
+ the next page only after yielding the current page's objects. Breaking out early
287
+ does not fetch further pages. Like Sandbox, iteration stops at an empty page or
288
+ when no next cursor remains. Errors propagate during iteration without restarting
289
+ or retrying the listing. Iterate within the session's lifetime.
290
+
291
+ `query_blobs` includes objects in nested folders. For browsing a single directory
292
+ level, use `query_blob_entries`. It yields the same `ListBlob` instances for objects
293
+ and frozen `BlobPrefix(prefix=...)` instances for virtual folders:
294
+
295
+ ```python
296
+ async for entry in blob.query_blob_entries(prefix="reports/", page_size=100):
297
+ match entry:
298
+ case blob.BlobPrefix(prefix=prefix):
299
+ print(f"Folder: {prefix}")
300
+ case blob.ListBlob(pathname=pathname, size=size):
301
+ print(f"Object: {pathname} ({size} bytes)")
302
+ ```
303
+
304
+ Nonempty directory prefixes must end in `/`; `None` or `""` browses the root.
305
+ Prefixes are literal, not normalized or URL-decoded. Each returned `BlobPrefix`
306
+ includes its trailing slash and can be passed directly to another
307
+ `query_blob_entries(prefix=entry.prefix)` call. These prefixes represent virtual
308
+ groupings, not stored objects with sizes or ETags.
309
+
310
+ `query_blob_entries` uses the same lazy pagination and starting-cursor conventions as
311
+ `query_blobs`. Its `page_size` counts both objects and folder prefixes per service
312
+ request. Objects precede folder prefixes within each page, preserving each
313
+ service-provided sequence. There is no globally sorted order across pages.
314
+ Folder-only pages are not empty: iteration continues through their next cursors.
315
+
316
+ Synchronous browsing uses `for entry in blob.sync.query_blob_entries(...)`. Neither
317
+ query exposes public page results. Listing is not a snapshot while objects change.
318
+
319
+ ```python
320
+ from vercel.blob import copy_blob, delete_blob
321
+
322
+ copied = await copy_blob(
323
+ "reports/source.bin",
324
+ "reports/archive.bin",
325
+ access="private",
326
+ content_type="application/octet-stream",
327
+ cache_control_max_age=300,
328
+ if_match=source_etag,
329
+ )
330
+ await delete_blob(["reports/source.bin", copied.url])
331
+ ```
332
+
333
+ Copy runs on the server within the credential's store and returns `CopyResult`
334
+ from the copy response without a download or preliminary HEAD. Source accepts
335
+ a pathname or Blob delivery URL; destination is a pathname. As with PUT,
336
+ `access` is required, and `add_random_suffix` and `allow_overwrite` default to
337
+ `False`. Source metadata is not preserved: set content type and cache age
338
+ explicitly when needed. Copy's `if_match` checks the **source** ETag, not the
339
+ destination. A mismatch raises `BlobPreconditionFailedError`.
340
+
341
+ Delete accepts one target or a sequence of 1–1,000 targets in one request.
342
+ Every target is validated before credentials or HTTP. It does not split large
343
+ batches, retry them, or promise atomic deletion; an error can leave a batch's
344
+ outcome uncertain. Missing targets are harmless. `if_match` is supported only
345
+ for a single target (including a sequence of length one), and checks that
346
+ object's ETag. Invalid sizes and batch preconditions fail locally.
347
+
348
+ For synchronous usage, iterate over `blob.sync.query_blobs` and call `blob.sync.copy_blob` and
349
+ `blob.sync.delete_blob` without `await`. The package examples exercise cursor
350
+ pagination, conditional copy, and batch cleanup in both runtimes.
351
+
352
+ ### Downloads and ownership
353
+
354
+ `get_blob` buffers the complete body in memory and returns a frozen, slotted
355
+ `GetResult` with `metadata: DownloadMetadata` and `body: bytes`. It closes the
356
+ response before returning, and the result remains usable after the session closes.
357
+ Read errors raise an exception rather than returning a partial body. There is no
358
+ `max_bytes` parameter or decoding helper.
359
+
360
+ `stream_blob` provides incremental reads without buffering the complete body. Entering
361
+ its context obtains the response. Both APIs accept the same pathname or Blob
362
+ delivery URL and require `access`. Neither issues a preliminary HEAD request.
363
+
364
+ `result.metadata` and `download.metadata` contain the URL, status code, and
365
+ response-derived headers such as size, content type, ETag, and last-modified time.
366
+ Header-derived fields are `None` when the server omits them. In particular,
367
+ `metadata.size` stays `None` when the size header is absent, even after `get_blob`
368
+ reads the body. Use `len(result.body)` for the actual number of downloaded bytes.
369
+
370
+ A streamed download has one consumer. Iterate it once inside its context. It yields
371
+ byte chunks of at most 64 KiB, with a smaller final chunk. It closes its response at
372
+ EOF, on early context exit, on read errors, and on cancellation. Explicit closure
373
+ uses `await download.aclose()` or `download.close()`. Closed downloads reject
374
+ further reads. There is no automatic restart after a partial download.
375
+
376
+ The session owns the HTTP client; each streamed download owns its response.
377
+ Exiting a download does not close the session. Enter `stream_blob` contexts inside their
378
+ session scope. Operations and streaming reads reject a closed session. Module
379
+ calls outside an explicit session use the SDK's default session.
380
+
381
+ A complete public delivery URL can be downloaded without Blob credentials.
382
+ Pathname downloads need credentials to identify the store. Private downloads
383
+ attach credentials only after validating the delivery URL and store.
384
+
385
+ ### Errors
386
+
387
+ `get_blob`, `stream_blob`, and `head_blob` raise `BlobNotFoundError` for missing objects.
388
+ Deleting an absent object succeeds when the backend returns its normal successful
389
+ deletion response.
390
+ Other deletion errors, including an unknown store, are not suppressed.
391
+
392
+ Service errors inherit from `BlobError` and expose `status_code` and `code` when
393
+ available. Common subclasses include `BlobAccessError`, `BlobStoreNotFoundError`,
394
+ `BlobPreconditionFailedError`, and `BlobServiceRateLimited`. Malformed responses
395
+ raise `BlobStreamError`; missing or invalid credentials raise `BlobCredentialsError`.
396
+ Invalid arguments fail before credential factories or HTTP requests run.
397
+
398
+ ## Session configuration
399
+
400
+ Default credential discovery uses OIDC with `BLOB_STORE_ID` when both are
401
+ available, then `BLOB_READ_WRITE_TOKEN` or `VERCEL_BLOB_READ_WRITE_TOKEN`.
402
+ Store IDs may include the `store_` prefix.
403
+
404
+ For application-managed credentials, configure a factory on the session:
405
+
406
+ ```python
407
+ import os
408
+
409
+ from vercel import blob
410
+ from vercel.api import session
411
+
412
+ async def credentials() -> blob.BlobCredentials:
413
+ return blob.BlobCredentials(
414
+ token=os.environ["MY_BLOB_TOKEN"],
415
+ store_id=os.environ["MY_BLOB_STORE_ID"],
416
+ )
417
+
418
+ async def inspect_object() -> None:
419
+ options = blob.BlobServiceOptions(credentials_factory=credentials)
420
+ async with session(service_options=[options]):
421
+ print(await blob.head_blob("hello.txt"))
422
+ ```
423
+
424
+ Set `kind=blob.CredentialKind.OIDC` for an OIDC token. The factory runs for each
425
+ operation that needs credentials, so it can refresh tokens. A session's factory
426
+ must continue to identify the same store.
427
+
428
+ Use `vercel.blob.sync.SyncBlobServiceOptions` with a synchronous factory for sync
429
+ calls. An async factory supplied to the sync API is rejected. Custom HTTP clients
430
+ are configured through the SDK session's `httpx_client_factory`, not through Blob.
431
+
432
+ ## Examples and verification
433
+
434
+ [Async lifecycle](examples/blob_async.py) and [sync lifecycle](examples/blob_sync.py)
435
+ upload a unique object, compare downloaded bytes, inspect metadata, and delete the
436
+ object in `finally`. The async example also adapts a sync file and a sync iterator
437
+ for streaming uploads. Both examples also stream multipart parts, verify the
438
+ published content, and delete the resulting object.
439
+
440
+ The collection operations have separate, independently runnable examples:
441
+
442
+ | Scenario | Async | Sync | What it demonstrates |
443
+ | --- | --- | --- | --- |
444
+ | Browse a documentation library | [Browse](examples/blob_browse_async.py) | [Browse](examples/blob_browse_sync.py) | Use `query_blobs` for an inventory and total storage size; recursively follow `BlobPrefix` entries from `query_blob_entries` to print a directory tree. |
445
+ | Publish a reviewed draft | [Copy](examples/blob_copy_async.py) | [Copy](examples/blob_copy_sync.py) | Copy a reviewed source revision with `copy_blob(if_match=...)`, configure the published document's metadata, and preview its content. |
446
+
447
+ The browser examples create a small library with an index, two guides, and an API
448
+ reference. They use a small `page_size` to exercise pagination. Each example seeds
449
+ its own unique pathnames and removes its objects in `finally`. All use the same
450
+ credential and access configuration as the lifecycle examples.
451
+
452
+ From the repository root:
453
+
454
+ ```sh
455
+ uv run poe test vercel-blob
456
+ uv run poe qa vercel-blob
457
+ uv run poe test vercel-blob -- -m live
458
+ uv run poe test-examples vercel-blob
459
+ ```
460
+
461
+ To run one scenario directly with your configured credentials:
462
+
463
+ ```sh
464
+ uv run python src/vercel-blob/examples/blob_browse_sync.py
465
+ uv run python src/vercel-blob/examples/blob_copy_async.py
466
+ ```
467
+
468
+ ### Live tests
469
+
470
+ Live tests and examples run against every store they find in the environment:
471
+
472
+ | Store | Credentials | Access |
473
+ | --- | --- | --- |
474
+ | Default | `BLOB_READ_WRITE_TOKEN`, or `BLOB_STORE_ID` with Vercel OIDC | `BLOB_TEST_ACCESS`, default `public` |
475
+ | `BLOB_PUBLIC` | `BLOB_PUBLIC_READ_WRITE_TOKEN`, or `BLOB_PUBLIC_STORE_ID` with Vercel OIDC | `public` |
476
+ | `BLOB_PRIVATE` | `BLOB_PRIVATE_READ_WRITE_TOKEN`, or `BLOB_PRIVATE_STORE_ID` with Vercel OIDC | `private` |
477
+
478
+ The prefixes match the environment variable prefix you choose when you connect a
479
+ store to a Vercel project. Each test object lives under a unique `vercel-py-live/`
480
+ or `vercel-py-examples/` pathname, and each test deletes its objects. With no
481
+ store configured, the tests skip, and a skip does not verify the service.
482
+
483
+ To test with a linked project, pull its development environment and source it
484
+ from the repository root. This example uses a project whose private store has no
485
+ prefix and whose public store uses `BLOB_PUBLIC`:
486
+
487
+ ```sh
488
+ vc link --scope <team> --project <project>
489
+ vc env pull .env.local
490
+ (set -a && . ./.env.local && BLOB_TEST_ACCESS=private uv run poe test vercel-blob -- -m live)
491
+ ```
492
+
493
+ Source the file instead of passing `uv run --env-file`. uv does not override
494
+ variables that are already set, so a `VERCEL_OIDC_TOKEN` exported for another
495
+ project wins, and the Blob API answers `403 Invalid token`.
496
+
497
+ This release does not include unknown-length streaming uploads or file-like
498
+ `open` operations.