sharefetch 1.0.0__py3-none-any.whl

sharefetch/manifest.py

@@ -0,0 +1,198 @@
+"""The run's user-facing record: one CSV row per enumerated item.
+
+The manifest answers, for a person who was not watching the run, what the tool
+was asked to fetch and what happened to each item. Every enumerated item gets a
+row whatever its status, so a run finishing with failures produces a manifest
+recording those failures next to the files that succeeded. The filename, the
+encoding and the ten columns are fixed.
+
+The file is written UTF-8 with a BOM, because it exists to be opened in Excel
+by double-click and Excel reads a BOM-less UTF-8 CSV as the system codepage.
+
+Nothing here removes a file. The rows go to ``manifest.csv.tmp`` which is
+renamed onto ``manifest.csv`` by ``os.replace``, so a run interrupted mid-write
+leaves the previous manifest whole and never a truncated one.
+
+Two column readings this module settles, because the fixed list names the
+columns without defining them:
+
+``local_path``
+    Written absolute, resolved against the destination the caller passes. The
+    ``relative_path`` column already carries the drive-relative form, so a
+    second relative path would duplicate it for every item except a sanitised
+    one. An absolute path pastes into Explorer. The state file's own
+    ``local_path`` field stays destination-relative and is unaffected.
+
+``verification_reason``
+    Carries the failing check's reason where verification failed, and the
+    advisory findings where it passed with warnings. Check 5 warns and never
+    fails, and this is the only column in the fixed ten that can report it.
+"""
+
+import csv
+import logging
+import os
+from pathlib import Path
+
+from .config import MANIFEST_FILENAME, TMP_SUFFIX
+from .errors import ManifestError
+from .paths import long_path
+from .state import ItemState, StateStore
+
+logger = logging.getLogger(__name__)
+
+# The fixed ten columns, in order. The header row and every data row are built
+# from this tuple, so the two cannot drift.
+MANIFEST_COLUMNS = (
+    "relative_path",
+    "local_path",
+    "size_bytes",
+    "ctag",
+    "etag",
+    "status",
+    "verification_status",
+    "verification_reason",
+    "original_name",
+    "completed_at",
+)
+
+# Excel and LibreOffice treat a cell opening with one of these as a formula
+# rather than as text. A SharePoint library can hold a file whose name starts
+# with any of them, so the condition is reported at WARNING and the value is
+# still written byte for byte. Rewriting it would make the manifest disagree
+# with the state file and with the name on disk, which is the one thing a
+# record of a download may not do.
+FORMULA_LEAD_CHARACTERS = ("=", "+", "-", "@", "\t", "\r")
+
+# The keys verify.VerificationResult.to_dict() writes. The manifest reads the
+# dictionary the state file carries rather than importing the dataclass,
+# because a record loaded from a previous run is a plain dictionary.
+_VERIFICATION_STATUS_KEY = "status"
+_VERIFICATION_REASON_KEY = "reason"
+_VERIFICATION_WARNINGS_KEY = "warnings"
+
+# Separates several advisory findings inside the one reason cell. A space
+# follows so Excel wraps the cell on the separator.
+_WARNING_SEPARATOR = "; "
+
+
+def _cell(value: object) -> str:
+    """Return the text written for one field.
+
+    ``None`` becomes an empty cell. Every other value is rendered by ``str``,
+    so an integer size is written without a thousands separator and a boolean
+    never reaches a cell at all.
+    """
+    if value is None:
+        return ""
+    return str(value)
+
+
+def _verification_cells(verification: object) -> tuple[str, str]:
+    """Return the ``verification_status`` and ``verification_reason`` cells.
+
+    ``verification`` is the dictionary
+    :meth:`verify.VerificationResult.to_dict` produced, as the state file
+    carries it, or ``None`` for an item that never reached verification. A
+    record that is neither is reported at WARNING and written as two empty
+    cells, because a manifest that omits a row is worse than one that omits a
+    verdict.
+    """
+    if verification is None:
+        return "", ""
+    if not isinstance(verification, dict):
+        logger.warning(
+            "verification record is a %s, expected an object; its manifest cells are left empty",
+            type(verification).__name__,
+        )
+        return "", ""
+
+    status = _cell(verification.get(_VERIFICATION_STATUS_KEY))
+    reason = _cell(verification.get(_VERIFICATION_REASON_KEY))
+    if reason:
+        return status, reason
+
+    warnings = verification.get(_VERIFICATION_WARNINGS_KEY)
+    if isinstance(warnings, (list, tuple)):
+        return status, _WARNING_SEPARATOR.join(_cell(warning) for warning in warnings)
+    if warnings is not None:
+        logger.warning(
+            "verification warnings are a %s, expected a list; "
+            "the manifest reason cell is left empty",
+            type(warnings).__name__,
+        )
+    return status, ""
+
+
+def _row(relative_path: str, item: ItemState, dest: Path) -> list[str]:
+    """Build one data row, in ``MANIFEST_COLUMNS`` order."""
+    values = {
+        "relative_path": relative_path,
+        "local_path": str(dest / item.local_path),
+        "size_bytes": item.size,
+        "ctag": item.ctag,
+        "etag": item.etag,
+        "status": item.status,
+        "original_name": item.original_name,
+        "completed_at": item.completed_at,
+    }
+    verification_status, verification_reason = _verification_cells(item.verification)
+    values["verification_status"] = verification_status
+    values["verification_reason"] = verification_reason
+    return [_cell(values[column]) for column in MANIFEST_COLUMNS]
+
+
+def _warn_on_formula_leads(rows: list[list[str]]) -> None:
+    """Report cells a spreadsheet will evaluate as a formula.
+
+    The count is logged once for the whole manifest, with the first offending
+    cell named, so a library holding a hundred such names produces one line and
+    not a hundred. The values themselves are written unchanged.
+    """
+    offenders = [cell for row in rows for cell in row if cell.startswith(FORMULA_LEAD_CHARACTERS)]
+    if not offenders:
+        return
+    logger.warning(
+        "%d manifest cell(s) open with a character a spreadsheet evaluates as a formula, "
+        "the first being %r; the values are written unchanged and the file is safe to "
+        "read as text",
+        len(offenders),
+        offenders[0],
+    )
+
+
+def write_manifest(store: StateStore, dest: Path) -> Path:
+    """Write ``<dest>/manifest.csv`` and return the path written.
+
+    Every item the store holds gets a row, ordered by its drive-relative path,
+    so two runs over an unchanged tree produce byte-identical manifests
+    whatever order the enumeration returned.
+
+    Raises :class:`errors.ManifestError` where the file cannot be written. The
+    caller decides what a failure means for the run's exit status; the
+    downloaded tree is already on disk and is unaffected either way.
+    """
+    dest = Path(dest)
+    manifest_path = dest / MANIFEST_FILENAME
+    tmp_path = dest / (MANIFEST_FILENAME + TMP_SUFFIX)
+
+    items = store.all_items()
+    rows = [_row(relative_path, items[relative_path], dest) for relative_path in sorted(items)]
+    _warn_on_formula_leads(rows)
+
+    try:
+        os.makedirs(long_path(dest), exist_ok=True)  # noqa: PTH103
+        with open(  # noqa: PTH123
+            long_path(tmp_path), "w", encoding="utf-8-sig", newline=""
+        ) as handle:
+            writer = csv.writer(handle)
+            writer.writerow(MANIFEST_COLUMNS)
+            writer.writerows(rows)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(long_path(tmp_path), long_path(manifest_path))  # noqa: PTH105
+    except OSError as exc:
+        raise ManifestError(f"the manifest {manifest_path} could not be written: {exc}") from exc
+
+    logger.info("manifest written to %s with %d item(s)", manifest_path, len(rows))
+    return manifest_path

sharefetch/pacing.py

@@ -0,0 +1,211 @@
+"""Traffic discipline: one shared pacer, the backoff curve and ``Retry-After``.
+
+A single ``Pacer`` instance is shared by every worker and by enumeration.
+Per-worker pacing doubles the effective request rate at concurrency 2, so the
+sharing is the mechanism this module exists to provide, and the inter-request
+delay, the byte-rate ceiling and the throttle hold are all measured globally
+across that one instance.
+
+``sleep``, ``clock`` and ``rand`` are injected so the behaviour is testable
+without elapsing real time. Nothing in this module calls ``time.sleep``
+directly.
+"""
+
+import logging
+import random
+import re
+import threading
+import time
+from collections.abc import Callable
+from datetime import timezone
+from email.utils import parsedate_to_datetime
+
+from .config import (
+    BACKOFF_BASE_SECONDS,
+    BACKOFF_CAP_SECONDS,
+    RETRY_AFTER_CLAMP,
+    check_delay,
+    check_limit_rate,
+)
+
+logger = logging.getLogger(__name__)
+
+# RFC 7231 delay-seconds is one or more digits and nothing else. Anything that
+# is not this shape is tried as an HTTP-date.
+_DELAY_SECONDS = re.compile(r"^\d+$")
+
+
+class Pacer:
+    """Global inter-request delay, byte-rate ceiling and throttle hold.
+
+    One instance is shared by every worker. ``acquire`` is called once per
+    request, ``consume`` once per chunk read, and ``hold`` once per ``429`` or
+    ``503``. A hold set from one worker is observed by every other worker
+    inside ``acquire``.
+
+    The lock guards ``_next_request``, ``_hold_until`` and the token bucket. It
+    is never held across a sleep, so a worker meeting a throttle can publish
+    its hold while another worker is waiting out a delay.
+    """
+
+    def __init__(
+        self,
+        delay: float,
+        limit_rate_kbps: int | None,
+        sleep: Callable[[float], None] = time.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._delay = float(check_delay(delay))
+        limit = check_limit_rate(limit_rate_kbps)
+        self._sleep = sleep
+        self._clock = clock
+        self._lock = threading.Lock()
+
+        # The next instant at which a request may leave. Initialised to the
+        # far past so the first acquire never waits.
+        self._next_request = float("-inf")
+        self._hold_until = float("-inf")
+
+        # A ceiling of None leaves the bucket off and makes consume a no-op.
+        # Capacity is one second of allowance, so a burst of up to one
+        # second's worth of bytes passes without a wait. The 1024 conversion
+        # from KB/s to bytes per second matches config.Settings.chunk_bytes.
+        self._rate: float | None = None if limit is None else float(limit) * 1024
+        self._capacity = 0.0 if self._rate is None else self._rate
+        self._tokens = self._capacity
+        self._bucket_updated = self._clock()
+
+    @property
+    def delay(self) -> float:
+        """The configured inter-request delay in seconds."""
+        return self._delay
+
+    @property
+    def rate_bytes_per_second(self) -> float | None:
+        """The configured byte-rate ceiling, or ``None`` when the ceiling is off."""
+        return self._rate
+
+    def acquire(self) -> None:
+        """Block until the inter-request delay and any active hold have elapsed.
+
+        Claiming the next slot happens under the lock, so two workers calling
+        at the same instant are staggered by the delay instead of both firing.
+        The hold is re-read after every sleep, so a hold published while this
+        worker was waiting is still observed.
+        """
+        while True:
+            with self._lock:
+                now = self._clock()
+                ready_at = max(self._next_request, self._hold_until)
+                if ready_at <= now:
+                    self._next_request = now + self._delay
+                    return
+                wait = ready_at - now
+            logger.debug("pacer waiting %.3fs before the next request", wait)
+            self._sleep(wait)
+
+    def consume(self, n: int) -> None:
+        """Block as long as the byte-rate ceiling requires after reading ``n`` bytes.
+
+        Returns immediately when no ceiling is configured. A chunk larger than
+        one second of allowance is charged in full and waited out in full, so
+        the ceiling holds for any chunk size.
+        """
+        if self._rate is None or n <= 0:
+            return
+        with self._lock:
+            now = self._clock()
+            elapsed = now - self._bucket_updated
+            if elapsed > 0:
+                self._tokens = min(self._capacity, self._tokens + elapsed * self._rate)
+                self._bucket_updated = now
+            # The balance is allowed to go negative. The debt is visible to
+            # every other worker, so two workers sharing one ceiling each wait
+            # out the combined overdraft rather than half of it.
+            self._tokens -= n
+            wait = 0.0 if self._tokens >= 0 else -self._tokens / self._rate
+        if wait > 0:
+            logger.debug("pacer waiting %.3fs to stay under the byte-rate ceiling", wait)
+            self._sleep(wait)
+
+    def hold(self, seconds: float) -> None:
+        """Set a global floor that every worker observes inside ``acquire``.
+
+        The floor only ever moves later, so a short hold never shortens a hold
+        already in force.
+        """
+        if seconds <= 0:
+            return
+        with self._lock:
+            until = self._clock() + seconds
+            if until <= self._hold_until:
+                logger.debug(
+                    "pacer hold of %.3fs is shorter than the hold already in force", seconds
+                )
+                return
+            self._hold_until = until
+        logger.info("pacer holding every worker for %.3fs", seconds)
+
+
+def backoff_delay(attempt: int, rand: Callable[[float, float], float] = random.uniform) -> float:
+    """Full-jitter exponential backoff for ``attempt``, counted from 1.
+
+    The jitter is applied so two workers recovering from the same outage do
+    not resynchronise.
+    """
+    if attempt < 1:
+        raise ValueError(f"attempt is counted from 1, received {attempt}")
+    computed = min(BACKOFF_BASE_SECONDS * 2 ** (attempt - 1), BACKOFF_CAP_SECONDS)
+    return rand(0.0, computed)
+
+
+def parse_retry_after(value: str | None, now: float | None = None) -> float | None:
+    """Return the ``Retry-After`` wait in seconds, or ``None`` when unusable.
+
+    Both forms RFC 7231 allows are accepted: delay-seconds as a bare integer,
+    and an HTTP-date. A missing, empty or unparseable value returns ``None``,
+    which the caller treats as a fall-through to ``backoff_delay``. The result
+    is clamped to ``config.RETRY_AFTER_CLAMP``, so a date already in the past
+    gives 0.0 and an implausibly distant one gives the ceiling.
+
+    ``now`` is epoch seconds and defaults to ``time.time()``. It is a wall
+    clock rather than a monotonic one because an HTTP-date is an absolute
+    instant.
+    """
+    if value is None:
+        return None
+    text = value.strip()
+    if not text:
+        return None
+
+    if _DELAY_SECONDS.match(text):
+        return _clamp(float(text))
+
+    seconds = _seconds_until_http_date(text, now)
+    if seconds is None:
+        logger.warning("Retry-After header %r is neither delay-seconds nor an HTTP-date", text)
+        return None
+    return _clamp(seconds)
+
+
+def _seconds_until_http_date(text: str, now: float | None) -> float | None:
+    try:
+        when = parsedate_to_datetime(text)
+    except (ValueError, TypeError):
+        return None
+    if when is None:  # pragma: no cover - older stdlib returned None here
+        return None
+    if when.tzinfo is None:
+        # RFC 7231 requires GMT. A date arriving without a zone is read as UTC
+        # rather than as local time, which would shift it by the offset.
+        when = when.replace(tzinfo=timezone.utc)
+    reference = time.time() if now is None else now
+    return when.timestamp() - reference
+
+
+def _clamp(seconds: float) -> float:
+    low, high = RETRY_AFTER_CLAMP
+    clamped = min(max(seconds, low), high)
+    if clamped != seconds:
+        logger.info("Retry-After of %.3fs clamped to %.3fs", seconds, clamped)
+    return clamped

sharefetch/paths.py

@@ -0,0 +1,245 @@
+"""Mapping a Graph drive-relative path onto a local path Windows accepts.
+
+The remote name space allows names the local one refuses. A drive item may be
+named ``report:final.txt``, may end in a dot or a space, may collide with a
+reserved device name such as ``CON``, and may exceed the 255-character ceiling a
+single Windows path component carries. This module holds every rule that closes
+that gap, and it holds them once, so the enumerator, the transfer loop, the
+state store and the manifest writer all agree on where an item lands.
+
+The module is pure: it opens no socket, reads no clock and touches no file. The
+``\\\\?\\`` prefix ``long_path`` produces is applied at the filesystem boundary
+and nowhere else; the internal representation stays an ordinary
+``pathlib.Path``.
+
+Every substitution is logged at INFO, so a run's log recovers the mapping back
+to the original name even where the state file is discarded.
+"""
+
+import ctypes
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import (
+    MAX_PATH_SEGMENT,
+    WINDOWS_FORBIDDEN_CHARS,
+    WINDOWS_RESERVED_NAMES,
+)
+from .config import REASON_PATH_TOO_LONG as _REASON_PATH_TOO_LONG
+from .errors import ValidationError
+
+logger = logging.getLogger(__name__)
+
+REASON_PATH_TOO_LONG = _REASON_PATH_TOO_LONG
+REPLACEMENT = "_"
+COLLISION_MARKER = "~"
+CONTROL_CHARACTER_CEILING = 0x20
+TRAILING_STRIP_CHARS = ". "
+
+# Beyond the forbidden set config.py names: a backslash is a path separator on
+# Windows, so a backslash surviving inside a segment would silently split one
+# component into two. A separator never appears inside a segment, and replacing
+# it makes that hold rather than leaving it assumed.
+_FORBIDDEN_CHARACTERS = frozenset(
+    set(WINDOWS_FORBIDDEN_CHARS) | {"\\"} | {chr(code) for code in range(CONTROL_CHARACTER_CEILING)}
+)
+
+
+@dataclass(frozen=True)
+class MappedPath:
+    """Where one drive item lands below the destination root.
+
+    ``local_path`` is relative to the destination root and carries the platform
+    separator. ``sanitised`` is true where the local path differs from the
+    drive-relative path for any reason, including a collision suffix.
+    ``original_name`` carries the drive-relative path exactly as supplied, and
+    is set only where ``sanitised`` is true, so the manifest and the state file
+    can map the local name back to the remote one.
+    """
+
+    local_path: Path
+    sanitised: bool
+    original_name: str | None
+
+
+def sanitise_segment(name: str) -> tuple[str, bool]:
+    """Return one path component Windows accepts, and whether it changed.
+
+    The rules apply in a fixed order: replace every forbidden and control
+    character, strip the trailing run of dots and spaces, prefix a reserved
+    device name, then substitute a single underscore for an empty result.
+
+    Raises ``ValidationError`` where the result exceeds
+    ``config.MAX_PATH_SEGMENT`` characters. The result is never truncated,
+    because a truncated name no longer identifies the item it came from.
+    """
+    replaced = "".join(REPLACEMENT if char in _FORBIDDEN_CHARACTERS else char for char in name)
+    trimmed = replaced.rstrip(TRAILING_STRIP_CHARS)
+
+    stem = trimmed.partition(".")[0]
+    prefixed = REPLACEMENT + trimmed if stem.upper() in WINDOWS_RESERVED_NAMES else trimmed
+
+    result = prefixed if prefixed else REPLACEMENT
+
+    if len(result) > MAX_PATH_SEGMENT:
+        raise ValidationError(
+            f"{REASON_PATH_TOO_LONG}: path component is {len(result)} characters after "
+            f"sanitisation, above the {MAX_PATH_SEGMENT}-character Windows limit that the "
+            f"long-path prefix does not lift; the name is never truncated because truncation "
+            f"destroys identity"
+        )
+
+    changed = result != name
+    if changed:
+        logger.info("path component %r mapped to %r", name, result)
+    return result, changed
+
+
+def map_drive_path(drive_relative: str, taken: set[str]) -> MappedPath:
+    """Map a drive-relative path onto a local path below the destination root.
+
+    ``taken`` holds the lowercased string form of every local path already
+    assigned in this run. A candidate colliding with one of them gains a ``~1``,
+    ``~2`` suffix before its extension, incrementing until free, so the result
+    is deterministic in enumeration order. The caller owns ``taken`` and adds
+    the returned path to it; this function never mutates it.
+
+    Raises ``ValidationError`` where the path is empty or where a component
+    exceeds ``config.MAX_PATH_SEGMENT``.
+    """
+    raw_segments = [segment for segment in drive_relative.split("/") if segment]
+    if not raw_segments:
+        raise ValidationError(
+            f"drive-relative path {drive_relative!r} holds no path component, so it names no "
+            f"location below the destination root"
+        )
+
+    segments: list[str] = []
+    sanitised = False
+    for raw_segment in raw_segments:
+        mapped_segment, changed = sanitise_segment(raw_segment)
+        sanitised = sanitised or changed
+        segments.append(mapped_segment)
+
+    local_path = Path(*segments)
+    if str(local_path).lower() in taken:
+        local_path = _disambiguate(segments, taken)
+        sanitised = True
+
+    return MappedPath(
+        local_path=local_path,
+        sanitised=sanitised,
+        original_name=drive_relative if sanitised else None,
+    )
+
+
+def _disambiguate(segments: list[str], taken: set[str]) -> Path:
+    """Return the first free ``~N`` variant of the last component.
+
+    The loop terminates because ``taken`` is finite and every iteration
+    produces a distinct candidate, so at most ``len(taken) + 1`` candidates are
+    tested.
+    """
+    parents = segments[:-1]
+    leaf = segments[-1]
+
+    dot = leaf.rfind(".")
+    if dot > 0:
+        stem, suffix = leaf[:dot], leaf[dot:]
+    else:
+        stem, suffix = leaf, ""
+
+    index = 1
+    while True:
+        candidate_leaf = f"{stem}{COLLISION_MARKER}{index}{suffix}"
+        if len(candidate_leaf) > MAX_PATH_SEGMENT:
+            raise ValidationError(
+                f"{REASON_PATH_TOO_LONG}: resolving a name collision would make the path "
+                f"component {len(candidate_leaf)} characters, above the "
+                f"{MAX_PATH_SEGMENT}-character Windows limit"
+            )
+        candidate = Path(*parents, candidate_leaf)
+        if str(candidate).lower() not in taken:
+            logger.info(
+                "path component %r renamed to %r to resolve a collision", leaf, candidate_leaf
+            )
+            return candidate
+        index += 1
+
+
+def long_path(p: Path) -> str:
+    """Return the string form every filesystem call in the package uses.
+
+    On Windows the ``\\\\?\\`` prefix is applied unconditionally, because
+    ``LongPathsEnabled`` cannot be assumed on a managed machine. The prefix
+    disables normalisation, so the path is made absolute and backslash-
+    normalised first. On any other platform the path is returned unchanged.
+    """
+    if os.name != "nt":
+        return str(p)
+    resolved = Path(os.path.abspath(str(p)))  # noqa: PTH100
+    text = str(resolved)
+    if text.startswith("\\\\?\\"):
+        return text
+    if text.startswith("\\\\"):
+        return "\\\\?\\UNC\\" + text[2:]
+    return "\\\\?\\" + text
+
+
+# The Windows hidden attribute lives here rather than in tokencache.py so that
+# state.py can set it without importing an authentication library. Saving
+# download state has no business depending on msal.
+FILE_ATTRIBUTE_HIDDEN = 0x02
+FILE_ATTRIBUTE_NORMAL = 0x80
+INVALID_FILE_ATTRIBUTES = -1
+
+
+def windows_attributes(path: Path) -> int | None:
+    """Return the Win32 attributes of ``path``, or ``None`` when they cannot be read."""
+    current = ctypes.windll.kernel32.GetFileAttributesW(str(path))
+    if current == INVALID_FILE_ATTRIBUTES:
+        return None
+    return current
+
+
+def hide_file(path: Path) -> None:
+    """Set the Windows hidden attribute on ``path``.
+
+    A no-op off Windows, where a dot prefix carries the same meaning and no
+    attribute exists. A failure is logged at WARNING and never raised: the
+    attribute is a tidiness measure and no caller depends on it.
+    """
+    if os.name != "nt":
+        return
+    current = windows_attributes(path)
+    if current is None:
+        logger.warning("could not read the file attributes of %s", path)
+        return
+    if current & FILE_ATTRIBUTE_HIDDEN:
+        return
+    if not ctypes.windll.kernel32.SetFileAttributesW(str(path), current | FILE_ATTRIBUTE_HIDDEN):
+        logger.warning("could not set the hidden attribute on %s", path)
+
+
+def unhide_file(path: Path) -> None:
+    """Clear the Windows hidden attribute so a truncating rewrite can open the file.
+
+    ``FilePersistence.save`` opens the cache with ``O_CREAT | O_TRUNC``, which the
+    C runtime maps to ``CREATE_ALWAYS``. Windows refuses that call with
+    ``ERROR_ACCESS_DENIED`` when the existing file is hidden, so the attribute is
+    cleared for the duration of the write and restored immediately afterwards.
+    Both calls happen while ``PersistedTokenCache.modify`` holds its cross-process
+    lock, so no other writer observes the file unhidden.
+    """
+    if os.name != "nt":
+        return
+    current = windows_attributes(path)
+    if current is None or not current & FILE_ATTRIBUTE_HIDDEN:
+        return
+    cleared = current & ~FILE_ATTRIBUTE_HIDDEN
+    if cleared == 0:
+        cleared = FILE_ATTRIBUTE_NORMAL
+    if not ctypes.windll.kernel32.SetFileAttributesW(str(path), cleared):
+        logger.warning("could not clear the hidden attribute on %s", path)