ezsort 0.1.0__tar.gz

ezsort-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kritagya Dubey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ezsort-0.1.0/PKG-INFO

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: ezsort
+Version: 0.1.0
+Summary: A safe, lightweight Python CLI that automatically organizes messy folders into categories.
+Author: Kritagya Dubey
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kritagyadubey/EzSort
+Project-URL: Repository, https://github.com/kritagyadubey/EzSort
+Project-URL: Issues, https://github.com/kritagyadubey/EzSort/issues
+Keywords: file-organizer,cli,cleanup,downloads,organization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# EzSort
+
+> Your downloads folder is a disaster. EzSort fixes that in one command.
+
+```
+  ___           ________  ____
+ /   |  ______ / ____/ / / / /
+/ /| | / __ \/ /   / / / / /
+/ ___ |/ /_/ / /___/ /_/ / /___
+/_/  |_/_____/\____/\____/_____/
+```
+
+---
+
+## What does EzSort do?
+
+It takes a messy folder and sorts every file into neat subfolders based on what kind of file it is.
+
+**Before:**
+```
+Downloads/
+├── vacation.jpg
+├── tax-return.pdf
+├── concert.mp4
+├── playlist.mp3
+├── backup.zip
+├── setup.exe
+├── app.py
+├── budget.csv
+├── presentation.pptx
+├── .DS_Store
+└── MyProject/
+```
+
+**After `ezsort organize ~/Downloads`:**
+```
+Downloads/
+├── Images/
+│   └── vacation.jpg
+├── Documents/
+│   └── tax-return.pdf
+├── Videos/
+│   └── concert.mp4
+├── Music/
+│   └── playlist.mp3
+├── Archives/
+│   └── backup.zip
+├── Applications/
+│   └── setup.exe
+├── Code/
+│   └── app.py
+├── Spreadsheets/
+│   └── budget.csv
+├── Presentations/
+│   └── presentation.pptx
+└── MyProject/          <- untouched
+```
+
+No files deleted. No files overwritten. Just organized.
+
+---
+
+## Install
+
+```bash
+pip install ezsort
+```
+
+That's it. Zero dependencies. Works on Windows, macOS, and Linux.
+
+---
+
+## Quick Start
+
+```bash
+# Preview what would happen (nothing gets moved)
+ezsort organize ~/Downloads --dry-run
+
+# Actually sort the folder
+ezsort organize ~/Downloads --yes
+
+# Scan a folder to see what's in it
+ezsort scan ~/Downloads
+
+# Undo the last sort
+ezsort undo
+```
+
+---
+
+## Commands
+
+### `organize` -- Sort a folder
+
+```bash
+ezsort organize ~/Downloads              # Interactive (asks before moving)
+ezsort organize ~/Downloads --yes        # Skip confirmation
+ezsort organize ~/Downloads --dry-run    # Preview only
+ezsort organize ~/Downloads -r           # Include subfolders
+```
+
+### `scan` -- Look without touching
+
+```bash
+ezsort scan ~/Downloads
+```
+
+Shows file counts by category, potential duplicates, and how many files could be organized.
+
+### `watch` -- Auto-sort new files
+
+```bash
+ezsort watch ~/Downloads
+```
+
+Keeps a folder sorted automatically. New files get moved as they appear. Press `Ctrl+C` to stop.
+
+### `undo` -- Take it back
+
+```bash
+ezsort undo
+```
+
+Reverses the last sort operation. Every file goes back to where it was.
+
+### `history` -- See what happened
+
+```bash
+ezsort history              # List of past operations
+ezsort history --details    # Show individual files per operation
+ezsort history --clear      # Wipe the history
+```
+
+### `stats` -- Your sorting numbers
+
+```bash
+ezsort stats
+```
+
+Shows total files organized and breakdown by category.
+
+### `config` -- View settings
+
+```bash
+ezsort config
+```
+
+Shows categories, custom rules, excluded directories, and preferences.
+
+### `--about` -- About EzSort
+
+```bash
+ezsort --about
+```
+
+Shows version, author, and GitHub repo info.
+
+---
+
+## Flags
+
+| Flag | What it does |
+|------|-------------|
+| `--help` | Show help for any command |
+| `--version` | Print version number |
+| `--verbose`, `-v` | Show detailed logs |
+| `--quiet`, `-q` | Suppress extra output |
+| `--dry-run` | Preview without moving files |
+| `--yes`, `-y` | Skip confirmation prompt |
+| `--recursive`, `-r` | Include subdirectories |
+
+---
+
+## How it works
+
+1. **Scan** -- EzSort walks through your folder and finds every file
+2. **Classify** -- Each file gets matched to a category by its extension (140+ types supported)
+3. **Plan** -- It builds a list of moves, skipping files that are already in the right place
+4. **Execute** -- Files get moved into their category folders
+5. **Record** -- Everything is logged so you can undo it later
+
+---
+
+## Safe by design
+
+EzSort will never:
+
+- Delete your files
+- Overwrite existing files (duplicates get renamed: `report.pdf` -> `report (1).pdf`)
+- Extract archives
+- Move folders (only files)
+- Upload anything
+- Require internet access
+
+It skips hidden files, symlinks, and its own working directories.
+
+---
+
+## Custom rules
+
+Create a config file to add your own classification rules:
+
+- **Windows:** `%APPDATA%/EzSort/config.json`
+- **Linux:** `~/.config/ezsort/config.json`
+- **macOS:** `~/Library/Application Support/ezsort/config.json`
+
+Example:
+
+```json
+{
+  "custom_rules": [
+    {
+      "type": "extension",
+      "pattern": ".psd",
+      "category": "Design"
+    },
+    {
+      "type": "filename_contains",
+      "pattern": "invoice",
+      "category": "Documents/Invoices"
+    },
+    {
+      "type": "filename_contains",
+      "pattern": "college",
+      "category": "Education"
+    }
+  ]
+}
+```
+
+Custom rules override the default categories. Priority goes top to bottom.
+
+---
+
+## Supported file types
+
+EzSort recognizes **140+ file extensions** across 12 categories:
+
+| Category | Examples |
+|----------|----------|
+| Images | `.jpg`, `.png`, `.gif`, `.webp`, `.heic`, `.raw`, `.psd` |
+| Videos | `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm` |
+| Music | `.mp3`, `.wav`, `.flac`, `.m4a`, `.ogg` |
+| Documents | `.pdf`, `.docx`, `.txt`, `.md`, `.rtf` |
+| Spreadsheets | `.xlsx`, `.csv`, `.ods`, `.tsv` |
+| Presentations | `.pptx`, `.key`, `.odp` |
+| Archives | `.zip`, `.rar`, `.7z`, `.tar.gz`, `.dmg` |
+| Applications | `.exe`, `.msi`, `.deb`, `.apk`, `.app` |
+| Code | `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.go`, `.rs`, `.html` |
+| Fonts | `.ttf`, `.otf`, `.woff2` |
+| Ebooks | `.epub`, `.mobi`, `.azw3` |
+| Torrents | `.torrent` |
+
+---
+
+## Platform support
+
+- Windows 10/11
+- macOS 10.15+
+- Linux (Ubuntu, Fedora, Debian, Arch, etc.)
+- Requires Python 3.8+
+
+---
+
+## Troubleshooting
+
+**"command not found: ezsort"**
+
+Make sure the package is installed:
+
+```bash
+pip install ezsort
+```
+
+Or run it as a Python module:
+
+```bash
+python -m ezsort organize ~/Downloads
+```
+
+**"Permission denied"**
+
+Some system folders need elevated permissions. Try running with appropriate access for that specific folder.
+
+**Files not being organized**
+
+Add `--verbose` to see what's happening:
+
+```bash
+ezsort organize ~/Downloads --verbose
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/kritagyadubey/EzSort.git
+cd EzSort
+python -m venv venv
+source venv/bin/activate   # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## Contributing
+
+Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License -- see [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+Built by **Kritagya Dubey**
+
+- GitHub: [github.com/kritagyadubey/EzSort](https://github.com/kritagyadubey/EzSort)
+- Issues: [github.com/kritagyadubey/EzSort/issues](https://github.com/kritagyadubey/EzSort/issues)
+
+> Keep Your Files Sorted, Effortlessly.

ezsort-0.1.0/README.md

@@ -0,0 +1,327 @@
+# EzSort
+
+> Your downloads folder is a disaster. EzSort fixes that in one command.
+
+```
+  ___           ________  ____
+ /   |  ______ / ____/ / / / /
+/ /| | / __ \/ /   / / / / /
+/ ___ |/ /_/ / /___/ /_/ / /___
+/_/  |_/_____/\____/\____/_____/
+```
+
+---
+
+## What does EzSort do?
+
+It takes a messy folder and sorts every file into neat subfolders based on what kind of file it is.
+
+**Before:**
+```
+Downloads/
+├── vacation.jpg
+├── tax-return.pdf
+├── concert.mp4
+├── playlist.mp3
+├── backup.zip
+├── setup.exe
+├── app.py
+├── budget.csv
+├── presentation.pptx
+├── .DS_Store
+└── MyProject/
+```
+
+**After `ezsort organize ~/Downloads`:**
+```
+Downloads/
+├── Images/
+│   └── vacation.jpg
+├── Documents/
+│   └── tax-return.pdf
+├── Videos/
+│   └── concert.mp4
+├── Music/
+│   └── playlist.mp3
+├── Archives/
+│   └── backup.zip
+├── Applications/
+│   └── setup.exe
+├── Code/
+│   └── app.py
+├── Spreadsheets/
+│   └── budget.csv
+├── Presentations/
+│   └── presentation.pptx
+└── MyProject/          <- untouched
+```
+
+No files deleted. No files overwritten. Just organized.
+
+---
+
+## Install
+
+```bash
+pip install ezsort
+```
+
+That's it. Zero dependencies. Works on Windows, macOS, and Linux.
+
+---
+
+## Quick Start
+
+```bash
+# Preview what would happen (nothing gets moved)
+ezsort organize ~/Downloads --dry-run
+
+# Actually sort the folder
+ezsort organize ~/Downloads --yes
+
+# Scan a folder to see what's in it
+ezsort scan ~/Downloads
+
+# Undo the last sort
+ezsort undo
+```
+
+---
+
+## Commands
+
+### `organize` -- Sort a folder
+
+```bash
+ezsort organize ~/Downloads              # Interactive (asks before moving)
+ezsort organize ~/Downloads --yes        # Skip confirmation
+ezsort organize ~/Downloads --dry-run    # Preview only
+ezsort organize ~/Downloads -r           # Include subfolders
+```
+
+### `scan` -- Look without touching
+
+```bash
+ezsort scan ~/Downloads
+```
+
+Shows file counts by category, potential duplicates, and how many files could be organized.
+
+### `watch` -- Auto-sort new files
+
+```bash
+ezsort watch ~/Downloads
+```
+
+Keeps a folder sorted automatically. New files get moved as they appear. Press `Ctrl+C` to stop.
+
+### `undo` -- Take it back
+
+```bash
+ezsort undo
+```
+
+Reverses the last sort operation. Every file goes back to where it was.
+
+### `history` -- See what happened
+
+```bash
+ezsort history              # List of past operations
+ezsort history --details    # Show individual files per operation
+ezsort history --clear      # Wipe the history
+```
+
+### `stats` -- Your sorting numbers
+
+```bash
+ezsort stats
+```
+
+Shows total files organized and breakdown by category.
+
+### `config` -- View settings
+
+```bash
+ezsort config
+```
+
+Shows categories, custom rules, excluded directories, and preferences.
+
+### `--about` -- About EzSort
+
+```bash
+ezsort --about
+```
+
+Shows version, author, and GitHub repo info.
+
+---
+
+## Flags
+
+| Flag | What it does |
+|------|-------------|
+| `--help` | Show help for any command |
+| `--version` | Print version number |
+| `--verbose`, `-v` | Show detailed logs |
+| `--quiet`, `-q` | Suppress extra output |
+| `--dry-run` | Preview without moving files |
+| `--yes`, `-y` | Skip confirmation prompt |
+| `--recursive`, `-r` | Include subdirectories |
+
+---
+
+## How it works
+
+1. **Scan** -- EzSort walks through your folder and finds every file
+2. **Classify** -- Each file gets matched to a category by its extension (140+ types supported)
+3. **Plan** -- It builds a list of moves, skipping files that are already in the right place
+4. **Execute** -- Files get moved into their category folders
+5. **Record** -- Everything is logged so you can undo it later
+
+---
+
+## Safe by design
+
+EzSort will never:
+
+- Delete your files
+- Overwrite existing files (duplicates get renamed: `report.pdf` -> `report (1).pdf`)
+- Extract archives
+- Move folders (only files)
+- Upload anything
+- Require internet access
+
+It skips hidden files, symlinks, and its own working directories.
+
+---
+
+## Custom rules
+
+Create a config file to add your own classification rules:
+
+- **Windows:** `%APPDATA%/EzSort/config.json`
+- **Linux:** `~/.config/ezsort/config.json`
+- **macOS:** `~/Library/Application Support/ezsort/config.json`
+
+Example:
+
+```json
+{
+  "custom_rules": [
+    {
+      "type": "extension",
+      "pattern": ".psd",
+      "category": "Design"
+    },
+    {
+      "type": "filename_contains",
+      "pattern": "invoice",
+      "category": "Documents/Invoices"
+    },
+    {
+      "type": "filename_contains",
+      "pattern": "college",
+      "category": "Education"
+    }
+  ]
+}
+```
+
+Custom rules override the default categories. Priority goes top to bottom.
+
+---
+
+## Supported file types
+
+EzSort recognizes **140+ file extensions** across 12 categories:
+
+| Category | Examples |
+|----------|----------|
+| Images | `.jpg`, `.png`, `.gif`, `.webp`, `.heic`, `.raw`, `.psd` |
+| Videos | `.mp4`, `.mkv`, `.mov`, `.avi`, `.webm` |
+| Music | `.mp3`, `.wav`, `.flac`, `.m4a`, `.ogg` |
+| Documents | `.pdf`, `.docx`, `.txt`, `.md`, `.rtf` |
+| Spreadsheets | `.xlsx`, `.csv`, `.ods`, `.tsv` |
+| Presentations | `.pptx`, `.key`, `.odp` |
+| Archives | `.zip`, `.rar`, `.7z`, `.tar.gz`, `.dmg` |
+| Applications | `.exe`, `.msi`, `.deb`, `.apk`, `.app` |
+| Code | `.py`, `.js`, `.ts`, `.java`, `.cpp`, `.go`, `.rs`, `.html` |
+| Fonts | `.ttf`, `.otf`, `.woff2` |
+| Ebooks | `.epub`, `.mobi`, `.azw3` |
+| Torrents | `.torrent` |
+
+---
+
+## Platform support
+
+- Windows 10/11
+- macOS 10.15+
+- Linux (Ubuntu, Fedora, Debian, Arch, etc.)
+- Requires Python 3.8+
+
+---
+
+## Troubleshooting
+
+**"command not found: ezsort"**
+
+Make sure the package is installed:
+
+```bash
+pip install ezsort
+```
+
+Or run it as a Python module:
+
+```bash
+python -m ezsort organize ~/Downloads
+```
+
+**"Permission denied"**
+
+Some system folders need elevated permissions. Try running with appropriate access for that specific folder.
+
+**Files not being organized**
+
+Add `--verbose` to see what's happening:
+
+```bash
+ezsort organize ~/Downloads --verbose
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/kritagyadubey/EzSort.git
+cd EzSort
+python -m venv venv
+source venv/bin/activate   # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## Contributing
+
+Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+MIT License -- see [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+Built by **Kritagya Dubey**
+
+- GitHub: [github.com/kritagyadubey/EzSort](https://github.com/kritagyadubey/EzSort)
+- Issues: [github.com/kritagyadubey/EzSort/issues](https://github.com/kritagyadubey/EzSort/issues)
+
+> Keep Your Files Sorted, Effortlessly.

ezsort-0.1.0/ezsort/__init__.py

@@ -0,0 +1,10 @@
+"""EzSort - Keep Your Files Sorted, Effortlessly.
+
+A safe, lightweight Python CLI that automatically organizes messy folders
+into categories based on file types.
+
+Created by Kritagya Dubey
+"""
+
+__version__ = "0.1.0"
+__author__ = "Kritagya Dubey"

ezsort-0.1.0/ezsort/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running EzSort as a module: python -m ezsort"""
+
+import sys
+from ezsort.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())