commonUtils is a reusable Python library for file automation and desktop tools. It provides filesystem objects and format registration, persistent directory indexing, archive and process operations, configuration and atomic persistence, and shared Qt browsers, readers and editors. Applications supply their own workflows, domain file types, dependency policy and settings.
Logistics and Blue Hole are existing consumers. Application features built on these components remain owned by their consuming projects.
Place the checkout in a directory named commonUtils, with its parent on
Python's import path. There is no pip-installable distribution or standalone
dependency lockfile in this repository. Python 3.10 syntax is used; the checked-in
CI configuration tests Python 3.12.2 on Windows, macOS and Linux. Compatibility
with every newer Python/dependency version is not established.
my_project/
├── example.py
└── commonUtils/
Install only the dependencies for the components you use. The following example needs Python's standard library; widgets require PySide6. See setup and dependencies for environment details.
import sys
from commonUtils.integrations.wrappers.cmdShellWrapper import run_command
result = run_command([sys.executable, '--version'], timeout=10)
if result.success:
print('\n'.join(result.stdout))
else:
print(result.returncode, result.stderr, result.timed_out, result.cancelled)Start at the developer hub.
| Task | Guide |
|---|---|
| Integrate the library | Getting started |
| Understand ownership and lifecycle | Architecture |
| Choose APIs and handle failures | Public APIs |
| Register formats, actions and information providers | Extension points |
| Upgrade an existing consumer | Integration contracts |
| Contribute and validate changes | Maintenance |
| Area | Capabilities and detailed reference |
|---|---|
| filesystem | Files, directories, links, traversal, transfers, removal, rename, storage and indexes |
| formats | File registry; text, CSV, JSON, XML, INI, Markdown and archive types |
| archives | Create, inspect, extract, edit and verify archives |
| runtime | Platform detection, diagnostics, cancellation, batches, streams and downloads |
| integrations | Applications, web links, Steam and external command adapters |
| configuration | Settings reads, optional typed INI schema and editor integration |
| persistence | Atomic publication, text snapshots, recovery and merge models |
| ui | PySide widgets, browser extensions, workspaces, readers and editors |
Launchers support consumer project startup; they are not a library installer. Optional native tools and platform restrictions belong to the operation that uses them.
These guides describe reusable behavior; host applications may add commands or choose which components to expose.
- File Browser: navigation, search, size maps and tabs
- Markdown: reading, editing, properties and diagrams
- Code editing and diff/merge review
- Archive contents and previews
- Shared text and INI editors
Use the current import paths and integration contracts. There is no documented semantic versioning or universal API stability promise. Test affected consumers before updating pinned or vendored revisions. See contributor guidance.
MIT. Copyright © 2020–2026 Marc-André Voyer.