cloudstorage-py
A Python SDK giving one consistent storage interface across AWS S3, Google Cloud Storage and Cloudflare R2 — swap providers by changing a single string.
3
providers, 1 interface
1
string to switch backend
0
credentials needed to test
// stack
// architecture
Abstract BaseProvider contract with three concrete implementations · typed result models identical across providers · unified exception hierarchy normalised at the boundary · environment-resolved per-provider config · batch operations and presigned URLs · fully mocked test suite · packaged with per-provider optional extras
// overview
Every cloud provider ships a different SDK with different method names, different exception trees and different configuration. Switching providers means touching every call site. cloudstorage-py puts an abstract provider contract in the middle: the client never branches on which cloud it is talking to, every provider returns the same typed models, and three unrelated exception hierarchies are normalised at the boundary into one. Upload, download, delete, list, batch operations and presigned URLs work identically across all three. The test suite is fully mocked, so it runs in CI and on a contributor’s laptop without live cloud credentials.
// what was built
- ·One consistent interface across AWS S3, Google Cloud Storage and Cloudflare R2, with providers swappable by changing a single config string — no call-site changes.
- ·An abstract provider contract is the whole design: the client never branches on provider, so Cloudflare’s S3-compatibility quirks stay absorbed inside R2Provider instead of leaking upward.
- ·Typed data models mean an upload result or a listed object has the same shape whichever cloud produced it.
- ·A unified exception hierarchy normalises three unrelated error trees at the boundary, so application code catches ObjectNotFoundError rather than botocore, google.api_core and Cloudflare errors separately.
- ·Batch operations and presigned URLs supported uniformly across all three providers.
- ·Fully mocked test suite — no live cloud credentials needed, which keeps the tests runnable in CI and by any contributor.
- ·Packaged with per-provider optional extras, so installing it for S3 alone does not pull in the Google and Cloudflare stacks.
System design
Drawn from the actual source: services, data ownership, message flow and failure paths. Drag to pan, scroll to zoom, or open any diagram fullscreen.
One interface, three providers
The abstract provider contract is the whole design. Every provider implements exactly that surface, so the client never branches on which cloud it is talking to, and provider-specific behaviour stays behind the boundary.