datetime — 기본 날짜와 시간 타입

datetime 모듈은 날짜와 시간을 다루는 클래스를 제공해요. 날짜와 시간을 조작하고, 표현하고, 산술 연산할 수 있는 풍부한 기능을 담고 있습니다.

출처: Python 표준 라이브러리

본문

날짜와 시간 산술은 시간대(가장 엄밀한 의미는 아니지만 서로 다른 인식)에 대해 섬세한 처리를 하거든요. 그래서 이 모듈의 원칙은 단순한 규칙을 따르는 나이브(naive) 객체와, 오프셋을 아는 인지(aware) 객체를 구분해서 다루는 거예요. 나이브 객체는 세계 협정시(UTC)·현지 시간·기타 시간대에 대한 정보를 전혀 담고 있지 않아요. 반면 인지 객체는 tzinfo 객체를 담고 있어서 정확한 시각을 결정할 수 있죠.

시간대 정보를 다루는 강력한 지원이 필요하다면 zoneinfo 모듈(표준 라이브러리의 IANA 시간대 데이터베이스)도 함께 살펴보는 걸 추천해요.

이 모듈이 다루는 타입

클래스	이름	설명
`datetime.date`	날짜	그레고리력 달력 날짜 하나를 표현해요. 속성: `year`, `month`, `day`
`datetime.time`	시간	하루 중 시간을, 독립적으로 표현해요. 속성: `hour`, `minute`, `second`, `microsecond`, `tzinfo`
`datetime.datetime`	날짜와 시간	날짜와 시간의 조합을 표현해요. 속성: `year` … `microsecond` 그리고 `tzinfo`
`datetime.timedelta`	기간	두 날짜, 시간, 날짜시간 인스턴스 차이(마이크로초 단위 해상도)를 표현해요
`datetime.tzinfo`	시간대 정보 객체	시간대 정보를 담는 추상 기본 클래스예요
`datetime.timezone`	시간대	UTC에서 고정 오프셋을 나타내는 `tzinfo`의 구현이에요

date 객체는 그레고리력 달력의 "현실적인" 날짜를 담고, time 객체는 하루 중 특정 순간을 담아요. datetime은 두 요소를 모두 합친 거고요. timedelta는 이 모든 것들과 함께 산술 연산을 수행할 수 있는 기간을 담아요.

date 타입과 datetime 타입, 그리고 time 타입 변환 순서를 정리하면 이렇게 돼요. date에서 datetime으로, datetime에서 date로, datetime에서 time으로 갈 수는 있지만 date에서 time으로는 직접 갈 수 없어요. date와 time의 결합은 datetime을 만들고, datetime과 timedelta는 timedelta를 만들죠. datetime에서 date, time을 각각 빼면 timedelta가 되어요.

인식 객체와 나이브 객체

표준 시간대 오프셋이 있으면 "지구상의 특정 시점"이 결정돼요. 그래서 인식 객체의 정의는 tzinfo와 tzinfo 상속 클래스가 제공하는 표준 시간대 오프셋을 담고 있는 datetime 또는 time 객체가 돼요. 즉 UtcTzInfo() 같은 표준 시간대 클래스가 있어야 하죠. (대부분 datetime.timezone.utc로 표기해요.)

datetime과 time 객체에 tzinfo가 None이거나 datetime.tzinfo를 상속받지 않은 객체면, datetime의 관점에서는 "인식"하지 못한 나이브 객체예요. 나이브 객체는 실제 시간대를 알 수 없고, 다른 나이브 객체와만 산술 연산할 수 있어요. 인지 여부가 다르면 RuntimeError가 발생하죠.

변환 규칙: datetime.combine()이나 datetime.utcfromtimestamp() 같은 일부 함수와 메서드는 나이브와 인지 datetime 객체의 제한적인 결합을 허용해요. 게다가 인지와 나이브 timedelta는 허용돼요. 다만 datetime.utcnow() 같은 다른 것들은 비판받을 만한 이유로 나이브 datetime을 반환할 수 있어요.

공통 속성

날짜와 시간을 산술 연산하는 데 필요한 기본 타입이 모두 공유하는 속성은 없어요. 단, date, datetime, time, timezone은 모두 timetuple()처럼 하루를 표현하는 데 필요한 핵심 속성을 공유합니다. 그 외에도 datetime은 date의 속성을 모두 갖고, datetime과 time은 date에서 유래한 여러 속성을 공유해요.

timedelta 객체

timedelta 객체는 기간(즉 두 날짜나 시간 사이의 차이)을 나타내요.

class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)

모든 인자는 선택이고 기본값은 0이에요. 인자는 정수나 부동 소수점(음수 포함)일 수 있고, int거나 float이거나 long(int와 동일) 또는 float일 수 있어요.

weeks, days, hours, minutes, seconds, milliseconds, microseconds 같은 인자 단위는 모두 정규화되는데, timedelta(0, 0, 0, 0, 0, 0, 1)은 timedelta(days=7)과 동일해요. timedelta(days=2, hours=6)은 2 days, 6:00:00이 되고 셋 모두 합산돼요.

>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23, minutes=50, seconds=600)  # adds up to 365 days
>>> year.total_seconds()
31536000.0
>>> year == another_year
True
>>> ten_years = 10 * year
>>> ten_years, ten_years.days // 365
(datetime.timedelta(days=3650), 10)
>>> nine_years = ten_years - year
>>> nine_years, nine_years.days // 365
(datetime.timedelta(days=3285), 9)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)

timedelta 객체는 다른 timedelta 객체와 더하거나 뺄 수 있고, 정수·부동 소수점·다른 timedelta와 곱하거나 나눌 수 있어요. min과 max은 음의 기간과 양의 기간 각각의 극한을 나타내요. resolution은 같지 않은 timedelta 객체 간의 가장 작은 차이이고, total_seconds()는 기간을 초 단위로 반환해요.

date 객체

date 객체는 특정 달력 날짜를 나타내요.

class datetime.date(year, month, day)

인자는 지정된 순서대로 위치 인자여야 해요. 모든 인자는 int여야 하고 범위 제약도 있어요: 1 <= year <= 9999, 1 <= month <= 12, 1 <= day <= 주어진 달의 일수.

>>> import datetime
>>> d = datetime.date(2002, 12, 31)
>>> d
datetime.date(2002, 12, 31)
>>> d.day
31
>>> d.month
12
>>> d.year
2002

date.today(), date.fromtimestamp(), date.fromordinal(), date.fromisoformat() 같은 클래스 메서드로도 날짜를 만들 수 있어요. 인스턴스 속성으로는 year, month, day가 있어요. 지원되는 연산으로는 날짜 비교, 날짜와 timedelta의 덧셈/뺄셈, date.replace(), date.weekday(), date.isoweekday(), date.isocalendar(), date.isoformat(), date.strftime(), date.ctime(), date.timetuple() 등이 있습니다.

datetime 객체

datetime 객체는 날짜와 시간의 단일 지점을 나타내요.

class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

year, month, day 인자는 필수고, 나머지는 기본값이 있어요. tzinfo는 None 또는 datetime.tzinfo의 하위 클래스 인스턴스여야 해요.

>>> from datetime import datetime, date, time, timezone
>>> datetime(2002, 12, 31, 23, 59, 59, 500)
datetime.datetime(2002, 12, 31, 23, 59, 59, 500)
>>> datetime.now()
datetime.datetime(2026, 9, 15, 12, 0, 0, 0)
>>> datetime.combine(date(2002, 12, 31), time(23, 59, 59))
datetime.datetime(2002, 12, 31, 23, 59, 59)
>>> datetime.fromtimestamp(1040241600, timezone.utc)
datetime.datetime(2002, 12, 31, 12, 0, 0, tzinfo=datetime.timezone.utc)

인스턴스 속성(year, month, day, hour, minute, second, microsecond, tzinfo, fold)과 더불어, datetime은 date의 속성(weekday, isocalendar 등)도 상속해요. strftime() 메서드로 형식 문자열(%Y-%m-%d %H:%M:%S 등)을 지정해 출력을 바꿀 수 있고, isoformat()은 ISO 8601 형식을 반환해요.

time 객체

time 객체는 (날짜와 무관하게) 하루 중 특정 시각을 나타내요.

class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)

>>> from datetime import time
>>> time(12, 30, 45)
datetime.time(12, 30, 45)
>>> time(hour=23, minute=59, second=59, microsecond=500000)
datetime.time(23, 59, 59, 500000)
>>> t = time(12, 30, 45, tzinfo=timezone.utc)
>>> t.isoformat()
'12:30:45+00:00'

시간 간격의 끝을 나타내는 max는 time(23, 59, 59, 999999)이고, min은 time(0), resolution은 time(0, 0, 0, 1)이에요.

tzinfo 객체

tzinfo는 시간대 정보를 담는 추상 기본 클래스예요. 인스턴스는 datetime과 time 객체에 전달돼서 지역 시간과 UTC 사이의 변환을 다루게 돼요. tzinfo 사용 예는 datetime과 time 생성자에 tzinfo를 전달하는 것이에요.

class datetime.tzinfo

tzinfo는 utcoffset(), dst(), tzname() 메서드를 제공해요. 이들은 하위 클래스에서 구현해야 해요. fromutc()도 오프셋이 변경되는 시간대(예: 일광 절약 시간제)의 산술을 올바르게 하려면 함께 구현해 주는 편이 좋아요.

datetime.tzinfo의 하위 클래스를 "파리" 같은 특정 지역 시간대를 표현하도록 인스턴스화하는 건 일반적이에요. zoneinfo가 IANA 시간대 데이터베이스 기반 구현을 제공해요.

표준 오프셋 인식을 만들려면 datetime.timezone을 사용하면 돼요:

>>> from datetime import datetime, timezone
>>> datetime.now(tz=timezone.utc)
datetime.datetime(2026, 9, 15, 3, 0, 0, 0, tzinfo=datetime.timezone.utc)

timezone 객체

timezone은 UTC로부터의 고정 오프셋을 나타내는 tzinfo의 구현이에요.

class datetime.timezone(offset, name=None)

>>> from datetime import timezone, timedelta
>>> timezone(timedelta(hours=-5))
datetime.timezone(datetime.timedelta(days=-1, seconds=68400))
>>> timezone(timedelta(hours=-5), name="EST")
datetime.timezone(datetime.timedelta(days=-1, seconds=68400), 'EST')

미리 정의된 timezone.utc 상수가 있어서 timezone.utc로 UTC 시간대를 바로 쓸 수 있어요.

strftime()과 strptime() 동작

datetime·date·time 객체는 모두 strftime(format)으로 형식 지정된 문자열을 만들고, datetime.strptime()은 파싱된 문자열에서 datetime을 만들어요. 주요 형식 지시자로는 %Y(연 4자리), %y(연 2자리), %m(월), %d(일), %H(24시간제 시), %M(분), %S(초), %f(마이크로초), %z(UTC 오프셋), %Z(시간대 이름) 등이 있어요.

>>> from datetime import datetime
>>> datetime.now().strftime("%Y-%m-%d %H:%M:%S")
'2026-09-15 12:00:00'
>>> datetime.strptime("2026-09-15 12:00:00", "%Y-%m-%d %H:%M:%S")
datetime.datetime(2026, 9, 15, 12, 0, 0)

더 알아보기

calendar 모듈: 달력 관련 일반 함수
time 모듈: 하위 수준의 시간 관련 함수
zoneinfo 모듈: IANA 시간대 데이터베이스 기반의 구체적 시간대
time.strftime()과 time.strptime() 및 날짜 형식 지시자 문서