Guide de Traitement des Timestamps en Python

Cette page est provisoirement disponible en anglais. La traduction française est en préparation.

Introduction

Python provides two main modules for working with dates and timestamps: datetime for high-level date operations and time for lower-level timestamp operations. Understanding how to properly use timestamps in Python is essential for data processing, API integration, and time-based applications. This guide covers timestamp fundamentals, conversions, timezone handling, and best practices.

Getting Current Timestamp

Using time Module

Copy
PYTHON
1import time
2
3# Get current Unix timestamp (seconds since epoch)
4now_seconds = time.time()
5print(now_seconds)  # e.g., 1704672000.123456
6
7# Get current timestamp as integer
8now_int = int(time.time())
9print(now_int)  # e.g., 1704672000
10
11# Get current time in milliseconds
12now_ms = int(time.time() * 1000)
13print(now_ms)  # e.g., 1704672000123

Using datetime Module

Copy
PYTHON
1from datetime import datetime
2
3# Get current UTC datetime
4now_utc = datetime.utcnow()
5print(now_utc)  # 2024-01-08 00:00:00.123456
6
7# Get current local datetime
8now_local = datetime.now()
9print(now_local)  # 2024-01-07 19:00:00.123456 (if EST)
10
11# Get timestamp from datetime
12timestamp = now_utc.timestamp()
13print(timestamp)  # e.g., 1704672000.123456

Best Practice: Use datetime.utcnow() for UTC timestamps and datetime.now() for local timestamps. Always be explicit about timezone.

Creating Datetime from Timestamp

From Unix Timestamp (Seconds)

Copy
PYTHON
1from datetime import datetime
2
3# Create datetime from Unix timestamp (seconds)
4dt = datetime.fromtimestamp(1704672000)
5print(dt)  # 2024-01-07 19:00:00 (local timezone)
6
7# Create UTC datetime from Unix timestamp
8dt_utc = datetime.utcfromtimestamp(1704672000)
9print(dt_utc)  # 2024-01-08 00:00:00+00:00 (UTC)

From Unix Timestamp (Milliseconds)

Copy
PYTHON
1from datetime import datetime
2
3# Convert milliseconds to datetime
4ts_ms = 1704672000123
5dt = datetime.fromtimestamp(ts_ms / 1000)
6print(dt)  # 2024-01-08 00:00:00.123000

Important: datetime.fromtimestamp() uses local timezone. Use datetime.utcfromtimestamp() for UTC.

From Date Components

Copy
PYTHON
1from datetime import datetime
2
3# Create from year, month, day, hour, minute, second
4dt = datetime(2024, 1, 8, 14, 30, 45)
5print(dt)  # 2024-01-08 14:30:45
6
7# Create date only (time defaults to midnight)
8dt_date = datetime(2024, 1, 8)
9print(dt_date)  # 2024-01-08 00:00:00
10
11# Create time only (date defaults to 1900-01-01)
12from datetime import time
13t = time(14, 30, 45)
14print(t)  # 14:30:45

Python Range: datetime objects can represent years 1 to 9999.

Converting Datetime to Timestamp

Using timestamp() Method

Copy
PYTHON
1from datetime import datetime
2
3# Convert datetime to Unix timestamp (seconds)
4dt = datetime(2024, 1, 8, 14, 30, 45)
5timestamp = dt.timestamp()
6print(timestamp)  # e.g., 1704672654.0
7
8# Convert UTC datetime to timestamp
9dt_utc = datetime(2024, 1, 8, 14, 30, 45, tzinfo=timezone.utc)
10timestamp_utc = dt_utc.timestamp()
11print(timestamp_utc)  # e.g., 1704695045.0

Using calendar.timegm() for UTC

Copy
PYTHON
1import calendar
2from datetime import datetime
3
4# Convert UTC datetime to timestamp (naive datetime assumed UTC)
5dt = datetime(2024, 1, 8, 14, 30, 45)
6timestamp_utc = calendar.timegm(dt.timetuple())
7print(timestamp_utc)  # e.g., 1704695045
8
9# More reliable than timestamp() for UTC naive datetimes

Use Case: calendar.timegm() is useful when working with UTC timestamps from naive datetimes.

Date Arithmetic

Adding and Subtracting Time

Copy
PYTHON
1from datetime import datetime, timedelta
2
3# Add 7 days
4dt = datetime(2024, 1, 8)
5future = dt + timedelta(days=7)
6print(future)  # 2024-01-15 00:00:00
7
8# Subtract 1 hour
9past = dt - timedelta(hours=1)
10print(past)  # 2024-01-07 23:00:00
11
12# Add 2 hours and 30 minutes
13dt = datetime(2024, 1, 8, 10, 0, 0)
14dt = dt + timedelta(hours=2, minutes=30)
15print(dt)  # 2024-01-08 12:30:00
16
17# Add negative timedelta (subtract)
18dt = datetime(2024, 1, 8)
19dt = dt + timedelta(days=-1)
20print(dt)  # 2024-01-07 00:00:00

Calculating Duration

Copy
PYTHON
1from datetime import datetime
2
3# Calculate duration between two datetimes
4dt1 = datetime(2024, 1, 8, 10, 0, 0)
5dt2 = datetime(2024, 1, 8, 18, 0, 0)
6
7duration = dt2 - dt1
8print(duration)  # 8:00:00
9
10# Extract duration components
11print(duration.days)    # 0
12print(duration.seconds)  # 28800 (8 hours)
13print(duration.total_seconds())  # 28800.0
14
15# Calculate in hours
16hours = duration.total_seconds() / 3600
17print(f"Duration: {hours} hours")  # Duration: 8.0 hours

Business Days Calculation

Copy
PYTHON
1from datetime import datetime, timedelta
2
3def add_business_days(start_date, days):
4    """Add business days to a date (excludes weekends)"""
5    result = start_date
6    added_days = 0
7
8    while added_days < days:
9        result += timedelta(days=1)
10        if result.weekday() < 5:  # Monday=0, Friday=4
11            added_days += 1
12
13    return result
14
15# Example
16start = datetime(2024, 1, 8)
17result = add_business_days(start, 5)
18print(result)  # 2024-01-15 (Monday)

Recommendation: Use the python-dateutil library for more advanced business day calculations including holidays.

Formatting Dates

ISO 8601 Format

Copy
PYTHON
1from datetime import datetime
2
3# Format as ISO 8601
4dt = datetime(2024, 1, 8, 14, 30, 45)
5iso_string = dt.isoformat()
6print(iso_string)  # 2024-01-08T14:30:45
7
8# With timezone (using pytz)
9import pytz
10tz = pytz.timezone('America/New_York')
11dt = datetime(2024, 1, 8, 14, 30, 45, tzinfo=tz)
12iso_with_tz = dt.isoformat()
13print(iso_with_tz)  # 2024-01-08T14:30:45-05:00

Custom Formatting with strftime

Copy
PYTHON
1from datetime import datetime
2
3dt = datetime(2024, 1, 8, 14, 30, 45)
4
5# Common format codes
6formats = {
7    'YYYY-MM-DD': dt.strftime('%Y-%m-%d'),  # 2024-01-08
8    'YYYY/MM/DD HH:MM': dt.strftime('%Y/%m/%d %H:%M'),  # 2024/01/08 14:30
9    'Day Month, Year': dt.strftime('%d %B, %Y'),  # 08 January, 2024
10    'Weekday': dt.strftime('%A'),  # Monday
11    'Short Weekday': dt.strftime('%a'),  # Mon
12    'Time': dt.strftime('%H:%M:%S'),  # 14:30:45
13    'AM/PM': dt.strftime('%I:%M %p'),  # 02:30 PM
14}
15
16for name, formatted in formats.items():
17    print(f"{name}: {formatted}")

Format Codes:

Copy
TEXT
1%Y  Year (4 digits)           %m  Month (01-12)
2%y  Year (2 digits)           %d  Day (01-31)
3%B  Month name (January)         %b  Month abbr (Jan)
4%A  Weekday name (Monday)       %a  Weekday abbr (Mon)
5%H  Hour (00-23)             %I  Hour (01-12)
6%M  Minute (00-59)            %S  Second (00-59)
7%p  AM/PM                     %f  Microseconds (000000-999999)

Format for Different Locales

Copy
PYTHON
1from datetime import datetime
2import locale
3
4dt = datetime(2024, 1, 8, 14, 30, 45)
5
6# Set locale
7locale.setlocale(locale.LC_ALL, 'en_US.UTF-8')
8en_format = dt.strftime('%B %d, %Y')  # January 08, 2024
9
10locale.setlocale(locale.LC_ALL, 'fr_FR.UTF-8')
11fr_format = dt.strftime('%d %B %Y')  # 08 janvier 2024
12
13locale.setlocale(locale.LC_ALL, 'zh_CN.UTF-8')
14zh_format = dt.strftime('%Y年%m月%d日')  # 2024年01月08日

Note: locale.setlocale() affects the entire process. Use locale.getlocale() to restore original locale.

Parsing Dates

Parsing ISO 8601 Strings

Copy
PYTHON
1from datetime import datetime
2
3# Parse ISO 8601 string
4iso_string = "2024-01-08T14:30:45"
5dt = datetime.fromisoformat(iso_string)
6print(dt)  # 2024-01-08 14:30:45
7
8# Parse with timezone
9iso_tz_string = "2024-01-08T14:30:45-05:00"
10dt_tz = datetime.fromisoformat(iso_tz_string)
11print(dt_tz)  # 2024-01-08 14:30:45-05:00

Parsing Custom Formats with strptime

Copy
PYTHON
1from datetime import datetime
2
3# Parse custom format
4date_string = "08 January, 2024 14:30:45"
5dt = datetime.strptime(date_string, '%d %B, %Y %H:%M:%S')
6print(dt)  # 2024-01-08 14:30:45
7
8# Parse US format
9us_string = "01/08/2024 2:30 PM"
10dt_us = datetime.strptime(us_string, '%m/%d/%Y %I:%M %p')
11print(dt_us)  # 2024-01-08 14:30:00
12
13# Parse 24-hour format
14eu_string = "08.01.2024 14:30"
15dt_eu = datetime.strptime(eu_string, '%d.%m.%Y %H:%M')
16print(dt_eu)  # 2024-01-08 14:30:00

Format Codes for strptime:

Copy
TEXT
1Same as strftime() format codes:
2  %Y (year), %m (month), %d (day)
3  %H (hour 24), %I (hour 12), %M (minute), %S (second)
4  %p (AM/PM), %f (microseconds)
5  %B (month name), %A (weekday name)

Handling Parse Errors

Copy
PYTHON
1from datetime import datetime
2
3def safe_parse_date(date_string, format_string):
4    """Parse date string with error handling"""
5    try:
6        return datetime.strptime(date_string, format_string)
7    except ValueError as e:
8        print(f"Failed to parse date: {date_string}")
9        print(f"Error: {e}")
10        return None
11
12# Examples
13valid = safe_parse_date("2024-01-08", "%Y-%m-%d")
14invalid = safe_parse_date("invalid date", "%Y-%m-%d")
15
16print(valid)   # 2024-01-08 00:00:00
17print(invalid)  # Failed to parse date: invalid date

Timezone Handling

Using pytz Library

Copy
PYTHON
1from datetime import datetime
2import pytz
3
4# Create datetime with timezone
5tz = pytz.timezone('America/New_York')
6dt_aware = datetime(2024, 1, 8, 14, 30, 45, tzinfo=tz)
7print(dt_aware)  # 2024-01-08 14:30:45-05:00
8
9# Convert between timezones
10tokyo_tz = pytz.timezone('Asia/Tokyo')
11dt_tokyo = dt_aware.astimezone(tokyo_tz)
12print(dt_tokyo)  # 2024-01-09 04:30:45+09:00
13
14# Get current time in specific timezone
15tz = pytz.timezone('Europe/London')
16now_london = datetime.now(tz)
17print(now_london)  # 2024-01-08 00:00:00+00:00

Best Practice: Install pytz with pip install pytz for comprehensive timezone support.

Using zoneinfo (Python 3.9+)

Copy
PYTHON
1from datetime import datetime, timezone
2from zoneinfo import ZoneInfo
3
4# Python 3.9+ built-in timezone support
5tz = ZoneInfo('America/New_York')
6dt_aware = datetime(2024, 1, 8, 14, 30, 45, tzinfo=tz)
7print(dt_aware)  # 2024-01-08 14:30:45-05:00
8
9# Convert to UTC
10dt_utc = dt_aware.astimezone(timezone.utc)
11print(dt_utc)  # 2024-01-08 19:30:45+00:00

Advantage: zoneinfo is built into Python 3.9+, no external dependencies needed.

UTC vs Local Time

Copy
PYTHON
1from datetime import datetime
2
3# Get local time (system timezone)
4dt_local = datetime.now()
5print(f"Local: {dt_local}")
6
7# Get UTC time
8dt_utc = datetime.utcnow()
9print(f"UTC: {dt_utc}")
10
11# Convert local to UTC (requires timezone-aware datetime)
12import pytz
13tz = pytz.timezone('America/New_York')
14dt_aware = datetime.now(tz)
15dt_utc = dt_aware.astimezone(pytz.utc)
16print(f"Converted to UTC: {dt_utc}")

Common Operations

Start/End of Period

Copy
PYTHON
1from datetime import datetime, timedelta
2
3def start_of_day(dt):
4    """Return start of day (midnight)"""
5    return dt.replace(hour=0, minute=0, second=0, microsecond=0)
6
7def end_of_day(dt):
8    """Return end of day (23:59:59.999999)"""
9    return dt.replace(hour=23, minute=59, second=59, microsecond=999999)
10
11def start_of_month(dt):
12    """Return start of month"""
13    return dt.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
14
15def end_of_month(dt):
16    """Return end of month"""
17    if dt.month == 12:
18        return dt.replace(year=dt.year + 1, month=1, day=1) - timedelta(days=1)
19    return dt.replace(month=dt.month + 1, day=1) - timedelta(days=1)
20
21# Examples
22dt = datetime(2024, 1, 15, 14, 30, 45)
23print(start_of_day(dt))    # 2024-01-15 00:00:00
24print(end_of_month(dt))    # 2024-01-31 23:59:59.999999

Age Calculation

Copy
PYTHON
1from datetime import datetime
2
3def calculate_age(birth_date):
4    """Calculate age in years, months, and days"""
5    today = datetime.now()
6    birth = datetime.fromisoformat(birth_date)
7
8    years = today.year - birth.year
9    months = today.month - birth.month
10    days = today.day - birth.day
11
12    # Adjust if birthday hasn't happened yet this year
13    if (months < 0 or (months == 0 and days < 0)):
14        years -= 1
15        months += 12
16
17    return {
18        'years': years,
19        'months': months,
20        'days': days
21    }
22
23# Example
24age = calculate_age('1990-06-15')
25print(f"Age: {age['years']} years, {age['months']} months, {age['days']} days")
26# Age: 33 years, 6 months, -7 days

Countdown Timer

Copy
PYTHON
1from datetime import datetime
2
3def countdown(target_date_str):
4    """Calculate countdown to target date"""
5    target = datetime.fromisoformat(target_date_str)
6    now = datetime.now()
7    diff = target - now
8
9    if diff.total_seconds() <= 0:
10        return {'expired': True, 'text': 'Target date passed'}
11
12    days = diff.days
13    hours = diff.seconds // 3600
14    minutes = (diff.seconds % 3600) // 60
15    seconds = diff.seconds % 60
16
17    return {
18        'expired': False,
19        'text': f"{days} days, {hours} hours, {minutes} minutes, {seconds} seconds",
20        'total_seconds': diff.total_seconds()
21    }
22
23# Example
24result = countdown('2024-12-31T00:00:00')
25print(result['text'])
26# "357 days, 11 hours, 29 minutes, 12 seconds"

Best Practices

Timezone Best Practices

Copy
TEXT
1✅ Always store UTC timestamps in databases
2✅ Convert to local timezone only for display
3✅ Use timezone-aware datetime objects for user-facing times
4✅ Document timezone assumptions in code comments
5✅ Use IANA timezone names (America/New_York, not UTC-5)
6❌ Don't store local timestamps without timezone metadata
7❌ Don't mix UTC and naive datetimes in calculations
8❌ Don't assume server timezone matches user timezone
9❌ Don't use pytz for Python 3.9+ (use zoneinfo instead)

Performance Tips

Copy
TEXT
1✅ Use datetime.timestamp() instead of time.time() for datetime objects
2✅ Cache timezone objects when used repeatedly
3✅ Use datetime.utcnow() for UTC (faster than aware datetimes)
4✅ Use timedelta arithmetic for time calculations (more readable)
5❌ Don't create timezone objects in loops (reuse them)
6❌ Don't call datetime.now() in tight loops (call once and reuse)

Data Integrity

Copy
PYTHON
1from datetime import datetime
2
3def validate_datetime(dt):
4    """Validate datetime object is within reasonable range"""
5    if not isinstance(dt, datetime):
6        return False, "Not a datetime object"
7
8    if dt.year < 1900 or dt.year > 2100:
9        return False, "Year out of reasonable range"
10
11    if dt.month < 1 or dt.month > 12:
12        return False, "Invalid month"
13
14    if dt.day < 1 or dt.day > 31:
15        return False, "Invalid day"
16
17    return True, "Valid"
18
19# Example
20valid = validate_datetime(datetime(2024, 1, 8, 14, 30, 45))
21print(valid)  # (True, "Valid")
22
23invalid = validate_datetime(datetime(2024, 13, 1))
24print(invalid)  # (False, "Invalid month")

Related Tools

• Unix Timestamp Converter - Convert Unix timestamps to dates
• Current Timestamp - Get current timestamp in multiple formats
• Timestamp Format Converter - Convert between timestamp formats
• UTC/Local Converter - Convert between UTC and local time
• Timestamp Validator - Validate timestamp formats and ranges

Additional Resources

• Python datetime Documentation↗
• Python time Module↗
• pytz Library↗
• Python zoneinfo (Python 3.9+)↗
• dateutil Library↗

For production applications with complex timezone or business day requirements, consider using:

• pytz: Legacy but widely supported timezone library
• zoneinfo: Built-in Python 3.9+ (preferred for new code)
• python-dateutil: Advanced date parsing and business day calculations
• pendulum: Pythonic datetime library with better timezone handling

Python's datetime module is sufficient for basic operations, but libraries provide better timezone support and parsing for complex use cases.