Skip to content

CLAUDE.md

Latest commit

 

History

History
86 lines (57 loc) · 2.96 KB

CLAUDE.md

File metadata and controls

86 lines (57 loc) · 2.96 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Workflow

Update this file, README.md, and/or ROADMAP.md in each session if they need to be to reflect new changes.

What This Is

Chronologanizer is a CLI tool that organizes photos into a YEAR/MONTH-MONTHNAME/ directory structure based on EXIF metadata. It reads JPEG images, extracts the capture date from EXIF tags, resizes to 600px max dimension, corrects orientation, and saves to the output directory.

Setup and Running

# Install (editable/dev mode)
pip install -e .

# Install with dev tools (ruff)
pip install -e ".[dev]"

# Or install normally
pip install .

# Run (after install)
chronologanizer --input=<input_dir> --output=<output_dir>

# Or run as a module
python -m chronologanizer --input=<input_dir> --output=<output_dir>

# Verbose / quiet modes
chronologanizer -v --input=<dir> --output=<dir>   # debug logging
chronologanizer -q --input=<dir> --output=<dir>   # warnings/errors only

Testing

make test      # runs pytest

26 tests across 3 files:

  • tests/test_photo.py — Unit tests for Photo class (is_jpeg, get_date_taken, orientation, resize)
  • tests/test_integration.py — End-to-end process_and_copy pipeline tests
  • tests/test_cli.py — CLI argument parsing and error handling tests

Tests use Pillow-generated images and mock exifread.process_file — no real EXIF files needed.

CI runs on push/PR via GitHub Actions (Python 3.9–3.13).

Linting and Formatting

make lint      # ruff check src/
make format    # ruff format + ruff check --fix

Ruff is configured in pyproject.toml with rules: E, F, W, I, UP, B, SIM. Line length is 120.

Architecture

Package layout under src/chronologanizer/:

  • cli.py — Entry point. Parses --input/--output/-v/-q args, configures logging, walks the input directory recursively, creates a Photo object per file, calls process_and_copy().
  • photo.py — Photo class that wraps a single image file. Handles EXIF reading (via exifread), date extraction, orientation correction, resizing, and saving (via Pillow). Uses pathlib.Path for file paths and logging for output.
  • __main__.py — Allows running as python -m chronologanizer.

The processing pipeline per file is: is_jpeg() → get_date_taken() → resize() → correct_orientation() → save().

Conventions

  • PEP 8 snake_case naming throughout (methods, variables, file names)
  • Type hints on all function signatures
  • pathlib.Path for file/directory paths
  • logging module instead of print() for all output
  • f-strings for string formatting
  • Enforced by ruff linter

Dependencies

Defined in pyproject.toml. Requires Python >= 3.9.

  • exifread==3.0.0 — EXIF metadata extraction
  • Pillow>=10.0.0 — Image manipulation
  • ruff>=0.4.0 — Linter/formatter (optional dev dependency)
  • pytest>=7.0.0 — Test framework (optional dev dependency)