Metadata-Version: 2.5
Name: ocloud
Version: 0.1.0
Summary: A production-grade Python library for unified cloud management across AWS, Azure, and GCP
Project-URL: Homepage, https://github.com/THE-S0HAM/ocloud
Project-URL: Repository, https://github.com/THE-S0HAM/ocloud
Project-URL: Documentation, https://github.com/THE-S0HAM/ocloud/tree/main/docs
Project-URL: Issues, https://github.com/THE-S0HAM/ocloud/issues
Project-URL: Changelog, https://github.com/THE-S0HAM/ocloud/blob/main/CHANGELOG.md
Author: OCloud Contributors
License: MIT
License-File: LICENSE
Keywords: aws,azure,blob,cli,cloud,cloud-management,ec2,functions,gcp,lambda,s3,vm
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
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 :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: bandit==1.8.3; extra == 'dev'
Requires-Dist: build==1.2.2.post1; extra == 'dev'
Requires-Dist: mypy==1.15.0; extra == 'dev'
Requires-Dist: pre-commit==4.1.0; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest==8.4.2; extra == 'dev'
Requires-Dist: ruff==0.9.10; extra == 'dev'
Requires-Dist: twine==7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# OCloud

[![CI](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml/badge.svg)](https://github.com/THE-S0HAM/ocloud/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/ocloud.svg)](https://pypi.org/project/ocloud/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**OCloud** is a lightweight, synchronous Python library for managing selected AWS, Azure, and Google Cloud resources through their official CLI tools. It provides a typed provider API, a deliberately narrow unified API, structured command results, and an advanced provider-only raw CLI escape hatch.

## What OCloud does

- Runs only the official `aws`, `az`, and `gcloud` executables—no cloud SDK dependency or credential store.
- Safely invokes subprocesses with argument lists; it never uses `shell=True`.
- Captures redacted stdout, stderr, exit code, parsed JSON where applicable, and redacted command metadata.
- Provides storage, compute, and serverless lifecycle helpers for the documented MVP surface.

## Install and authenticate

```bash
python -m pip install ocloud
aws configure       # AWS users
az login            # Azure users
gcloud auth login   # Google Cloud users
```

Install the provider CLI separately; OCloud does not install it. Python 3.10–3.13 is supported.

## Quick start

```python
from ocloud import AWS

aws = AWS()
aws.auth.check_status()
result = aws.s3.put_object_acl(
    bucket="my-bucket",
    key="path/to/file.pdf",
    acl="public-read",
)

if result.success:
    print(result.data)
else:
    print(result.stderr)
```

## Unified API

Use `Cloud` for operations with genuinely shared semantics. Provider-specific context remains explicit.

```python
from ocloud import Cloud

cloud = Cloud("aws")
result = cloud.storage.upload(
    file="document.pdf",
    bucket="my-bucket",
    key="documents/document.pdf",
    timeout=60,
)
```

## Provider APIs

| Provider | Storage | Compute | Serverless |
| --- | --- | --- | --- |
| AWS | S3 upload/download/delete/list/exists/ACL | EC2 start/stop/restart/status | Lambda deploy/invoke/status/delete |
| Azure | Blob upload/download/delete/list/exists | VM start/stop/restart/status | Function App ZIP deploy; Function status/delete |
| GCP | Cloud Storage upload/download/delete/list/exists | Compute Engine start/stop/restart/status | Cloud Functions deploy/invoke/status/delete |

Azure Functions has no generic Azure CLI invocation command. OCloud explicitly raises `UnsupportedOperationError` for that operation rather than misrepresenting a metadata request as an invocation.

### Advanced raw CLI API

Use this only for provider operations not exposed by the MVP. It accepts arguments, not a shell string.

```python
from ocloud import AWS

result = AWS().raw(
    "s3api", "put-object-acl", "--bucket", "my-bucket",
    "--key", "path/to/file.pdf", "--acl", "public-read",
)
```

## Results and errors

Every executed operation returns `CommandResult` with `success`, `returncode`, redacted `stdout`, redacted `stderr`, `data`, `command`, `provider`, and `operation`. The package raises OCloud-specific exceptions for unavailable CLIs, authentication checks, invalid parameters, unsupported operations, and timeouts.

```python
from ocloud import AWS, CLINotFoundError, OCloudTimeoutError

try:
    result = AWS().s3.list("my-bucket", timeout=30)
except CLINotFoundError:
    print("Install AWS CLI and ensure it is on PATH.")
except OCloudTimeoutError:
    print("The provider command exceeded its timeout.")
```

## Security

Authentication stays in the official cloud CLI. OCloud has no credential database and redacts common secret patterns from command metadata and diagnostics. Use least-privilege cloud identities; avoid secrets in raw arguments. See [SECURITY.md](SECURITY.md) and [docs/security.md](docs/security.md).

## Development

```bash
python -m pip install -e ".[dev]"
pre-commit install
ruff format --check .
ruff check .
mypy src/ocloud
pytest --cov=ocloud --cov-report=term-missing
python -m build
```

Unit tests use mocks and need no cloud account. The opt-in integration suite verifies only selected provider CLI authentication and performs no resource mutation; see [Testing](docs/testing.md).

## Documentation

- [Getting started](docs/getting-started.md)
- [Installation](docs/installation.md)
- [Authentication](docs/authentication.md)
- [Architecture](docs/architecture.md)
- [Testing](docs/testing.md)
- [Provider guides](docs/providers/)
- [Troubleshooting](docs/troubleshooting.md)
- [Contributing](CONTRIBUTING.md)

## Project status and roadmap

`0.1.0` is an alpha API. The repository has mocked unit coverage and successful package validation. AWS, Azure, and GCP CLI authentication were manually verified through OCloud on a Windows host; GCP validation used its SDK `bin` directory on `PATH` for the validation process. No cloud-resource integration validation has been performed. Planned work includes opt-in integration environments, stronger provider error classification, more services, native SDK adapters, and async execution.

OCloud is released under the [MIT License](LICENSE). See [CHANGELOG.md](CHANGELOG.md) for release history.
