Metadata-Version: 2.4
Name: ringsort
Version: 1.0.0
Summary: A fast and cross-platform CLI tool for automatically organizing files into categorized folders.
Author: Amir Mohammad Mohammadi
Maintainer: Amir Mohammad Mohammadi
License: MIT License
        
        Copyright (c) 2026
        
        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.
        
Project-URL: Homepage, https://github.com/ammagicring/ringsort
Project-URL: Repository, https://github.com/ammagicring/ringsort
Project-URL: Issues, https://github.com/ammagicring/ringsort/issues
Project-URL: Documentation, https://github.com/ammagicring/ringsort#readme
Project-URL: Changelog, https://github.com/ammagicring/ringsort/blob/main/CHANGELOG.md
Keywords: cli,file-organizer,automation,filesystem,productivity,python
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Dynamic: license-file

# RingSort

> A fast and cross-platform Python CLI tool for automatically organizing files into categorized folders.




RingSort helps you clean messy directories by automatically sorting files into organized folders based on their extensions.

## Example

Turn this:

```text
Downloads/
├── photo.jpg
├── report.pdf
├── movie.mp4
└── music.mp3
```

Into this:

```text
Downloads/
├── Images/
│   └── photo.jpg
├── Documents/
│   └── report.pdf
├── Videos/
│   └── movie.mp4
└── Music/
    └── music.mp3
```

---

## Features

* 📁 Automatic file organization
* 🖼 Categorization of Images, Videos, Music, Documents, Archives, Code, Executables, and Others
* 👀 Dry-run mode to preview changes before execution
* 🔄 Recursive directory scanning
* 🔍 Hash-based duplicate detection
* 🔒 Safe filename conflict handling without silent overwrites
* 📝 Optional verbose logging and log file output
* ⚡ Fast and lightweight CLI experience
* 💻 Cross-platform support:

  * Windows
  * Linux
  * macOS

---

## Installation

### From PyPI

```bash
pip install ringsort
```

Upgrade:

```bash
pip install --upgrade ringsort
```

### From Source

```bash
git clone https://github.com/ammagicring/ringsort.git

cd ringsort

python -m venv .venv
```

Activate environment:

Windows:

```bash
.venv\Scripts\activate
```

Linux/macOS:

```bash
source .venv/bin/activate
```

Install:

```bash
pip install -U pip
pip install -e .
```

---

## Quick Start

Organize a directory:

```bash
ringsort ~/Downloads
```

Example output:

```text
✓ 15 files scanned
✓ 4 Images
✓ 2 Documents
✓ 3 Videos
✓ Done in 0.42 seconds
```

---

## Usage

Basic:

```bash
ringsort PATH
```

Dry run:

```bash
ringsort PATH --dry-run
```

Recursive sorting:

```bash
ringsort PATH --recursive
```

Verbose mode:

```bash
ringsort PATH --verbose
```

Save logs:

```bash
ringsort PATH --log-file ringsort.log
```

Help:

```bash
ringsort --help
```

---

## Dry Run

Preview planned operations without modifying files:

```bash
ringsort ~/Downloads --dry-run
```

Example:

```text
[DRY RUN]

movie.mp4 -> Videos/
image.png -> Images/
document.pdf -> Documents/

✓ 3 files scanned
✓ Dry run complete (no files moved)
```

---

## Project Structure

```text
ringsort/
├── src/
│   └── ringsort/
│       ├── __init__.py
│       ├── cli.py
│       ├── scanner.py
│       ├── mover.py
│       ├── duplicates.py
│       ├── config.py
│       ├── logger.py
│       └── categories.py
├── tests/
├── docs/
├── examples/
├── .github/workflows/
├── README.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
├── LICENSE
├── pyproject.toml
└── requirements.txt
```

---

## Development

Install development dependencies:

```bash
pip install -e ".[dev]"
```

Run quality checks:

```bash
ruff check src tests
```

```bash
mypy
```

```bash
pytest
```

---

## Roadmap

* [x] v1.0.0 Initial release
* [ ] v1.1 Configurable category mappings
* [ ] v1.2 Undo support via transaction log
* [ ] v1.3 Watch mode for automatic sorting
* [ ] v2.0 Plugin-based rules engine

---

## Contributing

Contributions are welcome!

Please read `CONTRIBUTING.md` before opening a pull request.

---

## License

This project is licensed under the MIT License.

See LICENSE.

---

## Author

Created by **Amir Mohammad Mohammadi**

GitHub:
https://github.com/ammagicring
