mimedy 1.0.0__py3-none-any.whl

mimedy/config.example.yaml

@@ -0,0 +1,69 @@
+# mimedy — example configuration
+#
+# Copy this file to config.yaml and adapt it to your needs:
+#   cp config.example.yaml config.yaml
+#
+# Every key is optional: missing keys fall back to the built-in defaults.
+#
+# Rules are applied in this order (first match wins):
+#   1. hidden       -> files whose name starts with '.'
+#   2. large_files  -> files bigger than threshold_mb
+#   3. extensions   -> exact extension match (cheap, no content analysis)
+#   4. mimetypes    -> MIME type detected by Magika from the file content
+#   5. fallback     -> Magika content group (Image, Video, Code, Document, ...)
+
+# Destination folder for hidden files (.env, .bashrc, ...)
+hidden: "Hidden"
+
+# Large files are moved aside before any content analysis.
+# Sizes are in decimal MB (1 MB = 1000 * 1000 bytes), like Finder/Explorer.
+large_files:
+  threshold_mb: 500
+  target_dir: "Large"
+
+# Extension rules: use them for formats Magika cannot know about,
+# or when the extension carries more meaning than the content
+# (a .blend is "Blender", not just "unknown binary").
+extensions:
+  # Creative tools
+  .blend: "Blender"
+  .psd: "Photoshop"
+  .kra: "Krita"
+  .gd: "Godot"
+  .tscn: "Godot"
+  # Data files (Magika would otherwise group them under "code" or "text")
+  .csv: "Data"
+  .json: "Data"
+  .yaml: "Data"
+  .yml: "Data"
+  .toml: "Data"
+  # Disk images and installers
+  .dmg: "Installers"
+  .pkg: "Installers"
+  .msi: "Installers"
+  .iso: "Disk Images"
+
+# MIME type rules: matched against Magika's detection, so they work
+# even when the extension is wrong or missing.
+mimetypes:
+  # Documents
+  application/pdf: "PDF"
+  application/epub+zip: "Books"
+  application/msword: "Documents"
+  application/vnd.openxmlformats-officedocument.wordprocessingml.document: "Documents"
+  application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: "Spreadsheets"
+  application/vnd.openxmlformats-officedocument.presentationml.presentation: "Presentations"
+  # Images
+  image/jpeg: "Photos"
+  image/heic: "Photos"
+  image/png: "Images"
+  image/svg+xml: "Vector"
+  # Archives
+  application/zip: "Archives"
+  application/x-tar: "Archives"
+  application/gzip: "Archives"
+  application/x-7z-compressed: "Archives"
+  # Code
+  text/x-python: "Python"
+  text/x-c: "C"
+  text/x-c++: "C++"

mimedy/config.py

@@ -0,0 +1,308 @@
+"""Configuration loading and validation.
+
+Dataclasses do not check types at runtime: building a Config directly from
+unchecked data would accept anything. Always go through load_config(), which
+validates every value before building the dataclasses.
+"""
+
+import logging
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field, fields
+from difflib import get_close_matches
+from pathlib import Path, PurePath
+
+import yaml
+
+from mimedy.errors import ConfigError
+
+logger = logging.getLogger("mimedy.config")
+
+
+@dataclass(frozen=True, kw_only=True)
+class LargeFilesConfig:
+    """Where files bigger than threshold_mb (decimal MB) are moved."""
+
+    threshold_mb: float = 100
+    target_dir: str = "Large"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Config:
+    """The validated configuration, as returned by load_config().
+
+    The rest of the program can rely on these guarantees:
+
+    - every destination folder is a non-empty relative path that stays
+      inside the organized folder, normalized ("Code/Python", never
+      "./Code//Python/", "/tmp" or "../Data")
+    - extension keys are lowercase and start with a dot (".jpg"), so
+      they must be compared with file.suffix.lower()
+    - MIME type keys are lowercase ("application/pdf")
+    - no two rules conflict once normalized
+    """
+
+    hidden: str = "Hidden"
+    large_files: LargeFilesConfig = field(default_factory=LargeFilesConfig)
+    extensions: dict[str, str] = field(default_factory=dict)
+    mimetypes: dict[str, str] = field(default_factory=dict)
+
+
+def default_config_path() -> Path:
+    """Return the per-user config file: XDG on Linux and macOS, APPDATA on Windows."""
+    if sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA", Path.home() / "AppData" / "Roaming"))
+    else:
+        xdg = os.environ.get("XDG_CONFIG_HOME", "")
+        # The XDG spec says to ignore an empty or relative value
+        base = Path(xdg) if xdg and Path(xdg).is_absolute() else Path.home() / ".config"
+    return base / "mimedy" / "config.yaml"
+
+
+def check_unknown_keys(data: dict, config_class: type, errors: list[str]) -> None:
+    """Add an error for each key of data that is not a field of config_class.
+
+    A likely typo gets a suggestion: "did you mean 'extensions'?".
+    """
+    authorized_keys = {f.name for f in fields(config_class)}
+    unknown_keys = data.keys() - authorized_keys
+    for key in sorted(unknown_keys):
+        close_match = get_close_matches(key, authorized_keys, n=1)
+        err_msg = f"Unknown key '{key}'"
+        if close_match:
+            err_msg += f" (did you mean '{close_match[0]}'?)"
+        errors.append(err_msg)
+
+
+def read_dir(value: object, key: str, errors: list[str]) -> str | None:
+    """Read a destination folder, relative to the organized folder.
+
+    It must be a non-empty relative path that stays inside the organized
+    folder. Surrounding spaces are stripped and the path is normalized
+    ("./Code//Python/" becomes "Code/Python").
+    """
+    if not isinstance(value, str):
+        errors.append(f"'{key}' must be a string, got {type(value).__name__}")
+        return None
+
+    # PurePath only parses the text: destinations usually don't exist yet,
+    # and validating the config must not depend on the disk
+    path = PurePath(value.strip())
+
+    # "" and "." both have no parts: they would mean the organized folder itself
+    if not path.parts:
+        errors.append(f"'{key}' must not be empty")
+        return None
+
+    # Path("/organized") / "/tmp" gives "/tmp", and ".." climbs out of it:
+    # a destination must never lead outside the organized folder
+    if path.is_absolute():
+        errors.append(f"'{key}' must be a relative folder name, got '{path}'")
+        return None
+    if ".." in path.parts:
+        errors.append(f"'{key}' must stay inside the organized folder, got '{path}'")
+        return None
+
+    # Only the shell expands "~" (and "~user") at the start of a path: here it
+    # would create a folder literally named "~", not use the home directory
+    if path.parts[0].startswith("~"):
+        errors.append(
+            f"'{key}' must stay inside the organized folder "
+            f"('~' is not expanded), got '{path}'"
+        )
+        return None
+    return str(path)
+
+
+def read_threshold(value: object, key: str, errors: list[str]) -> float | None:
+    """Read a strictly positive number, booleans excluded."""
+    # YAML reads "yes" as True, and True is an int in Python: reject it first
+    if isinstance(value, bool):
+        errors.append(f"'{key}' must be a number, got bool")
+        return None
+
+    if not isinstance(value, (int, float)):
+        errors.append(f"'{key}' must be a positive number, got {type(value).__name__}")
+        return None
+
+    threshold = float(value)
+    if threshold <= 0:
+        errors.append(f"'{key}' must be a positive number")
+        return None
+    return threshold
+
+
+def add_section_errors(
+    section: str, section_errors: list[str], errors: list[str]
+) -> None:
+    """Add the errors of a config section, grouped under its name."""
+    details = "\n".join(f"    - {error}" for error in section_errors)
+    errors.append(f"In '{section}':\n{details}")
+
+
+def normalize_extension(extension: str) -> str:
+    """Normalize an extension: '.JPG' -> '.jpg', 'csv' -> '.csv'.
+
+    Raise ValueError for an empty extension ("" or ".").
+    """
+    name = extension.lower().removeprefix(".")
+    if not name:
+        msg = "is not a valid extension"
+        raise ValueError(msg)
+    return f".{name}"
+
+
+def read_mapping(
+    value: object, key: str, errors: list[str], normalize: Callable[[str], str]
+) -> dict[str, str] | None:
+    """Read a mapping of rules to destination folders (extensions, mimetypes).
+
+    Keys go through normalize. Two keys that become the same rule are
+    accepted when they point to the same folder, and reported otherwise.
+    """
+    if not isinstance(value, dict):
+        errors.append(f"'{key}' must be a mapping, got {type(value).__name__}")
+        return None
+
+    # Errors are grouped under the mapping's name, e.g. "In 'extensions':"
+    mapping_errors: list[str] = []
+    mapping: dict[str, str] = {}
+    # Normalized rule -> rule as written, to name both sides of a conflict
+    origins: dict[str, str] = {}
+    for rule, dest in value.items():
+        if not isinstance(rule, str):
+            mapping_errors.append(
+                f"{rule!r} must be a string, got {type(rule).__name__}"
+            )
+            continue
+
+        try:
+            normalized_rule = normalize(rule)
+        except ValueError as e:
+            mapping_errors.append(f"'{rule}' {e}")
+            continue
+
+        checked_dest = read_dir(dest, rule, mapping_errors)
+        if checked_dest is None:
+            continue
+
+        if normalized_rule not in mapping:
+            mapping[normalized_rule] = checked_dest
+            origins[normalized_rule] = rule
+        elif mapping[normalized_rule] != checked_dest:
+            mapping_errors.append(
+                f"'{origins[normalized_rule]}' and '{rule}' "
+                "are the same rule but go to different folders"
+            )
+            continue
+
+    if mapping_errors:
+        add_section_errors(key, mapping_errors, errors)
+        return None
+    return mapping
+
+
+def read_large_files(value: object, errors: list[str]) -> LargeFilesConfig | None:
+    """Read the large_files section: threshold_mb and target_dir."""
+    if not isinstance(value, dict):
+        errors.append(f"'large_files' must be a mapping, got {type(value).__name__}")
+        return None
+
+    # Errors are grouped under "In 'large_files':", unknown keys included
+    large_files_errors: list[str] = []
+    check_unknown_keys(value, LargeFilesConfig, large_files_errors)
+
+    kwargs = {}
+    if "threshold_mb" in value:
+        threshold_mb = read_threshold(
+            value["threshold_mb"], "threshold_mb", large_files_errors
+        )
+        if threshold_mb is not None:
+            kwargs["threshold_mb"] = threshold_mb
+    if "target_dir" in value:
+        target_dir = read_dir(value["target_dir"], "target_dir", large_files_errors)
+        if target_dir is not None:
+            kwargs["target_dir"] = target_dir
+
+    if large_files_errors:
+        add_section_errors("large_files", large_files_errors, errors)
+        return None
+
+    return LargeFilesConfig(**kwargs)
+
+
+def read_yaml(config_path: Path) -> dict:
+    """Read a YAML config file as a mapping of settings.
+
+    Raise ConfigError if the file is missing, unreadable, not valid YAML, or
+    not a mapping.
+    """
+    try:
+        with config_path.open() as f:
+            data = yaml.safe_load(f) or {}
+    except FileNotFoundError as e:
+        msg = f"Config file not found: {config_path}"
+        raise ConfigError(msg) from e
+    except OSError as e:
+        msg = f"Cannot read {config_path}: {e.strerror}"
+        raise ConfigError(msg) from e
+    except yaml.YAMLError as e:
+        msg = f"Invalid YAML in {config_path}: {e}"
+        raise ConfigError(msg) from e
+
+    if not isinstance(data, dict):
+        msg = f"Invalid config in {config_path}: expected a mapping of settings"
+        raise ConfigError(msg)
+    return data
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    """Load and validate the configuration.
+
+    config_path is the file given with --config: it must exist. Without it,
+    the per-user file from default_config_path() is used when it exists, and
+    the default configuration otherwise.
+
+    Raise ConfigError listing every problem found in an invalid file.
+    """
+    if config_path is None:
+        config_path = default_config_path()
+        if not config_path.exists():
+            logger.debug("No config file at %s, using defaults", config_path)
+            return Config()
+
+    config_to_load = read_yaml(config_path)
+
+    # Collect every error before reporting, so they can all be fixed at once
+    errors: list[str] = []
+    check_unknown_keys(config_to_load, Config, errors)
+
+    config_kwargs = {}
+    if "hidden" in config_to_load:
+        hidden = read_dir(config_to_load["hidden"], "hidden", errors)
+        if hidden is not None:
+            config_kwargs["hidden"] = hidden
+    if "extensions" in config_to_load:
+        extensions = read_mapping(
+            config_to_load["extensions"], "extensions", errors, normalize_extension
+        )
+        if extensions is not None:
+            config_kwargs["extensions"] = extensions
+    if "mimetypes" in config_to_load:
+        mimetypes = read_mapping(
+            config_to_load["mimetypes"], "mimetypes", errors, str.lower
+        )
+        if mimetypes is not None:
+            config_kwargs["mimetypes"] = mimetypes
+
+    large_files_config = config_to_load.get("large_files", {})
+    large_files = read_large_files(large_files_config, errors)
+
+    if errors:
+        details = "\n".join(f"  - {error}" for error in errors)
+        msg = f"Invalid config in {config_path}:\n{details}"
+        raise ConfigError(msg)
+
+    logger.info("Loaded config from %s", config_path)
+    return Config(**config_kwargs, large_files=large_files)

mimedy/errors.py

@@ -0,0 +1,13 @@
+"""Exceptions raised by mimedy."""
+
+
+class MimedyError(Exception):
+    """Base class for all mimedy errors."""
+
+
+class ConfigError(MimedyError):
+    """The configuration file cannot be loaded."""
+
+
+class ClassificationError(MimedyError):
+    """A file cannot be classified."""

mimedy/main.py

@@ -0,0 +1,172 @@
+"""Command-line interface of mimedy."""
+
+import logging
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from magika import Magika
+
+from mimedy.config import default_config_path, load_config
+from mimedy.errors import ConfigError
+from mimedy.organizer import execute, log_plan, plan_moves
+
+# Exit codes
+EXIT_OK = 0
+EXIT_FAILURES = 1  # the run completed, but at least one file failed
+# Invalid arguments or configuration exit with 2, handled by Typer
+
+logger = logging.getLogger("mimedy.main")
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+def init_logging(*, verbose: bool = False) -> None:
+    """Configure log output: short messages, or detailed ones with --verbose."""
+    if verbose:
+        log_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+    else:
+        log_format = "[%(levelname)s] %(message)s"
+    logging.basicConfig(format=log_format)
+
+    # Only our own loggers go down to DEBUG, not third-party libraries
+    logging.getLogger("mimedy").setLevel(logging.DEBUG if verbose else logging.INFO)
+
+
+def show_version(value: bool) -> None:
+    """Print the version and exit, before any other argument is checked."""
+    if value:
+        typer.echo(f"mimedy {version('mimedy')}")
+        raise typer.Exit(EXIT_OK)
+
+
+def init_config(value: bool) -> None:
+    """Copy the example config to the default location, then exit.
+
+    An existing config is never overwritten.
+    """
+    if not value:
+        return
+
+    target_config_path = default_config_path()
+
+    if target_config_path.exists():
+        typer.echo(f"Config file already exists: {target_config_path}", err=True)
+        raise typer.Exit(EXIT_FAILURES)
+
+    # Create the folder that holds the file (~/.config/mimedy), not the file itself
+    target_config_path.parent.mkdir(parents=True, exist_ok=True)
+    target_config_path.write_text((files("mimedy") / "config.example.yaml").read_text())
+
+    typer.echo(f"Created config file: {target_config_path}")
+    raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def main(  # noqa: PLR0913, PLR0917 (one parameter per CLI option)
+    directory: Annotated[
+        Path,
+        typer.Argument(
+            help="Folder to organize.",
+            exists=True,
+            file_okay=False,
+            readable=True,
+            resolve_path=True,
+        ),
+    ],
+    config_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help=f"YAML configuration file (default: {default_config_path()}).",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", "-n", help="Show planned moves without moving.")
+    ] = False,
+    yes: Annotated[
+        bool, typer.Option("--yes", "-y", help="Move without asking for confirmation.")
+    ] = False,
+    lowercase: Annotated[
+        bool,
+        typer.Option("--lowercase", "-l", help="Keep Magika folder names lowercase."),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Show the rule applied to each file."),
+    ] = False,
+    show_version_flag: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=show_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+    init_config_flag: Annotated[
+        bool,
+        typer.Option(
+            "--init-config",
+            callback=init_config,
+            is_eager=True,
+            help="Create a commented example config at the default location.",
+        ),
+    ] = False,
+) -> None:
+    """Organize a folder by real file type, detected from content with Magika."""
+    init_logging(verbose=verbose)
+
+    try:
+        config = load_config(config_path)
+    except ConfigError as e:
+        # Reported by Typer as a usage error, with exit code 2
+        raise typer.BadParameter(str(e), param_hint="--config") from e
+
+    # Loading the Magika model is slow: do it once for all files
+    magika = Magika()
+
+    # Phase 1: decide where every file goes, without touching anything
+    logger.info("Organizing %s", directory)
+    plan = plan_moves(directory, magika, config, lowercase=lowercase)
+    log_plan(plan)
+    planning_code = EXIT_FAILURES if plan.failures else EXIT_OK
+
+    if not plan.moves:
+        logger.info("Nothing to move")
+        raise typer.Exit(planning_code)
+
+    logger.info(
+        "%d files to move into %d folders, %d skipped",
+        len(plan.moves),
+        len(plan.folders),
+        len(plan.failures),
+    )
+
+    if dry_run:
+        logger.info("Dry run: nothing was moved")
+        raise typer.Exit(planning_code)
+
+    if not yes:
+        typer.confirm(f"Move {len(plan.moves)} files?", abort=True)
+
+    # Phase 2: perform the plan
+    failures = execute(plan)
+    logger.info(
+        "Done: %d moved, %d failed", len(plan.moves) - len(failures), len(failures)
+    )
+
+    if failures or plan.failures:
+        raise typer.Exit(EXIT_FAILURES)
+
+
+if __name__ == "__main__":
+    app()

mimedy/organizer.py

@@ -0,0 +1,202 @@
+"""Plan where each file goes, then move the files."""
+
+import errno
+import logging
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from magika import Magika
+
+from mimedy.config import Config
+from mimedy.errors import ClassificationError
+
+logger = logging.getLogger("mimedy.organizer")
+
+
+@dataclass(frozen=True)
+class Move:
+    """A planned move of one file."""
+
+    source: Path
+    target: Path
+    rule: str
+
+
+@dataclass(frozen=True)
+class Failure:
+    """A file that could not be planned or moved."""
+
+    source: Path
+    reason: str
+
+
+@dataclass
+class Plan:
+    """Every move to perform, computed without touching the disk."""
+
+    directory: Path
+    moves: list[Move] = field(default_factory=list)
+    failures: list[Failure] = field(default_factory=list)
+
+    @property
+    def folders(self) -> set[Path]:
+        """Return the destination folders used by the plan."""
+        return {move.target.parent for move in self.moves}
+
+
+def is_hidden(path: Path) -> bool:
+    """Return whether the file is hidden (its name starts with '.')."""
+    return path.name.startswith(".")
+
+
+def is_large(path: Path, threshold_mb: float) -> bool:
+    """Return whether the file size reaches threshold_mb."""
+    # Decimal MB (1000, not 1024), like Finder and Explorer display sizes
+    filesize_mb = path.stat().st_size / 1000 / 1000
+
+    return filesize_mb >= threshold_mb
+
+
+def get_file_mimetype_and_group(m: Magika, file: Path) -> tuple[str, str]:
+    """Return the MIME type and content group detected by Magika."""
+    # The magic happens here !
+    res = m.identify_path(file)
+
+    # Magika reports read errors in the result instead of raising
+    if not res.ok:
+        msg = f"Magika could not read the file ({res.status})"
+        raise ClassificationError(msg)
+
+    return (res.output.mime_type, res.output.group)
+
+
+def determine_target_directory(
+    file: Path, magika: Magika, config: Config, *, lowercase: bool
+) -> tuple[str, str]:
+    """Return the target directory and the rule that selected it."""
+    extension = file.suffix.lower()
+
+    if is_hidden(file):
+        return config.hidden, "hidden file"
+    threshold_mb = config.large_files.threshold_mb
+    if is_large(file, threshold_mb):
+        return config.large_files.target_dir, f"larger than {threshold_mb} MB"
+    if extension in config.extensions:
+        return config.extensions[extension], f"extension {extension}"
+
+    mimetype, group = get_file_mimetype_and_group(magika, file)
+    if mimetype in config.mimetypes:
+        return config.mimetypes[mimetype], f"mimetype {mimetype}"
+
+    target_dir = group if lowercase else group.capitalize()
+    return target_dir, f"magika group {group} ({mimetype})"
+
+
+def unique_path(path: Path, reserved: set[Path]) -> Path:
+    """Return a free target: "photo.jpg", then "photo (1).jpg", "photo (2).jpg"...
+
+    A target is taken if it exists on disk or was already given to another
+    file of the plan.
+    """
+    candidate = path
+    counter = 1
+    while candidate.exists() or candidate in reserved:
+        candidate = path.with_name(f"{path.stem} ({counter}){path.suffix}")
+        counter += 1
+    return candidate
+
+
+def describe_error(e: Exception) -> str:
+    """Return a short reason, e.g. "Permission denied".
+
+    OSError messages otherwise look like "[Errno 13] Permission denied: '/path'".
+    """
+    if isinstance(e, OSError) and e.strerror:
+        return e.strerror
+    return str(e)
+
+
+def plan_moves(
+    directory: Path, magika: Magika, config: Config, *, lowercase: bool = False
+) -> Plan:
+    """Decide where every file goes. Nothing is moved or created."""
+    plan = Plan(directory)
+    reserved: set[Path] = set()
+
+    for file in sorted(directory.iterdir()):
+        if not file.is_file():
+            continue
+
+        try:
+            target_dir, rule = determine_target_directory(
+                file, magika, config, lowercase=lowercase
+            )
+        except (OSError, ClassificationError) as e:
+            plan.failures.append(Failure(file, describe_error(e)))
+            continue
+
+        target = unique_path(directory / target_dir / file.name, reserved)
+        reserved.add(target)
+        plan.moves.append(Move(file, target, rule))
+
+    return plan
+
+
+def display_target(move: Move, directory: Path) -> str:
+    """Return "Photos/" when the name is kept, "Photos/photo (1).jpg" if renamed."""
+    relative = move.target.relative_to(directory)
+    if move.target.name == move.source.name:
+        return f"{relative.parent}/"
+    return str(relative)
+
+
+def log_plan(plan: Plan) -> None:
+    """Log every planned move, then every file skipped while planning."""
+    for move in plan.moves:
+        logger.debug("'%s': rule %s", move.source.name, move.rule)
+        logger.info("'%s' → %s", move.source.name, display_target(move, plan.directory))
+    for failure in plan.failures:
+        logger.warning("Skipped '%s': %s", failure.source.name, failure.reason)
+
+
+def apply_move(move: Move) -> None:
+    """Move one file to its planned target, creating its folder if needed."""
+    move.target.parent.mkdir(parents=True, exist_ok=True)
+
+    # The plan promised this exact target: never rename it again behind the
+    # user's back if something appeared there since planning
+    if move.target.exists():
+        raise FileExistsError(
+            errno.EEXIST, "Target appeared since planning", str(move.target)
+        )
+
+    shutil.move(move.source, move.target)
+
+
+def try_move(move: Move) -> Failure | None:
+    """Apply a move, returning a Failure instead of raising."""
+    try:
+        apply_move(move)
+    except OSError as e:
+        return Failure(move.source, describe_error(e))
+    return None
+
+
+def execute(plan: Plan) -> list[Failure]:
+    """Perform the planned moves. A failed move doesn't stop the others."""
+    failures: list[Failure] = []
+
+    for move in plan.moves:
+        failure = try_move(move)
+        if failure:
+            failures.append(failure)
+            logger.error("Failed to move '%s': %s", move.source.name, failure.reason)
+        else:
+            logger.debug(
+                "Moved '%s' → %s",
+                move.source.name,
+                display_target(move, plan.directory),
+            )
+
+    return failures

mimedy-1.0.0.dist-info/METADATA

@@ -0,0 +1,383 @@
+Metadata-Version: 2.5
+Name: mimedy
+Version: 1.0.0
+Summary: Organize messy folders by real file type, detected from content with Google Magika
+Project-URL: Homepage, https://github.com/ochapeau/mimedy
+Project-URL: Repository, https://github.com/ochapeau/mimedy
+Project-URL: Issues, https://github.com/ochapeau/mimedy/issues
+Project-URL: Releases, https://github.com/ochapeau/mimedy/releases
+Author: Olivier Chapeau
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,downloads,files,magika,mime,mimetype,organizer
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: magika>=0.6.2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: typer>=0.16
+Description-Content-Type: text/markdown
+
+# 🗂️ mimedy
+
+[![CI](https://github.com/ochapeau/mimedy/actions/workflows/ci.yml/badge.svg)](https://github.com/ochapeau/mimedy/actions/workflows/ci.yml)
+
+**Range un dossier en désordre selon le vrai type de chaque fichier, pas selon son extension.**\
+**Tidies up a messy folder by each file's real type, not by its extension.**
+
+*mimedy = **MIME** + **tidy** (ranger) : le type MIME de chaque fichier décide de sa place.*\
+*mimedy = **MIME** + **tidy**: each file's MIME type decides where it belongs.*
+
+[Français](#français) · [English](#english)
+
+---
+
+<a id="français"></a>
+
+## 🇫🇷 Français
+
+### Pourquoi ?
+
+Un dossier `Téléchargements` finit toujours par ressembler à ça : des PDF, des captures d'écran, des archives, un `.json` exporté un jour, un fichier sans extension dont personne ne se souvient…
+
+La plupart des outils de rangement se fient à l'extension. Or une extension peut mentir, manquer ou être fausse. **mimedy** utilise [Magika](https://github.com/google/magika), le modèle de deep learning de Google qui identifie un fichier **à partir de son contenu**, pour décider où il doit aller.
+
+```text
+$ mimedy ~/Downloads
+[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
+[INFO] Organizing /Users/me/Downloads
+[INFO] 'export.csv' → Data/
+[INFO] 'holidays.jpg' → Photos/
+[INFO] 'invoice' → PDF/
+[INFO] 'report.pdf' → PDF/report (1).pdf
+[INFO] 'script.py' → Python/
+[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
+[INFO] 5 files to move into 4 folders, 1 skipped
+Move 5 files? [y/N]: y
+[INFO] Done: 5 moved, 0 failed
+```
+
+### Fonctionnalités
+
+- 🧠 **Détection par le contenu** : Magika reconnaît plus de 200 types de fichiers, même renommés ou sans extension.
+- 🪜 **Règles en cascade** : fichiers cachés, fichiers volumineux, extensions, types MIME, puis le groupe Magika en dernier recours.
+- 📋 **Plan puis confirmation** : tous les déplacements sont affichés avant d'être effectués, et rien ne bouge sans votre accord. `--dry-run` s'arrête au plan.
+- 🧯 **Robuste** : un fichier illisible ou verrouillé est signalé et ignoré, sans interrompre le rangement.
+- 🛡️ **Aucun écrasement** : si `photo.jpg` existe déjà, le nouveau fichier devient `photo (1).jpg`.
+- 🐛 **Mode `--verbose`** : indique pour chaque fichier la règle qui a décidé de sa destination.
+- ⚙️ **Configuration YAML** simple, entièrement facultative.
+
+### Installation
+
+Prérequis : Python 3.10+ et [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/ochapeau/mimedy.git
+cd mimedy
+uv sync
+```
+
+### Utilisation
+
+> 💡 mimedy affiche toujours le plan complet et demande confirmation avant de déplacer quoi que ce soit.
+
+```bash
+# Afficher le plan, puis confirmer
+uv run mimedy ~/Downloads
+
+# Afficher le plan seulement
+uv run mimedy ~/Downloads --dry-run
+
+# Sans confirmation, par exemple dans un script
+uv run mimedy ~/Downloads --yes --config my-config.yaml
+
+# Comprendre pourquoi un fichier va à tel endroit
+uv run mimedy ~/Downloads --dry-run --verbose
+```
+
+| Option | Description |
+| :--- | :--- |
+| `DIRECTORY` | Dossier à ranger *(obligatoire)*. |
+| `--config`, `-c PATH` | Fichier de configuration YAML *(par défaut : voir [Configuration](#configuration))*. |
+| `--dry-run`, `-n` | Affiche les déplacements prévus sans les effectuer. |
+| `--yes`, `-y` | Déplace sans demander de confirmation. |
+| `--verbose`, `-v` | Affiche la règle appliquée à chaque fichier. |
+| `--lowercase`, `-l` | Garde en minuscules les dossiers nommés d'après Magika (`video/` au lieu de `Video/`). |
+| `--version`, `-V` | Affiche la version. |
+| `--help`, `-h` | Affiche l'aide. |
+| `--init-config` | Crée une configuration d'exemple commentée à l'emplacement par défaut (sans jamais écraser une configuration existante). |
+| `--install-completion` | Active l'autocomplétion des options avec Tab dans votre shell (une seule fois suffit). |
+
+Seuls les fichiers situés directement dans le dossier sont traités. Les sous-dossiers existants ne sont pas touchés, ce qui permet de relancer l'outil sans risque.
+
+| Code de sortie | Signification |
+| :-: | :--- |
+| `0` | Tout s'est bien passé, ou il n'y avait rien à ranger. |
+| `1` | Au moins un fichier n'a pas pu être traité, ou la confirmation a été refusée. |
+| `2` | Arguments ou configuration invalides. |
+
+### Configuration
+
+Sans `--config`, mimedy lit le fichier de configuration personnel, s'il existe :
+
+| Système | Emplacement |
+|---|---|
+| Linux, macOS | `~/.config/mimedy/config.yaml` (ou `$XDG_CONFIG_HOME/mimedy/config.yaml`) |
+| Windows | `%APPDATA%\mimedy\config.yaml` |
+
+S'il n'existe pas, les valeurs par défaut sont utilisées. Un fichier passé avec `--config` doit en revanche exister. `mimedy --help` affiche l'emplacement exact sur votre machine.
+
+Pour démarrer, créez une configuration d'exemple commentée, puis adaptez-la :
+
+```bash
+mimedy --init-config
+# Created config file: /Users/me/.config/mimedy/config.yaml
+```
+
+```yaml
+hidden: "Hidden"            # fichiers commençant par '.'
+
+large_files:
+  threshold_mb: 500         # en Mo décimaux, comme le Finder ou l'Explorateur
+  target_dir: "Large"
+
+extensions:                 # correspondance exacte sur l'extension
+  .blend: "Blender"
+  .csv: "Data"
+
+mimetypes:                  # type MIME détecté par Magika
+  application/pdf: "PDF"
+  image/jpeg: "Photos"
+```
+
+Toutes les clés sont facultatives : celles qui manquent reprennent leur valeur par défaut. Les destinations peuvent contenir des sous-dossiers (`"Code/Python"`). [`config.example.yaml`](src/mimedy/config.example.yaml), le fichier copié par `--init-config`, contient un exemple complet et commenté.
+
+### Comment un fichier est-il classé ?
+
+Les règles sont évaluées dans cet ordre ; **la première qui correspond l'emporte** :
+
+| # | Règle | Exemple |
+|:-:|:---|:---|
+| 1 | Fichier caché | `.env` → `Hidden/` |
+| 2 | Fichier volumineux | `film.mkv` (2 Go) → `Large/` |
+| 3 | Extension | `scene.blend` → `Blender/` |
+| 4 | Type MIME (Magika) | `facture` *(PDF sans extension)* → `PDF/` |
+| 5 | Groupe Magika | `script.py` → `Code/` |
+
+Les règles 1 à 3 ne lisent pas le contenu des fichiers : elles sont instantanées. Magika n'est appelé que si elles ne suffisent pas.
+
+### Structure du projet
+
+```text
+mimedy/
+├── pyproject.toml
+├── src/mimedy/
+│   ├── main.py              # Point d'entrée de la CLI (Typer)
+│   ├── config.py            # Chargement et validation de la configuration
+│   ├── config.example.yaml  # Configuration d'exemple commentée
+│   ├── organizer.py         # Règles de classement, planification et déplacements
+│   └── errors.py            # Exceptions du projet
+└── tests/                   # Tests pytest (configuration, règles, plan, CLI)
+```
+
+### Développement
+
+Le code est vérifié par [Ruff](https://docs.astral.sh/ruff/) (lint et formatage) à chaque commit, et testé avec [pytest](https://docs.pytest.org/). L'intégration continue lance les deux à chaque push, sur Python 3.10 à 3.13.
+
+```bash
+uv run pre-commit install   # vérifications automatiques à chaque commit
+uv run pytest               # lancer les tests
+```
+
+### Feuille de route
+
+- [x] Configuration typée et validée
+- [x] Configuration globale dans `~/.config/mimedy/`
+- [x] Tests automatisés et intégration continue
+- [ ] Publication sur PyPI (`uv tool install mimedy`)
+- [ ] Interface en terminal (TUI), en option
+
+### Licence
+
+Distribué sous licence MIT. Voir [LICENSE](LICENSE).
+
+---
+
+<a id="english"></a>
+
+## 🇬🇧 English
+
+### Why?
+
+A `Downloads` folder always ends up looking the same: PDFs, screenshots, archives, a `.json` exported at some point, a file with no extension that nobody remembers…
+
+Most organizing tools trust file extensions. But an extension can lie, be missing, or simply be wrong. **mimedy** uses [Magika](https://github.com/google/magika), Google's deep learning model that identifies a file **from its content**, to decide where it belongs.
+
+```text
+$ mimedy ~/Downloads
+[INFO] Loaded config from /Users/me/.config/mimedy/config.yaml
+[INFO] Organizing /Users/me/Downloads
+[INFO] 'export.csv' → Data/
+[INFO] 'holidays.jpg' → Photos/
+[INFO] 'invoice' → PDF/
+[INFO] 'report.pdf' → PDF/report (1).pdf
+[INFO] 'script.py' → Python/
+[WARNING] Skipped 'locked.txt': Magika could not read the file (permission_error)
+[INFO] 5 files to move into 4 folders, 1 skipped
+Move 5 files? [y/N]: y
+[INFO] Done: 5 moved, 0 failed
+```
+
+### Features
+
+- 🧠 **Content-based detection**: Magika recognizes over 200 file types, even when renamed or missing an extension.
+- 🪜 **Cascading rules**: hidden files, large files, extensions, MIME types, then the Magika group as a fallback.
+- 📋 **Plan, then confirm**: every move is shown before it happens, and nothing moves without your approval. `--dry-run` stops at the plan.
+- 🧯 **Robust**: an unreadable or locked file is reported and skipped, without stopping the run.
+- 🛡️ **Never overwrites**: if `photo.jpg` already exists, the new file becomes `photo (1).jpg`.
+- 🐛 **`--verbose` mode**: shows which rule decided each file's destination.
+- ⚙️ **Simple YAML configuration**, entirely optional.
+
+### Installation
+
+Requirements: Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/ochapeau/mimedy.git
+cd mimedy
+uv sync
+```
+
+### Usage
+
+> 💡 mimedy always shows the full plan and asks for confirmation before moving anything.
+
+```bash
+# Show the plan, then confirm
+uv run mimedy ~/Downloads
+
+# Only show the plan
+uv run mimedy ~/Downloads --dry-run
+
+# No confirmation, e.g. in a script
+uv run mimedy ~/Downloads --yes --config my-config.yaml
+
+# Understand why a file goes where it goes
+uv run mimedy ~/Downloads --dry-run --verbose
+```
+
+| Option | Description |
+| :--- | :--- |
+| `DIRECTORY` | Folder to organize *(required)*. |
+| `--config`, `-c PATH` | YAML configuration file *(default: see [Configuration](#configuration-1))*. |
+| `--dry-run`, `-n` | Show planned moves without performing them. |
+| `--yes`, `-y` | Move without asking for confirmation. |
+| `--verbose`, `-v` | Show which rule applied to each file. |
+| `--lowercase`, `-l` | Keep folders named after Magika groups lowercase (`video/` instead of `Video/`). |
+| `--version`, `-V` | Show the version. |
+| `--help`, `-h` | Show the help. |
+| `--init-config` | Create a commented example config at the default location (never overwrites an existing one). |
+| `--install-completion` | Enable Tab completion of the options in your shell (once is enough). |
+
+Only files directly inside the folder are processed. Existing subfolders are left untouched, so the tool can safely be run again.
+
+| Exit code | Meaning |
+| :-: | :--- |
+| `0` | Everything went fine, or there was nothing to organize. |
+| `1` | At least one file could not be processed, or the confirmation was declined. |
+| `2` | Invalid arguments or configuration. |
+
+### Configuration
+
+Without `--config`, mimedy reads your personal configuration file, if it exists:
+
+| System | Location |
+|---|---|
+| Linux, macOS | `~/.config/mimedy/config.yaml` (or `$XDG_CONFIG_HOME/mimedy/config.yaml`) |
+| Windows | `%APPDATA%\mimedy\config.yaml` |
+
+If it doesn't exist, the defaults are used. A file passed with `--config`, however, must exist. `mimedy --help` shows the exact location on your machine.
+
+To get started, create a commented example config, then adapt it:
+
+```bash
+mimedy --init-config
+# Created config file: /Users/me/.config/mimedy/config.yaml
+```
+
+```yaml
+hidden: "Hidden"            # files starting with '.'
+
+large_files:
+  threshold_mb: 500         # decimal MB, like Finder or Explorer
+  target_dir: "Large"
+
+extensions:                 # exact extension match
+  .blend: "Blender"
+  .csv: "Data"
+
+mimetypes:                  # MIME type detected by Magika
+  application/pdf: "PDF"
+  image/jpeg: "Photos"
+```
+
+Every key is optional: missing ones fall back to their default value. Destinations may include subfolders (`"Code/Python"`). See [`config.example.yaml`](src/mimedy/config.example.yaml), the file copied by `--init-config`, for a complete, commented example.
+
+### How is a file classified?
+
+Rules are evaluated in this order; **the first match wins**:
+
+| # | Rule | Example |
+|:-:|:---|:---|
+| 1 | Hidden file | `.env` → `Hidden/` |
+| 2 | Large file | `movie.mkv` (2 GB) → `Large/` |
+| 3 | Extension | `scene.blend` → `Blender/` |
+| 4 | MIME type (Magika) | `invoice` *(PDF with no extension)* → `PDF/` |
+| 5 | Magika group | `script.py` → `Code/` |
+
+Rules 1 to 3 don't read file contents, so they are instant. Magika only runs when they aren't enough.
+
+### Project structure
+
+```text
+mimedy/
+├── pyproject.toml
+├── src/mimedy/
+│   ├── main.py              # CLI entry point (Typer)
+│   ├── config.py            # Configuration loading and validation
+│   ├── config.example.yaml  # Commented example configuration
+│   ├── organizer.py         # Classification rules, planning and moves
+│   └── errors.py            # Project exceptions
+└── tests/                   # pytest tests (configuration, rules, plan, CLI)
+```
+
+### Development
+
+Code is checked by [Ruff](https://docs.astral.sh/ruff/) (linting and formatting) on every commit, and tested with [pytest](https://docs.pytest.org/). Continuous integration runs both on every push, on Python 3.10 to 3.13.
+
+```bash
+uv run pre-commit install   # automatic checks on every commit
+uv run pytest               # run the tests
+```
+
+### Roadmap
+
+- [x] Typed, validated configuration
+- [x] Global configuration in `~/.config/mimedy/`
+- [x] Automated tests and continuous integration
+- [ ] Publish on PyPI (`uv tool install mimedy`)
+- [ ] Optional terminal interface (TUI)
+
+### License
+
+Released under the MIT License. See [LICENSE](LICENSE).

mimedy-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+mimedy/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mimedy/config.example.yaml,sha256=4S9MH5uwcIGKh4-AmguPx4BPhOACvms_x0dMvNAtdeI,2264
+mimedy/config.py,sha256=K9fqe1w6KDGY9ZizQuLAab9DbXLAV3X2R0KgvgOWlIs,11128
+mimedy/errors.py,sha256=RX7eagHZhzReLOw-h5z2pPMxejtdmgSerinBH1C5kok,277
+mimedy/main.py,sha256=eQZ2zREfVYkbxqiOfTfVYoYHaNLRhr5DncNYP-VnoL4,5173
+mimedy/organizer.py,sha256=SxzS5GSIq_WQB59Y9-uEUikofNLkEiZj5kOP8s5cm1U,6254
+mimedy-1.0.0.dist-info/METADATA,sha256=kmkX43YUs0emaYU6K2EAxUCPtau5k18cNEAHOff1Wpw,15181
+mimedy-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+mimedy-1.0.0.dist-info/entry_points.txt,sha256=k6teYDmGJK1UKT7f1rORFFvoGyTfk1rlVCkZpHDwE30,43
+mimedy-1.0.0.dist-info/licenses/LICENSE,sha256=BmU3jrD8wlFYuTPdl454P0HwEEyRqWWraEJaKllS4Uo,1072
+mimedy-1.0.0.dist-info/RECORD,,

mimedy-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

mimedy-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mimedy = mimedy.main:app

mimedy-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Chapeau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.