Metadata-Version: 2.4
Name: pyfi-share
Version: 0.1.1
Summary: Fast, lightweight file sharing over local Wi-Fi with QR code
Home-page: https://github.com/vubon/pyfi
Author: Vubon Roy
Author-email: vubon.roy@gmail.com
License: MIT
Project-URL: Documentation, https://github.com/vubon/pyfi#readme
Project-URL: Source, https://github.com/vubon/pyfi
Project-URL: Issue Tracker, https://github.com/vubon/pyfi/issues
Platform: Python
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX :: Linux
Classifier: Natural Language :: English
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: File Sharing
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: segno>=1.5.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: requires-dist
Dynamic: summary

# PyFi 🚀

> **Fast, lightweight, zero-configuration local file sharing from your terminal to any device over Wi-Fi.**

**PyFi** (**Py**thon + **Fi**le / Wi-**Fi**) lets you instantly share files between your computer and mobile phone (iOS / Android) or other computers on the same local network by simply scanning a QR code in your terminal.

---

<p align="center">
  <img src="./docs/PyFi.png" alt="PyFi Demo" width="600">
</p>

---

## ✨ Features

- ⚡ **Ultra-Fast Streaming**: Pure standard-library multi-threaded socket streaming (no heavy Flask/Gunicorn runtime).
- 📱 **Camera-Ready QR Code**: High-contrast, compact terminal QR code for instant scanning with the iOS Camera app or Google Lens.
- 📊 **Live Dynamic Progress Bar**: Real-time single-line terminal progress bar tracking `%`, transferred MB, speed in MB/s, and auto-adjusting ETA.
- ⏩ **HTTP Range Requests (`206 Partial Content`)**: Supports paused download resumption and multi-chunk mobile download accelerators.
- 🚪 **Clean Auto-Exit**: Automatically shuts down and exits cleanly back to your shell prompt as soon as the transfer finishes.
- 🪶 **Minimal Dependencies**: Standalone lightweight package with zero bloated web framework dependencies.

---

## ⚡ Quick Start

### Installation

#### Option 1: Prebuilt Standalone Binary (Recommended)

Download the latest standalone binary from the [GitHub Releases](https://github.com/vubon/pyfi/releases) page:

**Linux / macOS:**
```bash
# Extract the archive
tar -xzf pyfi-linux-x86_64.tar.gz   # (or pyfi-macos-arm64.tar.gz)

# Move binary to PATH and set permissions
sudo mv pyfi /usr/local/bin/
sudo chmod +x /usr/local/bin/pyfi

# macOS: If Gatekeeper shows an unverified developer warning:
xattr -d com.apple.quarantine /usr/local/bin/pyfi
```

**Windows:**
Download `pyfi-windows-x64.zip`, extract `pyfi.exe`, and run it directly or add it to your system PATH.

---

#### Option 2: Install via pip

```bash
pip install pyfi-share
```

---

#### Option 3: Install from Source

```bash
# Clone the repository
git clone https://github.com/vubon/pyfi.git
cd pyfi

# Install in editable mode
pip install -e .
```

### Usage

Share any file by passing its name or path:

```bash
# 1. Using the pyfi command:
pyfi video.mp4

# 2. Or using the Python module:
python -m PyFi video.mp4
```

1. Run the command in your terminal.
2. Open your phone's native Camera app and point it at the terminal QR code.
3. Tap the prompt to download the file directly to your device!

---

## 🚀 Maximizing Transfer Speed (Tx Rate & Wi-Fi Guide)

To achieve maximum download speeds (e.g. **20 – 50+ MB/s**):

### 1. Connect Both Devices to 5 GHz or Wi-Fi 6
* **5 GHz / Wi-Fi 6 (802.11ax / 802.11ac)** provides wider bandwidth channels and high **Tx Rates (500 Mbps – 1200+ Mbps)**, allowing multi-gigabyte files to transfer in seconds.
* **Avoid 2.4 GHz networks**: 2.4 GHz Wi-Fi is crowded with high interference and low Tx Rates (often limited to 54–144 Mbps), resulting in slower transfers (~2–4 MB/s).

### 2. Check Your Mac's Wi-Fi Tx Rate
Hold <kbd>Option (⌥)</kbd> and click the **Wi-Fi icon** in your macOS menu bar:
* **Tx Rate > 500 Mbps**: Ideal for high-speed file transfers.
* **Tx Rate < 150 Mbps**: Check router distance or switch your Wi-Fi network to the `5 GHz` band.

### 3. 💡 Pro-Tip: Direct Phone Hotspot (P2P Wi-Fi)
When both sender and receiver are connected through a home router, Wi-Fi airtime is shared (half-duplex relay). For maximum speed on the go:
1. Turn on your **Phone's Personal Hotspot** (enable *Maximize Compatibility* / 5GHz).
2. Connect your Mac to the phone's Hotspot.
3. Run `pyfi <file>` — this establishes a direct point-to-point Wi-Fi link for maximum transfer rates!

---

## 🛠️ Developer & Makefile Commands

PyFi includes a handy `Makefile` for common tasks:

| Command | Action |
| :--- | :--- |
| `make test` | Run the complete unit test suite (`tests/test_pyfi.py`) |
| `make run FILE=video.mp4` | Run PyFi with a specified file |
| `make install` | Install PyFi in editable development mode |
| `make build` | Build source distribution and `.whl` package |
| `make binary` | Package a standalone executable with PyInstaller |
| `make clean` | Remove temporary cache and build artifacts |

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.1.1] - 2026-08-22

### Added
- **Automated PyPI Publishing**: Connected GitHub Actions `release.yml` with PyPI to automatically publish `.whl` and `.tar.gz` packages on git tag releases.
- **Package Manifest (`MANIFEST.in`)**: Added manifest template ensuring all markdown documentation, licenses, and media assets are included in the source distribution.

### Fixed
- Fixed sdist packaging issue when building wheel distributions from source.

---

## [0.1.0] - 2026-08-22

### Added
- **High-Performance HTTP Streaming**: Implemented lightweight, multi-threaded socket streaming server using Python's standard library (`http.server` & `socketserver.ThreadingMixIn`).
- **HTTP Range Request Support (`206 Partial Content`)**: Added full support for `Range: bytes=start-end` headers, enabling resumable downloads and multi-threaded mobile download accelerators.
- **Real-Time Live Progress Bar**: Added smooth, single-line terminal progress bar tracking completion percentage, data transferred/total size, real-time speed in `MB/s`, and smart ETA.
- **Smart Duration Formatting**: Formats elapsed time and ETA dynamically in seconds (`s`), minutes (`m`), or hours (`h`).
- **Dynamic Terminal Width Detection**: Automatically calculates terminal column width (`shutil.get_terminal_size`) to prevent text wrapping on narrow terminal panes.
- **Framed Terminal Card**: Displays high-contrast QR code (`border=2`) within an elegant box border matching terminal themes.
- **Automated Server Auto-Exit**: Automatically shuts down and returns to the shell prompt once the file transfer is complete.
- **Flexible Path Resolution**: Supports absolute paths (`/`), relative paths (`./`), and user home shortcuts (`~/`) from any directory.
- **Fast Standalone Binary (`zipapp`)**: Package standalone single-file executables with instant (~0.08s) startup time and ~640 KB footprint.
- **Automated CI/CD**: Added GitHub Actions workflows for multi-version testing (`ci.yml`) and automated cross-platform binary releases on git tags (`release.yml`).
- **Developer Makefile**: Added developer shortcuts for `make install`, `make test`, `make run`, `make build`, `make binary`, and `make clean`.
- **Unit Test Suite**: Created automated test suite (`tests/test_pyfi.py`) covering full streaming, range slicing, 404 handling, auto-exit, and formatting utilities.

### Changed
- Removed heavy external web framework dependencies (`Flask`, `Werkzeug`, `Gunicorn`) in favor of Python standard library.
- Refactored project architecture to follow standard Python separation of concerns (`PyFi/utils/util.py` for helpers and `PyFi/server/server.py` for networking).
- Made terminal logs quiet by default, adding `-d` / `--debug` flag for low-level connection inspection.
- Updated documentation and README with Wi-Fi 5 GHz / Tx Rate optimization guide.

### Fixed
- Fixed macOS socket truncation issue when streaming large files.
- Fixed `runpy` module collision runtime warning during CLI module invocation.
- Fixed socket handling to gracefully handle client disconnections (`ConnectionResetError`, `BrokenPipeError`) from mobile browsers.

---

## [0.0.1-alpha] - 2026-07-20

### Added
- Initial project prototype for sharing files over local Wi-Fi with QR code generation.
