Skip to main content

Time and Epoch Concepts

Have you ever wondered how your computer knows what time it is right now? Or how servers store timestamps in logs? In this lesson, you'll discover how computers measure time using a universal reference point called epoch, and you'll learn to work with the Python time module to capture, convert, and display timestamps.

Unlike a calendar date you can read (November 9, 2025), computers prefer a simple number: seconds since a fixed moment in time. This approach makes calculations instant and storage efficient. Let's explore how this works.

Understanding Epoch: The Computer's Reference Point​

All computers on Earth use the same reference point for measuring time: January 1, 1970 UTC (Coordinated Universal Time). This moment is called the Unix epoch, and it's the zero point from which all time is measured.

Every moment since then is simply a number representing how many seconds have passed since epoch. Right now, as you read this, the number might be something like 1731120000 (which represents November 9, 2025, at 12:00 UTC). By tomorrow, it'll be 1731206400. Simple, consistent, and perfect for computers.

Why 1970? It's when Unix (the operating system) was created, and the industry standardized on this date for simplicity. What about dates before 1970? Those are represented as negative numbers (less commonly used in practice).

💬 AI Colearning Prompt​

"Why is January 1, 1970 chosen as epoch? What happens with dates before 1970? How does epoch handle timezones?"

This prompt invites you to explore the historical and technical reasoning behind epoch. Your AI can explain why this arbitrary date became universal and how it solves problems for global systems.

Getting Current Timestamp: time.time()​

The simplest way to get the current time is with time.time(), which returns the number of seconds since epoch as a floating-point number:

Specification Reference: Understand how time.time() captures the current moment as a single number AI Prompt Used: "Show me how time.time() works and explain what the number represents" Generated Code:

import time

def display_current_timestamp() -> None:
    """Get and display the current Unix timestamp."""
    current_time: float = time.time()
    print(f"Current timestamp: {current_time}")
    print(f"That's {current_time:.0f} seconds since January 1, 1970 UTC")

display_current_timestamp()

Output:

Current timestamp: 1731120456.7382598
That's 1731120456 seconds since January 1, 1970 UTC

Notice the type hint: float. The .time() function returns a floating-point number because it includes fractional seconds (microseconds). The integer part represents complete seconds; the decimal part represents fractions of a second.

This timestamp is universal—your computer in New York and a server in Tokyo both get the same number at the same instant. That's powerful for logs, databases, and distributed systems.

🎓 Instructor Commentary​

Timestamps might look like random numbers (1731120456.7382598), but they're just seconds since a fixed point—perfect for calculations. The key insight: let AI handle converting between timestamp numbers and human-readable dates; you focus on understanding why timestamps matter for storage, comparison, and calculations. In AI-native development, you specify what you want ("get current time in readable format"), and AI handles the conversion.

Converting Timestamps to Time Tuples: time.localtime()​

Now that you have a timestamp, you might want to extract individual components: What year? What month? What day of the week? The time.localtime() function converts a timestamp into a time tuple—a structured representation with individual fields.

Specification Reference: Convert a timestamp into its component parts using time tuples AI Prompt Used: "Show me how to convert a timestamp into a time tuple and access individual fields" Generated Code:

import time

def show_timestamp_components(timestamp: float) -> None:
    """Convert timestamp to time tuple and display components."""
    time_tuple = time.localtime(timestamp)

    # Access individual fields
    year: int = time_tuple.tm_year
    month: int = time_tuple.tm_mon
    day: int = time_tuple.tm_mday
    hour: int = time_tuple.tm_hour
    minute: int = time_tuple.tm_min
    second: int = time_tuple.tm_sec
    weekday: int = time_tuple.tm_wday  # 0=Monday, 6=Sunday

    print(f"Date: {year}-{month:02d}-{day:02d}")
    print(f"Time: {hour:02d}:{minute:02d}:{second:02d}")
    print(f"Weekday: {weekday} (0=Monday, 6=Sunday)")

# Get current timestamp and show its components
current: float = time.time()
show_timestamp_components(current)

Output:

Date: 2025-11-09
Time: 14:27:36
Weekday: 6 (0=Monday, 6=Sunday)

The time tuple has 9 fields total. The most useful ones are:

  • tm_year: Full year (2025)
  • tm_mon: Month (1-12)
  • tm_mday: Day of month (1-31)
  • tm_hour: Hour (0-23)
  • tm_min: Minute (0-59)
  • tm_sec: Second (0-59)
  • tm_wday: Weekday (0=Monday, 6=Sunday)
  • tm_yday: Day of year (1-366)
  • tm_isdst: Daylight saving time flag (-1=unknown, 0=no, 1=yes)

🚀 CoLearning Challenge​

Ask your AI Co-Teacher:

"Generate a function that takes a timestamp and returns just the weekday name (e.g., 'Monday', 'Saturday'). Then explain what each field in the time tuple represents."

Expected Outcome: You'll understand how to map the numeric weekday (0-6) to day names and appreciate the structure of time tuples.

Formatting Time Tuples: time.asctime()​

Time tuples are structured but not pretty. The time.asctime() function converts a time tuple into a human-readable string:

Specification Reference: Format time tuples as readable strings using asctime() AI Prompt Used: "Show me how to format a time tuple using time.asctime()" Generated Code:

import time

def display_readable_time(timestamp: float) -> None:
    """Convert timestamp to readable string format."""
    time_tuple = time.localtime(timestamp)
    readable: str = time.asctime(time_tuple)
    print(f"Readable format: {readable}")

# Example with current time
current: float = time.time()
display_readable_time(current)

Output:

Readable format: Sun Nov 09 14:27:36 2025

The asctime() function produces a standard format: Day Mon DD HH:MM:SS YYYY. It's perfect for logs and displays where you need quick, recognizable time strings.

Notice: asctime() also accepts None as an argument, in which case it formats the current time:

import time

# These two are equivalent
readable1: str = time.asctime(time.localtime())
readable2: str = time.asctime()  # None is implicit

print(readable1)
print(readable2)

Calculating Elapsed Time: Subtracting Timestamps​

One powerful advantage of timestamps: you can subtract them to find durations. This is much harder with formatted date strings.

Specification Reference: Calculate durations between timestamps using arithmetic AI Prompt Used: "Show me how to calculate the time elapsed between two timestamps" Generated Code:

import time

def measure_operation_time() -> None:
    """Measure how long an operation takes."""
    start_time: float = time.time()

    # Simulate some work (building a list)
    result: list[int] = [x ** 2 for x in range(1000000)]

    end_time: float = time.time()
    elapsed: float = end_time - start_time

    print(f"Operation took {elapsed:.4f} seconds")
    print(f"That's {elapsed * 1000:.2f} milliseconds")

    # Convert to minutes and seconds
    minutes: int = int(elapsed // 60)
    seconds: float = elapsed % 60
    if minutes > 0:
        print(f"Or {minutes} minute(s) and {seconds:.2f} seconds")

measure_operation_time()

Output:

Operation took 0.0427 seconds
That's 42.70 milliseconds

This pattern is invaluable for benchmarking, profiling, and understanding performance. You capture a timestamp before an operation, capture another after, subtract them, and you know exactly how long it took. No manual tracking needed.

✨ Teaching Tip​

Use Claude Code to explore with your AI: "Show me the timestamp for my birthday and explain how Python calculates it. What would the timestamp be for midnight on that date in UTC?"

This helps you internalize the epoch concept by connecting it to a personal date, making the abstract number feel concrete.

Exercises: Apply What You've Learned​

Exercise 1: Timestamp Inspector​

Write a function that takes a timestamp as input and displays:

  • The readable date and time (using asctime())
  • The year, month, and day separately
  • The weekday (as a name, not a number)

Start with the code provided and modify it to add these features. Ask your AI for help with formatting the weekday name.

Exercise 2: Benchmark Your Code​

Write a function that measures how long it takes to:

  1. Create a list of 100,000 random numbers
  2. Sort the list
  3. Calculate the average

Use time.time() to measure each step separately, then display results in seconds and milliseconds.

Exercise 3: Time Until Event​

Given a target date in the future (as a timestamp), write a function that calculates and displays:

  • Days until that date
  • Hours remaining (after accounting for complete days)
  • Minutes remaining (after accounting for hours)

For example: "285 days, 4 hours, and 23 minutes until launch."

Hint: You'll need to convert time differences to different units. Ask your AI for help with the math.

Try With AI​

Your AI companion is perfect for exploring epoch, timestamps, and time conversions. Use these prompts to deepen your understanding and practice applying what you've learned.

Using ChatGPT Web or Your AI Companion (Claude CLI, Gemini CLI):

Prompt 1: Recall – Understand the Basics​

"What is the Unix epoch and why do computers use it? Explain how it simplifies time representation and calculations."

Expected Outcome: A clear explanation of January 1, 1970 UTC as the reference point and why having a single universal reference point is better than formatted date strings for computing.

Prompt 2: Understand – Connect the Concepts​

"Explain the relationship between time.time(), time.localtime(), and time.asctime(). Show an example timestamp and how it flows through each function to become human-readable."

Expected Outcome: Understanding that time.time() gives you the raw number, time.localtime() breaks it into components, and time.asctime() formats those components as a string.

Prompt 3: Apply – Generate Working Code​

"Generate a Python function that takes a birthday as a string (e.g., '1995-03-15') and calculates how many days have passed since that date. Include type hints and error handling for invalid dates. Assume the birthday is in UTC."

Expected Outcome: A working function that converts the birthday string to a timestamp, gets the current timestamp, subtracts them, and converts the difference to days. You'll see how timestamps make this calculation trivial.

Prompt 4: Analyze – Higher-Order Thinking​

"Why are timestamps better than formatted date strings for storage and comparison in databases? Give three specific advantages and explain when you might use formatted strings instead."

Expected Outcome: Understanding that timestamps are: (1) sortable by numeric value, (2) timezone-independent, (3) efficient for calculations. Formatted strings are for display, not for computation or storage.

Learning Note: This lesson prepared you for the next lesson on Python 3.14's datetime module, which provides higher-level abstractions while building on the same epoch foundation. The time module is lower-level and essential for understanding how systems work internally.