python-cad-tools 0.1.0rc1__py3-none-any.whl

python_cad_tools/__init__.py

@@ -0,0 +1,10 @@
+"""Python CAD Tools package metadata."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("python-cad-tools")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = ["__version__"]

python_cad_tools/_locking.py

@@ -0,0 +1,63 @@
+"""Portable-enough process locks for project operations on claimed platforms."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from .exceptions import BuildLockedError
+
+
+@contextmanager
+def project_lock(project_root: Path) -> Iterator[None]:
+    """Hold the non-blocking interprocess lock for one canonical project path."""
+    root = project_root.resolve()
+    identity = hashlib.sha256(os.fsencode(root)).hexdigest()
+    lock_dir = Path(tempfile.gettempdir()) / "python-cad-tools-locks"
+    lock_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+    path = lock_dir / f"{identity}.lock"
+    fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o700)
+    try:
+        _acquire(fd, root)
+        os.lseek(fd, 0, os.SEEK_SET)
+        os.ftruncate(fd, 0)
+        os.write(fd, f"pid={os.getpid()}\nproject_root={root}\n".encode())
+        os.fsync(fd)
+        yield
+    finally:
+        _release(fd)
+        os.close(fd)
+
+
+def _acquire(fd: int, root: Path) -> None:
+    if sys.platform == "win32":
+        import msvcrt
+
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError as error:
+            raise BuildLockedError(f"Another Python CAD operation is active for {root}") from error
+    else:
+        import fcntl
+
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError as error:
+            raise BuildLockedError(f"Another Python CAD operation is active for {root}") from error
+
+
+def _release(fd: int) -> None:
+    if sys.platform == "win32":
+        import msvcrt
+
+        os.lseek(fd, 0, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl
+
+        fcntl.flock(fd, fcntl.LOCK_UN)

python_cad_tools/_project_loader.py

@@ -0,0 +1,273 @@
+"""Isolated, serialized loading of trusted project entry points."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import itertools
+import os
+import subprocess
+import sys
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from importlib.machinery import ModuleSpec
+from importlib.util import source_from_cache
+from pathlib import Path
+from types import ModuleType
+from typing import Any, cast
+
+from ._project_state import authoritative_path, begin_source_tracking, end_source_tracking, record_source
+from .context import BuildContext, DrawingContext
+from .drawings import DrawingAnnotationSet, DrawingSheet
+from .drawings._catalog import standard_sheet_catalog
+from .drawings._validation import validate_annotation_set
+from .elements import DesignModel
+from .exceptions import BuildLockedError, CadToolsError, ModelValidationError, ProjectConfigError
+from .project_config import ProjectConfig, load_project_config, split_callable_target
+from .validation import ValidationIssue, validate_model
+
+_PROJECT_EXECUTION_LOCK = threading.Lock()
+_PROJECT_EXECUTION_LOCAL = threading.local()
+_NAMESPACE_COUNTER = itertools.count()
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedProject:
+    project_root: Path
+    project_config: ProjectConfig
+    runtime_config: Any
+    model: DesignModel
+    issues: tuple[ValidationIssue, ...]
+    source_inputs: tuple[str, ...]
+    source_revision: str | None
+    source_dirty: bool
+    drawing_sheets: tuple[DrawingSheet, ...]
+    annotations: DrawingAnnotationSet | None
+
+
+@dataclass(slots=True)
+class _ProcessSnapshot:
+    modules: dict[str, ModuleType]
+    path: list[str]
+    path_importer_cache: dict[str, Any]
+    meta_path: list[Any]
+    path_hooks: list[Any]
+    argv: list[str]
+    environment: dict[str, str]
+    cwd: Path
+
+    @classmethod
+    def capture(cls) -> _ProcessSnapshot:
+        return cls(
+            modules=dict(sys.modules),
+            path=list(sys.path),
+            path_importer_cache=dict(sys.path_importer_cache),
+            meta_path=list(sys.meta_path),
+            path_hooks=list(sys.path_hooks),
+            argv=list(sys.argv),
+            environment=dict(os.environ),
+            cwd=Path.cwd(),
+        )
+
+    def restore(self) -> None:
+        os.chdir(self.cwd)
+        os.environ.clear()
+        os.environ.update(self.environment)
+        sys.argv[:] = self.argv
+        sys.path[:] = self.path
+        sys.meta_path[:] = self.meta_path
+        sys.path_hooks[:] = self.path_hooks
+        sys.path_importer_cache.clear()
+        sys.path_importer_cache.update(self.path_importer_cache)
+        sys.modules.clear()
+        sys.modules.update(self.modules)
+
+
+def load_project_model(project_root: Path, *, include_drawings: bool = False) -> LoadedProject:
+    """Load and invoke one project model with complete process-state cleanup."""
+    with project_execution():
+        return load_project_model_guarded(project_root, include_drawings=include_drawings)
+
+
+@contextmanager
+def project_execution() -> Iterator[None]:
+    """Serialize the complete trusted project execution/build lifecycle."""
+    reject_nested_project_execution()
+    with _PROJECT_EXECUTION_LOCK:
+        _PROJECT_EXECUTION_LOCAL.active = True
+        try:
+            yield
+        finally:
+            _PROJECT_EXECUTION_LOCAL.active = False
+
+
+def load_project_model_guarded(project_root: Path, *, include_drawings: bool = False) -> LoadedProject:
+    if not getattr(_PROJECT_EXECUTION_LOCAL, "active", False):
+        raise BuildLockedError("Project loading requires the active project execution guard")
+    return _load_project_model_locked(project_root.resolve(), include_drawings=include_drawings)
+
+
+def reject_nested_project_execution() -> None:
+    if getattr(_PROJECT_EXECUTION_LOCAL, "active", False):
+        raise BuildLockedError("Nested Python CAD project execution is not allowed")
+
+
+def _load_project_model_locked(project_root: Path, *, include_drawings: bool) -> LoadedProject:
+    project_config = load_project_config(project_root)
+    revision, dirty = _source_state(project_root)
+    snapshot = _ProcessSnapshot.capture()
+    token = begin_source_tracking()
+    tracking_active = True
+    namespace = f"_python_cad_project_{next(_NAMESPACE_COUNTER):x}"
+    accessed: set[str] = set()
+    try:
+        record_source("pyproject.toml")
+        os.chdir(project_root)
+        sys.path.insert(0, str(project_root))
+        _install_namespace(namespace, project_root)
+        runtime_config = _import_project_module(namespace, project_config.config_target, "configuration")
+        model_module_name, callable_name = split_callable_target(project_config.model_target)
+        model_module = _import_project_module(namespace, model_module_name, "model")
+        builder = getattr(model_module, callable_name, None)
+        _validate_entry_point(builder, project_config.model_target, "Model")
+        typed_builder = cast(Callable[[BuildContext], Any], builder)
+        context = BuildContext(project_root, runtime_config, revision, dirty)
+        try:
+            model = typed_builder(context)
+        except CadToolsError:
+            raise
+        except Exception as error:
+            raise ModelValidationError(f"Model entry point {project_config.model_target!r} failed: {error}") from error
+        if not isinstance(model, DesignModel):
+            raise ModelValidationError(
+                f"Model entry point {project_config.model_target!r} returned {type(model).__name__}; expected DesignModel"
+            )
+        issues = tuple(validate_model(model))
+        drawing_sheets: tuple[DrawingSheet, ...] = ()
+        annotations: DrawingAnnotationSet | None = None
+        if include_drawings:
+            drawing_sheets = standard_sheet_catalog(model)
+            if project_config.drawing_annotations_target is not None:
+                annotation_module_name, annotation_callable_name = split_callable_target(
+                    project_config.drawing_annotations_target
+                )
+                annotation_module = _import_project_module(namespace, annotation_module_name, "drawing annotation")
+                provider = getattr(annotation_module, annotation_callable_name, None)
+                _validate_entry_point(provider, project_config.drawing_annotations_target, "Drawing annotation")
+                typed_provider = cast(Callable[[DrawingContext], Any], provider)
+                drawing_context = DrawingContext(project_root, runtime_config, model, drawing_sheets)
+                try:
+                    annotations = validate_annotation_set(typed_provider(drawing_context), drawing_sheets)
+                except CadToolsError:
+                    raise
+                except Exception as error:
+                    raise ModelValidationError(
+                        f"Drawing annotation entry point {project_config.drawing_annotations_target!r} failed: {error}"
+                    ) from error
+        accessed.update(_project_module_sources(project_root, snapshot.modules))
+        accessed.update(end_source_tracking(token))
+        tracking_active = False
+        undeclared = sorted(accessed - project_config.declared_sources)
+        if undeclared:
+            raise ProjectConfigError(
+                "Loaded authoritative project input(s) missing from source-inputs: " + ", ".join(undeclared)
+            )
+        return LoadedProject(
+            project_root=project_root,
+            project_config=project_config,
+            runtime_config=runtime_config,
+            model=model,
+            issues=issues,
+            source_inputs=tuple(sorted(accessed)),
+            source_revision=revision,
+            source_dirty=dirty,
+            drawing_sheets=drawing_sheets,
+            annotations=annotations,
+        )
+    finally:
+        if tracking_active:
+            end_source_tracking(token)
+        snapshot.restore()
+
+
+def _install_namespace(namespace: str, project_root: Path) -> None:
+    package = ModuleType(namespace)
+    package.__file__ = None
+    package.__package__ = namespace
+    package.__path__ = [str(project_root)]
+    package.__spec__ = ModuleSpec(namespace, loader=None, is_package=True)
+    sys.modules[namespace] = package
+    importlib.invalidate_caches()
+
+
+def _import_project_module(namespace: str, target: str, label: str) -> ModuleType:
+    qualified = f"{namespace}.{target}"
+    try:
+        return importlib.import_module(qualified)
+    except CadToolsError:
+        raise
+    except Exception as error:
+        raise ProjectConfigError(f"Unable to import project {label} module {target!r}: {error}") from error
+
+
+def _validate_entry_point(builder: Any, target: str, label: str) -> None:
+    if not callable(builder):
+        raise ProjectConfigError(f"{label} target {target!r} does not resolve to a callable")
+    try:
+        signature = inspect.signature(builder)
+    except (TypeError, ValueError) as error:
+        raise ProjectConfigError(f"Unable to inspect {label.lower()} target {target!r}: {error}") from error
+    parameters = tuple(signature.parameters.values())
+    valid = (
+        len(parameters) == 1
+        and parameters[0].name == "context"
+        and parameters[0].kind in {inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD}
+        and parameters[0].default is inspect.Parameter.empty
+    )
+    if not valid:
+        required = "build_model(context)" if label == "Model" else "build_annotations(context)"
+        raise ProjectConfigError(f"{label} target {target!r} must have the exact signature {required}")
+
+
+def _project_module_sources(project_root: Path, original_modules: dict[str, ModuleType]) -> set[str]:
+    sources: set[str] = set()
+    for name, module in sys.modules.items():
+        if original_modules.get(name) is module:
+            continue
+        raw = getattr(module, "__file__", None)
+        if not raw:
+            continue
+        path = Path(raw)
+        if path.suffix in {".pyc", ".pyo"}:
+            try:
+                raw = source_from_cache(str(path))
+            except ValueError:
+                continue
+            path = Path(raw)
+        lexical = Path(os.path.abspath(path))
+        if lexical.is_relative_to(project_root):
+            _, relative = authoritative_path(project_root, lexical.relative_to(project_root).as_posix())
+            sources.add(relative)
+    return sources
+
+
+def _source_state(project_root: Path) -> tuple[str | None, bool]:
+    revision = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=project_root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if revision.returncode != 0:
+        return None, False
+    status = subprocess.run(
+        ["git", "status", "--short", "--untracked-files=normal"],
+        cwd=project_root,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    return revision.stdout.strip(), status.returncode != 0 or bool(status.stdout.strip())

python_cad_tools/_project_state.py

@@ -0,0 +1,65 @@
+"""Operation-local authoritative source tracking for project contexts."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from pathlib import Path
+from typing import BinaryIO, Literal, TextIO
+
+from .exceptions import ProjectConfigError, UnsafePathError
+
+_accessed_sources: ContextVar[set[str] | None] = ContextVar("python_cad_accessed_sources", default=None)
+
+
+def begin_source_tracking() -> Token[set[str] | None]:
+    return _accessed_sources.set(set())
+
+
+def end_source_tracking(token: Token[set[str] | None]) -> set[str]:
+    accessed = _accessed_sources.get()
+    _accessed_sources.reset(token)
+    return set() if accessed is None else accessed
+
+
+def record_source(relative_path: str) -> None:
+    accessed = _accessed_sources.get()
+    if accessed is None:
+        raise ProjectConfigError("Authoritative project files may be accessed only while a project entry point is running")
+    accessed.add(relative_path)
+
+
+def authoritative_path(project_root: Path, relative_path: str | Path) -> tuple[Path, str]:
+    raw = str(relative_path)
+    parts = raw.split("/")
+    if not raw or "\\" in raw or "\x00" in raw or ":" in raw or any(part in {"", ".", ".."} for part in parts):
+        raise UnsafePathError(f"Unsafe project-relative source path: {raw!r}")
+    candidate = Path(*parts)
+    if candidate.is_absolute():
+        raise UnsafePathError(f"Unsafe project-relative source path: {raw!r}")
+    root = project_root.resolve()
+    target = root
+    traverses_symlink = False
+    for part in candidate.parts:
+        target /= part
+        traverses_symlink = traverses_symlink or target.is_symlink()
+    if traverses_symlink or not target.is_file():
+        raise ProjectConfigError(f"Authoritative source must be a regular, non-symlink file: {candidate.as_posix()}")
+    resolved = target.resolve()
+    if not resolved.is_relative_to(root):
+        raise UnsafePathError(f"Authoritative source escapes the project root: {candidate.as_posix()}")
+    return resolved, candidate.as_posix()
+
+
+def open_authoritative_source(
+    project_root: Path,
+    relative_path: str | Path,
+    mode: Literal["r", "rb"],
+    encoding: str | None,
+) -> TextIO | BinaryIO:
+    if mode not in {"r", "rb"}:
+        raise ValueError("BuildContext.open_source supports only 'r' and 'rb'")
+    target, relative = authoritative_path(project_root, relative_path)
+    record_source(relative)
+    if mode == "rb":
+        return target.open("rb")
+    return target.open("r", encoding=encoding or "utf-8")

python_cad_tools/_scaffold.py

@@ -0,0 +1,66 @@
+"""Generic project scaffold creation for the ``python-cad init`` command."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .exceptions import ProjectConfigError, UnsafePathError
+
+_TEMPLATE_DIR = Path(__file__).resolve().parent / "templates" / "project"
+
+
+@dataclass(frozen=True, slots=True)
+class ScaffoldResult:
+    destination: Path
+    created_files: tuple[str, ...]
+
+
+def scaffold_project(destination: Path, *, force: bool = False) -> ScaffoldResult:
+    root = destination.expanduser().resolve()
+    if not root.parent.exists():
+        raise ProjectConfigError(f"Parent directory does not exist: {root.parent}")
+    if root.is_symlink():
+        raise UnsafePathError(f"Destination must not be a symlink: {root}")
+    _validate_safe_path(root)
+
+    existing: list[Path] = []
+    if root.exists():
+        for child in root.iterdir():
+            if child.name == ".git":
+                continue
+            existing.append(child)
+    if existing and not force:
+        raise ProjectConfigError(
+            f"Destination is not empty: {root}; use --force to overwrite scaffold files"
+        )
+
+    root.mkdir(parents=True, exist_ok=True)
+    created: list[str] = []
+    for template in sorted(_TEMPLATE_DIR.rglob("*")):
+        if not template.is_file():
+            continue
+        relative = template.relative_to(_TEMPLATE_DIR)
+        target = root / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists() or target.is_symlink():
+            if not force:
+                continue
+            if target.is_dir() and not target.is_symlink():
+                target.rmdir()
+            else:
+                target.unlink()
+        target.write_bytes(template.read_bytes())
+        created.append(relative.as_posix())
+    return ScaffoldResult(root, tuple(created))
+
+
+def _validate_safe_path(path: Path) -> None:
+    resolved = path.resolve(strict=False)
+    parts = resolved.parts
+    if not parts:
+        raise UnsafePathError(f"Unsafe destination: {path}")
+    dangerous = {"", ".", ".."}
+    for part in parts:
+        if part in dangerous:
+            raise UnsafePathError(f"Unsafe destination component: {part!r} in {path}")

python_cad_tools/_transaction.py

@@ -0,0 +1,208 @@
+"""Recoverable, journaled same-filesystem directory promotion."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import uuid
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .determinism import canonical_json_bytes
+from .exceptions import ArtifactIntegrityError, UnsafePathError
+
+PROMOTION_SCHEMA = "urn:python-cad-tools:schema:promotion-journal:1"
+VerifyDirectory = Callable[[Path], object]
+
+
+def staging_directory(output: Path) -> Path:
+    return output.with_name(f".{output.name}-staging-{uuid.uuid4().hex}")
+
+
+def recover_promotion(output: Path, verify: VerifyDirectory) -> None:
+    journal = _journal_path(output)
+    if not journal.exists():
+        _recover_orphans(output, verify)
+        return
+    document = _read_journal(journal, output)
+    staging = output.parent / document["staging_name"]
+    backup = output.parent / document["backup_name"]
+
+    output_valid = _is_valid(output, verify)
+    backup_valid = _is_valid(backup, verify)
+    if output_valid:
+        _safe_remove(backup)
+        _safe_remove(staging)
+        journal.unlink(missing_ok=True)
+        _fsync_directory(output.parent)
+        return
+    if backup_valid:
+        _safe_remove(output)
+        os.replace(backup, output)
+        _safe_remove(staging)
+        journal.unlink(missing_ok=True)
+        _fsync_directory(output.parent)
+        return
+    if document["state"] == "prepared" and output.exists() and not backup.exists():
+        _safe_remove(staging)
+        journal.unlink(missing_ok=True)
+        _fsync_directory(output.parent)
+        return
+    raise UnsafePathError(f"Cannot safely recover interrupted promotion recorded by {journal}")
+
+
+def _recover_orphans(output: Path, verify: VerifyDirectory) -> None:
+    staging = sorted(output.parent.glob(f".{output.name}-staging-*"))
+    backups = sorted(output.parent.glob(f".{output.name}-backup-*"))
+    if not staging and not backups:
+        return
+    if _is_valid(output, verify):
+        for path in [*staging, *backups]:
+            _safe_remove(path)
+        _fsync_directory(output.parent)
+        return
+    valid_backups = [path for path in backups if _is_valid(path, verify)]
+    if len(valid_backups) == 1:
+        _safe_remove(output)
+        os.replace(valid_backups[0], output)
+        for path in [*staging, *backups]:
+            if path != valid_backups[0]:
+                _safe_remove(path)
+        _fsync_directory(output.parent)
+        return
+    raise UnsafePathError(f"Cannot safely recover stale promotion paths adjacent to {output}")
+
+
+def promote_directory(staging: Path, output: Path, verify: VerifyDirectory) -> None:
+    _validate_destination(output)
+    if staging.parent != output.parent or not staging.name.startswith(f".{output.name}-staging-"):
+        raise UnsafePathError(f"Invalid staging directory for {output}: {staging}")
+    transaction = uuid.uuid4().hex
+    backup = output.with_name(f".{output.name}-backup-{transaction}")
+    journal = _journal_path(output)
+    document: dict[str, Any] = {
+        "schema_id": PROMOTION_SCHEMA,
+        "schema_version": 1,
+        "output_name": output.name,
+        "staging_name": staging.name,
+        "backup_name": backup.name,
+        "state": "prepared",
+    }
+    _write_state(journal, document, "prepared")
+    try:
+        if output.exists():
+            _around("rename_output_to_backup", lambda: os.replace(output, backup))
+        _write_state(journal, document, "backup")
+        _around("rename_staging_to_output", lambda: os.replace(staging, output))
+        _write_state(journal, document, "promoted")
+        verify(output)
+    except BaseException:
+        if backup.exists():
+            _safe_remove(output)
+            os.replace(backup, output)
+        raise
+    else:
+        _safe_remove(backup)
+        _safe_remove(staging)
+        journal.unlink(missing_ok=True)
+        _fsync_directory(output.parent)
+
+
+def _journal_path(output: Path) -> Path:
+    return output.with_name(f".{output.name}-promotion.json")
+
+
+def _write_state(path: Path, document: dict[str, Any], state: str) -> None:
+    document["state"] = state
+
+    def write() -> None:
+        temporary = path.with_suffix(f".tmp-{uuid.uuid4().hex}")
+        try:
+            temporary.write_bytes(canonical_json_bytes(document))
+            with temporary.open("r+b") as stream:
+                os.fsync(stream.fileno())
+            os.replace(temporary, path)
+            _fsync_directory(path.parent)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    _around(f"write_journal_{state}", write)
+
+
+def _around(name: str, operation: Callable[[], None]) -> None:
+    _crash(f"before_{name}")
+    operation()
+    _crash(f"after_{name}")
+
+
+def _crash(point: str) -> None:
+    if os.environ.get("PYTHON_CAD_TEST_CRASH_POINT") == point:
+        os._exit(91)
+
+
+def _read_journal(path: Path, output: Path) -> dict[str, Any]:
+    if path.is_symlink() or not path.is_file():
+        raise UnsafePathError(f"Unsafe promotion journal: {path}")
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as error:
+        raise UnsafePathError(f"Invalid promotion journal {path}: {error}") from error
+    required = {"schema_id", "schema_version", "output_name", "staging_name", "backup_name", "state"}
+    if not isinstance(value, dict) or set(value) != required:
+        raise UnsafePathError(f"Invalid promotion journal shape: {path}")
+    if value["schema_id"] != PROMOTION_SCHEMA or value["schema_version"] != 1:
+        raise UnsafePathError(f"Unsupported promotion journal schema: {path}")
+    if value["output_name"] != output.name or value["state"] not in {"prepared", "backup", "promoted"}:
+        raise UnsafePathError(f"Promotion journal does not match {output}")
+    if not _safe_transaction_name(value["staging_name"], output.name, "staging"):
+        raise UnsafePathError(f"Unsafe staging name in {path}")
+    if not _safe_transaction_name(value["backup_name"], output.name, "backup"):
+        raise UnsafePathError(f"Unsafe backup name in {path}")
+    return value
+
+
+def _safe_transaction_name(value: object, output_name: str, kind: str) -> bool:
+    return (
+        isinstance(value, str)
+        and value.startswith(f".{output_name}-{kind}-")
+        and "/" not in value
+        and "\\" not in value
+        and value not in {".", ".."}
+    )
+
+
+def _validate_destination(output: Path) -> None:
+    if output.is_symlink() or not output.parent.is_dir():
+        raise UnsafePathError(f"Unsafe output directory: {output}")
+    if output.exists() and not output.is_dir():
+        raise UnsafePathError(f"Configured output is not a directory: {output}")
+
+
+def _is_valid(path: Path, verify: VerifyDirectory) -> bool:
+    if not path.is_dir() or path.is_symlink():
+        return False
+    try:
+        verify(path)
+    except (ArtifactIntegrityError, OSError, ValueError):
+        return False
+    return True
+
+
+def _safe_remove(path: Path) -> None:
+    if path.is_symlink() or path.is_file():
+        path.unlink(missing_ok=True)
+    elif path.is_dir():
+        shutil.rmtree(path)
+
+
+def _fsync_directory(path: Path) -> None:
+    if sys.platform == "win32":
+        return
+    descriptor = os.open(path, os.O_RDONLY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)