downsorter 0.2.0__py3-none-any.whl

downsorter-0.2.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: downsorter
+Version: 0.2.0
+Summary: Organize files by extension into category folders from the command line.
+Author: Your Name
+License: MIT
+Keywords: downloads,file sorting,organization,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Downsorter
+
+A small Python CLI tool that organizes files by extension into category folders.
+
+Use it to clean up a messy folder, especially downloads, by moving images, documents, archives, installers, code, audio, and video files into the right subfolders.
+
+## Features
+
+- Organizes files by extension into category folders
+- Preview mode so you can see changes before moving anything
+- Safe move mode with `--apply` to actually perform the file moves
+- Handles duplicate names by renaming files to `name (1).ext`, `name (2).ext`, etc.
+- Ignores common system files like `desktop.ini` and `thumbs.db`
+- Supports minimum file age filtering with `--min-age-days`
+- Writes a CSV log of all moves for auditing
+- Works on Windows, macOS, and Linux with Python 3.10+
+
+## Platform Support
+
+| Platform | Support | Notes |
+| --- | --- | --- |
+| Windows 10/11 | Supported | Best tested platform for this project |
+| macOS | Supported | Works with Python 3.10+ |
+| Linux | Supported | Works with Python 3.10+ |
+
+## Files
+
+- `sorter.py` - main CLI script and package entry point
+- `README.md` - project instructions
+- `pyproject.toml` - package metadata for PyPI
+- `LICENSE` - MIT license text
+- `movelogs.csv` - example move log file written by the script
+
+## Install
+
+### From source
+
+```bash
+pip install .
+```
+
+### From PyPI
+
+```bash
+pip install downsorter
+```
+
+## Usage
+
+### Preview what will happen
+
+This is the safest way to run the tool first.
+
+```bash
+downsorter --folder "C:\Users\YourName\Downloads"
+```
+
+### Actually move files
+
+```bash
+downsorter --folder "C:\Users\YourName\Downloads" --apply
+```
+
+### Only move files older than 7 days
+
+```bash
+downsorter --folder "C:\Users\YourName\Downloads" --min-age-days 7 --apply
+```
+
+### Use a custom log file
+
+```bash
+downsorter --folder "C:\Users\YourName\Downloads" --apply --log-file my-moves.csv
+```
+
+## Options
+
+- `--folder`: Folder to organize. Defaults to the current user's Downloads folder.
+- `--apply`: Actually move files. Without this flag, the script only previews the planned moves.
+- `--min-age-days`: Only move files that have not been modified for at least this many days.
+- `--log-file`: CSV file where completed moves are recorded.
+
+## How it works
+
+1. The script scans the target folder for files.
+2. It matches each file extension against a category list.
+3. It builds a plan showing where each file would move.
+4. In preview mode, it only prints the plan.
+5. In apply mode, it creates category folders, moves files, and logs the results.
+
+## Categories
+
+The project currently sorts files into:
+
+- `Images` (.jpg, .jpeg, .png, .webp, .bmp)
+- `PDFs` (.pdf)
+- `Documents` (.doc, .docx, .txt, .md, .rtf)
+- `Spreadsheets` (.xls, .xlsx, .csv, .tsv)
+- `PPTs` (.ppt, .pptx)
+- `Archives` (.rar, .zip, .7z, .tar, .gz)
+- `Installers` (.exe, .msi)
+- `Code` (.py, .js, .html, .css, .json, .xml, .cpp, .java)
+- `Audio` (.mp3, .wav, .flac, .aac, .ogg)
+- `Videos` (.mp4, .gif, .mov, .mkv, .avi, .webm)
+- `Other` for everything else
+
+## Example
+
+Run this to preview then apply:
+
+```bash
+downsorter --folder "C:\Users\YourName\Downloads"
+downsorter --folder "C:\Users\YourName\Downloads" --apply
+```
+
+## License
+
+This project is licensed under the MIT License.

downsorter-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+sorter.py,sha256=qMkePEUX86d3jVeusBAI1G5WAhcF0vI6hNsxxnIxglQ,4880
+downsorter-0.2.0.dist-info/licenses/LICENSE,sha256=S_fbX1OLfL7GYfxafKhn4E6-9cDMpbxy3-OgQisZr5A,1087
+downsorter-0.2.0.dist-info/METADATA,sha256=SyTanw3fBs6CafOzB4YpkmTDxnvW6wYBOAiR0TVgRiA,3890
+downsorter-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+downsorter-0.2.0.dist-info/entry_points.txt,sha256=_gGMAUB8BfuaeY3SBVlGPtjliLKhMgIFvZwxwkkESzk,43
+downsorter-0.2.0.dist-info/top_level.txt,sha256=6PgYfJOJ6CnmzIwV3qA6Gso2mBYIELKxdlBfnm1CSzo,7
+downsorter-0.2.0.dist-info/RECORD,,

downsorter-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

downsorter-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+downsorter = sorter:main

downsorter-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

downsorter-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sorter

sorter.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+
+import argparse 
+import shutil
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+
+
+CATEGORIES = {
+    "Images": {".jpg" , ".jpeg" , ".png" , ".webp" , ".bmp"},
+    "PDFs" : {".pdf"},
+    "Documents" : {".doc" , ".docx" , ".txt" , ".md" , ".rtf"},
+    "Spreadsheets" : {".xls" , ".xlsx" , ".csv" , ".tsv"},
+    "PPTs" : {".ppt" , ".pptx"},
+    "Archives" : {".rar" , ".zip" ,".7z" , ".tar" , ".gz"},
+    "Installers" : {".exe" , ".msi"},
+    "Code" : {".py" , ".js" , ".html" , ".css" , ".json" , ".xml" , ".cpp" , ".java"},
+    "Audio" : {".mp3" , ".wav" , ".flac" , ".aac" , ".ogg"},
+    "Videos" : {".mp4" , ".gif" , ".mov" , ".mkv" , ".avi" , ".webm"}
+}
+IGNORE_NAMES = {
+    "desktop.ini",
+    "thumbs.db",
+}
+
+
+@dataclass(frozen=True)
+class MovePlan:
+    source: Path
+    destination: Path
+
+def default_downloads_folder():
+    return Path.home()/ "Downloads"
+
+
+def category_in(file_path: Path):
+    suffix = file_path.suffix.lower()
+    for category, extensions in CATEGORIES.items():
+        if suffix in extensions:
+            return category
+    return "Other"
+
+def agecheck(file_path: Path, minimum_days: int):
+    if minimum_days <= 0:
+        return True
+    mod_time = datetime.fromtimestamp(file_path.stat().st_mtime)
+    return mod_time <= datetime.now() - timedelta(days= minimum_days)
+
+def unique_des(des: Path):
+    if not des.exists():
+        return des
+    counter = 1
+    while True:
+        candidate = des.with_name(
+            f"{des.stem} ({counter}){des.suffix}"
+        )
+        if not candidate.exists():
+            return candidate
+        counter = counter + 1
+
+
+def normalize_category_folder(downloads_folder: Path, category: str) -> Path:
+    canonical = downloads_folder / category
+    if canonical.exists():
+        return canonical
+
+    for item in downloads_folder.iterdir():
+        if item.is_dir() and item.name.lower() == category.lower():
+            temp = downloads_folder / f".{category}.tmp"
+            item.rename(temp)
+            temp.rename(canonical)
+            return canonical
+
+    return canonical
+
+
+def BUILD_plan(downloads_folder:Path , minimum_days:int):
+    plans: list[MovePlan] = []
+    for item in downloads_folder.iterdir():
+        if not item.is_file():
+            continue
+        if item.name.lower() in IGNORE_NAMES:
+            continue
+        if not agecheck(item,minimum_days):
+            continue
+        
+        category = category_in(item)
+        destination_folder = normalize_category_folder(downloads_folder, category)
+        des = unique_des(destination_folder / item.name)
+        plans.append(MovePlan(source=item , destination=des))
+    return plans
+
+def PRINT_plan(plans :list[MovePlan] , apply : bool):
+    if not plans:
+        print("Nothing to clean , your folder is already tidy lmao")
+        return
+    action = "Moving" if apply else "Would move"
+    for plan in plans:
+        file_name = plan.source.name
+        destination = plan.destination.parent.name + "\\" + plan.destination.name
+        print(action + ": " + file_name + " -> " + destination)
+    
+def APPLY_plan(plans : list[MovePlan]):
+    for plan in plans:
+        plan.destination.parent.mkdir(parents=True , exist_ok=True)
+        shutil.move(str(plan.source) , str(plan.destination))
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Safely organize your downloads folder by file type"
+    )
+    parser.add_argument(
+        "--folder",
+        type=Path,
+        default=default_downloads_folder(),
+        help="Folder to clean . By default downloads folder"
+    )
+    parser.add_argument(
+        "--apply",
+        action="store_true",
+        help="Actually move files. Without this flag, the script only previews changes.",
+    )
+    parser.add_argument(
+        "--min-age-days",
+        type=int,
+        default=0,
+        help="Only move files at least this many days old. can be edited",
+    )
+    return parser.parse_args()
+
+def main():
+    args = parse_args()
+    downloads_folder = args.folder.expanduser().resolve()
+    
+    if not downloads_folder.exists():
+        raise SystemExit(f"Folder does not exist: {downloads_folder}")
+    if not downloads_folder.is_dir():
+        raise SystemExit(f"Not a folder: {downloads_folder}")
+    if args.min_age_days < 0:
+        raise SystemExit(f"--min-age-days cannot be NEGATIVE")
+        
+    plans = BUILD_plan(downloads_folder, args.min_age_days)
+    PRINT_plan(plans , args.apply)
+
+    if args.apply and plans:
+        APPLY_plan(plans)
+        print("Done.")
+    elif plans:
+        print("Preview only. Run again with --apply to move these files")
+
+if __name__=="__main__":
+    main()