{"id":14979125,"url":"https://github.com/suryasekhar14/vercel_blob","last_synced_at":"2025-10-28T14:30:50.223Z","repository":{"id":243371135,"uuid":"810510846","full_name":"SuryaSekhar14/vercel_blob","owner":"SuryaSekhar14","description":"A Python wrapper for the Vercel Blob Storage API","archived":false,"fork":false,"pushed_at":"2024-10-03T19:48:37.000Z","size":45,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-10-11T18:42:14.012Z","etag":null,"topics":["blob-storage","python","vercel"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/vercel_blob/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SuryaSekhar14.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-04T20:51:44.000Z","updated_at":"2024-10-03T19:48:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"762d52dc-810f-4632-af37-d69a006c0be1","html_url":"https://github.com/SuryaSekhar14/vercel_blob","commit_stats":{"total_commits":45,"total_committers":2,"mean_commits":22.5,"dds":"0.022222222222222254","last_synced_commit":"19fbceb06b839152f39824944bbd568e0efa382f"},"previous_names":["suryasekhar14/vercel_blob"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuryaSekhar14%2Fvercel_blob","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuryaSekhar14%2Fvercel_blob/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuryaSekhar14%2Fvercel_blob/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SuryaSekhar14%2Fvercel_blob/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SuryaSekhar14","download_url":"https://codeload.github.com/SuryaSekhar14/vercel_blob/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859520,"owners_count":16556036,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blob-storage","python","vercel"],"created_at":"2024-09-24T13:59:19.034Z","updated_at":"2025-10-28T14:30:50.217Z","avatar_url":"https://github.com/SuryaSekhar14.png","language":"Python","funding_links":["https://www.buymeacoffee.com/suryasekhar"],"categories":[],"sub_categories":[],"readme":"# vercel_blob\n\nA Python wrapper for the Vercel Blob Storage API\n\n![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/SuryaSekhar14/vercel_blob/custom-tests.yaml?branch=master\u0026label=tests)\n![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https://toolkit.surya.dev/api/stats?package=vercel_blob\u0026query=totalDownloads\u0026label=Total%20Downloads)\n\n\n\u003ca href=\"https://www.buymeacoffee.com/suryasekhar\" target=\"_blank\"\u003e\u003cimg src=\"https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png\" alt=\"Buy Me A Coffee\" style=\"height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;\" \u003e\u003c/a\u003e\n\n## Installation\n\n\n```bash\npip3 install vercel_blob\n```\n\n## Getting Started\n\n### Python Version\n\nThis package (vercel_blob) was written using Python 3 in mind, and Python 2 will not work properly.\n\n### Set Environment Variable for Authorization\n\n```bash\nexport BLOB_READ_WRITE_TOKEN=\"superssecretkey\"\n```\n\n### Add vercel_blob to your code\n\n```python\nimport vercel_blob\n#or\nimport vercel_blob.blob_store\n# or if you want to use an alias\nimport vercel_blob.blob_store as vb_store\n```\n\n## Using vercel_blob\n\nCurrently only supports the basic list, put, delete, copy and head(get file metadata) operations. Here's a quick overview:\n\n### List all files in the Blob Storage\n\nThe list method will return a list of all files in the blob storage. You can pass 'limit' to limit the returned number of blobs.\n\n```python\ndef list_all_blobs():\n    blobs = vercel_blob.list({\n        'limit': '5',\n    })\n```\n\nlist() returns a JSON object in the following format:\n\n```javascript\nblobs: {\n  size: `number`;\n  uploadedAt: `Date`;\n  pathname: `string`;\n  url: `string`;\n  downloadUrl: `string`\n}[]\ncursor?: `string`;\nhasMore: `boolean`;\nfolders?: `string[]`\n```\n\nFor a long list of blob objects (the default list limit is 1000), you can use the cursor and hasMore parameters to paginate through the results as shown in the example below:\n\n```python\nblobs = vercel_blob.list({\n        'limit': '4',\n        'cursor': cursor,\n    })\n```\n\n### Upload File / Blob to the Storage\n\nThe put method can be used to upload a blob to the blob store. If the blob is already present in the store, it will be overwritten.\n\n```python\ndef upload_a_blob():\n    with open('file.txt', 'rb') as f:\n        resp = vercel_blob.put('test.txt', f.read(), verbose=True)\n        print(resp)\n```\n\nThe method takes in the filename as the first argument, and the bytes of the file as the second argument. The third parameters can be the options dictionary. The `verbose` parameter (default: False) can be used to show detailed progress information during upload.\n\nFor large files, you can enable multipart uploads by passing `multipart=True` to the `put` method. This splits the file into smaller parts, offering resilience against network issues and potentially speeding up the upload process. Vercel Blob Storage supports multipart uploads for files up to 5TB.\n\n```python\ndef upload_large_file_multipart():\n    with open('large_video.mp4', 'rb') as f:\n        resp = vercel_blob.put('large_video.mp4', f.read(), multipart=True, verbose=True)\n        print(resp)\n```\n\nThe response object would look something like this:\n```javascript\npathname: `string`,\ncontentType: `string`,\ncontentDisposition: `string`,\nurl: `string`\ndownloadUrl: `string`\n```\n\nBy default, blobs are uploaded without a random suffix. If you want to add a random suffix to prevent overwriting existing files, you can set the 'addRandomSuffix' parameter to \"true\" in the options dictionary. Here's an example:\n\n```python\ndef upload_a_blob():\n    with open('file.txt', 'rb') as f:\n        resp = vercel_blob.put('test.txt', f.read(), {\n                \"addRandomSuffix\": \"true\",\n            })\n        print(resp)\n```\n\n### Delete a blob or a list of blobs from the Blob Storage\n\nThe delete method will delete a file from the Blob Storage. It takes in the URL of the blob, or a list of blobs. Here's an example:\n\n```python\ndef delete_a_list_of_blobs():\n    resp = vercel_blob.delete([\n            'blob_url_1',\n            'blob_url_2'\n        ])\n    print(resp)\n```\n\nPrinting the response will result in \"None\", since the delete method does not return anything. If a blob is present, it will be deleted. If a blob is not present, it will not result in any error.\n\n### Get blob metadata\n\nThe head method will return the blob object's metadata.\n\n```python\ndef get_blob_metadata():\n    resp = vercel_blob.head('blob_url')\n    print(resp)\n```\n\nThe JSON object returned will contain the following properties:\n```javascript\n  size: `number`;\n  uploadedAt: `Date`;\n  pathname: `string`;\n  contentType: `string`;\n  contentDisposition: `string`;\n  url: `string`;\n  downloadUrl: `string`\n  cacheControl: `string`;\n```\n\nIf the blob url provided is not valid, an Exception will be thrown.\n\n### Copy blob from one folder to another\n\nThe copy method can be used to copy an existing blob to another location inside the same blob store. Note that the addRandomSuffix option is False by default for copy operations, hence it overwrites by default. To prevent this behavior, you can set the 'addRandomSuffix' option to \"true\".\n\n```python\ndef copy_a_blob():\n    resp = vercel_blob.copy(\"https://surya.public.blob.vercel-storage.com/test.txt\", \"new-folder/test.txt\", verbose=True)\n    print(resp)\n```\n\nThe `verbose` parameter (default: False) can be used to show detailed progress information during the copy operation.\n\nThe JSON representation of the response should look something like this:\n```javascript\n  pathname: `string`,\n  contentType: `string`,\n  contentDisposition: `string`,\n  url: `string`\n  downloadUrl: `string`\n```\n\n### Download a file on the server\n\nIf you want to make the client download a file, you just redirect him to the downloadUrl. But for the server, you can use the download_file() method.\n\n```python\ndef download_a_file_on_the_server():\n    vercel_blob.download_file('blob_url', 'path/to/directory/', {'token': 'my_token'}, verbose=True)\n```\n\nThe file will be downloaded to the specified directory. If no directory is specified, it will be downloaded to the program's base directory. The `verbose` parameter (default: False) can be used to show detailed progress information during download.\n\n\n## Common Issues\n\n1. Since this storage is still in beta, the requests sometimes results in unexpected Connection Errors. To mitigate this, I used a 'retry request' function, that attempts 3 requests with exponential backoff between requests. \n\n    This might result in error messages like ```Request failed on attempt 1 (HTTPSConnectionPool(host='blob.vercel-storage.com', port=443): Read timed out. (read timeout=10))``` in the terminal.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuryasekhar14%2Fvercel_blob","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuryasekhar14%2Fvercel_blob","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuryasekhar14%2Fvercel_blob/lists"}