Improve photo organization controls and reference completion

This commit is contained in:
ajp_anton committed 2026-10-06 19:27:32 +00:00
1 parent ad2b15994f
commit e3633b8e1a
6 files changed
+316 -41

No files matched your search

Regular → Executable
+17 -8
View File
@@ -18,6 +18,7 @@ import sys
from tools.console import (
ProgressView,
clear_screen,
launch_terminal_if_needed,
pause_if_interactive,
prompt_yes_no as ask_yes_no,
)
@@ -34,24 +35,30 @@ from tools.filesystem import (
cleanup_roots_from_args,
collect_files,
determine_working_dir,
input_paths,
remove_empty_dirs,
)
def run(argv: list[str]) -> int:
if len(argv) < 2:
print("Usage: python3 photo_metadata.py path/to/file/or/directory [...]")
return 2
try:
args = input_paths(argv)
except RuntimeError as exc:
print(exc)
return 1
if not args:
print("No inputs selected.")
return 0
try:
working_dir = determine_working_dir(argv[1:])
working_dir = determine_working_dir(args)
except RuntimeError as exc:
print(exc)
return 1
cleanup_roots = cleanup_roots_from_args(argv[1:])
files = collect_files(argv[1:], allowed_exts=SUPPORTED_EXTS, print_missing=True)
pto_files = collect_files(argv[1:], allowed_exts={".pto"})
cleanup_roots = cleanup_roots_from_args(args)
files = collect_files(args, allowed_exts=SUPPORTED_EXTS, print_missing=True)
pto_files = collect_files(args, allowed_exts={".pto"})
if not files:
print("No supported media files found.")
return 1
@@ -112,7 +119,7 @@ def run(argv: list[str]) -> int:
failures = apply_changes(exiftool, records, choices)
failures.extend(apply_pto_changes(pto_plans))
removed_dirs = remove_empty_dirs(cleanup_roots, keep_dirs={working_dir.resolve()})
removed_dirs = remove_empty_dirs(cleanup_roots, keep_dirs={choices.working_dir.resolve()})
print_removed_dirs(removed_dirs)
if failures:
@@ -126,6 +133,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:
+3 -2
View File
@@ -51,8 +51,9 @@ def print_preview(records: list[MediaRecord], choices: UserChoices, pto_plans: l
elif choices.fill_timezone_gaps:
print(" Timezone offsets: fill missing gaps")
print(f" Filename mode: {choices.rename_mode.replace('_', '/')}")
print(f" Organize/group: {'yes' if choices.organize_files else 'no'}")
if choices.organize_files:
organization = "grouping" if choices.organize_files and choices.group_files else "flat" if choices.organize_files else "no moving"
print(f" Organize/group: {organization}")
if choices.group_photos:
print(f" Burst/HDR minimum: {choices.group_min_size}+ files")
print(f" Panorama project files: {'yes' if choices.process_pto_files else 'no'}")
if choices.artist_action != "leave":
+1 -1
View File
@@ -123,7 +123,7 @@ def infer_group_subseconds(groups: list[list[MediaRecord]]) -> None:
count = len(records)
if count <= 1:
continue
if len(seconds) == 2:
if len(seconds) <= 2:
fps = max(counts.values())
elif index == 0:
fps = max(count, counts[seconds[1]])
+32 -5
View File
@@ -42,10 +42,11 @@ class UserChoices:
group_min_size: int
process_pto_files: bool
infer_missing_timestamps: bool
group_files: bool = True
@property
def group_photos(self) -> bool:
return self.organize_files and self.group_min_size >= 2
return self.organize_files and self.group_files and self.group_min_size >= 2
@property
def move_to_working_dir(self) -> bool:
@@ -114,7 +115,9 @@ def filename_timestamp_stem(stem: str, timestamp: datetime, mode: str) -> str:
def plan_names(records: list[MediaRecord], choices: UserChoices) -> None:
by_stem = _unique_records_by_stem(records)
for record in records:
record.new_stem = record.rename_skip_reason = None
record.new_stem = record.final_name = record.rename_skip_reason = None
if choices.rename_mode == "none":
continue
if record.adjusted_time is None:
record.new_stem = _camera_range_stem(record, by_stem)
record.rename_skip_reason = None if record.new_stem else "missing timestamp"
@@ -227,6 +230,31 @@ def plan_targets(records: list[MediaRecord], choices: UserChoices) -> None:
record.target_path = directory / name
if record.sidecar:
record.target_sidecar = directory / f"{Path(name).stem}M01.XML"
_make_targets_unique(records)
def _make_targets_unique(records: list[MediaRecord]) -> None:
used: set[tuple[Path, str]] = set()
ordered = sorted(
records,
key=lambda record: (
record.target_path != record.path,
group_sort_key(record),
),
)
for record in ordered:
assert record.target_path is not None
target = record.target_path
index = 0
while (target.parent.resolve(), target.name.lower()) in used:
index += 1
target = record.target_path.with_name(
f"{record.target_path.stem}-{index}{record.target_path.suffix}"
)
used.add((target.parent.resolve(), target.name.lower()))
record.target_path = target
if record.sidecar:
record.target_sidecar = target.with_name(f"{target.stem}M01.XML")
def normalize_reference(value: str) -> str:
@@ -370,9 +398,8 @@ def prepare_plan(records: list[MediaRecord], choices: UserChoices, references: l
apply_time_offset(records, choices.time_offset)
burst_groups = detect_photo_groups(records, choices.group_min_size) if choices.group_photos else []
groups = merge_record_groups(records, [*burst_groups, *(reference.records for reference in references if choices.process_pto_files)])
if groups:
assign_groups(records, groups)
if choices.organize_files:
assign_groups(records, groups)
if choices.group_photos:
infer_group_subseconds(burst_groups)
plan_names(records, choices)
if groups:
+69 -24
View File
@@ -12,6 +12,7 @@ from pathlib import Path
from tools.console import dark_field, dim, draw_screen, inverse, light_red, raw_key_input
from tools.exiftool import run_exiftool_json
from tools.filenames import naive_wall_time
from tools.filesystem import complete_path, entered_path, resolve_output_directory
from tools.media_metadata import DATETIME_RE
from tools.photo_planning import UserChoices
from tools.photo_records import IMAGE_EXTS, MediaRecord, build_records
@@ -137,6 +138,7 @@ class TimezoneAnalysis:
@dataclass
class SettingsState:
working_dir: Path
time_offset: timedelta | None
infer_missing_timestamps: bool
fixed_timezone: timezone
@@ -146,6 +148,7 @@ class SettingsState:
artist_enabled: bool = False
artist_value: str = ""
organize_files: bool = False
group_files: bool = True
group_min_size: int = 2
process_pto_files: bool = True
@@ -218,7 +221,7 @@ def parse_clock_time(value: str, reference: datetime) -> datetime:
def reference_record(executable: str, records: list[MediaRecord], value: str) -> MediaRecord:
text = value.strip().strip('"')
text = str(entered_path(value))
absolute = os.path.isabs(text) or bool(re.match(r"^[A-Za-z]:[\\/]", text) or text.startswith("\\\\"))
candidates = records if absolute else [record for record in records if record.path.name.lower() == text.lower()]
if not candidates and not absolute:
@@ -243,6 +246,16 @@ def reference_record(executable: str, records: list[MediaRecord], value: str) ->
return photos[0]
def reference_completions(text: str, records: list[MediaRecord]) -> list[str]:
quote = text[0] if text[:1] in {"\"", "'"} else ""
prefix = text[1:] if quote else text
if quote and prefix.endswith(quote):
prefix = prefix[:-1]
names = {record.path.name for record in records if record.is_image}
return [quote + name + quote for name in sorted(names, key=str.casefold)
if name.casefold().startswith(prefix.casefold())]
def option_text(text: str, selected: bool, active: bool = True) -> str:
value = f"{text}"
if not active:
@@ -271,7 +284,6 @@ def default_artist(records: list[MediaRecord]) -> str:
def settings_lines(
state: SettingsState,
analysis: TimezoneAnalysis,
working_dir: Path,
rows: list[str],
row: int,
option: int,
@@ -287,7 +299,8 @@ def settings_lines(
option_text("none", option == 0),
option_text(time_value if state.time_offset else "shift", option == 1),
]
rename_names = ["Adjust/replace", "Adjust/add", "Replace", "Add"]
rename_modes = ("none", "adjust_replace", "adjust_add", "replace", "add")
rename_names = ["No", "Adjust/replace", "Adjust/add", "Replace", "Add"]
rename_options = [option_text(name, option == index) for index, name in enumerate(rename_names)]
fixed = timezone_to_string(state.fixed_timezone)
fixed_option = f"Set {fixed} ({'on' if state.fixed_timezone_enabled else 'off'})"
@@ -295,18 +308,19 @@ def settings_lines(
option_text(fixed_option, option == 0),
option_text("Fill gaps", option == 1, analysis.gap_count > 0),
]
group_options = [option_text("Yes" if state.organize_files else "No", option == 0)]
if selected == "organize" or state.organize_files:
organize_mode = "Grouping" if state.organize_files and state.group_files else "Flat" if state.organize_files else "No moving"
group_options = [option_text(organize_mode, selected == "organize" and option == 0)]
if selected == "organize" or organize_mode == "Grouping":
group_options.extend(
(
option_text(f"{state.group_min_size}+ files", option == 1, state.organize_files),
option_text(".pto", option == 2, state.organize_files and state.process_pto_files),
option_text(f"{state.group_min_size}+ files", selected == "organize" and option == 1, organize_mode == "Grouping"),
option_text(f".pto {'on' if state.process_pto_files else 'off'}", selected == "organize" and option == 2, organize_mode == "Grouping"),
)
)
if selected != "time":
time_options = [time_value]
if selected != "rename":
rename_options = [rename_names[("adjust_replace", "adjust_add", "replace", "add").index(state.rename_mode)]]
rename_options = [rename_names[rename_modes.index(state.rename_mode)]]
if selected != "timezone":
enabled = []
if state.fixed_timezone_enabled:
@@ -319,11 +333,10 @@ def settings_lines(
artist = light_red("(remove)")
if selected == "artist":
artist = option_text("no change", True) if not state.artist_enabled else option_text(artist, True)
if selected != "organize" and not state.organize_files:
group_options = ["No"]
if selected != "organize" and organize_mode != "Grouping":
group_options = [organize_mode]
lines = [
f"Working directory: {working_dir}",
"",
f"Output directory: {option_text(str(state.working_dir), selected == 'working')}",
f"Time correction: {' '.join(time_options)}",
]
if "infer" in rows:
@@ -372,6 +385,7 @@ def prompt_choices(
analysis = analyze_timezones(records)
first_zone = analysis.ordered_zones[0] if analysis.ordered_zones else local_timezone()
state = copy.deepcopy(initial_state) if initial_state else SettingsState(
working_dir=working_dir,
time_offset=None,
infer_missing_timestamps=True,
fixed_timezone=first_zone,
@@ -380,7 +394,7 @@ def prompt_choices(
process_pto_files=has_pto_files,
artist_value=default_artist(records),
)
rows = ["time"]
rows = ["working", "time"]
if any(record.original_time is None for record in records):
rows.append("infer")
rows.extend(["timezone", "rename", "artist", "organize", "confirm"])
@@ -389,12 +403,13 @@ def prompt_choices(
editor = None
text = message = ""
reference = None
completions = []
def enter_row(index: int) -> None:
nonlocal row, option
row = index % len(rows)
if rows[row] == "rename":
option = ("adjust_replace", "adjust_add", "replace", "add").index(state.rename_mode)
option = ("none", "adjust_replace", "adjust_add", "replace", "add").index(state.rename_mode)
elif rows[row] == "time":
option = 1 if state.time_offset is not None else 0
else:
@@ -408,13 +423,26 @@ def prompt_choices(
with raw_key_input() as next_key:
while True:
draw_screen(settings_lines(state, analysis, working_dir, rows, row, option, editor=editor, text=text, message=message, reference=reference))
lines = settings_lines(state, analysis, rows, row, option, editor=editor, text=text, message=message, reference=reference)
if completions:
lines.insert(-2, dim(" ".join(completions[:8]) + (" ..." if len(completions) > 8 else "")))
draw_screen(lines)
key = next_key()
completions = []
if editor:
if key == "esc":
finish_editor()
elif key == "backspace":
text = text[:-1]
elif key == "tab" and editor == "working":
text = complete_path(text, working_dir)
elif key == "tab" and editor == "time-source":
matches = reference_completions(text, records)
if matches:
common = os.path.commonprefix([name.casefold() for name in matches])
text = matches[0][:len(common)]
completions = matches if len(matches) > 1 else []
message = ""
elif key == "enter":
if editor == "timezone":
try:
@@ -424,6 +452,13 @@ def prompt_choices(
else:
state.fixed_timezone_enabled = True
finish_editor()
elif editor == "working":
try:
state.working_dir = resolve_output_directory(text, working_dir)
except ValueError as exc:
message = str(exc)
else:
finish_editor()
elif editor == "artist":
state.artist_value = text
state.artist_enabled = True
@@ -473,7 +508,7 @@ def prompt_choices(
apply_timezone_settings(records, state)
artist_action = "leave" if not state.artist_enabled else ("set" if state.artist_value else "clear")
return UserChoices(
working_dir=working_dir,
working_dir=state.working_dir,
time_offset=state.time_offset,
fixed_timezone=state.fixed_timezone if state.fixed_timezone_enabled else None,
fill_timezone_gaps=state.fill_timezone_gaps,
@@ -482,14 +517,20 @@ def prompt_choices(
rename_mode=state.rename_mode,
organize_files=state.organize_files,
group_min_size=state.group_min_size,
process_pto_files=state.organize_files and state.process_pto_files,
process_pto_files=state.organize_files and state.group_files and state.process_pto_files,
infer_missing_timestamps=state.infer_missing_timestamps,
group_files=state.group_files,
), state
if key == "down" or (key == "enter" and current != "time"):
if key == "down" or (key == "enter" and current not in {"working", "time"}):
enter_row(row + 1)
continue
if current == "time":
if current == "working":
if key == "enter":
editor, text = "working", ""
elif len(key) == 1:
editor, text = "working", key
elif current == "time":
if key == "left":
option = 0
state.time_offset = None
@@ -519,8 +560,8 @@ def prompt_choices(
if key == "left":
option = max(0, option - 1)
elif key == "right":
option = min(3, option + 1)
state.rename_mode = ("adjust_replace", "adjust_add", "replace", "add")[option]
option = min(4, option + 1)
state.rename_mode = ("none", "adjust_replace", "adjust_add", "replace", "add")[option]
elif current == "artist":
if key == "space":
state.artist_enabled = not state.artist_enabled
@@ -529,15 +570,19 @@ def prompt_choices(
elif current == "organize":
if key == "left":
option = max(0, option - 1)
elif key == "right" and state.organize_files:
elif key == "right" and state.organize_files and state.group_files:
option = min(2, option + 1)
elif key == "space":
if option == 0:
state.organize_files = not state.organize_files
if not state.organize_files:
state.organize_files, state.group_files = True, False
elif not state.group_files:
state.group_files = True
else:
state.organize_files = False
elif option == 2:
state.process_pto_files = not state.process_pto_files
elif option == 1 and key.isdigit():
editor, text = "group", key
elif current == "confirm" and key in {"left", "right"}:
option = 1 - option
+194 -1
View File
@@ -1,9 +1,15 @@
from __future__ import annotations
import os
import unittest
from contextlib import contextmanager
from datetime import datetime, timedelta, timezone
from pathlib import Path
from tempfile import TemporaryDirectory
from unittest.mock import patch
from tools.console import read_key
from tools.filesystem import complete_path, path_completions, prompt_existing_paths, resolve_output_directory
from tools.photo_grouping import detect_photo_groups, infer_group_subseconds
from tools.photo_planning import (
UserChoices,
@@ -11,12 +17,20 @@ from tools.photo_planning import (
filename_timestamp_stem,
infer_missing_timestamps,
merge_record_groups,
prepare_plan,
)
from tools.photo_records import (
MediaRecord,
infer_video_timezone,
)
from tools.photo_settings import default_artist
from tools.photo_settings import (
SettingsState,
TimezoneAnalysis,
default_artist,
prompt_choices,
reference_completions,
settings_lines,
)
class PhotoMetadataLogicTests(unittest.TestCase):
@@ -37,6 +51,98 @@ class PhotoMetadataLogicTests(unittest.TestCase):
base.update(values)
return UserChoices(**base)
def test_interactive_paths_accept_quotes_and_file_urls(self) -> None:
with TemporaryDirectory() as temporary:
directory = Path(temporary)
photo = directory / "a photo.jpg"
photo.touch()
answers = ["missing", f'"{photo}"', directory.as_uri(), ""]
with (
patch("tools.filesystem.prompt_input", side_effect=answers),
patch("builtins.print"),
):
self.assertEqual(
prompt_existing_paths(),
[str(photo.resolve()), str(directory.resolve())],
)
def test_path_completion_supports_spaces_and_directories(self) -> None:
with TemporaryDirectory() as temporary:
directory = Path(temporary)
(directory / "a photo.jpg").touch()
(directory / "a folder").mkdir()
prefix = str(directory / "a")
self.assertEqual(
path_completions(prefix),
[str(directory / "a folder") + os.sep, str(directory / "a photo.jpg")],
)
self.assertEqual(complete_path("a ", directory), "a ")
self.assertEqual(complete_path("a f", directory), "a folder" + os.sep)
(directory / "a folder" / "nested.jpg").touch()
self.assertEqual(complete_path("a folder/", directory), str(Path("a folder") / "nested.jpg"))
def test_reference_completion_uses_only_selected_photo_names(self) -> None:
records = [
MediaRecord(Path("one/Clock photo.jpg"), {}, "image"),
MediaRecord(Path("two/Clock photo.jpg"), {}, "image"),
MediaRecord(Path("Clock video.mp4"), {}, "video"),
MediaRecord(Path("Other.jpg"), {}, "image"),
]
self.assertEqual(reference_completions("cl", records), ["Clock photo.jpg"])
self.assertEqual(reference_completions('"Cl', records), ['"Clock photo.jpg"'])
self.assertEqual(reference_completions("+1:00", records), [])
def test_reference_photo_can_be_selected_with_tab(self) -> None:
timestamp = datetime(2026, 6, 7, 14, 0, 0)
record = MediaRecord(Path("Clock photo.jpg"), {}, "image", original_time=timestamp)
keys = iter(["down", "right", "C", "l", "tab", "enter", *"14:03:25", "enter",
"down", "down", "down", "down", "enter"])
@contextmanager
def key_input():
yield lambda: next(keys)
with (
patch("tools.photo_settings.raw_key_input", key_input),
patch("tools.photo_settings.draw_screen"),
):
choices, _ = prompt_choices("exiftool", [record], Path("/photos"), False)
self.assertEqual(choices.time_offset, timedelta(minutes=3, seconds=25))
@unittest.skipIf(os.name == "nt", "Unix terminal sequence")
def test_arrow_sequence_is_read_as_one_key(self) -> None:
class Input:
def fileno(self) -> int:
return 7
terminal = Input()
with (
patch("tools.console.sys.stdin", terminal),
patch("tools.console.os.read", side_effect=[b"\x1b", b"[", b"A"]),
patch("tools.console.select.select", return_value=([7], [], [])),
):
self.assertEqual(read_key(), "up")
@unittest.skipIf(os.name == "nt", "Unix terminal input")
def test_raw_key_reader_keeps_unicode_characters(self) -> None:
terminal = type("Input", (), {"fileno": lambda self: 7})()
with (
patch("tools.console.sys.stdin", terminal),
patch("tools.console.os.read", side_effect=[b"\xc3", b"\xa4"]),
):
self.assertEqual(read_key(), "ä")
def test_output_directory_defaults_and_resolves_relative_paths(self) -> None:
with TemporaryDirectory() as temporary:
default = Path(temporary).resolve()
self.assertEqual(resolve_output_directory("", default), default)
self.assertEqual(resolve_output_directory("organized", default), default / "organized")
self.assertEqual(resolve_output_directory(default.as_uri(), Path.cwd()), default)
file_path = default / "photo.jpg"
file_path.touch()
with self.assertRaisesRegex(ValueError, "not a directory"):
resolve_output_directory(str(file_path), default)
def test_adjusted_filename_preserves_each_timestamp_interval(self) -> None:
stem = "20260516_130011-20260516_130102_fused"
result = filename_timestamp_stem(stem, datetime(2026, 6, 7, 14, 0, 0), "adjust_replace")
@@ -87,6 +193,93 @@ class PhotoMetadataLogicTests(unittest.TestCase):
infer_group_subseconds([records])
self.assertIsNone(records[1].inferred_subsec)
def test_infers_subseconds_for_a_single_second_burst(self) -> None:
records = [
MediaRecord(
Path(f"photo-{index}.jpg"),
{},
"image",
adjusted_time=datetime(2026, 6, 7, 14, 0, 0),
)
for index in range(3)
]
infer_group_subseconds([records])
self.assertEqual([record.inferred_subsec for record in records], [0, 333, 666])
def test_flat_organization_preserves_names_and_resolves_collisions(self) -> None:
with TemporaryDirectory() as temporary:
root = Path(temporary)
records = [
MediaRecord(
root / folder / "photo.jpg",
{},
"image",
adjusted_time=datetime(2026, 6, 7, 14, 0, 0),
)
for folder in ("one", "two")
]
choices = self.choices(
working_dir=root,
rename_mode="none",
organize_files=True,
group_files=False,
)
self.assertEqual(prepare_plan(records, choices, []), [])
self.assertEqual(
[record.target_path for record in records],
[root / "photo.jpg", root / "photo-1.jpg"],
)
self.assertTrue(all(record.inferred_subsec is None for record in records))
def test_confirm_selection_does_not_highlight_organization_controls(self) -> None:
state = SettingsState(
working_dir=Path("/photos"),
time_offset=None,
infer_missing_timestamps=True,
fixed_timezone=timezone.utc,
fixed_timezone_enabled=False,
fill_timezone_gaps=False,
organize_files=True,
group_files=True,
)
lines = settings_lines(
state,
TimezoneAnalysis([], 0, 0),
["organize", "confirm"],
1,
1,
)
organize_line = next(line for line in lines if line.startswith("Organize/group:"))
confirm_line = next(line for line in lines if "Confirm" in line and line.startswith(" "))
self.assertNotIn("\x1b[30;47m", organize_line)
self.assertIn("\x1b[30;47mExit", confirm_line)
def test_settings_can_disable_rename_and_select_flat_organization(self) -> None:
timestamp = datetime(2026, 6, 7, 14, 0, 0)
record = MediaRecord(
Path("photo.jpg"),
{},
"image",
original_time=timestamp,
adjusted_time=timestamp,
)
keys = iter(["down", "down", "down", "left", "down", "down", "space", "down", "enter"])
@contextmanager
def key_input():
yield lambda: next(keys)
with (
patch("tools.photo_settings.raw_key_input", key_input),
patch("tools.photo_settings.draw_screen"),
):
choices, _state = prompt_choices("exiftool", [record], Path("/photos"), False)
assert choices is not None
self.assertEqual(choices.rename_mode, "none")
self.assertTrue(choices.organize_files)
self.assertFalse(choices.group_files)
def test_burst_detection_stays_per_camera(self) -> None:
timestamp = datetime(2026, 6, 7, 14, 0, 0)
records = [