DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""Small, dependency-free helpers for durable service files."""
from __future__ import annotations
import json
import logging
import os
from pathlib import Path
import tempfile
import threading
import time
from typing import Any, Callable, TypeVar
logger = logging.getLogger(__name__)
T = TypeVar("T")
# fsync failures weaken the durability promise but do not corrupt the write:
# the replacement below still publishes complete content. Warn about them,
# rate-limited, so a failing disk fills the log once per interval instead of
# once per write.
_FSYNC_WARNING_INTERVAL_SECONDS = 60.0
_last_fsync_warning_at: float | None = None
_fsync_warning_lock = threading.Lock()
def _sync_to_disk(handle: Any, path: Path) -> None:
"""fsync *handle*, surfacing a failure as a rate-limited warning."""
global _last_fsync_warning_at
try:
os.fsync(handle.fileno())
except OSError as exc:
now = time.monotonic()
with _fsync_warning_lock:
should_warn = (
_last_fsync_warning_at is None
or now - _last_fsync_warning_at >= _FSYNC_WARNING_INTERVAL_SECONDS
)
if should_warn:
_last_fsync_warning_at = now
if should_warn:
logger.warning(
"fsync failed while writing %s; the write succeeded but is not"
" guaranteed durable on disk (%r)",
path,
exc,
)
def _retry_permission_error(operation: Callable[[], T], *, max_retries: int) -> T:
"""Run *operation*, retrying a transient ``PermissionError`` with backoff.
On Windows a file is occasionally locked by another process (antivirus,
indexer, or a concurrent reader), which makes opening or replacing it
raise ``PermissionError``. A short exponential backoff recovers in most
cases; a lock that outlasts it is re-raised unchanged.
"""
delay = 0.2
for attempt in range(max_retries):
try:
return operation()
except PermissionError:
if attempt == max_retries - 1:
raise
time.sleep(delay)
delay = min(delay * 2, 1.6)
raise ValueError("max_retries must be at least 1")
def _atomic_replace(src: Path, dst: Path, *, max_retries: int = 5) -> None:
"""Replace *dst* with *src*, retrying on transient ``PermissionError``."""
_retry_permission_error(lambda: src.replace(dst), max_retries=max_retries)
def read_text(path: Path, *, max_retries: int = 5) -> str:
"""Read a UTF-8 file written by the atomic helpers below.
Reads use the writers' encoding instead of the locale default, and a
transient Windows sharing lock gets the same bounded retry as writes.
``FileNotFoundError`` and decoding errors propagate immediately.
"""
path = Path(path)
return _retry_permission_error(
lambda: path.read_text(encoding="utf-8"), max_retries=max_retries
)
def atomic_write_json(path: Path, payload: dict[str, Any]) -> None:
"""Write *payload* as UTF-8 JSON without exposing a partial target file."""
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
temporary_path: Path | None = None
try:
with tempfile.NamedTemporaryFile(
"w",
encoding="utf-8",
dir=str(path.parent),
delete=False,
) as handle:
temporary_path = Path(handle.name)
json.dump(payload, handle, indent=2, ensure_ascii=False)
handle.write("\n")
handle.flush()
_sync_to_disk(handle, path)
_atomic_replace(temporary_path, path)
finally:
if temporary_path is not None:
temporary_path.unlink(missing_ok=True)
def atomic_write_text(path: Path, text: str) -> None:
"""Write UTF-8 text with a same-directory atomic replacement."""
path = Path(path)
path.parent.mkdir(parents=True, exist_ok=True)
temporary_path: Path | None = None
try:
with tempfile.NamedTemporaryFile(
"w",
encoding="utf-8",
dir=str(path.parent),
delete=False,
) as handle:
temporary_path = Path(handle.name)
handle.write(text)
handle.flush()
_sync_to_disk(handle, path)
_atomic_replace(temporary_path, path)
finally:
if temporary_path is not None:
temporary_path.unlink(missing_ok=True)
__all__ = ["atomic_write_json", "atomic_write_text", "read_text"]