BoostedBlob

1.0.0 · active · verified Thu Apr 09

BoostedBlob is a Python library and command-line tool designed for efficient, async-first file operations across local filesystems, Google Cloud Storage, and Azure Blob Storage. It provides a unified API for common tasks like copying, moving, listing, reading, and writing files. The current version is 1.0.0, which introduced significant API changes, moving from a single generic `Path` object to specific `LocalPath`, `GooglePath`, and `AzurePath` types. Its primary release cadence has been irregular but reached a stable `1.0.0` in April 2024.

Warnings

breaking The generic `boostedblob.Path` object was removed in v1.0.0. You must now use specific path types: `LocalPath`, `GooglePath`, or `AzurePath` imported from `boostedblob.path`.
Fix: Replace `Path(...)` with `LocalPath(...)`, `GooglePath(...)`, or `AzurePath(...)` and update imports accordingly (e.g., `from boostedblob.path import AzurePath`).
breaking Specific operations like `read_json`, `write_json`, `copy`, and `move` were moved from top-level `boostedblob` imports to dedicated submodules in v1.0.0.
Fix: Update imports from `from boostedblob import read_json` to `from boostedblob.read import read_json` (and similarly for `write`, `copy`, `move`). Note that `delete` and `list_dir` remain top-level imports for convenience.
breaking The return type of `list_dir` changed from `AsyncIterator[str]` to `AsyncIterator[boostedblob.path.BasePath]` in v1.0.0.
Fix: Adjust code that processes `list_dir` results to expect `BasePath` objects instead of raw strings. Access the path string via `.path` attribute if needed (e.g., `async for item in list_dir(...): print(item.path)`).
gotcha As of v1.0.0, `boostedblob.path.BasePath` objects are immutable. Modifying their attributes directly is no longer possible.
Fix: Instead of modifying an existing `BasePath` object, create a new one with the desired changes if you need a different path (e.g., `new_path = old_path.joinpath('new_segment')`).

Install

pip install boostedblob Local-only operations
pip install boostedblob[gcs,azure] With Google Cloud Storage and Azure Blob Storage support

Imports

LocalPath, AzurePath, GooglePath
```
from boostedblob.path import LocalPath, AzurePath, GooglePath
```
As of v1.0.0, the generic `Path` object was removed in favor of specific path types from `boostedblob.path`.
read_json, write_json
```
from boostedblob.read import read_json
from boostedblob.write import write_json
```
As of v1.0.0, `read_json` and `write_json` (and other specific operations like `copy`, `move`) were moved into dedicated submodules (`.read`, `.write`, `.copy`, `.move`). Top-level `delete`, `list_dir` are still available.

delete, list_dir

from boostedblob import delete, list_dir

Quickstart

This quickstart demonstrates basic file operations for local paths, and conditional operations for Azure Blob Storage. To run the Azure part, set `AZURE_STORAGE_ACCOUNT_NAME` and `AZURE_STORAGE_CONTAINER` environment variables. For Google Cloud Storage, ensure `boostedblob[gcs]` is installed and set `GOOGLE_APPLICATION_CREDENTIALS` and `GCS_BUCKET_NAME`.

import asyncio
import os
from boostedblob.path import LocalPath, AzurePath
from boostedblob import delete, list_dir
from boostedblob.read import read_json
from boostedblob.write import write_json

async def main():
    # 1. Local File Operations
    print("--- Local File Operations ---")
    local_path = LocalPath("./boostedblob_quickstart_test.json")
    try:
        await write_json({"message": "Hello from BoostedBlob local!"}, local_path)
        print(f"Wrote to {local_path}")
        content = await read_json(local_path)
        print(f"Read from {local_path}: {content}")
        # Clean up
        await delete(local_path)
        print(f"Deleted {local_path}")
    except Exception as e:
        print(f"Error during local operations: {e}")

    # 2. Azure Blob Storage Operations (requires environment variables)
    print("\n--- Azure Blob Storage Operations ---")
    azure_account = os.environ.get('AZURE_STORAGE_ACCOUNT_NAME')
    azure_container = os.environ.get('AZURE_STORAGE_CONTAINER')

    if azure_account and azure_container:
        # Example Azure path
        azure_path = AzurePath(f"az://{azure_account}/{azure_container}/boostedblob_quickstart_azure.json")
        print(f"Target Azure Path: {azure_path}")
        try:
            await write_json({"message": "Hello from BoostedBlob Azure!"}, azure_path)
            print(f"Wrote to {azure_path}")
            content = await read_json(azure_path)
            print(f"Read from {azure_path}: {content}")
            # Uncomment the line below to delete the file after reading
            # await delete(azure_path)
            # print(f"Deleted {azure_path}")
            print("Azure operations completed. (Deletion is commented out for safety).")
        except Exception as e:
            print(f"Azure operations failed (check credentials, account, container, permissions): {e}")
    else:
        print("Skipping Azure operations: Set AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_CONTAINER environment variables to enable.")
        print("For GCS, install with `boostedblob[gcs]` and set `GOOGLE_APPLICATION_CREDENTIALS` and `GCS_BUCKET_NAME`.")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →