photo-tools-cli 0.1.0__tar.gz

photo_tools_cli-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: photo-tools-cli
+Version: 0.1.0
+Summary: Python CLI tools for photography workflows
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: typer<1.0,>=0.24
+Requires-Dist: pillow<13.0,>=12.1
+Requires-Dist: python-dotenv<2.0,>=1.2
+
+[![CI](https://github.com/aga87/python-photo-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/aga87/python-photo-tools/actions)
+
+# Python Photo Tools
+
+Command-line tools for organising photos by date, managing RAW/JPG pairs, and optimising images.
+
+## Supported formats
+
+- RAW: .raf
+- JPG: .jpg, .jpeg
+
+## Prerequisites - System Tools
+
+This project depends on external system tools in addition to Python.
+
+### ExifTool
+
+Used for extracting image metadata (including RAW formats).
+- Supports all major image formats, including RAW
+- Provides consistent metadata fields across formats
+- More reliable than Python-only EXIF libraries
+
+If `exiftool` is not installed, the CLI will fail with a clear error message and exit code `1`.
+
+Install (macOS)
+
+```shell
+brew install exiftool
+```
+
+On Linux, install via your package manager (e.g. `apt install exiftool`).
+
+## Installation
+
+### Using pipx (recommended)
+
+```shell
+pipx install git+https://github.com/aga87/python-photo-tools.git
+```
+
+### Local development
+
+Clone the repository and install:
+
+```shell
+pip install -e .
+pip install --group dev -e .
+```
+
+## Usage
+
+List available commands:
+
+```bash
+photo-tools --help
+```
+Each command provides detailed usage, including arguments and options:
+
+```shell
+photo-tools <command> --help
+```
+
+**Note: All commands currently process files in the top-level input directory only.**
+
+### Global flags
+
+All commands support:
+
+- `--dry-run` — preview changes without modifying files
+- `--verbose` / `-v` — show per-file output
+
+Flags can be combined:
+
+```shell
+photo-tools <command> ... --dry-run --verbose
+```
+
+### `by-date`
+
+- Organise images into date-based folders (`YYYY-MM-DD`, optional suffix)
+- Files are moved (not copied) into the output directory
+- If a destination file already exists, it is skipped (no overwrite)
+
+```shell
+photo-tools by-date <INPUT_DIR> <OUTPUT_DIR>
+```
+```shell
+photo-tools by-date <INPUT_DIR> <OUTPUT_DIR> --suffix <SUFFIX>
+```
+
+
+### `raws`
+
+- Move RAW images into a `raws/` subfolder within the input directory
+- Non-RAW files are left unchanged
+- Files are moved (not copied) in place
+- If a destination file already exists, it is skipped (no overwrite)
+
+```shell
+photo-tools raws <INPUT_DIR>
+```
+
+### `clean-raws`
+
+- Move RAW files to `raws-to-delete/` if no matching JPG (same prefix) exists
+- Matching is based on filename prefix (e.g. `abcd.RAF` matches `abcd_edit.jpg`)
+- Files are moved (not deleted), making the operation reversible
+
+```shell
+photo-tools clean-raws <RAW_DIR> <JPG_DIR>
+```
+
+### `optimise`
+
+- Resize images to a maximum width of `2500px`
+- Choose the highest quality that results in a file size ≤ `500 KB` (never below `70%`)
+- Saves optimised images with prefix `lq_` in the same directory (overwrites existing files)
+
+
+```shell
+photo-tools optimise <INPUT_DIR>
+```
+
+
+## Local Development Setup
+
+### Data 
+
+For convenience during development, you can create a local structure:
+
+```bash
+mkdir -p data/input data/output
+```
+
+Place test photos in:
+
+```
+data/input/
+```
+
+### Running the CLI
+
+You can run the CLI module directly for testing:
+
+```shell
+python -m photo_tools.cli by-date ./data/input ./data/output
+```
+
+### Running tests
+
+This project uses `pytest`:
+
+```bash
+pytest
+```
+
+### Makefile
+
+Common development tasks are available via the Makefile.

photo_tools_cli-0.1.0/README.md

@@ -0,0 +1,159 @@
+[![CI](https://github.com/aga87/python-photo-tools/actions/workflows/ci.yml/badge.svg)](https://github.com/aga87/python-photo-tools/actions)
+
+# Python Photo Tools
+
+Command-line tools for organising photos by date, managing RAW/JPG pairs, and optimising images.
+
+## Supported formats
+
+- RAW: .raf
+- JPG: .jpg, .jpeg
+
+## Prerequisites - System Tools
+
+This project depends on external system tools in addition to Python.
+
+### ExifTool
+
+Used for extracting image metadata (including RAW formats).
+- Supports all major image formats, including RAW
+- Provides consistent metadata fields across formats
+- More reliable than Python-only EXIF libraries
+
+If `exiftool` is not installed, the CLI will fail with a clear error message and exit code `1`.
+
+Install (macOS)
+
+```shell
+brew install exiftool
+```
+
+On Linux, install via your package manager (e.g. `apt install exiftool`).
+
+## Installation
+
+### Using pipx (recommended)
+
+```shell
+pipx install git+https://github.com/aga87/python-photo-tools.git
+```
+
+### Local development
+
+Clone the repository and install:
+
+```shell
+pip install -e .
+pip install --group dev -e .
+```
+
+## Usage
+
+List available commands:
+
+```bash
+photo-tools --help
+```
+Each command provides detailed usage, including arguments and options:
+
+```shell
+photo-tools <command> --help
+```
+
+**Note: All commands currently process files in the top-level input directory only.**
+
+### Global flags
+
+All commands support:
+
+- `--dry-run` — preview changes without modifying files
+- `--verbose` / `-v` — show per-file output
+
+Flags can be combined:
+
+```shell
+photo-tools <command> ... --dry-run --verbose
+```
+
+### `by-date`
+
+- Organise images into date-based folders (`YYYY-MM-DD`, optional suffix)
+- Files are moved (not copied) into the output directory
+- If a destination file already exists, it is skipped (no overwrite)
+
+```shell
+photo-tools by-date <INPUT_DIR> <OUTPUT_DIR>
+```
+```shell
+photo-tools by-date <INPUT_DIR> <OUTPUT_DIR> --suffix <SUFFIX>
+```
+
+
+### `raws`
+
+- Move RAW images into a `raws/` subfolder within the input directory
+- Non-RAW files are left unchanged
+- Files are moved (not copied) in place
+- If a destination file already exists, it is skipped (no overwrite)
+
+```shell
+photo-tools raws <INPUT_DIR>
+```
+
+### `clean-raws`
+
+- Move RAW files to `raws-to-delete/` if no matching JPG (same prefix) exists
+- Matching is based on filename prefix (e.g. `abcd.RAF` matches `abcd_edit.jpg`)
+- Files are moved (not deleted), making the operation reversible
+
+```shell
+photo-tools clean-raws <RAW_DIR> <JPG_DIR>
+```
+
+### `optimise`
+
+- Resize images to a maximum width of `2500px`
+- Choose the highest quality that results in a file size ≤ `500 KB` (never below `70%`)
+- Saves optimised images with prefix `lq_` in the same directory (overwrites existing files)
+
+
+```shell
+photo-tools optimise <INPUT_DIR>
+```
+
+
+## Local Development Setup
+
+### Data 
+
+For convenience during development, you can create a local structure:
+
+```bash
+mkdir -p data/input data/output
+```
+
+Place test photos in:
+
+```
+data/input/
+```
+
+### Running the CLI
+
+You can run the CLI module directly for testing:
+
+```shell
+python -m photo_tools.cli by-date ./data/input ./data/output
+```
+
+### Running tests
+
+This project uses `pytest`:
+
+```bash
+pytest
+```
+
+### Makefile
+
+Common development tasks are available via the Makefile.

photo_tools_cli-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "photo-tools-cli"
+version = "0.1.0"
+description = "Python CLI tools for photography workflows"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "typer>=0.24,<1.0",
+    "pillow>=12.1,<13.0",
+    "python-dotenv>=1.2,<2.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9,<10",
+    "ruff>=0.15,<1.0",
+    "mypy>=1.19,<2.0",
+    "build>=1.4,<2.0",
+    "twine>=6.2,<7.0",
+]
+
+[project.scripts]
+photo-tools = "photo_tools.cli:app"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+mypy_path = "src"
+explicit_package_bases = true

photo_tools_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

photo_tools_cli-0.1.0/src/photo_tools/cli.py

@@ -0,0 +1,164 @@
+import typer
+from dotenv import load_dotenv
+
+from photo_tools.cli_support.cli_errors import handle_cli_errors
+from photo_tools.cli_support.cli_reporter import make_reporter
+from photo_tools.commands.clean_unpaired_raws import clean_unpaired_raws
+from photo_tools.commands.optimise import optimise
+from photo_tools.commands.organise_by_date import organise_by_date
+from photo_tools.commands.separate_raws import separate_raws
+from photo_tools.core.dependencies import validate_feature
+from photo_tools.exceptions import MissingDependencyError
+from photo_tools.logging_config import setup_logging
+
+app = typer.Typer(help="CLI tools for organising and optimising photography workflows.")
+
+
+load_dotenv()
+setup_logging()
+
+
+@app.callback()
+def main() -> None:
+    try:
+        # validate dependencies needed globally (if any)
+        validate_feature("exif")
+    except MissingDependencyError as e:
+        typer.secho(f"Error: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command("by-date")
+@handle_cli_errors
+def organise_by_date_cmd(
+    input_dir: str = typer.Argument(
+        ...,
+        help="Directory containing input images.",
+    ),
+    output_dir: str = typer.Argument(
+        ...,
+        help="Directory where organised images will be saved.",
+    ),
+    suffix: str | None = typer.Option(
+        None,
+        "--suffix",
+        help="Optional suffix appended to folder names (e.g. location).",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview changes without moving files.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show per-file output.",
+    ),
+) -> None:
+    """Organise images into folders based on capture date."""
+    organise_by_date(
+        input_dir=input_dir,
+        output_dir=output_dir,
+        report=make_reporter(verbose),
+        suffix=suffix,
+        dry_run=dry_run,
+    )
+
+
+@app.command(
+    "raws",
+    help="Move RAW images into a 'raws' folder",
+)
+@handle_cli_errors
+def separate_raws_cmd(
+    input_dir: str = typer.Argument(
+        ...,
+        help="Directory containing images from which RAW files should be separated.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview changes without moving files.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show per-file output.",
+    ),
+) -> None:
+    """Move RAW images into a 'raws' folder."""
+    separate_raws(
+        input_dir=input_dir,
+        report=make_reporter(verbose),
+        dry_run=dry_run,
+    )
+
+
+@app.command(
+    "clean-raws",
+    help="Move RAW files without matching JPGs to 'raws-to-delete'.",
+)
+@handle_cli_errors
+def clean_unpaired_raws_cmd(
+    raw_dir: str = typer.Argument(
+        ...,
+        help="Directory containing RAW files.",
+    ),
+    jpg_dir: str = typer.Argument(
+        ...,
+        help="Directory containing JPG files used for matching.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Preview changes without moving files.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show per-file output.",
+    ),
+) -> None:
+    clean_unpaired_raws(
+        raw_dir=raw_dir,
+        jpg_dir=jpg_dir,
+        report=make_reporter(verbose),
+        dry_run=dry_run,
+    )
+
+
+@app.command(
+    "optimise",
+    help="Resize JPG images to max 2500px width and compress to ≤500KB using quality "
+    "70-100, saving as prefixed copies.",
+)
+@handle_cli_errors
+def optimise_cmd(
+    input_dir: str = typer.Argument(
+        ...,
+        help="Directory containing JPG images to optimise.",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show resulting size and quality without writing files.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show per-file output.",
+    ),
+) -> None:
+    optimise(
+        input_dir=input_dir,
+        report=make_reporter(verbose),
+        dry_run=dry_run,
+    )
+
+
+if __name__ == "__main__":
+    app()

photo_tools_cli-0.1.0/src/photo_tools/cli_support/cli_errors.py

@@ -0,0 +1,22 @@
+import functools
+from typing import Callable, ParamSpec, TypeVar
+
+import typer
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+# Decorator to handle common CLI errors and present clean messages to the user.
+# Keeps core logic free of CLI concerns
+def handle_cli_errors(func: Callable[P, R]) -> Callable[P, R]:
+    # Preserve original function metadata so Typer can correctly parse arguments
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return func(*args, **kwargs)
+        except (FileNotFoundError, NotADirectoryError) as e:
+            typer.echo(f"Error: {e}")
+            raise typer.Exit(code=1)
+
+    return wrapper

photo_tools_cli-0.1.0/src/photo_tools/cli_support/cli_reporter.py

@@ -0,0 +1,17 @@
+from collections.abc import Callable
+
+import typer
+
+Reporter = Callable[[str, str], None]
+
+
+def make_reporter(verbose: bool) -> Reporter:
+    def report(level: str, message: str) -> None:
+        if level == "warning":
+            typer.secho(message, fg=typer.colors.YELLOW, err=True)
+        elif level == "summary":
+            typer.echo(message)
+        elif level == "info" and verbose:
+            typer.echo(message)
+
+    return report

photo_tools_cli-0.1.0/src/photo_tools/commands/clean_unpaired_raws.py

@@ -0,0 +1,89 @@
+import logging
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from photo_tools.core.validation import validate_input_dir
+
+logger = logging.getLogger(__name__)
+
+RAW_EXTENSIONS = {".raf"}
+JPG_EXTENSIONS = {".jpg", ".jpeg"}
+
+Reporter = Callable[[str, str], None]
+
+
+def clean_unpaired_raws(
+    raw_dir: str,
+    jpg_dir: str,
+    report: Reporter,
+    dry_run: bool = False,
+) -> None:
+    raw_path = Path(raw_dir)
+    jpg_path = Path(jpg_dir)
+    trash_dir = raw_path / "raws-to-delete"
+
+    validate_input_dir(raw_path)
+    validate_input_dir(jpg_path)
+
+    moved_count = 0
+    dry_run_count = 0
+    skipped_existing_count = 0
+
+    jpg_files = [
+        f
+        for f in jpg_path.iterdir()
+        if f.is_file() and f.suffix.lower() in JPG_EXTENSIONS
+    ]
+
+    for raw_file in raw_path.iterdir():
+        if not raw_file.is_file():
+            continue
+
+        if raw_file.suffix.lower() not in RAW_EXTENSIONS:
+            continue
+
+        raw_stem = raw_file.stem.lower()
+        has_match = any(jpg.name.lower().startswith(raw_stem) for jpg in jpg_files)
+
+        if has_match:
+            logger.debug("Keeping %s (matched JPG)", raw_file.name)
+            continue
+
+        target_file = trash_dir / raw_file.name
+
+        if target_file.exists():
+            skipped_existing_count += 1
+            report(
+                "warning",
+                f"Skipping {raw_file.name}: already in raws-to-delete",
+            )
+            continue
+
+        if dry_run:
+            dry_run_count += 1
+            report(
+                "info",
+                f"[DRY RUN] Would move {raw_file.name} -> {trash_dir}",
+            )
+            continue
+
+        trash_dir.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(raw_file), str(target_file))
+        moved_count += 1
+
+        report("info", f"Moved {raw_file.name} -> {trash_dir}")
+
+    # Summary
+
+    if dry_run:
+        report("summary", f"Dry run complete: would move {dry_run_count} file(s)")
+    else:
+        report("summary", f"Moved {moved_count} file(s)")
+
+    if skipped_existing_count:
+        report(
+            "warning",
+            f"Skipped {skipped_existing_count} file(s): "
+            "already exist in raws-to-delete",
+        )