Metadata-Version: 2.4
Name: amber-cloud
Version: 1.0.0
Summary: Local-first Azure emulator — build, test, and iterate without an Azure account.
Author: Vishwa Kumaresh
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Vishwa-docs/amber
Project-URL: Documentation, https://vishwa-docs.github.io/amber/
Project-URL: Repository, https://github.com/Vishwa-docs/amber
Project-URL: Issues, https://github.com/Vishwa-docs/amber/issues
Keywords: azure,cloud,emulator,local-development,serverless,infrastructure,devops,testing,cosmosdb,blob-storage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == "server"
Requires-Dist: uvicorn[standard]>=0.20; extra == "server"
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Provides-Extra: all
Requires-Dist: amber-cloud[cli,dev,docs,server]; extra == "all"
Dynamic: license-file

# Amber

<p align="center">
  <img src="https://raw.githubusercontent.com/Vishwa-docs/amber/main/docs/_static/amber-logo.png" alt="Amber logo" width="180">
</p>

**Local-first Azure emulator** — Build, test, and iterate on Azure services without an Azure account.

[![PyPI version](https://img.shields.io/pypi/v/amber-cloud.svg)](https://pypi.org/project/amber-cloud/)
[![Python versions](https://img.shields.io/pypi/pyversions/amber-cloud.svg)](https://pypi.org/project/amber-cloud/)
[![CI](https://github.com/Vishwa-docs/amber/actions/workflows/ci.yml/badge.svg)](https://github.com/Vishwa-docs/amber/actions/workflows/ci.yml)
[![Docs](https://github.com/Vishwa-docs/amber/actions/workflows/docs.yml/badge.svg)](https://vishwa-docs.github.io/amber/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Amber emulates **86 Azure service-family surfaces** across 17 categories, all running locally with zero core runtime dependencies. Every operation records billing usage so you can estimate costs before deploying to real Azure.

Amber is a developer test double, not Microsoft Azure. It provides useful local behavior, ARM-shaped
resource IDs, region and zone metadata, billing ledgers, and adapter hooks while documenting where
cloud validation is still required.

Amber is inspired by the local-cloud developer experience pioneered by
[Floci](https://github.com/floci-io/floci) for AWS, and brings that same kind of fast local
workflow to Azure-shaped Python, CLI, and REST development.

## Quick Start

```python
from amber import AmberWorkspace

ws = AmberWorkspace.create(".amber")

# Blob Storage
ws.storage.blob.create_container("data")
ws.storage.blob.put_blob("data", "hello.txt", b"Hello, Azure!")

# Redis Cache
ws.redis.set(0, "session:1", "active")
assert ws.redis.get(0, "session:1") == "active"

# Cosmos DB
ws.cosmosdb.create_account("myaccount")
ws.cosmosdb.create_database("myaccount", "mydb")
ws.cosmosdb.create_container("myaccount", "mydb", "items", "/category")
ws.cosmosdb.create_document("myaccount", "mydb", "items", {
    "id": "doc1", "category": "fruit", "name": "apple"
})

# Service Bus messaging
ws.servicebus.create_queue("orders")
ws.servicebus.send_to_queue("orders", "new-order-123")

# Check billing
for key, usage in sorted(ws.billing.summary().items()):
    print(f"{key}: {usage.quantity} {usage.unit}")

ws.close()
```

## Installation

```bash
pip install amber-cloud
```

Amber is published on PyPI as `amber-cloud`, while the import package and CLI are both `amber`.

## Documentation

- Documentation: <https://vishwa-docs.github.io/amber/>
- PyPI: <https://pypi.org/project/amber-cloud/>
- Issues and roadmap: <https://github.com/Vishwa-docs/amber/issues>

## Local Azure Workflows

```bash
amber doctor
amber az group create --name apps --location eastus --tags env=dev
amber az group list
eval "$(amber env --endpoint http://127.0.0.1:8000)"
```

For an optional ARM-shaped local endpoint:

```bash
pip install "amber-cloud[server]"
python -m amber.server --workspace .amber --host 127.0.0.1 --port 8000
```

## Why Amber

- Run Azure-shaped integration tests locally without cloud accounts or shared test subscriptions.
- Keep application code close to ARM-shaped IDs, locations, tags, resource groups, and service-family names.
- Prototype lift-and-shift flows before replacing local adapters with real Azure SDK clients or deployment pipelines.
- Give students, teams, and open-source projects a fast local playground for Azure concepts.

## Service Coverage (86 services)

| Category | Services |
|----------|----------|
| **Storage** | Blob, Queue, Table, Files, Data Lake Gen2 |
| **Databases** | Redis, Cosmos DB, Azure SQL, PostgreSQL, MySQL, Database Migration Service |
| **Messaging** | Service Bus, Event Hubs, Event Grid |
| **Compute** | Functions, App Service, Container Apps, Batch, Static Web Apps, Virtual Machines, Managed Disks, VM Scale Sets, Service Fabric, Azure Virtual Desktop |
| **Containers** | ACR, AKS |
| **Networking** | VNet, Load Balancer, DNS, Firewall, App Gateway, Front Door, CDN, Traffic Manager, NAT Gateway, Private DNS, Bastion, Private Link, ExpressRoute, VPN Gateway, WAF |
| **AI** | Azure OpenAI, Azure AI services, AI Search, Maps, Document Intelligence/Form Recognizer, Speech, Content Safety/Content Moderator compatibility |
| **Analytics** | Data Factory, Kusto (Data Explorer), Stream Analytics, Purview, Synapse Analytics, Machine Learning |
| **Governance** | Policy, RBAC, Cost Management, Advisor, Resource Graph |
| **Observability** | Azure Monitor, Application Insights |
| **Identity** | Managed Identity / Service Principals |
| **Security** | Key Vault, Managed HSM, Confidential Ledger, DDoS Protection |
| **Integration** | Logic Apps, API Management, IoT Hub, SignalR, Communication Services, Notification Hubs, Web PubSub, Digital Twins |
| **DevOps** | Azure DevOps (projects, pipelines) |
| **Automation** | Azure Automation (runbooks, jobs, variables) |
| **Media** | Azure Media Services-style legacy workflows (retired in Azure; local compatibility only) |
| **Management** | Billing, Resource Groups, Subscriptions, Locks, Tags, Activity Log, Blueprints legacy workflows, Maintenance, Change Analysis |

## Public Python API

Amber is packaged as `amber-cloud` and imported as `amber`:

```python
from amber import AmberWorkspace
from amber.core import ServiceRegistry
from amber.cosmosdb import CosmosDBService
from amber.storage import BlobStorageService, QueueStorageService
from amber.networking import VNetService
```

The subpackages intentionally mirror Azure service families so tests and prototypes can move from
local Amber code toward Azure SDK or deployment workflows with minimal conceptual translation.
See the Sphinx documentation's Microsoft References page for the official Microsoft docs that each
local service surface maps to.

## Architecture

- **SQLite persistence** with WAL mode for concurrent access
- **Content-addressed blob storage** with SHA-256 deduplication
- **Lazy service initialization** — only loaded when accessed
- **Thread-safe** workspace with double-checked locking
- **Zero external dependencies** — pure Python stdlib

## Commands

| Command | Description |
|---------|-------------|
| `pip install -e '.[dev]'` | Install for local development |
| `.venv/bin/python -m pytest` | Run the Python test suite |
| `.venv/bin/ruff check src tests` | Run Python lint checks |
| `.venv/bin/mypy src` | Run the configured type checks |
| `.venv/bin/python -m build` | Build sdist and wheel |
| `amber registry list` | List all registered services |
| `amber doctor` | Check local package, workspace, SQLite, registry, and optional server deps |
| `amber status` | Show workspace, registered services, resource groups, and resources |
| `amber env --format json` | Emit local endpoint and Azure-shaped environment metadata |
| `amber az account show` | Show the local subscription document |
| `amber az group create --name apps --location eastus` | Create an ARM-shaped local resource group |
| `amber compose` | Print a Docker Compose service for the optional REST server |
| `amber billing summary` | Show local billing summary |

## Go Core

The Go runtime and CLI remain alongside the Python package:

```bash
go test ./...
go run ./cmd/amber --workspace .amber doctor
go run ./cmd/amber --workspace .amber status
```

## License

Apache 2.0. Azure, Microsoft Azure, and related service names are trademarks of Microsoft
Corporation. Amber is independent and is not affiliated with, endorsed by, or sponsored by
Microsoft Corporation.
