7Z_Python_Script/README.md

# 📦 Folder Compressor

A command-line Python script that lets you pick any sub-folder to compress, or compress **all folders in one go** — each one individually with its own live progress bar. Uses **7-Zip store mode** (no compression) for maximum speed and zero CPU overhead.

---

## Features

- Browse all sub-folders with their sizes before choosing
- **Two modes at runtime:**
  - **Single folder** — select one folder by number
  - **Compress all** — process every folder sequentially, one by one
- Real-time progress bar per job showing:
  - Percentage complete
  - Elapsed time
  - Live transfer speed (MB/s)
  - File count
  - Currently processing file name
- Pause between jobs in batch mode so you can read each result before continuing
- Batch summary table at the end showing all jobs, sizes, times, and speeds
- Color-coded terminal output (auto-disabled if not supported)
- Cross-platform: Windows, macOS, Linux

---

## Requirements

### Python
Version **3.10 or higher** is required (uses `str | None` union type syntax).

Check your version:
```bash
python --version
# or
python3 --version
```

No third-party packages are needed — only Python's standard library is used.

### 7-Zip
7-Zip must be installed and accessible on your system PATH.

| Platform | Install command |
|----------|----------------|
| **Linux** (Debian/Ubuntu) | `sudo apt install p7zip-full` |
| **Linux** (Fedora/RHEL) | `sudo dnf install p7zip p7zip-plugins` |
| **macOS** (Homebrew) | `brew install p7zip` |
| **macOS** (MacPorts) | `sudo port install p7zip` |
| **Windows** | Download installer from [https://www.7-zip.org/download.html](https://www.7-zip.org/download.html) |

> **Windows note:** After installing, make sure `C:\Program Files\7-Zip\` is added to your system PATH, or the script will auto-detect it from the default install location automatically.

> **Minimum version:** 7-Zip **15.06 or newer** is required for the `-bsp1` progress flag used for real-time output. Most current installs will meet this requirement.

Verify 7-Zip is available:
```bash
7z i
```

---

## Installation

No installation needed. Just download the script:

```bash
# Download compress_folder.py to any directory, then run it directly with Python
```

Optionally make it executable on Linux/macOS:
```bash
chmod +x compress_folder.py
```

---

## Usage

### Basic — scan the current directory
```bash
python compress_folder.py
```

### Specify a directory to scan
```bash
python compress_folder.py /path/to/directory
```

### On Linux/macOS (if made executable)
```bash
./compress_folder.py
./compress_folder.py /path/to/directory
```

### On Windows
```bash
python compress_folder.py
python compress_folder.py C:\Users\YourName\Documents
```

---

## Step-by-step walkthrough

### Step 1 — Launch the script

```
📦  Folder Compressor
    Scanning: /home/user/projects
```

### Step 2 — Browse folders and choose a mode

All sub-folders are listed with their sizes, followed by the option to compress all:

```
Available folders:

  [  1]  archive  (240.0 MB)
  [  2]  builds   (1.4 GB)
  [  3]  logs     (88.3 MB)
  [  4]  source   (320.5 MB)

  [  A]  Compress ALL folders one by one

Enter a folder number or  A  to compress all:
```

**To compress a single folder:** type its number and press Enter.  
**To compress all folders:** type `A` and press Enter.

---

### Single folder mode

```
Enter a folder number or  A  to compress all: 2

  ✔  Mode: Single folder  →  builds
  Calculating source size… 1.4 GB

  ────────────────────────────────────────────────────────────────

  ████████████████░░░░░░░░░░░░░░░░░░░   62%  elapsed 0m 08s  178.4 MB/s  files: 312
  ↳ builds/release/v2.1.0/installer.exe

  ────────────────────────────────────────────────────────────────

  ✅  Archive created successfully!
     Path     : /home/user/projects/builds.7z
     Source   : 1.4 GB
     Archive  : 1.4 GB
     Time     : 0m 09s
     Avg speed: 159.2 MB/s
```

---

### Compress all mode

Each folder gets a numbered job header and its own progress bar. Each folder gets a numbered job header and its own progress bar. As soon as one job finishes and displays its stats, the next one starts automatically:

```
Enter a folder number or  A  to compress all: A

  ✔  Mode: Compress all folders sequentially


  [1/4]  archive  ────────────────────────────────────────────

  Calculating source size… 240.0 MB
  ...
  ✅  Archive created successfully!  (240.0 MB · 1s · 240.0 MB/s)


  [2/4]  builds  ─────────────────────────────────────────────

  ...
```

After all jobs complete, a **batch summary** is printed:

```
  ══════════════════════════════════════════════════════════════════
  BATCH SUMMARY  —  4 folder(s) processed
  ══════════════════════════════════════════════════════════════════
  ✅  archive        240.0 MB  →  1s   @  240.0 MB/s
  ✅  builds           1.4 GB  →  9s   @  159.2 MB/s
  ✅  logs            88.3 MB  →  0s   @  310.5 MB/s
  ✅  source         320.5 MB  →  2s   @  192.1 MB/s
  ──────────────────────────────────────────────────────────────────
  Total source size : 2.0 GB
  Total archive size: 2.0 GB
  Total time        : 12s
  Overall avg speed : 170.4 MB/s
  ══════════════════════════════════════════════════════════════════
```

If any jobs fail, they are flagged in the summary with their error code.

---

## Progress bar reference

| Element | Description |
|---------|-------------|
| `████░░░` | Progress bar filling left to right |
| `62%` | Percentage of data processed |
| `elapsed 0m 08s` | Time since this job started |
| `178.4 MB/s` | Rolling average throughput speed |
| `files: 312` | Number of files added so far |
| `↳ filename` | The file currently being processed |

---

## Compression settings

The script uses the following 7-Zip flags:

| Flag | Value | Meaning |
|------|-------|---------|
| `-t7z` | — | Output format: 7z |
| `-mx=0` | 0 | Compression level 0 = **store** (no compression) |
| `-ms=off` | off | Solid archive **disabled** (faster for many files) |
| `-bsp1` | — | Stream progress output to stdout (enables live display) |

**Why no compression?**  
Store mode (`-mx=0`) copies files into the archive as-is without compressing them. This is ideal when:
- Speed matters more than file size reduction
- The contents are already compressed (videos, images, zip files, etc.)
- You want to bundle files for transfer without the CPU cost of compression

---

## How the real-time progress works

7-Zip does not write progress on separate lines — instead it continuously overwrites the same terminal line using special control characters. The exact character it uses depends on the platform:

| Platform | Character used | Code |
|----------|---------------|------|
| Linux / macOS | Backspace | `\x08` |
| Windows | Carriage return | `\r` |

The script reads 7-Zip's output as a raw binary stream and splits on **both** characters, so progress is captured correctly on every platform. The percentage, file count, and current filename are extracted from each segment using a regex and rendered live into two reserved terminal lines that update in place.

---

## Output location

Each archive is created in the **same directory that contains the source folder**.

Example:
```
/home/user/projects/          ← scanned directory
    archive/                  ← source folder
    archive.7z                ← archive created here
    builds/
    builds.7z
```

If an archive with the same name already exists, 7-Zip will update it (adding/replacing files). Delete the existing `.7z` first if you want a clean archive.

---

## Interrupting a batch

Press `Ctrl+C` at any point during a batch to stop early. Any jobs already completed will have their archives saved. A partial batch summary will be printed for the jobs that ran.

---

## Troubleshooting

**`7-Zip not found` error**
- Ensure 7-Zip is installed (see Requirements above)
- Confirm `7z` is on your PATH: run `which 7z` (Linux/macOS) or `where 7z` (Windows)
- On Windows, try re-installing 7-Zip and ticking the "Add to PATH" option, or place `7z.exe` in `C:\Program Files\7-Zip\` which the script checks automatically

**Progress bar stays at 0% / no stats shown**
- Make sure you are using the latest version of the script
- The root cause of this bug was that Windows 7-Zip uses `\r` to update progress lines while Linux/macOS uses `\x08` (backspace). The current version handles both
- If you still see 0% after updating, confirm your 7-Zip version is 15.06 or newer: run `7z i` and check the version line at the top

**No progress bar / garbled output**
- The live progress display requires a terminal that supports ANSI escape codes
- On older Windows CMD, switch to Windows Terminal or PowerShell
- Progress and stats are still printed even if color/ANSI is not supported

**`SyntaxError` on startup**
- Your Python version is below 3.10 — upgrade to Python 3.10+

**Permission denied on folder**
- Run the script with elevated permissions (`sudo` on Linux/macOS, Run as Administrator on Windows)
- Or select a folder you have read access to

---

## Examples

```bash
# Compress a single folder or all folders in the current directory
python compress_folder.py

# Compress a single folder or all folders inside a specific path
python compress_folder.py /mnt/data/backups

# Windows example
python compress_folder.py "C:\Users\Alice\Desktop"
```

---

## License

This script is provided as-is for personal and commercial use. No warranty is expressed or implied.