Metadata-Version: 2.4
Name: mega-sdk
Version: 0.1.1
Summary: A lightweight Python client library for interacting with the MEGA.nz API
Author: edward011
License: MIT
Project-URL: Homepage, https://github.com/theUser0011/mega-sdk
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Requires-Dist: pycryptodome>=3.10.0

# mega-sdk

A lightweight, reliable Python client library for interacting with the **MEGA.nz** API. `mega-sdk` provides simple abstractions for logging in, uploading/downloading files, managing folders, exporting public links, and handling rate limits with built-in retries.

---

## Features

- **Flexible Login**: Support for full user accounts, salt v1/v2 login, and temporary anonymous user sessions.
- **File Management**: Upload, download, move, rename, delete, and empty the rubbish bin.
- **Folder Support**: Nested folder creation (`mkdir` / `create_folder`), path-based folder lookups, and target directory resolution.
- **Sharing & Links**: Generate public links for files and folders or import public file URLs directly into your cloud drive.
- **Built-in Backoff**: Automatic exponential backoff and retry handling for transient API failures (`EAGAIN` / rate limits).

---

## Installation

Install `mega-sdk` directly from PyPI using `pip`:

```bash
pip install mega-sdk
```

---

## Quick Start

### 1. User Authentication

```python
from mega_sdk import Mega

# Initialize instance
mega = Mega()

# Login with email and password
mega.login("your_email@example.com", "your_password")

# Get user quota information (in MB)
remaining_quota = mega.get_quota()
print(f"Remaining quota: {remaining_quota:.2f} MB")
```

### 2. Anonymous Login

```python
from mega_sdk import Mega

# Login as a temporary anonymous user session
mega = Mega()
mega.login()  # Calling login with no arguments creates an anonymous session
```

---

## File Operations

### Uploading a File

```python
# Basic upload to root folder
uploaded_file = mega.upload("example.pdf")

# Upload with a progress callback
def on_progress(current_bytes, total_bytes):
    percent = (current_bytes / total_bytes) * 100
    print(f"Progress: {percent:.1f}% ({current_bytes}/{total_bytes} bytes)")

mega.upload("large_file.zip", progress_callback=on_progress)
```

### Downloading a File

```python
# Find a file in your cloud drive
file_info = mega.find("example.pdf")

# Download file to a local destination directory
if file_info:
    mega.download(file_info, dest_path="./downloads")

# Download directly via a public MEGA URL
mega.download_url(
    "https://mega.nz/#!file_handle!file_key",
    dest_path="./downloads"
)
```

### Creating Folders

```python
# Create a single directory or nested path in your Cloud Drive
created_folders = mega.create_folder("Documents/Projects/2026")
```

### Generating Public Links

```python
# Get a shareable link for a file object
file_info = mega.find("example.pdf")
public_link = mega.get_link(file_info)
print("Share link:", public_link)
```

---

## Exception Handling

`mega-sdk` exports structured exceptions for API errors:

```python
from mega_sdk import Mega, RequestError, ValidationError

mega = Mega()

try:
    mega.login("user@example.com", "wrong_password")
except RequestError as err:
    print(f"API Error Code {err.code}: {err.message}")
except ValidationError as err:
    print(f"Validation Error: {err}")
```

---

## Requirements

- **Python**: `>= 3.8`
- **Dependencies**: `requests`, `pycryptodome`

---

## License

This project is licensed under the **MIT License**.
