Welcome to Sortium’s Documentation#

Plan-first file orchestration

Preview every move before touching disk.

Sortium scans millions of files without blowing up memory, builds human-readable JSON plans, and applies them only when you are ready. Audit, edit, or hand off the plan with confidence—or drive everything from the new Sortium CLI.

pip install sortium View on GitHub Explore the CLI
JSON Plan files you can diff and version.
3+ Sorting modes: type, date, regex.
0 Overwrites thanks to collision guards.

Plan-First Workflow

Generate editable JSON instructions and keep them under git to document every move.

Flexible Categorization

Mix file-type buckets, date partitions, and regex captures to shape exactly how archives look.

Safety Nets Built-In

Automatic collision avoidance, dry-run previews, and deterministic destination builders.

Minimal Memory Footprint

Streams directories with generators so even sprawling NAS shares stay manageable.

Recursive On-Demand

Flip a ``recursive=True`` flag on any strategy to pull nested files into the plan—or leave it off for shallow sweeps.

First-Class CLI

Use ``sortium plan/apply/undo/tree`` to script workflows, automate cron jobs, or integrate with deployment pipelines.

Note

This documentation covers installation, usage guides, and the complete API reference for Sortium.

Contents:

A 30-Second Guide#

Warning

Always back up your files before running Sortium. This utility performs file move operations that modify your directory structure. Misuse could lead to data loss.

First, install the library via pip:

pip install sortium

Example 1: Basic Sorting by Type (In-Place)

This is the simplest use case. It organizes all files in a folder into subdirectories like Images, Documents, and Videos.

from sortium.sorter import Sorter

# The folder you want to clean up
my_folder = "/path/to/my_messy_downloads"

# Create a Sorter instance and produce a plan
sorter = Sorter()
plan_path = sorter.sort_by_type(my_folder, recursive=True)

# Inspect/edit the JSON if desired, then apply it
sorter.file_utils.apply_move_plan(str(plan_path))

Tip

Drop recursive=True (the default) if you only want to move files living directly inside my_folder.

Example 2: Sorting to a New Destination

Organize files from a source folder and move the categorized results to a separate, clean location.

from sortium.sorter import Sorter

source_dir = "/path/to/source_files"
destination_dir = "/path/to/organized_archive"

sorter = Sorter()

# Prepare a plan that moves files into categorized folders inside destination_dir
plan_path = sorter.sort_by_type(
   source_dir,
   dest_folder_path=destination_dir,
   recursive=True,
)
sorter.file_utils.apply_move_plan(str(plan_path))

Example 3: Advanced Sorting with Regex

Recursively scan a directory and sort files based on custom patterns. This is great for organizing project files, logs, or datasets.

from sortium.sorter import Sorter

project_folder = "/path/to/data_science_project"
sorted_output = "/path/to/sorted_project_files"

# Define categories and their corresponding regex patterns
regex_patterns = {
   "Datasets": r".*\.csv$",
   "Notebooks": r".*\.ipynb$",
   "Final_Reports": r"final_report_.*\.pdf$"
}

sorter = Sorter()
plan_path = sorter.sort_by_regex(
   project_folder,
   regex_patterns,
   sorted_output,
   recursive=True,
)
sorter.file_utils.apply_move_plan(str(plan_path))

Note

recursive defaults to True for regex sorting so deep project trees are handled automatically. Pass recursive=False to limit the scan to the root directory only.

Command-Line Workflow#

Prefer working from a terminal? Install Sortium and use the bundled CLI:

# Generate a plan using the type strategy
sortium plan type --source ./Downloads --dest ./Archive --recursive

# Apply or undo the plan later
sortium apply --plan ./Downloads/sortium_plan_type_20250101_101010.json
sortium undo --plan ./Downloads/sortium_plan_type_20250101_101010.json

# Export a tree snapshot for quick audits
sortium tree --source ./Downloads --output ./downloads_structure.json

  • plan works with the type, extension, date, and regex strategies and honors --ignore, --plan-output, and --recursive.

  • apply executes a plan as-is, optionally with --dry-run for validation, while undo is a shortcut for apply --reverse.

  • tree produces a JSON snapshot of any folder so you can review structures before moving files.

Run sortium --help or sortium plan --help to view every flag (custom regex maps, folder-specific date sorting, dry-run previews, etc.).

Project Info#

On this page
Show Source