Dates and Timedeltas in Python

Select a timestamp to watch that moment on YouTube.

1. 00:00

   A date written as year-month-day looks like text, but changing its characters is not calendar arithmetic. Two days after February 28, 2024, is March 1, because 2024 has a leap day. One day after February 28, 2023, is also March 1, because 2023 does not. The difference is exactly why a homemade string shortcut is dangerous. In this video we will run that shortcut, inspect the wrong result, parse the text as a real date, and add a timedelta. We will also count the days between two dates and explain when a date alone is insufficient.

2. 00:40

   The companion lesson lets you run and edit every example in a browser console. Before we touch the code, keep a separate expected result in mind. If we first see the program's output and only then decide whether it looks reasonable, an impossible February thirtieth can slip through as a seemingly simple number change. Dates appear in deadlines, birthdays, and reports. A whole calendar day is a different thing from a timestamp measured down to seconds. Keeping that distinction visible helps you pick the right Python type. Today's examples concern whole days, so we will use date and not assume any clock time or location.

3. 01:21

   The string operation produced February thirtieth. Python did not complain because no calendar operation happened. We sliced off the last two characters, converted them to an integer, added two, and glued the pieces back together. For a day in the middle of a month, that may appear to work. At the end of a month it fails, and at the end of a year it fails even more visibly. Adding a few special cases for month lengths soon becomes complicated, especially when leap years are involved. The real problem is that a string does not know it represents a calendar date. We should parse it into a date object, so Python can validate its year, month, and day.

4. 02:03

   Then we can add a duration with a unit. That is a smaller and more reliable program than rebuilding calendar rules in string manipulation. The shortcut fails at other boundaries too. Changing the day characters of 2024-12-31 by one would invent December 32 rather than January 1 of the next year. A patch for every month and leap year would be longer than using the standard library. The wrong output is useful because it reveals the model error. `date.fromisoformat` converts an ISO year-month-day string to a date object. The first input is valid and comes back in the same format from `isoformat`.

5. 02:45

   The second input is impossible: 2023 is not a leap year, so February has only twenty-eight days. Python raises ValueError, which we catch only to keep this demonstration running. In an application, you would decide whether to show the user a validation message or let a caller handle the exception. The lesson's practice function lets invalid input raise ValueError, so the checker can confirm it truly parses dates. A date object has a year, month, and day, but no clock time or time zone. It represents a calendar day. That is exactly what we need for a due date measured in whole days.

6. 03:26

   Next we give Python a number of days to add, using timedelta. Parsing also gives you a clear failure point for bad input. If a web form sends an impossible date, you can ask for a correction instead of computing a deadline from nonsense. The exception is not a nuisance to suppress blindly; it tells you the text did not identify a valid calendar day. `timedelta(days=days)` tells Python exactly what the offset means. Adding it to a date crosses the leap day, an ordinary month boundary, or a year boundary without special string cases. A negative offset moves backward. The function returns an ISO string because that is the interface the exercise asks for.

7. 04:11

   Inside a larger program you might keep the date object until it is time to display or save it. Notice also that `fromisoformat` validates the starting date before we shift it. We did not invent a recovery rule for impossible input; the caller receives ValueError. Try replacing 2024 with 2023 in the first call and predict whether two days after February 28 is March 1 or March 2. The best way to learn date handling is to test the boundaries rather than only comfortable middle-of-month inputs. Try a zero offset as a control case: a date plus zero days should come back unchanged.

8. 04:52

   Then test one negative day from March 1 in a leap year; it lands on February 29. These checks help distinguish true calendar arithmetic from code that only special-cases the positive example shown first. Subtracting two date objects gives a timedelta. From February 28 to March 1 in leap year 2024 is two days because February 29 lies between them. Reverse the operands and the sign becomes negative. That is useful for calendar-day counts, overdue checks, or planning tasks. It does not answer a question about an exact instant across locations. A date has no hour or time zone; a meeting at six o'clock in Bratislava and six o'clock in New York are different instants.

9. 05:39

   For those requirements, use timezone-aware datetime values and define which location's clock you mean. The website task intentionally handles whole calendar days only. Test a leap day, a non-leap February, a year boundary, zero days, and a negative offset, then complete the quiz. The browser checker also tries an impossible date to verify you parsed it rather than edited its characters. As an extension, write a function that returns the number of days until a chosen date using date subtraction, and test both future and past targets. The difference of two dates counts elapsed calendar-day boundaries, so the endpoints are not both counted as full days.

10. 06:22

    If a product asks for inclusive days in a booking or billing period, that is a separate rule you must define. date subtraction gives the underlying difference; your application decides how to interpret it.