Add interactive grouping ranges, wildcards, counts and completion

This commit is contained in:
ajp_anton committed 2026-10-06 19:27:32 +00:00
1 parent e3633b8e1a
commit 9c637a67aa
2 files changed
+437 -10

No files matched your search

Regular → Executable
+170 -10
View File
@@ -2,7 +2,7 @@
"""
Fast manual grouping helper.
Drag files or directories onto this script, or run:
Run without arguments to enter paths/ranges interactively, or run:
python3 grouping.py path/to/file/or/directory [...]
Files are sorted by their current path and moved into one folder named
@@ -11,21 +11,174 @@ Files are sorted by their current path and moved into one folder named
from __future__ import annotations
import glob
import os
import shlex
import shutil
import sys
from pathlib import Path
from tools.console import pause_if_interactive
from tools.console import launch_terminal_if_needed, pause_if_interactive, prompt_input
from tools.filenames import group_stem
from tools.filesystem import (
cleanup_roots_from_args,
collect_files,
determine_working_dir,
entered_path,
path_completion,
path_completions,
remove_empty_dirs,
unique_path,
)
def range_lexer(value: str) -> shlex.shlex:
lexer = shlex.shlex(value, posix=True)
lexer.whitespace_split = True
lexer.commenters = lexer.escape = ""
return lexer
def sibling_items(source: Path) -> list[Path]:
folders = source.is_dir()
return sorted(
(item for item in source.parent.iterdir() if (item.is_dir() if folders else item.is_file())),
key=lambda item: (item.name.casefold(), item.name),
)
def range_completions(text: str) -> list[str]:
lexer = range_lexer(text)
try:
first = lexer.get_token()
except ValueError: # Completing inside an unfinished quote.
first = lexer.token
if first and "*" in first:
return []
if lexer.state != " ":
return [shlex.quote(path) for path in path_completions(first or "")]
boundary = lexer.instream.tell()
prefix = text[:boundary]
remainder = text[boundary:]
prefix += remainder[:len(remainder) - len(remainder.lstrip())]
second = range_lexer(remainder)
tokens: list[str] = []
try:
tokens.extend(second)
except ValueError:
tokens.append(second.token)
if len(tokens) > 1:
return []
value = tokens[0] if tokens else ""
if value.lstrip("+-").isdecimal() or "*" in value:
return []
source = entered_path(first).absolute()
if not (source.is_file() or source.is_dir()):
return []
directory = ""
if value.startswith(("/", "~")) or Path(value).is_absolute():
directory = os.path.join(str(source.parent), "")
if value.startswith("~"):
home = str(Path.home()) + os.sep
if not directory.startswith(home):
return []
directory = "~/" + directory[len(home):]
if directory != value and directory.startswith(value):
return [prefix + shlex.quote(directory)]
if not value.startswith(directory):
return []
value = value[len(directory):]
return [
prefix + shlex.quote(directory + item.name)
for item in sibling_items(source)
if item.name.startswith(value)
]
def expand_range(value: str) -> tuple[Path, list[Path]]:
tokens = list(range_lexer(value))
if len(tokens) not in {1, 2}:
raise ValueError("Enter a path/pattern, two range endpoints, or a path and count; quote names containing spaces.")
first = entered_path(tokens[0]).absolute()
if any("*" in token for token in tokens):
if len(tokens) != 1:
raise ValueError("Wildcards are only supported in a single-path entry, not a range or count.")
pattern = glob.escape(str(first)).replace("[*]", "*")
matches = sorted(
(path for name in glob.glob(pattern) if (path := Path(name)).is_file() or path.is_dir()),
key=lambda path: (str(path).casefold(), str(path)),
)
if not matches:
raise ValueError(f"No files or directories match: {first}")
return Path(os.path.commonpath([path.parent for path in matches])).resolve(), matches
if not (first.is_file() or first.is_dir()):
raise ValueError(f"File or directory not found: {first}")
parent = first.parent
if len(tokens) == 1:
return parent.resolve(), [first]
siblings = sibling_items(first)
names = [item.name for item in siblings]
start = names.index(first.name)
if tokens[1].lstrip("+-").isdecimal():
count = int(tokens[1])
if count < 1:
raise ValueError("Count must be a positive integer, including the starting item.")
if count > len(siblings) - start:
raise ValueError(f"Requested {count} items, but only {len(siblings) - start} remain from {first.name}.")
return parent.resolve(), siblings[start:start + count]
last = entered_path(tokens[1])
if not last.is_absolute():
if last.parent != Path("."):
raise ValueError("The second endpoint must be a name or an absolute path.")
last = parent / last
if last.parent.resolve() != parent.resolve():
raise ValueError("Range endpoints must be in the same directory.")
if not (last.is_file() or last.is_dir()):
raise ValueError(f"File or directory not found: {last}")
if first.is_dir() != last.is_dir():
raise ValueError("Range endpoints must both be files or both be directories.")
start, end = sorted((start, names.index(last.name)))
return parent.resolve(), siblings[start:end + 1]
def prompt_group_ranges() -> tuple[list[str], Path | None]:
print("Enter selections, one per line:")
print(" /photos/A.jpg One file or folder (folders are collected recursively)")
print(" /photos/DSC*.JPG Wildcard: * matches zero or more characters in a name")
print(" /photos/A.jpg C.jpg Inclusive range, in either order, both files or both folders")
print(" /photos/A.jpg 5 Five files starting at A.jpg (or five folders if A is a folder)")
print("Ranges/counts use alphabetical order and skip the other type; counts include A.")
print("Range endpoints must share a directory; B can be a name or an absolute path.")
print("Wildcards cannot be combined with ranges/counts. Use an absolute path for a numeric endpoint name.")
print('Quote paths/names containing spaces: "/photos/Trip A" "Trip C". Tab completes paths.')
print("Leave the line empty to group all selections together.")
args: list[str] = []
working_dir = None
with path_completion(range_completions):
while True:
value = prompt_input("Selection: ").strip()
if not value:
return args, working_dir
try:
parent, paths = expand_range(value)
if working_dir is not None and parent != working_dir:
raise ValueError(f"Use entries from the working directory: {working_dir}")
except ValueError as exc:
print(exc)
continue
if working_dir is None:
working_dir = parent
print(f"Working directory: {working_dir}")
args.extend(str(path) for path in paths)
print(f"Selected {len(paths)} file(s)/folder(s).")
def collect_group_files(args: list[str]) -> list[Path]:
return collect_files(args, sort_by_name=True)
@@ -41,6 +194,8 @@ def group_files(files: list[Path], working_dir: Path) -> Path | None:
target_dir.mkdir(parents=True, exist_ok=True)
for source in sorted_files:
if source.parent == target_dir:
continue
destination = unique_path(target_dir / source.name)
shutil.move(str(source), str(destination))
@@ -56,22 +211,25 @@ def print_removed_dirs(removed_dirs: list[Path]) -> None:
def run(argv: list[str]) -> int:
if len(argv) < 2:
print("Usage: python3 grouping.py path/to/file/or/directory [...]")
return 2
try:
working_dir = determine_working_dir(argv[1:])
if argv[1:]:
args = argv[1:]
working_dir = determine_working_dir(args)
else:
args, working_dir = prompt_group_ranges()
if not args:
print("No inputs selected.")
return 0
except RuntimeError as exc:
print(exc)
return 1
cleanup_roots = cleanup_roots_from_args(argv[1:])
files = collect_group_files(argv[1:])
cleanup_roots = cleanup_roots_from_args(args)
files = collect_group_files(args)
if not files:
print("No files to group.")
return 0
assert working_dir is not None
target_dir = group_files(files, working_dir)
if target_dir is not None:
print(f"Moved {len(files)} file(s) into {target_dir}")
@@ -81,6 +239,8 @@ def run(argv: list[str]) -> int:
def main(argv: list[str]) -> int:
if launch_terminal_if_needed(argv):
return 0
try:
return run(argv)
finally:
+267
View File
@@ -0,0 +1,267 @@
from __future__ import annotations
import os
import unittest
from contextlib import nullcontext
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest.mock import patch
from grouping import expand_range, prompt_group_ranges, range_completions, run
from tools.filesystem import remove_empty_dirs
class GroupingTests(unittest.TestCase):
def test_first_endpoint_completion_accepts_files_folders_and_quotes(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "A photo.jpg").touch()
(root / "A folder").mkdir()
for prefix in (str(root / "A"), '"' + str(root / "A")):
candidates = range_completions(prefix)
self.assertEqual(len(candidates), 2)
self.assertEqual(
{expand_range(candidate)[1][0] for candidate in candidates},
{root / "A photo.jpg", root / "A folder"},
)
def test_second_endpoint_completes_only_same_type_siblings(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("A photo.jpg", "B photo.jpg", "C photo.jpg"):
(root / name).touch()
for name in ("A folder", "C folder"):
(root / name).mkdir()
prefix = f'"{root / "C photo.jpg"}" '
candidates = range_completions(prefix)
self.assertEqual(len(candidates), 3)
self.assertEqual(range_completions(prefix + '"A ph'), [candidates[0]])
self.assertEqual([p.name for p in expand_range(candidates[0])[1]],
["A photo.jpg", "B photo.jpg", "C photo.jpg"])
folder_candidates = range_completions(f'"{root / "C folder"}" ')
self.assertEqual(len(folder_candidates), 2)
self.assertTrue(all(p.is_dir() for p in expand_range(folder_candidates[0])[1]))
self.assertEqual(range_completions(prefix + '"B photo.jpg" "third'), [])
@unittest.skipIf(os.name == "nt", "Unix absolute and home-directory paths")
def test_absolute_second_endpoint_completes_parent_then_sibling(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "A.jpg").touch()
(root / "B.jpg").touch()
prefix = f'"{root / "B.jpg"}" '
directory = str(root) + "/"
self.assertEqual(range_completions(prefix + "/"), [prefix + directory])
self.assertEqual(range_completions(prefix + directory),
[prefix + str(root / "A.jpg"), prefix + str(root / "B.jpg")])
self.assertEqual(range_completions(prefix + "/elsewhere/"), [])
with patch.dict("os.environ", {"HOME": str(root.parent)}):
completed = range_completions(prefix + "~")
self.assertEqual(len(completed), 1)
candidates = range_completions(completed[0])
self.assertEqual([p.name for p in expand_range(candidates[0])[1]], ["A.jpg", "B.jpg"])
def run_interactive(self, *lines: str) -> int:
with (
patch("grouping.prompt_input", side_effect=[*lines, ""]),
patch("grouping.path_completion", return_value=nullcontext()),
patch("builtins.print"),
):
return run(["grouping.py"])
def test_file_range_is_inclusive_sorted_and_skips_folders(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("D.jpg", "C.jpg", "a.jpg", "B.jpg"):
(root / name).touch()
(root / "BB-folder").mkdir()
parent, paths = expand_range(f'"{root / "a.jpg"}" C.jpg')
self.assertEqual(parent, root)
self.assertEqual([path.name for path in paths], ["a.jpg", "B.jpg", "C.jpg"])
self.assertEqual(expand_range(f'"{root / "C.jpg"}" a.jpg')[1], paths)
self.assertEqual(expand_range(f'"{root / "a.jpg"}" "{root / "C.jpg"}"')[1], paths)
def test_folder_range_skips_files_and_single_folder_uses_parent(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("A folder", "B folder", "C folder"):
(root / name).mkdir()
(root / "B.jpg").touch()
parent, paths = expand_range(f'"{root / "A folder"}" "C folder"')
self.assertEqual(parent, root)
self.assertEqual([path.name for path in paths], ["A folder", "B folder", "C folder"])
self.assertEqual(expand_range(f'"{root / "A folder"}"'), (root, [root / "A folder"]))
def test_invalid_ranges_are_rejected(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "A.jpg").touch()
(root / "folder").mkdir()
(root / "folder" / "B.jpg").touch()
for line in (
f'"{root / "A.jpg"}" folder',
f'"{root / "A.jpg"}" folder/B.jpg',
f'"{root / "A.jpg"}" missing.jpg',
f'"{root / "A.jpg"}',
f'"{root / "A.jpg"}" B C',
):
with self.subTest(line=line), self.assertRaises(ValueError):
expand_range(line)
def test_wildcard_matches_zero_or_more_characters_and_folders(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("Trip .jpg", "Trip A.jpg", "Trip AB.jpg", "Other.jpg"):
(root / name).touch()
(root / "Trip folder").mkdir()
parent, paths = expand_range(f'"{root / "Trip *.jpg"}"')
self.assertEqual(parent, root)
self.assertEqual([p.name for p in paths], ["Trip .jpg", "Trip A.jpg", "Trip AB.jpg"])
self.assertEqual(len(expand_range(f'"{root / "Trip *"}"')[1]), 4)
(root / "[photo]1.jpg").touch()
(root / "p1.jpg").touch()
self.assertEqual(expand_range(f'"{root / "[photo]*.jpg"}"')[1], [root / "[photo]1.jpg"])
def test_wildcard_directory_components_use_common_parent(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("Trip1", "Trip2"):
(root / name).mkdir()
(root / name / "A.jpg").touch()
parent, paths = expand_range(f'"{root}/Trip*/A.jpg"')
self.assertEqual(parent, root)
self.assertEqual(paths, [root / "Trip1" / "A.jpg", root / "Trip2" / "A.jpg"])
def test_invalid_wildcards_do_not_become_ranges_or_counts(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "A.jpg").touch()
for line in (
f'"{root / "*.jpg"}" A.jpg',
f'"{root / "A.jpg"}" *.jpg',
f'"{root / "*.jpg"}" 2',
f'"{root / "missing*"}"',
):
with self.subTest(line=line), self.assertRaises(ValueError):
expand_range(line)
def test_count_includes_start_and_skips_other_type(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("A.jpg", "b.jpg", "C.jpg", "D.jpg"):
(root / name).touch()
for name in ("A folder", "B folder", "C folder"):
(root / name).mkdir()
self.assertEqual(expand_range(f'"{root / "b.jpg"}" 2'), (root, [root / "b.jpg", root / "C.jpg"]))
self.assertEqual(expand_range(f'"{root / "D.jpg"}" 1'), (root, [root / "D.jpg"]))
self.assertEqual(expand_range(f'"{root / "A folder"}" 2')[1], [root / "A folder", root / "B folder"])
for count in ("0", "-1", "3", "1.5"):
with self.subTest(count=count), self.assertRaises(ValueError):
expand_range(f'"{root / "C.jpg"}" {count}')
(root / "2").touch()
self.assertEqual(range_completions(f'"{root / "A.jpg"}" 2'), [])
self.assertEqual(expand_range(f'"{root / "A.jpg"}" "{root / "2"}"')[1], [root / "2", root / "A.jpg"])
def test_wildcards_and_counts_combine_into_one_group(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("A.jpg", "B.jpg", "C.jpg", "D.jpg"):
(root / name).write_bytes(name.encode())
(root / "Extra" / "empty").mkdir(parents=True)
(root / "Extra" / "E.jpg").touch()
self.assertEqual(self.run_interactive(
f'"{root / "A.jpg"}" 99',
f'"{root / "A.jpg"}" 2',
f'"{root / "B*"}"',
f'"{root / "Extra*"}"',
), 0)
self.assertEqual(sorted(p.name for p in (root / "A-E").iterdir()), ["A.jpg", "B.jpg", "E.jpg"])
self.assertEqual((root / "C.jpg").read_bytes(), b"C.jpg")
self.assertEqual((root / "D.jpg").read_bytes(), b"D.jpg")
self.assertFalse((root / "Extra").exists())
def test_prompt_lists_all_input_forms(self) -> None:
with (
patch("grouping.prompt_input", return_value=""),
patch("grouping.path_completion", return_value=nullcontext()),
patch("builtins.print") as output,
):
self.assertEqual(prompt_group_ranges(), ([], None))
instructions = "\n".join(call.args[0] for call in output.call_args_list)
for form in ("One file or folder", "Wildcard", "Inclusive range", "Five files", "Quote", "Tab", "empty"):
self.assertIn(form, instructions)
def test_overlapping_ranges_group_once_after_blank_line(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for name in ("A.jpg", "B.jpg", "C.jpg", "D.jpg"):
(root / name).write_bytes(name.encode())
self.assertEqual(self.run_interactive(
f'"{root / "missing.jpg"}"',
f'"{root / "A.jpg"}" B.jpg',
f'"{root / "B.jpg"}" C.jpg',
), 0)
group = root / "A-C"
self.assertEqual(sorted(path.name for path in group.iterdir()), ["A.jpg", "B.jpg", "C.jpg"])
self.assertEqual((root / "D.jpg").read_bytes(), b"D.jpg")
self.assertEqual((group / "B.jpg").read_bytes(), b"B.jpg")
def test_recursive_folders_flatten_with_collision_suffixes_and_cleanup(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
for folder in ("A", "B", "C"):
(root / folder / "nested" / "empty").mkdir(parents=True)
(root / "A" / "nested" / "photo.jpg").write_bytes(b"first")
(root / "C" / "photo.jpg").write_bytes(b"second")
self.assertEqual(self.run_interactive(f'"{root / "A"}" C'), 0)
group = root / "photo-photo"
self.assertEqual(set(path.name for path in group.iterdir()), {"photo.jpg", "photo-1.jpg"})
self.assertEqual({path.read_bytes() for path in group.iterdir()}, {b"first", b"second"})
self.assertEqual(list(root.iterdir()), [group])
def test_empty_only_folder_selection_still_gets_removed(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "A" / "empty" / "leaf").mkdir(parents=True)
self.assertEqual(self.run_interactive(f'"{root / "A"}"'), 0)
self.assertEqual(list(root.iterdir()), [])
def test_existing_group_is_reused_without_renaming_its_own_files(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
target = root / "A-C"
target.mkdir()
(target / "A.jpg").write_bytes(b"existing")
(root / "C.jpg").write_bytes(b"new")
self.assertEqual(self.run_interactive(f'"{target}"', f'"{root / "C.jpg"}"'), 0)
self.assertEqual(sorted(path.name for path in target.iterdir()), ["A.jpg", "C.jpg"])
self.assertEqual((target / "A.jpg").read_bytes(), b"existing")
def test_command_line_folder_keeps_existing_working_directory_rule(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
nested = root / "nested"
nested.mkdir()
(nested / "photo.jpg").touch()
(nested / "notes.txt").touch()
with patch("builtins.print"):
self.assertEqual(run(["grouping.py", str(root)]), 0)
self.assertEqual(
sorted(path.name for path in (root / "notes-photo").iterdir()),
["notes.txt", "photo.jpg"],
)
self.assertFalse(nested.exists())
def test_cleanup_keeps_any_remaining_files_and_their_parents(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
(root / "selected" / "empty" / "leaf").mkdir(parents=True)
notes = root / "selected" / "notes.txt"
notes.write_bytes(b"keep")
remove_empty_dirs([root / "selected"], {root})
self.assertEqual(notes.read_bytes(), b"keep")
self.assertFalse((root / "selected" / "empty").exists())
if __name__ == "__main__":
unittest.main()