Metadata-Version: 2.4
Name: s3-desktop-explorer
Version: 0.1.0
Summary: A fast, compact, cross-platform S3 desktop explorer
Home-page: https://github.com/yigitbasalma/s3explorer
Author: Yiğit Can Başalma
Author-email: yigit.basalma@warewave.tech
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Desktop Environment :: File Managers
Classifier: Environment :: X11 Applications :: Qt
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PySide6>=6.6.0
Requires-Dist: boto3>=1.34.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# S3 Explorer

A fast, compact, cross-platform desktop application for browsing and downloading files from any S3-compatible storage service.

Built with Python, PySide6 (Qt6), and boto3.

![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-green)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

## Features

- **Universal S3 Compatibility** — Works with AWS S3, MinIO, Ceph, Wasabi, DigitalOcean Spaces, and any service that exposes an S3-compatible endpoint.
- **AWS Profile Support** — Automatically detects profiles from `~/.aws/credentials` and `~/.aws/config`. Supports key-based, SSO, and role-based authentication.
- **Bucket & Object Browsing** — List buckets, navigate folders with double-click, go back with the back button.
- **Multi-File Download** — Select multiple files (Ctrl/Cmd+Click or Shift+Click) and download them all at once.
- **Folder Download** — Select one or more folders to recursively download their entire contents, preserving directory structure.
- **Access Denied Handling** — Clear error messages when permissions are insufficient. Partial failures during batch downloads are reported per-file.
- **Non-Blocking I/O** — All S3 operations run in background threads. The UI stays responsive.
- **Modern Dark UI** — Catppuccin Mocha themed interface with smooth styling across all platforms.
- **Custom Endpoint & SSL Toggle** — Connect to local or private S3 servers with or without SSL.

## Installation

### From PyPI

```bash
pip install s3-desktop-explorer
```

Then run:

```bash
s3-desktop-explorer
```

### From Source

```bash
git clone <repo-url>
cd s3explorer
pip install -r requirements.txt
python main.py
```

## Requirements

- Python 3.10+
- PySide6 >= 6.6.0
- boto3 >= 1.34.0

## Usage

1. Launch the application.
2. Choose an AWS profile from the dropdown, or select "Manual" and enter your credentials.
3. For non-AWS services, enter the endpoint URL (e.g. `http://localhost:9000` for MinIO).
4. Toggle SSL off if your endpoint doesn't support it.
5. Click **Connect**.
6. Click a bucket on the left to browse its contents.
7. Double-click a folder to enter it, use **Back** to go up.
8. Select one or more files/folders and click **Download** to save them locally.

## Project Structure

```
s3explorer/
├── main.py          # Application entry point
├── app.py           # Main window, UI, and event handling
├── s3client.py      # S3 operations and AWS profile reader
├── requirements.txt # Python dependencies
├── setup.py         # PyPI packaging config
└── README.md
```

## Configuration

No configuration files are needed. The app reads standard AWS config locations:

| File | Purpose |
|---|---|
| `~/.aws/credentials` | Access keys per profile |
| `~/.aws/config` | Region, endpoint URL, and other settings per profile |

Profiles are merged from both files. If a profile defines keys in `credentials` and a region in `config`, both are picked up.

## Keyboard Shortcuts

| Shortcut | Action |
|---|---|
| `Ctrl/Cmd + Click` | Add item to selection |
| `Shift + Click` | Range select |
| `Double-click folder` | Navigate into folder |

## Troubleshooting

| Problem | Solution |
|---|---|
| Empty error dialog | Upgrade to latest version — error formatting has been improved |
| Cannot connect to MinIO | Make sure to uncheck "Use SSL" if your MinIO instance runs on HTTP |
| Access Denied on list | Your credentials lack `s3:ListBucket` permission for that bucket |
| Access Denied on download | Your credentials lack `s3:GetObject` permission for that key |
| No profiles found | Ensure `~/.aws/credentials` or `~/.aws/config` exists and is readable |

## License

MIT

---

<p align="center">
  <sub>Crafted with <a href="https://kiro.dev">Kiro</a> — the AI-powered IDE for developers.</sub>
</p>
