EasyStorage

A Python library and CLI tool for managing folder-based Containers in Google Drive with persistent OAuth authentication, SHA-256 deduplication, and automated offloading verification. Made with Gemini ! 🚀

Features

• Persistent Long-Term Authentication: Stores OAuth refresh tokens in ~/.easystorage_creds.txt so browser login is required only once.
• Unique Container Identification: Automatically manages .container.json inside each folder storing a unique container ID and the original folder name.
• SHA-256 Deduplication: Computes filename + content hashes for file items, skipping upload/download for identical files.
• Store & Offload (store_folder): Uploads local folders to Google Drive, verifies that all file hashes match in Drive, and moves the local directory to Trash.
• Container Fetching (fetch_container): Downloads containers from Drive into local directories using original folder names. Supports interactive TUI selection!
• Full uv and pip Support: Modern pyproject.toml packaging built with hatchling.

Installation

Using uv (Recommended)

uv pip install -e .

Using pip

pip install -e .

Setup & Authentication

Before running EasyStorage, you need a Google Drive OAuth client secrets JSON file.

• Step-by-Step Setup Guide: See SETUP_SECRETS.md for detailed instructions on creating and saving your Google Drive OAuth credentials.
• Default File Locations: Save your JSON file to ~/.easystorage_secrets.json (global) or ./client_secrets.json (project local).

CLI Usage

Interactive Container Fetch (TUI)

If you specify only the destination path, an interactive TUI menu will open displaying all available containers from Google Drive for selection:

easystorage fetch /path/to/destination

You can also explicitly pass the container_id:

easystorage fetch <container_id> /path/to/destination

Other Commands

# List all active containers in Drive
easystorage list

# Upload & update a local folder (without deleting local files)
easystorage update /path/to/my_folder

# Upload, verify integrity, and move local folder to Trash
easystorage store /path/to/my_folder

Python API Usage

from easystorage import (
    get_drive,
    get_containers_folder,
    get_list_of_containers,
    update_container,
    store_folder,
    fetch_container
)

# 1. Authorize Drive session
drive = get_drive()

# 2. List containers in Google Drive
containers = get_list_of_containers(drive)
for c in containers:
    print(f"Container: {c.name} | ID: {c.id}")

# 3. Synchronize a local folder to Drive (keeps local files)
update_container("/path/to/my_folder", drive=drive)

# 4. Offload a folder to Drive (verifies upload integrity, then trashes local folder)
store_folder("/path/to/my_folder", drive=drive)

# 5. Fetch a container from Drive back to local disk
fetch_container("<container_id>", "/path/to/destination", drive=drive)