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.
- vercel_blob_bundle-0.5.0/LICENSE +21 -0
- vercel_blob_bundle-0.5.0/PKG-INFO +498 -0
- vercel_blob_bundle-0.5.0/README.md +484 -0
- vercel_blob_bundle-0.5.0/_vercel_hatch_build.py +151 -0
- vercel_blob_bundle-0.5.0/hatch_build.py +29 -0
- vercel_blob_bundle-0.5.0/pyproject.toml +98 -0
- vercel_blob_bundle-0.5.0/vercel/blob/__init__.py +288 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/__init__.py +1 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/api_client.py +658 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/credentials.py +128 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/download.py +196 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/multipart.py +213 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/options.py +77 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/pagination.py +106 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/service.py +235 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/upload.py +291 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_internal/validation.py +246 -0
- vercel_blob_bundle-0.5.0/vercel/blob/_vendor/__init__.py +1 -0
- vercel_blob_bundle-0.5.0/vercel/blob/errors.py +215 -0
- vercel_blob_bundle-0.5.0/vercel/blob/models.py +121 -0
- vercel_blob_bundle-0.5.0/vercel/blob/py.typed +0 -0
- vercel_blob_bundle-0.5.0/vercel/blob/sync/__init__.py +287 -0
- vercel_blob_bundle-0.5.0/vercel/blob/version.py +1 -0
|
@@ -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.
|