Metadata-Version: 2.4
Name: fetchtastic
Version: 0.10.9
Summary: Meshtastic Firmware and APK Downloader
Author-email: Jeremiah K <jeremiahk@gmx.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/jeremiah-k/fetchtastic
Project-URL: Repository, https://github.com/jeremiah-k/fetchtastic
Project-URL: Issues, https://github.com/jeremiah-k/fetchtastic/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Android
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pick
Requires-Dist: PyYAML
Requires-Dist: urllib3>=2.0
Requires-Dist: packaging
Requires-Dist: platformdirs==4.9.6
Requires-Dist: rich
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiofiles>=23.1.0
Provides-Extra: win
Requires-Dist: pywin32; extra == "win"
Requires-Dist: winshell; extra == "win"
Provides-Extra: test
Requires-Dist: pytest==9.0.3; extra == "test"
Requires-Dist: pytest-mock==3.15.1; extra == "test"
Requires-Dist: pytest-cov==7.1.0; extra == "test"
Requires-Dist: pytest-asyncio==1.3.0; extra == "test"
Requires-Dist: aioresponses==0.7.8; extra == "test"
Dynamic: license-file

# Fetchtastic

**A simple, cross-platform utility for downloading and managing Meshtastic firmware and client app releases.**

Fetchtastic automatically downloads the latest Meshtastic firmware and selected client app assets from GitHub, with support for notifications, scheduling, and repository browsing.

Requires Python 3.10+; Python 3.9 and earlier are unsupported.

## ✨ Features

- 🔄 **Automatic Downloads**: Latest firmware and Meshtastic client app assets
- ⚡ **Async Download Engine**: `aiohttp`-based downloads with connection pooling and retry/backoff
- 📱 **Cross-Platform**: Linux, macOS, Windows, and Android (Termux)
- 🗂️ **Repository Browser**: Browse and download files from meshtastic.github.io
- 🔔 **Notifications**: Push notifications via NTFY
- ⏰ **Scheduling**: Automatic downloads via cron/startup scripts
- 🎯 **Smart Selection**: Choose specific devices, APKs, and desktop installers
- 📦 **Auto-extraction**: Extract firmware files from zip archives
- ✅ **Stronger Integrity Checks**: Hash-based verification and ZIP integrity validation
- 🚦 **GitHub API Resilience**: Centralized release fetching, defensive parsing, caching, and rate-limit-aware behavior
- 🧵 **Parallel Validation**: Release completeness checks run in parallel for faster scans
- 🔧 **Easy Setup**: One-command installation with guided setup

## 🚀 Quick Start

### One-Line Installation

Requires Python 3.10+.

**Linux/MacOS/Android (Termux):**

```bash
curl -sSL https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.sh | bash
```

> **Security Note:** For security-conscious users, you can [inspect the script](https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.sh) before running it.

**Windows (PowerShell):**

```powershell
irm https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.ps1 | iex
```

> **Security Note:** For security-conscious users, you can [inspect the script](https://raw.githubusercontent.com/jeremiah-k/fetchtastic/main/src/fetchtastic/tools/setup_fetchtastic.ps1) before running it.

### Basic Usage

```bash
# Run setup (first time)
fetchtastic setup

# Download latest releases
fetchtastic download

# Browse repository files
fetchtastic repo browse
```

## 📖 Documentation

### Installation Guides

- **[Linux Installation](docs/linux-installation.md)** - Complete installation guide for Linux distributions
- **[macOS Installation](docs/macos-installation.md)** - Installation guide for macOS with Homebrew
- **[Windows Installation](docs/windows-installation.md)** - Windows installation with integration features
- **[Termux Installation](docs/termux-installation.md)** - Android installation using Termux

### Usage

- **[Usage Guide](docs/usage-guide.md)** - Complete guide to using Fetchtastic
- **[Configuration Reference](docs/configuration.md)** - YAML settings, advanced options, and latest symlink behavior

## 🔧 Commands

```bash
fetchtastic setup         # Run the setup process
fetchtastic download      # Download firmware and client app assets
fetchtastic cache clear   # Clear cached API data
fetchtastic repo browse   # Browse repository files
fetchtastic repo clean    # Clean repository downloads
fetchtastic topic         # Show NTFY topic
fetchtastic version       # Show version
fetchtastic clean         # Remove all configuration
```

## 🏗️ Architecture Highlights

- **Shared GitHub release source**: Release parsing and validation are centralized for consistency across firmware and client app assets.
- **Async + sync compatibility**: Async download paths are first-class, with sync fallbacks when async libraries are unavailable.
- **Defensive verification flow**: Size checks, hash baselines, and ZIP integrity checks are combined to reduce false positives.
- **Better retry semantics**: Retryable vs non-retryable errors are preserved to improve behavior and diagnostics.

## 📁 File Organization

Downloads are organized in a clean structure:

```text
~/Downloads/Meshtastic/
├── app/
│   ├── v2.7.14/
│   │   ├── app-fdroid-universal-release.apk
│   │   ├── Meshtastic-2.7.14.dmg
│   │   └── release_notes-v2.7.14.md
│   └── prerelease/   # Pre-release client app builds (optional)
├── firmware/
│   ├── v2.3.2/
│   ├── v2.3.1/
│   ├── repo-dls/      # Repository browser downloads
│   └── prerelease/    # Pre-release firmware (optional)
```

APKs and desktop installers intentionally share `app/<version>/` because they are treated as client app assets from the same release pipeline.

## 🔔 Notifications

Get notified when new releases are downloaded:

1. Enable NTFY during setup
2. Install the [ntfy app](https://ntfy.sh/app/) or use the web interface
3. Subscribe to your unique topic
4. Receive push notifications for new downloads

## ⏰ Scheduling

Set up automatic downloads:

- **Linux/macOS**: Cron jobs (daily at 3 AM)
- **Windows**: Startup folder shortcuts
- **Termux**: Boot scripts and cron jobs

## 🆙 Upgrading

**Automatic (recommended):**

- **Windows**: Use Start Menu → Fetchtastic → "Check for Updates"
- **Linux/macOS/Termux**: Re-run the installation script

**Manual:**

```bash
pipx upgrade fetchtastic
```

## 🤝 Contributing

Contributions are welcome! Please feel free to:

- Report bugs and issues
- Suggest new features
- Submit pull requests
- Improve documentation

Visit the [GitHub repository](https://github.com/jeremiah-k/fetchtastic) to get started.

## 🧪 Development & Testing

```bash
# create and activate environment
python3 -m venv .venv
. .venv/bin/activate

# install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# run tests
python -m pytest tests/
```

Test suite organization uses markers such as `unit`, `integration`, `core_downloads`, `user_interface`, `configuration`, and `infrastructure`.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.
