or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-win32-setctime

A small Python utility to set file creation time on Windows

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/win32-setctime@1.2.x

To install, run

npx @tessl/cli install tessl/pypi-win32-setctime@1.2.0

index.mddocs/

win32-setctime

A small Python utility to set file creation time on Windows. This library provides Windows-specific functionality for modifying file creation time (ctime) attributes using the Windows API through Python's ctypes interface, offering precise control over Windows file metadata that standard Python libraries cannot provide.

Package Information

  • Package Name: win32-setctime
  • Package Type: pypi
  • Language: Python
  • Installation: pip install win32-setctime
  • Platform: Windows only
  • Python Version: 3.5+

Core Imports

from win32_setctime import setctime, SUPPORTED

Module import:

import win32_setctime
# Access via win32_setctime.setctime(), win32_setctime.SUPPORTED

Basic Usage

from win32_setctime import setctime, SUPPORTED

# Check if the library is supported on this platform
if SUPPORTED:
    # Set file creation time using unix timestamp
    setctime("my_file.txt", 1561675987.509)
    
    # Set creation time while following symbolic links (default)
    setctime("my_file.txt", 1561675987.509, follow_symlinks=True)
    
    # Set creation time without following symbolic links
    setctime("symlink.txt", 1561675987.509, follow_symlinks=False)
else:
    print("win32-setctime is not supported on this platform")

Capabilities

File Creation Time Modification

Sets the creation time (ctime) attribute of a file or directory using direct Windows API calls to bypass Python's standard library limitations.

def setctime(
    filepath: Union[str, PathLike], 
    timestamp: float, 
    *, 
    follow_symlinks: bool = True
) -> None:
    """
    Set the "ctime" (creation time) attribute of a file given a unix timestamp (Windows only).
    
    Parameters:
    - filepath: Union[str, PathLike] - Path to the file or directory
    - timestamp: float - Unix timestamp (seconds since epoch, supports fractional seconds)
    - follow_symlinks: bool - Whether to follow symbolic links (keyword-only, default: True)
    
    Returns:
    None
    
    Raises:
    - OSError: If not running on Windows platform
    - ValueError: If timestamp exceeds valid Windows FILETIME range
    - WinError: If Windows API calls fail (file access, permissions, etc.)
    - FileNotFoundError: If the specified file does not exist
    """

Platform Support Detection

Boolean constant indicating whether the library is supported on the current platform and has all required dependencies available.

SUPPORTED: bool

SUPPORTED is True when:

  • Running on Windows (os.name == "nt")
  • Required ctypes Windows API bindings are available
  • kernel32.dll functions are accessible

SUPPORTED is False when:

  • Running on non-Windows platforms
  • Missing required ctypes dependencies
  • Windows API functions unavailable

Types

from typing import Union

# Python version-specific PathLike import
if sys.version_info >= (3, 6):
    from os import PathLike
else:
    from pathlib import PurePath as PathLike

Error Handling

The library provides comprehensive error handling:

  • Platform Compatibility: Raises OSError with message "This function is only available for the Windows platform" on non-Windows systems
  • Timestamp Validation: Raises ValueError if timestamp exceeds the valid range for Windows FILETIME format
  • File System Errors: Raises FileNotFoundError if the target file doesn't exist
  • Windows API Errors: Raises WinError for various API failures including permission errors, invalid handles, or file access issues

Advanced Usage

Working with Symbolic Links

from win32_setctime import setctime

# Follow symbolic links (default behavior)
# Sets creation time of the target file
setctime("symlink.txt", timestamp, follow_symlinks=True)

# Don't follow symbolic links
# Sets creation time of the symlink itself
setctime("symlink.txt", timestamp, follow_symlinks=False)

Timestamp Range and Precision

from win32_setctime import setctime

# Supports negative timestamps (dates before Unix epoch)
setctime("file.txt", -5694948000)  # Historical date

# Supports high precision with nanoseconds
setctime("file.txt", 737206464.123456789)

# Valid timestamp range (tested bounds from test suite):
# Minimum: -11644473599 (January 1, 1601 00:00:00 UTC)
# Maximum: ~1833029933770 (far future dates beyond practical use)

Working with Different Path Types

from win32_setctime import setctime
from pathlib import Path

# String paths
setctime("C:\\Users\\file.txt", timestamp)

# Forward slashes (automatically normalized)
setctime("C:/Users/file.txt", timestamp)

# PathLike objects (Python 3.6+)
path = Path("C:\\Users\\file.txt")
setctime(path, timestamp)

# Unicode file names
setctime("𤭢.txt", timestamp)

# Directories
setctime("C:\\Users\\MyDirectory", timestamp)

Platform Dependencies

The library uses Windows-specific ctypes bindings to access kernel32.dll:

  • CreateFileW - Opens file handles with specific access rights
  • SetFileTime - Modifies file timestamps
  • CloseHandle - Releases file handles
  • wintypes - Provides Windows type definitions (HANDLE, FILETIME, etc.)

These dependencies are automatically detected during import, and the SUPPORTED constant indicates availability.