Metadata-Version: 2.4
Name: appfx-storage
Version: 0.1.1
Summary: Python helpers for Azure Storage Blob and Queue operations.
Author-email: DB Lee <dongbum@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Dongbumlee/appfx-storage
Project-URL: Repository, https://github.com/Dongbumlee/appfx-storage.git
Project-URL: Issues, https://github.com/Dongbumlee/appfx-storage/issues
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: azure-core>=1.29.0
Requires-Dist: azure-identity>=1.15.0
Requires-Dist: azure-storage-blob>=12.20.0
Requires-Dist: azure-storage-queue>=12.9.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pytest>=8.4; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

# appfx-storage

[![CI](https://github.com/Dongbumlee/appfx-storage/actions/workflows/ci.yml/badge.svg)](https://github.com/Dongbumlee/appfx-storage/actions/workflows/ci.yml)
[![Publish](https://github.com/Dongbumlee/appfx-storage/actions/workflows/publish.yml/badge.svg)](https://github.com/Dongbumlee/appfx-storage/actions/workflows/publish.yml)
[![PyPI](https://img.shields.io/pypi/v/appfx-storage.svg)](https://pypi.org/project/appfx-storage/)
[![Python versions](https://img.shields.io/pypi/pyversions/appfx-storage.svg)](https://pypi.org/project/appfx-storage/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Dongbumlee/appfx-storage/blob/main/LICENSE)

Python helpers for Azure Storage Blob and Queue operations.

The `appfx-storage` package exposes the `appfx.storage` import namespace. It
wraps common Azure Blob Storage and Azure Queue Storage tasks with sync and
async helper classes, typed package metadata, and release-ready packaging.

## Features

- Blob container and blob upload, download, listing, delete, metadata, and SAS
  URL helpers.
- Queue create, send, receive, peek, update, delete, clear, and worker-pattern
  helpers.
- Sync and async clients for both blob and queue operations.
- Azure credential support through connection strings, account names, managed
  identity, and `DefaultAzureCredential`.
- Python 3.12 and 3.13 support.

## Installation

```bash
python -m pip install appfx-storage
```

For local development:

```bash
python -m pip install -e ".[dev]"
```

## Quickstart

Set the storage account name before running examples. When `account_name`
is provided, the helpers use Azure Identity `DefaultAzureCredential`, so local
development can authenticate with Azure CLI and Azure-hosted apps can use
managed identity. Connection strings are supported, but examples intentionally
prefer Entra ID authentication.

```bash
export AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
az login
```

Do not commit `.env` files, connection strings, account keys, or generated SAS
URLs.

## Async blob usage

```python
import asyncio
import os

from appfx.storage import AsyncStorageBlobHelper


async def main() -> None:
    account_name = os.environ["AZURE_STORAGE_ACCOUNT_NAME"]
    async with AsyncStorageBlobHelper(account_name=account_name) as helper:
        await helper.create_container("documents")
        await helper.upload_blob("documents", "hello.txt", "Hello from appfx-storage")
        blobs = await helper.list_blobs("documents")
        print([blob["name"] for blob in blobs])


asyncio.run(main())
```

## Sync blob usage

```python
import os

from appfx.storage import StorageBlobHelper


helper = StorageBlobHelper(account_name=os.environ["AZURE_STORAGE_ACCOUNT_NAME"])
helper.create_container("documents")
helper.upload_blob("documents", "hello.txt", "Hello from appfx-storage")
print(helper.list_blobs("documents"))
```

## Async queue usage

```python
import asyncio
import os

from appfx.storage import AsyncStorageQueueHelper


async def main() -> None:
    account_name = os.environ["AZURE_STORAGE_ACCOUNT_NAME"]
    async with AsyncStorageQueueHelper(account_name=account_name) as helper:
        await helper.create_queue("jobs")
        result = await helper.send_message("jobs", {"task": "process-file"})
        print(f"Sent message: {result['message_id']}")
        messages = await helper.receive_messages("jobs")
        print([message["message_id"] for message in messages])


asyncio.run(main())
```

## Sync queue usage

```python
import os

from appfx.storage import StorageQueueHelper


helper = StorageQueueHelper(account_name=os.environ["AZURE_STORAGE_ACCOUNT_NAME"])
helper.create_queue("jobs")
result = helper.send_message("jobs", {"task": "process-file"})
print(f"Next visible at: {result['next_visible_on']}")
print([message["message_id"] for message in helper.peek_messages("jobs")])
```

## Tests and quality checks

```bash
python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m pytest --cov
python -m build
python -m twine check dist/*
```

Live Azure tests and examples require your own Azure Storage account and
credentials. Keep live credentials out of source control and CI logs.

## Release notes

- Package name: `appfx-storage`
- Import namespace: `appfx.storage`
- Repository: <https://github.com/Dongbumlee/appfx-storage>
- PyPI publishing is configured for trusted publishing from GitHub Actions on
  published releases and manual workflow dispatch.

## License

MIT License - see [LICENSE](LICENSE) for details.
