🔍 Code Extractor

Copies a file from source to destination and sets the file's modification and access times to match a provided datetime object.

Purpose

This function is designed to preserve temporal metadata when copying files, particularly useful when extracting email attachments or archiving files where maintaining the original date/time context is important. It combines file copying with timestamp manipulation to ensure the copied file reflects a specific date rather than the copy operation's timestamp.

Source Code

def copy_file_with_date(src, dst, date_obj):
    """Copy file and set modification/access times to match email date"""
    shutil.copy2(src, dst)
    
    # Set file times to email received date
    timestamp = date_obj.timestamp()
    os.utime(dst, (timestamp, timestamp))

Parameters

Parameter Details

src: String representing the source file path. Must be a valid path to an existing file that the process has read permissions for.

dst: String representing the destination file path. Can be a directory (file will be copied with same name) or a full file path. The process must have write permissions for this location.

date_obj: A datetime object (from Python's datetime module) representing the desired modification and access time for the destination file. Must have a timestamp() method that returns a Unix timestamp.

Return Value

This function returns None. It performs side effects by creating a file at the destination path and modifying its timestamps. If successful, the destination file will exist with modification and access times matching the provided date_obj.

Dependencies

• shutil
• os

Required Imports

import shutil
import os

Usage Example

from datetime import datetime
import shutil
import os

def copy_file_with_date(src, dst, date_obj):
    """Copy file and set modification/access times to match email date"""
    shutil.copy2(src, dst)
    timestamp = date_obj.timestamp()
    os.utime(dst, (timestamp, timestamp))

# Example usage
source_file = '/path/to/source/document.pdf'
destination_file = '/path/to/destination/document.pdf'
email_received_date = datetime(2023, 6, 15, 14, 30, 0)

copy_file_with_date(source_file, destination_file, email_received_date)

# Verify the timestamp was set correctly
import os.path
mod_time = os.path.getmtime(destination_file)
print(f"File modification time: {datetime.fromtimestamp(mod_time)}")

Best Practices

• Always verify that the source file exists before calling this function to avoid FileNotFoundError
• Ensure the destination directory exists before calling, or handle potential exceptions
• Be aware that shutil.copy2() preserves original metadata first, which is then overwritten by os.utime()
• Consider wrapping this function in try-except blocks to handle permission errors, disk space issues, or invalid paths
• The date_obj parameter must be a datetime object with timezone awareness if working with emails from different timezones
• On some file systems or operating systems, setting timestamps may require elevated permissions
• Both access time and modification time are set to the same value; if different times are needed, modify the os.utime() call accordingly

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function fix_file_dates 60.7% similar

  Normalizes all timestamp attributes (creation, modification, access) of a file to the oldest timestamp among them, with optional dry-run mode for preview.

  From: /tf/active/vicechatdev/mailsearch/fix_file_dates.py

• function set_file_dates 57.4% similar

  Sets all file timestamps (creation time, modification time, access time, and change time) to a specified Unix timestamp by directly modifying the file's inode using debugfs.

  From: /tf/active/vicechatdev/mailsearch/fix_file_dates.py

• function get_file_times 52.8% similar

  Retrieves all available timestamps for a file, including modification time, access time, change time, and birth time (creation time) when available.

  From: /tf/active/vicechatdev/mailsearch/fix_file_dates.py

• function load_email_dates 49.9% similar

  Reads a CSV file (DOWNLOAD_REGISTER) containing email metadata and extracts filename-to-date mappings, parsing dates in YYYY-MM-DD format.

  From: /tf/active/vicechatdev/mailsearch/copy_signed_documents.py

• function modify_test_document 49.7% similar

  Modifies the content of a test document file by writing new content to it, with a built-in delay to ensure the file's modification time changes.

  From: /tf/active/vicechatdev/docchat/test_incremental_indexing.py