fops 0.1.0__tar.gz

fops-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.3
+Name: fops
+Version: 0.1.0
+Summary: 
+Author: oyghen
+Author-email: oyghen <oyghen@duck.com>
+Requires-Dist: typer>=0.21.0 ; extra == 'cli'
+Requires-Python: >=3.11
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# fops
+
+[![GitHub](https://img.shields.io/badge/github-code-blue?label=GitHub)](https://github.com/oyghen/fops)
+[![PyPI](https://img.shields.io/pypi/v/fops?label=PyPI)](https://pypi.org/project/fops)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/oyghen/fops/blob/main/LICENSE)
+[![CI](https://github.com/oyghen/fops/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/oyghen/fops/actions/workflows/ci.yml)
+
+</div>
+
+```shell
+uv tool install 'fops[cli]'
+```

fops-0.1.0/README.md

@@ -0,0 +1,14 @@
+<div align="center">
+
+# fops
+
+[![GitHub](https://img.shields.io/badge/github-code-blue?label=GitHub)](https://github.com/oyghen/fops)
+[![PyPI](https://img.shields.io/pypi/v/fops?label=PyPI)](https://pypi.org/project/fops)
+[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/oyghen/fops/blob/main/LICENSE)
+[![CI](https://github.com/oyghen/fops/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/oyghen/fops/actions/workflows/ci.yml)
+
+</div>
+
+```shell
+uv tool install 'fops[cli]'
+```

fops-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "fops"
+version = "0.1.0"
+description = ""
+readme = "README.md"
+authors = [
+    { name = "oyghen", email = "oyghen@duck.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+fops = "fops._cli_entry:main"
+
+[project.optional-dependencies]
+cli = [
+    "typer>=0.21.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.10",
+]

fops-0.1.0/src/fops/__init__.py

@@ -0,0 +1,12 @@
+__all__ = ("__version__", "core")
+
+import logging
+from importlib import metadata
+
+from fops import core
+
+__version__ = metadata.version(__name__)
+
+# Prevent "No handlers could be found" warnings when the library is imported.
+# Applications are responsible for configuring handlers/formatters/levels.
+logging.getLogger(__name__).addHandler(logging.NullHandler())

fops-0.1.0/src/fops/__main__.py

@@ -0,0 +1,4 @@
+from fops import _cli_entry as cli_entry
+
+if __name__ == "__main__":
+    cli_entry.main()

fops-0.1.0/src/fops/_cli_entry.py

@@ -0,0 +1,14 @@
+import sys
+
+
+def main() -> None:
+    try:
+        from fops import cli
+    except (ImportError, ModuleNotFoundError) as exc:
+        print(
+            "CLI dependencies missing. Use: uv tool install 'fops[cli]'",
+            file=sys.stderr,
+        )
+        raise SystemExit(2) from exc
+
+    cli.main()

fops-0.1.0/src/fops/cli.py

@@ -0,0 +1,63 @@
+__all__ = ("app", "main")
+
+import logging
+import sys
+
+import typer
+
+import fops
+
+app = typer.Typer(add_completion=False)
+
+# command imports need to be after app creation
+from fops.commands import (  # noqa: E402,F401
+    create_archive,
+    delete_branches,
+    delete_cache,
+    rename_extensions,
+)
+
+
+def configure_logging(level: int) -> None:
+    root = logging.getLogger()
+    if root.handlers:
+        root.handlers.clear()
+
+    handler = logging.StreamHandler(sys.stderr)
+    fmt = "%(levelname)s: %(message)s"
+    handler.setFormatter(logging.Formatter(fmt))
+
+    root.addHandler(handler)
+    root.setLevel(level)
+
+
+@app.callback(invoke_without_command=True)
+def cli(
+    version: bool = typer.Option(
+        False, "--version", "-V", help="Show app version and exit."
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", "-v", help="Enable debug logging."
+    ),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress info logging."),
+) -> None:
+    if version:
+        typer.echo(f"{fops.__name__} {fops.__version__}")
+        raise typer.Exit()
+
+    if verbose and quiet:
+        raise typer.BadParameter("Cannot use --verbose and --quiet together")
+
+    if verbose:
+        level = logging.DEBUG
+    elif quiet:
+        level = logging.WARNING
+    else:
+        level = logging.INFO
+
+    configure_logging(level)
+
+
+def main() -> None:
+    """Canonical entry point for CLI execution."""
+    app()

fops-0.1.0/src/fops/commands/create_archive.py

@@ -0,0 +1,52 @@
+import logging
+from pathlib import Path
+
+import typer
+
+import fops
+from fops.cli import app
+
+logger = logging.getLogger(__name__)
+
+DIRECTORY_ARG = typer.Argument(help="Directory to process.")
+
+ARCHIVE_NAME_OPT = typer.Option(None, help="Archive name.")
+PATTERN_OPT = typer.Option(None, help="File pattern to include.")
+ARCHIVE_FORMAT_OPT = typer.Option("zip", help="Archive format.")
+
+
+@app.command()
+def create_archive(
+    directory_path: Path = DIRECTORY_ARG,
+    archive_name: str | None = ARCHIVE_NAME_OPT,
+    pattern: list[str] | None = PATTERN_OPT,
+    archive_format: str = ARCHIVE_FORMAT_OPT,
+) -> None:
+    """Archive files.
+
+    Example:
+    $ fops create-archive . --pattern '*.txt' --pattern '*.md'
+    """
+    directory = Path(directory_path).resolve()
+
+    if not directory.exists():
+        typer.secho(f"Directory not found: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    if not directory.is_dir():
+        typer.secho(f"Not a directory: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        archive_path = fops.core.create_archive(
+            directory,
+            archive_name,
+            pattern,
+            archive_format,
+        )
+        typer.secho(f"Done - {archive_path}", fg=typer.colors.GREEN)
+    except Exception as exc:
+        message = "Failed to create archive"
+        logger.exception(message)
+        typer.secho(f"{message} (see log for details).", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc

fops-0.1.0/src/fops/commands/delete_branches.py

@@ -0,0 +1,22 @@
+import logging
+
+import typer
+
+import fops
+from fops.cli import app
+
+logger = logging.getLogger(__name__)
+
+
+@app.command()
+def delete_branches() -> None:
+    """Delete local git branches and remote-tracking refs except protected ones."""
+    try:
+        fops.core.delete_local_branches()
+        fops.core.delete_remote_branch_refs()
+        typer.secho("Done.", fg=typer.colors.GREEN)
+    except Exception as exc:
+        message = "Failed to delete branches"
+        logger.exception(message)
+        typer.secho(f"{message} (see log for details).", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc

fops-0.1.0/src/fops/commands/delete_cache.py

@@ -0,0 +1,38 @@
+import logging
+from pathlib import Path
+
+import typer
+
+import fops
+from fops.cli import app
+
+logger = logging.getLogger(__name__)
+
+DIRECTORY_ARG = typer.Argument(help="Directory to process.")
+
+
+@app.command()
+def delete_cache(directory_path: Path = DIRECTORY_ARG) -> None:
+    """Delete cache directories and files.
+
+    Example:
+    $ fops delete-cache .
+    """
+    directory = Path(directory_path).resolve()
+
+    if not directory.exists():
+        typer.secho(f"Directory not found: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    if not directory.is_dir():
+        typer.secho(f"Not a directory: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        fops.core.delete_cache(directory_path=directory)
+        typer.secho("Done.", fg=typer.colors.GREEN)
+    except Exception as exc:
+        message = "Failed to delete cache"
+        logger.exception(message)
+        typer.secho(f"{message} (see log for details).", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc

fops-0.1.0/src/fops/commands/rename_extensions.py

@@ -0,0 +1,65 @@
+import logging
+from pathlib import Path
+
+import typer
+
+import fops
+from fops.cli import app
+
+logger = logging.getLogger(__name__)
+
+DIRECTORY_ARG = typer.Argument(help="Directory to process.")
+OLD_EXT_ARG = typer.Argument(help="File extension to match (e.g. 'txt' or '.txt').")
+NEW_EXT_ARG = typer.Argument(help="New file extension to apply (e.g. 'md' or '.md').")
+
+CREATE_COPY_OPT = typer.Option(False, help="Copy files instead of renaming them.")
+RECURSIVE_OPT = typer.Option(False, help="Process files recursively in subdirectories.")
+OVERWRITE_OPT = typer.Option(
+    False, help="Overwrite existing target files if they already exist."
+)
+DRY_RUN_OPT = typer.Option(
+    False, help="Show what would be changed without modifying any files."
+)
+
+
+@app.command()
+def rename_extensions(
+    directory_path: Path = DIRECTORY_ARG,
+    old_ext: str = OLD_EXT_ARG,
+    new_ext: str = NEW_EXT_ARG,
+    create_copy: bool = CREATE_COPY_OPT,
+    recursive: bool = RECURSIVE_OPT,
+    overwrite: bool = OVERWRITE_OPT,
+    dry_run: bool = DRY_RUN_OPT,
+) -> None:
+    """Rename (or copy) files in a directory by changing their extensions.
+
+    Example:
+    $ fops rename-extensions --create-copy --recursive . .txt .md --dry-run
+    """
+    directory = Path(directory_path).resolve()
+
+    if not directory.exists():
+        typer.secho(f"Directory not found: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    if not directory.is_dir():
+        typer.secho(f"Not a directory: {directory}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        fops.core.rename_extensions(
+            directory,
+            old_ext,
+            new_ext,
+            create_copy=create_copy,
+            recursive=recursive,
+            overwrite=overwrite,
+            dry_run=dry_run,
+        )
+        typer.secho("Done.", fg=typer.colors.GREEN)
+    except Exception as exc:
+        message = "Failed to rename extensions"
+        logger.exception(message)
+        typer.secho(f"{message} (see log for details).", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from exc

fops-0.1.0/src/fops/core.py

@@ -0,0 +1,478 @@
+__all__ = (
+    "PathLikeStr",
+    "PROTECTED_BRANCHES",
+    "CACHE_DIRECTORIES",
+    "CACHE_FILE_EXTENSIONS",
+    "delete_cache",
+    "confirm",
+    "create_archive",
+    "iter_lines",
+    "terminal_width",
+    "delete_local_branches",
+    "delete_remote_branch_refs",
+    "get_current_branch_name",
+    "get_local_branch_names",
+    "get_remote_branch_names",
+    "get_last_commit_hash",
+    "run_command",
+    "get_installed_package_count",
+    "rename_extensions",
+    "safe_copy",
+)
+
+import contextlib
+import logging
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from collections.abc import Iterator, Sequence
+from importlib import metadata
+from pathlib import Path
+from shutil import copy2, get_archive_formats, get_terminal_size, make_archive
+from typing import Final, TypeAlias
+
+from fops import utils
+
+PathLikeStr: TypeAlias = str | Path | os.PathLike[str]
+
+logger = logging.getLogger(__name__)
+
+PROTECTED_BRANCHES: Final[frozenset[str]] = frozenset({"main", "master", "develop"})
+
+CACHE_DIRECTORIES: Final[tuple[str, ...]] = (
+    "__pycache__",
+    ".pytest_cache",
+    ".ipynb_checkpoints",
+    ".ruff_cache",
+    "spark-warehouse",
+)
+
+CACHE_FILE_EXTENSIONS: Final[tuple[str, ...]] = (
+    "*.py[co]",
+    ".coverage",
+    ".coverage.*",
+)
+
+
+def delete_cache(
+    directory_path: PathLikeStr,
+    cache_directories: Sequence[str] | None = None,
+    cache_file_extensions: Sequence[str] | None = None,
+) -> None:
+    """Delete cache directories and files in the specified directory."""
+    root = Path(directory_path).resolve()
+
+    if cache_directories is None:
+        cache_directories = CACHE_DIRECTORIES
+
+    if cache_file_extensions is None:
+        cache_file_extensions = CACHE_FILE_EXTENSIONS
+
+    for directory in cache_directories:
+        for path in root.rglob(directory):
+            if "venv" in str(path):
+                continue
+            shutil.rmtree(path.absolute(), ignore_errors=False)
+            logger.info("deleted - %s", path)
+    logger.info("done with deleting cache directories")
+
+    for file_extension in cache_file_extensions:
+        for path in root.rglob(file_extension):
+            if "venv" in str(path):
+                continue
+            path.unlink()
+            logger.info("deleted - %s", path)
+    logger.info("done with deleting cache files")
+
+
+def confirm(prompt: str, default: str | None = None) -> bool:
+    """Return True if the user confirms ('yes'); repeats until valid input."""
+    if default not in (None, "yes", "no"):
+        raise ValueError(f"invalid {default=!r}; expected None, 'yes', or 'no'")
+
+    true_tokens = frozenset(("y", "yes", "t", "true", "on", "1"))
+    false_tokens = frozenset(("n", "no", "f", "false", "off", "0"))
+    prompt_map = {None: "[y/n]", "yes": "[Y/n]", "no": "[y/N]"}
+    suffix = prompt_map[default]
+
+    while True:
+        reply = input(f"{prompt} {suffix} ").strip().lower()
+
+        if not reply:
+            if default is not None:
+                return default == "yes"
+            print("Please respond with 'yes' or 'no'.")
+            continue
+
+        if reply in true_tokens:
+            return True
+        if reply in false_tokens:
+            return False
+
+        print("Please respond with 'yes' or 'no'.")
+
+
+def create_archive(
+    directory_path: PathLikeStr,
+    archive_name: str | None = None,
+    patterns: Sequence[str] | None = None,
+    archive_format: str = "zip",
+) -> Path:
+    """Return the path of the created archive file."""
+    dir_path = Path(directory_path).resolve()
+    if not dir_path.exists() or not dir_path.is_dir():
+        raise ValueError(f"{directory_path!r} does not exist or is not a directory")
+
+    patterns = list(patterns) if patterns else ["**/*"]
+    archive_format = archive_format.lower()
+    supported = {fmt for fmt, _ in get_archive_formats()}
+    if archive_format not in supported:
+        raise ValueError(
+            f"invalid choice {archive_format!r}; expected a value from {supported!r}"
+        )
+
+    if archive_name is None:
+        base_name = f"{utils.utctimestamp()}_{dir_path.stem}"
+    else:
+        if Path(archive_name).name != archive_name:
+            raise ValueError("archive_name must not contain directory components")
+        base_name = archive_name
+
+    # collect matches deterministically and deduplicate
+    matched: set[Path] = set()
+    for pattern in patterns:
+        matched.update(dir_path.rglob(pattern))
+
+    # sort by relative path for deterministic archive contents/order
+    paths = sorted((p for p in matched), key=lambda p: str(p.relative_to(dir_path)))
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = Path(tmpdir)
+        for src_path in paths:
+            logger.debug("processing - %s", src_path)
+            try:
+                rel = src_path.relative_to(dir_path)
+            except Exception:
+                # skip anything not under target (shouldn't happen with rglob)
+                continue
+
+            dst_path = tmpdir_path / rel
+            if src_path.is_dir():
+                dst_path.mkdir(parents=True, exist_ok=True)
+                continue
+
+            dst_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if src_path.is_symlink():
+                target_link = os.readlink(src_path)
+                if dst_path.exists() or dst_path.is_symlink():
+                    dst_path.unlink()
+                os.symlink(target_link, dst_path)
+
+            elif src_path.is_file():
+                copy2(src_path, dst_path)
+
+            else:
+                continue
+
+        archive_path = make_archive(
+            str(Path(base_name)),
+            archive_format,
+            root_dir=str(tmpdir_path),
+        )
+
+    return Path(archive_path)
+
+
+def iter_lines(
+    filepath: PathLikeStr,
+    encoding: str | None = None,
+    errors: str | None = None,
+    newline: str | None = None,
+) -> Iterator[str]:
+    """Return an iterator over text lines from filepath."""
+    path = os.fspath(filepath)
+    with open(path, encoding=encoding, errors=errors, newline=newline) as fh:
+        yield from fh
+
+
+def terminal_width(default: int = 79) -> int:
+    """Return the current terminal width or a fallback value."""
+    try:
+        return get_terminal_size().columns
+    except OSError:
+        return default
+
+
+def delete_local_branches() -> None:
+    """Delete local git branches except protected ones."""
+    logger.debug("running '%s'", utils.get_caller_name())
+    current = get_current_branch_name()
+    exclude = PROTECTED_BRANCHES | {current}
+
+    local = get_local_branch_names()
+    to_delete = [b for b in local if b not in exclude]
+
+    if not to_delete:
+        logger.info("no local branches to delete")
+        return
+
+    logger.debug("deleting %d local branch(es): %s", len(to_delete), to_delete)
+    for branch in to_delete:
+        try:
+            run_command(f"git branch -D {branch}", label=utils.get_caller_name())
+            logger.info("deleted local branch '%s'", branch)
+        except subprocess.CalledProcessError as exc:
+            logger.exception(
+                "failed deleting local branch %s; exit=%s; stderr=%s",
+                branch,
+                getattr(exc, "returncode", None),
+                getattr(exc, "stderr", None),
+            )
+
+
+def delete_remote_branch_refs() -> None:
+    """Delete remote-tracking git branch refs except protected ones."""
+    logger.debug("running '%s'", utils.get_caller_name())
+    current = get_current_branch_name()
+    exclude = PROTECTED_BRANCHES | {current}
+
+    remote = get_remote_branch_names()
+    to_delete = [r for r in remote if r.split("/", 1)[-1] not in exclude]
+
+    if not to_delete:
+        logger.info("no remote-tracking refs to delete")
+        return
+
+    logger.debug("deleting %d remote ref(s): %s", len(to_delete), to_delete)
+    for ref in to_delete:
+        try:
+            run_command(f"git branch -r -d {ref}", label=utils.get_caller_name())
+            logger.info("deleted remote ref '%s'", ref)
+        except subprocess.CalledProcessError as exc:
+            logger.exception(
+                "failed deleting remote ref %s; exit=%s; stderr=%s",
+                ref,
+                getattr(exc, "returncode", None),
+                getattr(exc, "stderr", None),
+            )
+
+
+def get_current_branch_name() -> str:
+    """Return current branch name as string."""
+    return run_command("git rev-parse --abbrev-ref HEAD", label=utils.get_caller_name())
+
+
+def get_local_branch_names() -> list[str]:
+    """Return list of local branch names."""
+    out = run_command("git branch", label=utils.get_caller_name())
+    branches: list[str] = []
+    for line in out.splitlines():
+        branches.append(line.lstrip("*").strip())
+    return branches
+
+
+def get_remote_branch_names() -> list[str]:
+    """Return list of remote-tracking branch refs."""
+    out = run_command("git branch --remotes", label=utils.get_caller_name())
+    branches: list[str] = []
+    for line in out.splitlines():
+        line = line.strip()
+        if "->" in line:
+            continue
+        branches.append(line)
+    return branches
+
+
+def get_last_commit_hash(max_length: int | None = None) -> str:
+    """Return the full or truncated commit hash of the current branch."""
+    if max_length is not None:
+        if not isinstance(max_length, int):
+            raise TypeError(
+                f"unsupported type {type(max_length).__name__!r}; expected int or None"
+            )
+        if max_length < 1:
+            raise ValueError(f"invalid value {max_length!r}; expected >= 1")
+
+    commit = run_command("git rev-parse HEAD", label=utils.get_caller_name())
+    if not commit:
+        raise RuntimeError("git returned an empty commit hash")
+
+    return commit if max_length is None else commit[:max_length]
+
+
+def run_command(command: str | Sequence[str], label: str) -> str:
+    """Return stdout as string of the executed command."""
+    cmd = shlex.split(command) if isinstance(command, str) else list(command)
+    response = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    logger.debug("'%s' ran '%s'", label, " ".join(cmd))
+    return response.stdout.strip()
+
+
+def get_installed_package_count() -> int:
+    """Return the number of installed packages for the current Python environment."""
+    try:
+        count = sum(1 for _ in metadata.distributions())
+    except Exception:
+        count = 0
+
+    # fallback: use the same interpreter's pip to get a reliable package list
+    if count < 10:
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-m", "pip", "list", "--format=freeze"],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            # ignore blank lines and count non-empty entries
+            lines = [ln for ln in proc.stdout.splitlines() if ln.strip()]
+            return len(lines)
+        except (subprocess.SubprocessError, OSError):
+            # if pip fails, return what metadata provided (possibly 0)
+            return int(count)
+
+    return int(count)
+
+
+def rename_extensions(
+    directory_path: PathLikeStr,
+    old_ext: str | None,
+    new_ext: str,
+    *,
+    create_copy: bool = False,
+    recursive: bool = False,
+    overwrite: bool = False,
+    dry_run: bool = False,
+) -> None:
+    """Rename (or copy) files in a directory by changing their extensions."""
+    logger.debug(
+        "running '%s' with %s",
+        utils.get_caller_name(),
+        {
+            "directory_path": directory_path,
+            "old_ext": old_ext,
+            "new_ext": new_ext,
+            "create_copy": create_copy,
+            "recursive": recursive,
+            "overwrite": overwrite,
+            "dry_run": dry_run,
+        },
+    )
+
+    dir_path = Path(directory_path).resolve()
+    if not dir_path.exists() or not dir_path.is_dir():
+        raise ValueError(f"{directory_path!r} does not exist or is not a directory")
+
+    def _normalize(ext: str | None) -> str | None:
+        if ext is None:
+            return None
+        if ext == "":
+            return ""
+        return ext if ext.startswith(".") else f".{ext}"
+
+    src_ext = _normalize(old_ext)
+    dst_ext = _normalize(new_ext)
+    if dst_ext is None:
+        raise ValueError("new_ext must be provided")
+
+    # iterable of Path objects
+    file_paths = dir_path.rglob("*") if recursive else dir_path.iterdir()
+
+    for file_path in file_paths:
+        logger.debug("processing: %s", file_path)
+
+        if not file_path.is_file():
+            logger.debug("skipping - not a file: %s", file_path)
+            continue
+
+        name = file_path.name
+        lower_name = name.lower()
+
+        # decide if file matches src_ext
+        if src_ext is None:
+            matches = True
+        else:
+            src_lower = src_ext.lower()
+            # treat multi-dot extensions (e.g. '.tar.gz') via endswith
+            if src_lower.count(".") > 1:
+                matches = lower_name.endswith(src_lower)
+            else:
+                matches = file_path.suffix.lower() == src_lower
+
+        if not matches:
+            logger.debug("skipping - not a match: %s", file_path)
+            continue
+
+        # compute new path
+        if (
+            src_ext
+            and src_ext.lower().count(".") > 1
+            and lower_name.endswith(src_ext.lower())
+        ):
+            # replace trailing multi-dot ext
+            new_name = name[: -len(src_ext)] + dst_ext
+            new_path = file_path.with_name(new_name)
+        else:
+            # pathlib.with_suffix accepts '' to remove suffix
+            new_path = file_path.with_suffix(dst_ext)
+
+        # no-op
+        if new_path == file_path:
+            logger.debug("skipping - new_path is current file_path")
+            continue
+
+        if new_path.exists() and not overwrite:
+            raise FileExistsError(f"file already exists: {new_path}")
+
+        if dry_run:
+            op = "copy" if create_copy else "rename"
+            logger.info("[dry-run] %s %s -> %s", op, file_path, new_path)
+            continue
+
+        if create_copy:
+            safe_copy(file_path, new_path, overwrite=overwrite)
+            logger.info("copied %s -> %s", file_path, new_path)
+        else:
+            # use replace when allowing overwrite (atomic where supported)
+            if overwrite and new_path.exists():
+                file_path.replace(new_path)
+            else:
+                file_path.rename(new_path)
+            logger.info("renamed %s -> %s", file_path, new_path)
+
+
+def safe_copy(
+    old_file: PathLikeStr,
+    new_file: PathLikeStr,
+    *,
+    overwrite: bool = False,
+) -> None:
+    """Safely copy a file with metadata and atomically replace the target if desired."""
+    src = Path(old_file)
+    dst = Path(new_file)
+
+    if not src.exists() or not src.is_file():
+        raise FileNotFoundError(f"source does not exist or is not a file: {src}")
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+
+    if dst.exists() and not overwrite:
+        raise FileExistsError(f"target already exists: {dst}")
+
+    tmp_path: Path | None = None
+    try:
+        # create a named temporary file in the destination directory for atomic replace
+        with tempfile.NamedTemporaryFile(delete=False, dir=dst.parent) as tmp:
+            tmp_path = Path(tmp.name)
+        copy2(src, tmp_path)  # copy2 preserves metadata (mtime, permissions, flags)
+        os.replace(str(tmp_path), str(dst))  # atomic rename (replace) to final dst
+    except Exception:
+        # best-effort cleanup of temp file
+        with contextlib.suppress(Exception):
+            if tmp_path is not None and tmp_path.exists():
+                tmp_path.unlink()
+        raise

fops-0.1.0/src/fops/utils.py

@@ -0,0 +1,36 @@
+import datetime as dt
+import inspect
+from collections.abc import Callable, Iterable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def get_caller_name(depth: int = 1) -> str:
+    """Return the name of the calling function; depth=1 is the immediate caller."""
+    if depth < 1:
+        raise ValueError(f"invalid {depth=!r}; expected >= 1")
+
+    frame = inspect.currentframe()
+    try:
+        caller = frame
+        for _ in range(depth):
+            caller = caller.f_back if caller is not None else None
+        if caller is None:
+            raise RuntimeError("expected to be executed within a function")
+        return caller.f_code.co_name
+    finally:
+        del frame
+
+
+def pipe(value: T, functions: Iterable[Callable[[Any], Any]]) -> Any:
+    """Return the result of applying a sequence of functions to the initial value."""
+    result: Any = value
+    for function in functions:
+        result = function(result)
+    return result
+
+
+def utctimestamp() -> str:
+    """Return UTC timestamp string."""
+    return dt.datetime.now(dt.UTC).strftime("%Y%m%d%H%M%S")