pathmagic

What it is and what it does

Pathmagic wraps filesystem paths in ORM-like File and Dir classes that trigger I/O operations when their properties are modified—similar to how database ORMs work. Instead of calling functions like os.rename() or os.remove(), you set properties like Dir.name or File.path, and the filesystem changes automatically. The File class adds a FormatHandler factory that detects file type by extension and reads or writes using the appropriate library: PDF via PyPDF2, images via Pillow, audio via pydub, video via moviepy, Word docs via python-docx, spreadsheets via pysubtypes, and JSON, pickle, HTML, and XML via standard or custom handlers.

The package is in alpha and explicitly under development, with the maintainer warning that the API will likely break and documentation will fall out of sync. The project has been abandoned since early 2022, with no releases or commits since then. It carries 13 runtime dependencies, several of which are heavy media libraries, making it a substantial addition to any environment. Use it only if you need its specific abstraction style and are prepared to maintain a fork if issues arise.

Use it for:

• Automate batch file operations (rename, move, delete) on mixed file types using property assignment instead of function calls.
• Read and write multiple document formats (PDF, Word, Excel, JSON, images) with a single unified File.read()/File.write() interface.
• Recursively search and filter directory trees by file extension, regex patterns, or content without manual os.walk() loops.
• Traverse filesystem hierarchies using attribute access (e.g., my_dir.f.subfolder.file_name) instead of path string manipulation.
• Compress directories into zip files or visualize directory trees as ASCII art for debugging or reporting.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides File and Dir classes that wrap filesystem operations as ORM-like objects with properties and methods for reading, writing, traversing, and manipulating files and directories across multiple formats.

No. The project is abandoned (last commit April 2022, last release February 2021) and explicitly in alpha with a warning that the API will break. The 13 runtime dependencies—including unmaintained or slow-moving libraries like moviepy—add significant install weight and potential security risk. Unless you need its specific ORM-style abstraction and are willing to fork and maintain it yourself, use pathlib (standard library) or a more actively maintained alternative.

Install

pathmagic on PyPI

pip install pathmagic

uv add pathmagic

poetry add pathmagic

Installing pathmagic

Before you install

Low install friction with a pure-Python wheel, but maintenance is a significant concern: last release was 2021-02-01 and the last commit 2022-04-22, with the project marked abandoned. The 13 runtime dependencies include media libraries (moviepy, pydub) and document handlers (PyPDF2, python-docx) that may themselves have unaddressed issues.

License in practice

MIT license is permissive and poses no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart

from pathmagic import File, Dir

# Create a Dir object and list files
my_dir = Dir('/path/to/directory')
for f in my_dir.files:
    print(f.name)

# Read a file with automatic format detection
my_file = File('/path/to/file.json')
content = my_file.read()

No compiled dependencies, but requires Python 3.8 or later per the classifiers; exact minimum version unspecified.

Verify before relying

• Whether the 13 runtime dependencies (especially moviepy, pydub, PyPDF2) are actively maintained or have known security issues.
• Whether the API has stabilized since the last release or remains subject to breaking changes as the description warns.
• Compatibility with Python versions beyond 3.8 given the project's abandoned status.

Package facts

Evidence: pathmagic-0.3.14-py3-none-any.whl

Tags

More Software Development packages