OCloud

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

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

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.

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

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.

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.

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 and docs/security.md.

Development

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.

Documentation

• Getting started
• Installation
• Authentication
• Architecture
• Testing
• Provider guides
• Troubleshooting
• Contributing

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. See CHANGELOG.md for release history.