Metadata-Version: 2.4
Name: appfx-storage
Version: 0.1.0
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

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. The helpers support
connection strings, but public examples intentionally use account-name
authentication with managed identity or Azure CLI credentials.

```bash
set AZURE_STORAGE_ACCOUNT_NAME=your-storage-account
```

Use managed identity or Azure CLI login for account-name authentication. 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.
