0
# win32-setctime
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: win32-setctime
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install win32-setctime`
10
- **Platform**: Windows only
11
- **Python Version**: 3.5+
12

13
## Core Imports
14

15
```python
16
from win32_setctime import setctime, SUPPORTED
17
```
18

19
Module import:
20

21
```python
22
import win32_setctime
23
# Access via win32_setctime.setctime(), win32_setctime.SUPPORTED
24
```
25

26
## Basic Usage
27

28
```python
29
from win32_setctime import setctime, SUPPORTED
30

31
# Check if the library is supported on this platform
32
if SUPPORTED:
33
    # Set file creation time using unix timestamp
34
    setctime("my_file.txt", 1561675987.509)
35
    
36
    # Set creation time while following symbolic links (default)
37
    setctime("my_file.txt", 1561675987.509, follow_symlinks=True)
38
    
39
    # Set creation time without following symbolic links
40
    setctime("symlink.txt", 1561675987.509, follow_symlinks=False)
41
else:
42
    print("win32-setctime is not supported on this platform")
43
```
44

45
## Capabilities
46

47
### File Creation Time Modification
48

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

51
```python { .api }
52
def setctime(
53
    filepath: Union[str, PathLike], 
54
    timestamp: float, 
55
    *, 
56
    follow_symlinks: bool = True
57
) -> None:
58
    """
59
    Set the "ctime" (creation time) attribute of a file given a unix timestamp (Windows only).
60
    
61
    Parameters:
62
    - filepath: Union[str, PathLike] - Path to the file or directory
63
    - timestamp: float - Unix timestamp (seconds since epoch, supports fractional seconds)
64
    - follow_symlinks: bool - Whether to follow symbolic links (keyword-only, default: True)
65
    
66
    Returns:
67
    None
68
    
69
    Raises:
70
    - OSError: If not running on Windows platform
71
    - ValueError: If timestamp exceeds valid Windows FILETIME range
72
    - WinError: If Windows API calls fail (file access, permissions, etc.)
73
    - FileNotFoundError: If the specified file does not exist
74
    """
75
```
76

77
### Platform Support Detection
78

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

81
```python { .api }
82
SUPPORTED: bool
83
```
84

85
`SUPPORTED` is `True` when:
86
- Running on Windows (os.name == "nt")
87
- Required ctypes Windows API bindings are available
88
- kernel32.dll functions are accessible
89

90
`SUPPORTED` is `False` when:
91
- Running on non-Windows platforms
92
- Missing required ctypes dependencies
93
- Windows API functions unavailable
94

95
## Types
96

97
```python { .api }
98
from typing import Union
99

100
# Python version-specific PathLike import
101
if sys.version_info >= (3, 6):
102
    from os import PathLike
103
else:
104
    from pathlib import PurePath as PathLike
105
```
106

107
## Error Handling
108

109
The library provides comprehensive error handling:
110

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

116
## Advanced Usage
117

118
### Working with Symbolic Links
119

120
```python
121
from win32_setctime import setctime
122

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

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

132
### Timestamp Range and Precision
133

134
```python
135
from win32_setctime import setctime
136

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

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

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

148
### Working with Different Path Types
149

150
```python
151
from win32_setctime import setctime
152
from pathlib import Path
153

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

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

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

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

167
# Directories
168
setctime("C:\\Users\\MyDirectory", timestamp)
169
```
170

171
## Platform Dependencies
172

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

175
- `CreateFileW` - Opens file handles with specific access rights
176
- `SetFileTime` - Modifies file timestamps 
177
- `CloseHandle` - Releases file handles
178
- `wintypes` - Provides Windows type definitions (HANDLE, FILETIME, etc.)
179

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