win32-setctime

win32-setctime is a minimal, dependency-light Python package that exposes a single function, setctime(), for changing the creation timestamp (“ctime”) of a file or directory on Windows. Windows is one of the only major operating systems that tracks a true file-creation time distinct from modification and access time, and Python’s standard library offers no supported way to set it — win32-setctime fills that gap by calling CreateFileW and SetFileTime directly through ctypes, without requiring pywin32 or any compiled extension.

The library is a wrapper, not a platform abstraction: on non-Windows platforms calling setctime() raises a clear OSError immediately, and a SUPPORTED boolean lets callers detect availability before calling. Its best-known real-world consumer is Loguru, which uses it to preserve or restore file creation times when rotating log files, but any tool that stages files for backup, deployment, packaging, or archival on Windows can adopt it directly.

What You Get

• A single setctime(filepath, timestamp, *, follow_symlinks=True) function with a small, stable API surface
• A SUPPORTED boolean flag to detect at runtime whether the current platform can set creation time
• A pure-ctypes implementation with zero compiled dependencies — no pywin32 or C extension required
• A bundled py.typed marker for full static type-checking support in consuming projects
• Symlink handling via follow_symlinks, letting callers target either the link itself or its target

Common Use Cases

• Restoring original file creation timestamps after copying, backing up, or moving files on Windows
• Preserving creation time metadata across log file rotation (its use inside Loguru)
• Setting synthetic creation timestamps in test fixtures or file-based test suites
• Rebuilding accurate file metadata after extracting archives or synchronizing files across systems

Under The Hood

Architecture win32-setctime is a minimal, single-module wrapper: the public setctime() function in src/win32_setctime/_setctime.py normalizes the input path, converts the Unix timestamp into a Windows FILETIME structure, opens a handle to the target file or directory via CreateFileW, calls SetFileTime with a wildcard access/modify time so only the creation time changes, then closes the handle. The init.py re-exports setctime and a SUPPORTED flag that is computed once at import time by probing for os.name == ‘nt’ inside a try/except around the ctypes bindings, so the entire capability check happens up front rather than per call. There are no internal layers, abstractions, or configuration surface beyond this single function — the design intentionally trades architectural depth for a tiny, auditable surface area, which is appropriate for a utility whose only job is one focused Win32 syscall sequence.

Tech Stack The stack is pure Python standard library — ctypes (byref, wintypes, WinDLL, WinError, get_last_error) is the only dependency, with no pywin32, no compiled extension, and no third-party runtime packages. Packaging uses classic setuptools (setup.py) with a src/ layout, and a py.typed marker ships to signal PEP 561 type-checking support to consumers. Development-only extras declare black for formatting and pytest for testing. CI runs via a GitHub Actions workflow (tests.yml) gated on the master branch, and the project supports Python 3.5 through 3.13 per its classifiers.

Code Quality Test coverage is extensive relative to the codebase size: tests/test_setctime.py exercises normal files and directories, negative and far-future timestamps, nanosecond precision, upper/lower FILETIME bounds with explicit ValueError assertions, missing files raising FileNotFoundError, already-open file handles, unicode filenames, forward-slash paths, symlink follow/no-follow behavior, mtime/atime preservation, and NTFS file-tunneling edge cases. Error handling is explicit and typed — WinError(get_last_error()) surfaces real Win32 error codes rather than swallowing failures, and out-of-range timestamps raise ValueError with a descriptive message. Naming is consistent and the public API carries full type hints (Union[str, PathLike], float, bool). No linter config is checked in beyond the black formatter listed in dev extras, but CI enforces the test suite runs green on every change.

API Design The public API is a single function with three parameters and sensible defaults (follow_symlinks=True), requiring zero setup or configuration objects — call setctime(path, timestamp) and it either works or raises a clear, typed exception. The SUPPORTED flag gives callers a documented way to feature-detect the capability without wrapping every call in a broad try/except, which is a small but genuinely useful ergonomic touch for cross-platform codebases that only care about creation time on Windows. There is nothing architecturally novel here — it is a thin, well-tested ctypes shim over a single Win32 syscall sequence — but the API surface is about as low-friction as this kind of interop utility can be.