## Introduction
Aleph BlobStorage provides a unified interface for versioned blob storage across multiple backends, including local filesystem and Azure Blob Storage. It supports hierarchical paths, content-based versioning, metadata tagging, and robust lifecycle management for data assets.

## Installation
### `pip`
```bash
pip install git+https://github.com/AlephTechAi/aleph_blobstorage.git

# Particular release
pip install git+https://github.com/AlephTechAi/aleph_blobstorage.git@0.1.0
```

### `poetry`
```toml
[tool.poetry.dependencies]
aleph_blobstorage = {git = "https://github.com/AlephTechAi/aleph_blobstorage.git"}

# Particular release
aleph_blobstorage = {git = "https://github.com/AlephTechAi/aleph_blobstorage.git", rev = "0.1.0"}
```
### `uv`
```bash
uv pip install --git https://github.com/AlephTechAi/aleph_blobstorage.git

# Particular release
uv pip install --git https://github.com/AlephTechAi/aleph_blobstorage.git@0.1.0
```

## Code Organization
The codebase follows a port-and-adapter architecture:

**Port (Abstract Interface):** Defines the generic blob storage operations and domain models. See [aleph_blobstorage/ports.py](aleph_blobstorage/ports.py).

**Adapters:** Implement backend-specific logic for local filesystem (LocalFilesystemAdaptor) and Azure (AzureBlobAdaptor). See [aleph_blobstorage/adapters.py](aleph_blobstorage/adapters.py)

**Entities & Value Objects:** Pydantic models for blob URIs, metadata, and lifecycle management.
Tests: Comprehensive pytest suite for both adaptors in tests/. See [aleph_blobstorage/valueobjects.py](aleph_blobstorage/valueobjects.py) and [aleph_blobstorage/entities.py](aleph_blobstorage/entities.py)

As you will see below, the main way for interacting with a blob is through the `VOBlobURI` object. 

## Usage Examples
### Azure Blob Storage
```python
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

from aleph_blobstorage.adapters import AzureBlobAdaptor
from aleph_blobstorage.valueobjects import VOBlobURI

# Initialize adapter
account_name = "teststorageaccount"
container_name = "testcontainer"

credentials = DefaultAzureCredential()
blob_client = BlobServiceClient(account_url=f"https://{account_name}.blob.core.windows.net", credential=credentials)
storage = AzureBlobAdaptor(container_name="testazureblobstorage3",blob_client=blob_client)

# Upload file to blob
source_path = Path() / "local_folder/test.py"
blob_uri = VOBlobURI(logical_path="test_folder", logical_name="test.py")
storage.upload_from_file(destination=blob_uri, source_path=source_path)

# Download blob to file
destination_path = Path() / "local_folder/download.py"
storage.download_to_file(source=blob_uri, destination_path=destination_path)

# Delete blob
storage.delete(blob_uri)

# Restore deleted blob
storage.restore(blob_uri)
```

## Dependencies
**Python 3.8+**
- `pydantic`
- `pytest`
- `azure-storage-blob`
- `azure-identity`

**Cloud Credentials**
- Azure: Storage Account connection string, or be logged into Azure CLI with your user identity having "Storage Blob Data Owner" role assignment.