Metadata-Version: 2.4
Name: pathxio
Version: 0.2.0
Summary: Safe, predictable filesystem operations for Python.
Author: holy
License-Expression: MIT
Project-URL: Documentation, https://github.com/holyholical/pathxio/blob/main/README.md
Project-URL: Repository, https://github.com/holyholical/pathxio.git
Project-URL: Bug Tracker, https://github.com/holyholical/pathxio/issues
Project-URL: Changelog, https://github.com/holyholical/pathxio/blob/main/CHANGELOG.md
Keywords: filesystem,file,path,safe,undo,copy,move,remove,async,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: aiofiles

# Pathxio

**Safe, predictable filesystem operations for Python.**

Pathxio is a small, safety-first wrapper around common file operations like copy, move, and delete.
It helps you avoid destructive mistakes by making safe behavior the default.

---

## Why Pathx?

Python’s built-in filesystem tools (os, shutil) are powerful but easy to misuse:

- Overwrites happen silently
- Deletes are irreversible
- APIs are inconsistent
- Safety checks are manual

Pathxio flips that around.
If an operation looks dangerous, it fails loudly.

---

## Installation

    pip install pathxio

---

## Quick Start

### Safe Copy

    from pathxio import copy

    copy("src/", "dst/")

- Copies files or directories
- Fails if destination already exists
- Raises clear, readable errors

---

### Safe Move

    from pathxio import move

    move("old/", "new/")

- No overwrite by default
- Uses atomic moves when possible
- Explicit failure on unsafe operations

---

### Guarded Delete

    from pathxio import remove

    remove("build/")

By default, Pathx refuses to delete:
- root directories
- home directories
- non-empty directories

To force deletion:

    remove("build/", force=True)

---

### Dry Run Mode

Preview what would happen without touching the filesystem:

    copy("src/", "dst/", dry_run=True)

Returns a list of planned operations instead of executing them.

---

## API (MVP)

    copy(src, dst, *, dry_run=False)
    move(src, dst, *, dry_run=False)
    remove(path, *, force=False, dry_run=False)

---

## Design Principles

- Safety over convenience
- Fail fast and loudly
- No surprising defaults
- Readable exceptions over clever magic

---

## Note

- Please give me new ideas to maintain this project

## Important Notice: Remove Operations and Undo Limitations

**Undo functionality is NOT available for remove operations.**

### Why This Limitation Exists:
- **Irreversible Nature**: File deletion cannot be properly reversed without maintaining permanent backups
- **Storage Requirements**: Full file restoration would require significant storage space
- **Data Integrity**: Removing the original file makes recovery impossible without external backup systems

### Recommended Practice:
Always maintain backups of important files before performing removal operations. For critical data, implement your own backup strategy using tools like rsync, cp, or cloud storage solutions.

### Workaround for Critical Operations:
For critical files, implement your own backup strategy that creates copies before deletion, ensuring you can restore files if needed.

---

## License

MIT
