philiprehberger-file-organizer 0.2.0

Rule-based file sorting engine with pattern matching and dry run support

philiprehberger-file-organizer

Rule-based file sorting engine with pattern matching and dry run support.

Installation

pip install philiprehberger-file-organizer

Usage

from philiprehberger_file_organizer import Organizer, Rule

organizer = Organizer(
    rules=[
        Rule(extensions=[".pdf", ".doc", ".docx"], destination="~/Documents"),
        Rule(extensions=[".jpg", ".png", ".gif"], destination="~/Pictures"),
        Rule(extensions=[".mp4", ".mkv"], destination="~/Videos"),
        Rule(pattern="invoice_*", destination="~/Documents/Invoices"),
    ]
)

# Preview what would happen (dry run)
report = organizer.preview("~/Downloads")
for action in report.actions:
    print(f"{action.source} -> {action.destination}")

# Execute
report = organizer.organize("~/Downloads")
print(f"Moved {report.total_moved} files ({report.total_size} bytes)")

# Undo
restored = Organizer.undo("~/Downloads")

Rule Options

Option	Description
extensions	Match by file extension
pattern	Match by glob pattern
name_contains	Match if filename contains string
larger_than	Minimum file size in bytes
smaller_than	Maximum file size in bytes
older_than_days	Match files older than N days
newer_than_days	Match files newer than N days
predicate	Custom matching function

Move Hooks

Register callbacks that fire after each successful move. Useful for logging, checksums, notifications, or kicking off downstream pipelines without subclassing.

organizer = Organizer(rules=rules)

@organizer.on_move
def log_move(action, rule):
    print(f"moved {action.source.name} -> {action.destination} (rule #{action.rule_index})")

Hooks fire only on organize() (not preview()), and only after the file has actually moved. Hook exceptions are captured in report.errors.

Conflict Resolution

organizer = Organizer(rules=rules, conflict="rename")   # default: adds (1), (2)...
organizer = Organizer(rules=rules, conflict="skip")      # skip existing
organizer = Organizer(rules=rules, conflict="overwrite")  # overwrite existing

API

Function / Class	Description
Organizer(rules, conflict, recursive)	Rule-based file organizer with preview(), organize(), and undo() methods
Organizer.on_move(hook)	Register a (action, rule) -> None callback fired after each successful move
Rule(destination, extensions, pattern, ...)	A rule that matches files by extension, pattern, size, or age
MoveAction	Describes a planned or executed file move (source, destination, size)
OrganizeReport	Result of an organize operation with actions, skipped, errors, total_moved, total_size

Development

pip install -e .
python -m pytest tests/ -v

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT