fs_remove.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/tools/fs_remove.py
 
"""
Purpose
-------
One recursive-remove that survives a read-only directory, for every ``oct``
command that deletes a generated tree.
 
The defect this replaces: ``shutil.rmtree(path)`` raises
``PermissionError: [WinError 5] Access is denied`` when a directory carries the
Windows read-only attribute, because ``os.rmdir`` refuses it. Its
``ignore_errors=True`` form is no better -- it swallows the refusal and leaves
the tree standing while the caller reports success. On 2026-09-07 that let
``oct clean`` count 947 surviving directories as removed; on 2026-09-25 the
bare form ended ``oct docs --all`` in a traceback out of
``run_sphinx_build``'s pre-build clean.
 
The attribute is not exotic here (ENV-03): a Google Drive or OneDrive mirror
sets it on every directory it syncs, so an entire checkout under a mirror root
has it. Clearing the mirror is the real remedy and stays an operator action;
this module is what makes the tools survive until then.
 
Responsibilities
----------------
- :func:`remove_tree_force` -- remove a tree, clearing the read-only attribute
  on whatever refuses, and report whether it is really gone.
- :func:`remove_tree_or_warn` -- the same, plus the one standard warning, so
  six call sites do not word the same failure six ways.
- :data:`READ_ONLY_HINT` -- that wording, in one place.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L1 -- a tree that is still standing after the retry
    L2 -- lifecycle (a tree removed)
    L3 -- semantic details (the path, and the retry firing)
    L4 -- deep tracing
 
Contracts
---------
- The verdict is the filesystem's, never the call's: the return value is a
  fresh existence check, so a swallowed error cannot read as success. This is
  the property ``ignore_errors=True`` lacks and the reason it is not used here.
- Failure is never raised. Every caller here is deleting generated output as
  one step of a longer pipeline, and an unremovable cache directory must not
  end the run with a traceback.
- ``False`` does NOT mean nothing was deleted. A recursive delete works
  bottom-up, so a refusal at the final ``rmdir`` has already taken the files
  and leaves the directory shell behind. A caller that plans to rebuild into
  the path should copy or build into what remains (``exist_ok`` /
  ``dirs_exist_ok``) rather than treat the target as still intact.
- The attribute is cleared only on a path that has already refused removal and
  only to delete it. Nothing is made writable and left behind.
- ``target`` that does not exist is success -- the postcondition ("it is not
  there") already holds.
- stdlib plus the ``_dbg`` shim only; imports nothing of ``oct``'s beyond
  diagnostics, so any module may call it.
 
Dependencies
------------
- oct.core.diagnostics (the ``_dbg`` shim)
"""
from __future__ import annotations
 
import os
import shutil
import stat
import sys
from pathlib import Path
 
from oct.core.diagnostics import _dbg
 
#: Why a removal failed, in the one wording every caller uses. The attribute is
#: the cause in every case seen so far; a genuine lock reads the same way to the
#: operator, and the ``attrib`` command is harmless either way.
READ_ONLY_HINT = (
    "it or something inside it is read-only or locked. On Windows a Google "
    "Drive / OneDrive mirror sets the read-only attribute on every synced "
    "directory; clear it with:  attrib -R /S /D <path>"
)
 
 
def remove_tree_force(target: Path) -> bool:
    """Remove *target* recursively and report whether it is really gone.
 
    Clears the read-only attribute on whatever refuses and retries that one
    path once. Returns the result of an existence check made afterwards, so the
    answer is what is on disk rather than what the call believed.
    """
    func = "remove_tree_force"
    if not Path(target).exists():
        _dbg("OCT-CORE", func, f"nothing to remove at {target}", 4)
        return True
 
    def _clear_and_retry(remover, path, _exc) -> None:
        """Make one refusing path writable and try that one removal again."""
        try:
            os.chmod(path, stat.S_IWRITE | stat.S_IREAD | stat.S_IEXEC)
            remover(path)
        except OSError:
            pass  # the existence check below is the verdict
 
    try:
        if sys.version_info >= (3, 12):
            shutil.rmtree(target, onexc=_clear_and_retry)
        else:  # pragma: no cover - the onerror signature carries exc_info
            shutil.rmtree(target, onerror=_clear_and_retry)
    except OSError as exc:
        # SYSTEM_ERROR (S6/L1) - reported by the return value, never raised:
        # the caller is mid-pipeline and owns what a failed clean means.
        _dbg("OCT-CORE", func, f"SYSTEM_ERROR: rmtree({target}) raised: {exc}", 3)
 
    gone = not Path(target).exists()
    _dbg("OCT-CORE", func, f"{target}: {'removed' if gone else 'still present'}",
         2 if gone else 1)
    return gone
 
 
def remove_tree_or_warn(target: Path, *, label: str = "") -> bool:
    """Remove *target*; on failure print one standard warning and return False.
 
    *label* names the thing in the operator's terms ("Sphinx doctree cache"),
    so the warning says what was not cleaned as well as where it is.
    """
    func = "remove_tree_or_warn"
    if remove_tree_force(target):
        return True
    what = f"{label} " if label else ""
    print(f"Warning: could not remove {what}{target} - {READ_ONLY_HINT}",
          file=sys.stderr)
    _dbg("OCT-CORE", func, f"warned about surviving tree {target}", 3)
    return False