vercel-blob-bundle 0.5.0__py3-none-any.whl

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,288 @@
1
+ """Asynchronous Vercel Blob SDK surface."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import AsyncIterator, Sequence
6
+ from contextlib import AbstractAsyncContextManager
7
+ from typing import Literal, overload
8
+
9
+ from vercel._internal.core.session import get_active_session
10
+
11
+ from . import sync
12
+ from ._internal.api_client import _PutRequest
13
+ from ._internal.download import AsyncBlobDownload, AsyncDownloadContext
14
+ from ._internal.multipart import AsyncMultipartUpload
15
+ from ._internal.options import BlobServiceOptions
16
+ from ._internal.pagination import (
17
+ query_blob_entries as _query_blob_entries,
18
+ query_blobs as _query_blobs,
19
+ )
20
+ from ._internal.service import get_blob_service
21
+ from .errors import (
22
+ BlobAccessError,
23
+ BlobContentLengthError,
24
+ BlobContentTypeNotAllowedError,
25
+ BlobCredentialsError,
26
+ BlobError,
27
+ BlobFileTooLargeError,
28
+ BlobNotFoundError,
29
+ BlobPathnameMismatchError,
30
+ BlobPreconditionFailedError,
31
+ BlobServiceNotAvailable,
32
+ BlobServiceRateLimited,
33
+ BlobStoreNotFoundError,
34
+ BlobStoreSuspendedError,
35
+ BlobStreamError,
36
+ BlobUnknownError,
37
+ )
38
+ from .models import (
39
+ Access,
40
+ AsyncByteReader,
41
+ BlobCredentials,
42
+ BlobCredentialsFactory,
43
+ BlobPrefix,
44
+ CopyResult,
45
+ CredentialKind,
46
+ DownloadMetadata,
47
+ GetResult,
48
+ HeadResult,
49
+ ListBlob,
50
+ PutBody,
51
+ PutResult,
52
+ SyncBlobCredentialsFactory,
53
+ SyncByteReader,
54
+ SyncPutBody,
55
+ )
56
+
57
+
58
+ @overload
59
+ async def put_blob(
60
+ pathname: str,
61
+ body: bytes | bytearray | memoryview,
62
+ *,
63
+ access: Literal["public", "private"],
64
+ content_length: int | None = None,
65
+ content_type: str | None = None,
66
+ add_random_suffix: bool = False,
67
+ allow_overwrite: bool = False,
68
+ cache_control_max_age: int | None = None,
69
+ ) -> PutResult: ...
70
+
71
+
72
+ @overload
73
+ async def put_blob(
74
+ pathname: str,
75
+ body: PutBody,
76
+ *,
77
+ access: Literal["public", "private"],
78
+ content_length: int,
79
+ content_type: str | None = None,
80
+ add_random_suffix: bool = False,
81
+ allow_overwrite: bool = False,
82
+ cache_control_max_age: int | None = None,
83
+ ) -> PutResult: ...
84
+
85
+
86
+ async def put_blob(
87
+ pathname: str,
88
+ body: bytes | bytearray | memoryview | PutBody,
89
+ *,
90
+ access: Literal["public", "private"],
91
+ content_length: int | None = None,
92
+ content_type: str | None = None,
93
+ add_random_suffix: bool = False,
94
+ allow_overwrite: bool = False,
95
+ cache_control_max_age: int | None = None,
96
+ ) -> PutResult:
97
+ """Store an object in Vercel Blob with bytes or streaming payload."""
98
+ service = get_blob_service(get_active_session())
99
+ return await service.put(
100
+ pathname,
101
+ body,
102
+ access=access,
103
+ content_length=content_length,
104
+ content_type=content_type,
105
+ add_random_suffix=add_random_suffix,
106
+ allow_overwrite=allow_overwrite,
107
+ cache_control_max_age=cache_control_max_age,
108
+ )
109
+
110
+
111
+ async def get_blob(
112
+ url_or_pathname: str,
113
+ *,
114
+ access: Literal["public", "private"],
115
+ ) -> GetResult:
116
+ """Download the complete object into memory and close its response."""
117
+ async with stream_blob(url_or_pathname, access=access) as download:
118
+ body = b"".join([chunk async for chunk in download])
119
+ return GetResult(metadata=download.metadata, body=body)
120
+
121
+
122
+ def multipart_upload_blob(
123
+ pathname: str,
124
+ *,
125
+ access: Literal["public", "private"],
126
+ content_type: str | None = None,
127
+ add_random_suffix: bool = False,
128
+ allow_overwrite: bool = False,
129
+ cache_control_max_age: int | None = None,
130
+ ) -> AsyncMultipartUpload:
131
+ """Create a scoped upload that publishes on successful context exit."""
132
+ request = _PutRequest(
133
+ pathname=pathname,
134
+ access=access,
135
+ content_type=content_type,
136
+ add_random_suffix=add_random_suffix,
137
+ allow_overwrite=allow_overwrite,
138
+ cache_control_max_age=cache_control_max_age,
139
+ )
140
+ service = get_blob_service(get_active_session())
141
+ return AsyncMultipartUpload(service, request)
142
+
143
+
144
+ def stream_blob(
145
+ url_or_pathname: str,
146
+ *,
147
+ access: Literal["public", "private"],
148
+ ) -> AbstractAsyncContextManager[AsyncBlobDownload]:
149
+ """Open an asynchronous streaming download context manager."""
150
+ session = get_active_session()
151
+
152
+ async def opener() -> AsyncBlobDownload:
153
+ service = get_blob_service(session)
154
+ stream, metadata = await service.open_download(url_or_pathname, access=access)
155
+ return AsyncBlobDownload(stream, metadata, check_session=service.check_open)
156
+
157
+ return AsyncDownloadContext(opener)
158
+
159
+
160
+ async def head_blob(
161
+ url_or_pathname: str,
162
+ ) -> HeadResult:
163
+ """Retrieve catalog metadata for a Blob object."""
164
+ service = get_blob_service(get_active_session())
165
+ return await service.head(url_or_pathname)
166
+
167
+
168
+ def query_blobs(
169
+ *,
170
+ prefix: str | None = None,
171
+ page_size: int | None = None,
172
+ cursor: str | None = None,
173
+ ) -> AsyncIterator[ListBlob]:
174
+ """Iterate over Blobs, transparently following pagination cursors.
175
+
176
+ Args:
177
+ prefix: Literal pathname prefix to filter objects.
178
+ page_size: Maximum number of objects fetched per API request (1–1,000).
179
+ cursor: Cursor at which to begin pagination.
180
+ """
181
+ return _query_blobs(
182
+ get_blob_service(get_active_session()),
183
+ prefix=prefix,
184
+ page_size=page_size,
185
+ cursor=cursor,
186
+ )
187
+
188
+
189
+ def query_blob_entries(
190
+ *,
191
+ prefix: str | None = None,
192
+ page_size: int | None = None,
193
+ cursor: str | None = None,
194
+ ) -> AsyncIterator[ListBlob | BlobPrefix]:
195
+ """Iterate over objects and virtual folders at one directory level.
196
+
197
+ Nonempty prefixes must end with '/'. Objects precede folder prefixes
198
+ within each page; no global sort order is guaranteed. Pagination follows
199
+ cursors lazily, including pages containing only folders.
200
+ """
201
+ return _query_blob_entries(
202
+ get_blob_service(get_active_session()),
203
+ prefix=prefix,
204
+ page_size=page_size,
205
+ cursor=cursor,
206
+ )
207
+
208
+
209
+ async def copy_blob(
210
+ source: str,
211
+ pathname: str,
212
+ *,
213
+ access: Literal["public", "private"],
214
+ content_type: str | None = None,
215
+ add_random_suffix: bool = False,
216
+ allow_overwrite: bool = False,
217
+ cache_control_max_age: int | None = None,
218
+ if_match: str | None = None,
219
+ ) -> CopyResult:
220
+ """Copy within a store; if_match checks the source ETag."""
221
+ service = get_blob_service(get_active_session())
222
+ return await service.copy(
223
+ source,
224
+ pathname,
225
+ access=access,
226
+ content_type=content_type,
227
+ add_random_suffix=add_random_suffix,
228
+ allow_overwrite=allow_overwrite,
229
+ cache_control_max_age=cache_control_max_age,
230
+ if_match=if_match,
231
+ )
232
+
233
+
234
+ async def delete_blob(
235
+ url_or_pathname: str | Sequence[str],
236
+ *,
237
+ if_match: str | None = None,
238
+ ) -> None:
239
+ """Delete 1–1000 objects in one request; if_match requires a single target."""
240
+ service = get_blob_service(get_active_session())
241
+ await service.delete(url_or_pathname, if_match=if_match)
242
+
243
+
244
+ __all__ = [
245
+ "Access",
246
+ "AsyncByteReader",
247
+ "AsyncMultipartUpload",
248
+ "BlobAccessError",
249
+ "BlobContentLengthError",
250
+ "BlobContentTypeNotAllowedError",
251
+ "BlobCredentials",
252
+ "BlobCredentialsError",
253
+ "BlobCredentialsFactory",
254
+ "BlobError",
255
+ "BlobFileTooLargeError",
256
+ "BlobNotFoundError",
257
+ "BlobPathnameMismatchError",
258
+ "BlobPreconditionFailedError",
259
+ "BlobPrefix",
260
+ "BlobServiceNotAvailable",
261
+ "BlobServiceOptions",
262
+ "BlobServiceRateLimited",
263
+ "BlobStoreNotFoundError",
264
+ "BlobStoreSuspendedError",
265
+ "BlobStreamError",
266
+ "BlobUnknownError",
267
+ "CopyResult",
268
+ "CredentialKind",
269
+ "DownloadMetadata",
270
+ "GetResult",
271
+ "HeadResult",
272
+ "ListBlob",
273
+ "PutBody",
274
+ "PutResult",
275
+ "SyncBlobCredentialsFactory",
276
+ "SyncByteReader",
277
+ "SyncPutBody",
278
+ "copy_blob",
279
+ "delete_blob",
280
+ "get_blob",
281
+ "head_blob",
282
+ "multipart_upload_blob",
283
+ "put_blob",
284
+ "query_blobs",
285
+ "query_blob_entries",
286
+ "stream_blob",
287
+ "sync",
288
+ ]
@@ -0,0 +1 @@
1
+ """Internal implementation details for Vercel Blob."""