time — 시간 접근과 변환

time — 시간 접근과 변환

이 모듈은 다양한 시간 관련 함수를 제공해요. 관련 기능에 대해서는 datetime 모듈과 calendar 모듈도 참고하세요.

이 모듈은 항상 사용할 수 있지만, 모든 함수가 모든 플랫폼에서 사용 가능한 것은 아니에요. 이 모듈에 정의된 대부분의 함수는 같은 이름의 플랫폼 C 라이브러리 함수를 호출해요. 함수의 의미가 플랫폼마다 다르므로 플랫폼 문서를 참고하는 것이 도움이 될 때가 있어요.

출처: Python documentation

본문

용어와 규칙

• epoch(에포크): 시간이 시작되는 지점이자 time.gmtime(0)의 반환값이에요. 모든 플랫폼에서 1970년 1월 1일 00:00:00 (UTC)이에요.
• seconds since the epoch(에포크 이후 초): 에포크 이후 경과한 총 초 수로, 보통 윤초(leap second)를 제외해요. 모든 POSIX 호환 플랫폼에서 윤초는 이 합계에서 제외돼요.
• 이 모듈의 함수는 에포크 이전이나 먼 미래의 날짜와 시간을 처리하지 못할 수 있어요. 미래의 한계 지점은 C 라이브러리에 의해 결정되며, 32비트 시스템에서는 보통 2038년이에요.
• strptime()은 %y 형식 코드가 주어지면 두 자리 연도를 파싱할 수 있어요. 두 자리 연도를 파싱할 때는 POSIX와 ISO C 표준에 따라 변환돼요. 즉 69–99는 1969–1999로, 0–68은 2000–2068로 매핑돼요.
• UTC는 국제 시간 기준(Coordinated Universal Time)이며, 국제 시간 유지의 기준으로서 그리니치 표준시(GMT)를 대체했어요. 약어 UTC는 오타가 아니라, UT0, UT1, UT2 같은 시간 표준의 초기 언어 비종속적 명명 체계를 따르는 것이에요.
• DST는 일광 절약 시간(Daylight Saving Time)으로, 일 년 중 일부 기간 동안(보통) 한 시간씩 시간대를 조정하는 것이에요. DST 규칙은 지역 법률에 따라 정해지고 매년 바뀔 수 있어요.

각종 실시간 함수의 정밀도는 값이나 인자를 표현하는 단위가 암시하는 것보다 낮을 수 있어요. 예를 들어 대부분의 Unix 시스템에서 시계는 1초에 50~100회만 "틱"해요. 반면에 time()과 sleep()의 정밀도는 Unix 대응 함수보다 좋아요. 시간은 부동소수점 수로 표현되고, time()은 사용 가능한 가장 정확한 시간을 반환하며, sleep()은 0이 아닌 소수 부분을 가진 시간을 받아들여요.

gmtime(), localtime(), strptime()이 반환하고 asctime(), mktime(), strftime()이 받아들이는 시간 값은 9개의 정수 시퀀스예요. struct_time에 대한 설명은 해당 항목을 참고하세요.

Functions (함수)

다음 함수들을 사용해 시간 표현을 변환할 수 있어요: 에포크 이후 초 → UTC의 struct_time은 gmtime(), 에포크 이후 초 → 지역 시간의 struct_time은 localtime(), UTC의 struct_time → 에포크 이후 초는 calendar.timegm(), 지역 시간의 struct_time → 에포크 이후 초는 mktime()을 사용해요.

• time.asctime([time_tuple]) — gmtime() 또는 localtime()이 반환한 시간을 나타내는 튜플이나 struct_time을 'Sun Jun 20 23:21:05 1993' 형태의 문자열로 변환해요. time_tuple이 주어지지 않으면 localtime()이 반환한 현재 시간을 사용해요.
• time.pthread_getcpuclockid(thread_id, /) — 지정된 thread_id에 대한 스레드별 CPU 시간 시계의 clk_id를 반환해요. threading.get_ident()나 threading.Thread 객체의 ident 속성을 사용해 thread_id에 적합한 값을 얻을 수 있어요. 유효하지 않거나 만료된 thread_id를 전달하면 segmentation fault 같은 정의되지 않은 동작이 발생할 수 있어요. (Unix)
• time.clock_getres(clk_id, /) — 지정된 시계 clk_id의 분해능(정밀도)을 반환해요. (Unix)
• time.clock_gettime(clk_id, /) → float — 지정된 시계 clk_id의 시간을 반환해요. float 타입으로 인한 정밀도 손실을 피하려면 clock_gettime_ns()를 사용하세요. (Unix)
• time.clock_gettime_ns(clk_id, /) → int — clock_gettime()과 비슷하지만 시간을 나노초로 반환해요. (Unix)
• time.clock_settime(clk_id, time: float, /) — 지정된 시계 clk_id의 시간을 설정해요. 현재 CLOCK_REALTIME이 clk_id에 허용되는 유일한 값이에요. (Unix, Android와 iOS 아님)
• time.clock_settime_ns(clk_id, time: int, /) — clock_settime()과 비슷하지만 나노초로 시간을 설정해요.
• time.ctime(seconds=None, /) — 에포크 이후 초로 표현된 시간을 'Sun Jun 20 23:21:05 1993' 형태의 지역 시간 문자열로 변환해요. seconds가 주어지지 않거나 None이면 time()이 반환한 현재 시간을 사용해요.
• time.get_clock_info(name, /) — 지정된 시계에 대한 정보를 namespace 객체로 가져와요. 지원되는 시계 이름과 값 읽기 함수는 'monotonic'(time.monotonic()), 'perf_counter'(time.perf_counter()), 'process_time'(time.process_time()), 'thread_time'(time.thread_time()), 'time'(time.time())이에요. 결과에는 adjustable, implementation, monotonic, resolution 속성이 있어요.
• time.gmtime(seconds=None, /) — 에포크 이후 초로 표현된 시간을 UTC의 struct_time으로 변환해요. 이때 dst 플래그는 항상 0이에요. seconds가 주어지지 않거나 None이면 현재 시간을 사용해요.
• time.localtime(seconds=None, /) — gmtime()과 비슷하지만 지역 시간으로 변환해요. dst 플래그는 주어진 시간에 DST가 적용되면 1로 설정돼요. 타임스탬프가 플랫폼 C localtime()이나 gmtime()이 지원하는 값 범위 밖이면 OverflowError를, localtime()이나 gmtime() 실패 시에는 OSError를 일으킬 수 있어요.
• time.mktime(time_tuple, /) — localtime()의 역함수예요. 인자는 지역 시간(UTC 아님)을 표현하는 struct_time 또는 전체 9튜플이에요. time()과의 호환을 위해 부동소수점 수를 반환해요. 유효한 시간으로 표현할 수 없는 입력이면 OverflowError나 ValueError가 발생해요.
• time.monotonic() → float — 거슬러 갈 수 없는 단조 시계(monotonic clock)의 값(소수 초)을 반환해요. 시스템 시계 업데이트의 영향을 받지 않아요. 반환값의 기준점은 정의되지 않으므로, 두 호출 결과의 차이만 유효해요. float 타입으로 인한 정밀도 손실을 피하려면 monotonic_ns()를 사용하세요.
• time.perf_counter() → float — 짧은 기간을 측정하는 데 가장 높은 분해능을 가진 성능 카운터 값(소수 초)을 반환해요. sleep 중 경과한 시간도 포함해요. 모든 프로세스에서 같은 시계를 사용해요. perf_counter_ns()도 참고하세요.
• time.process_time() → float — 현재 프로세스의 시스템 및 사용자 CPU 시간 합계(소수 초)를 반환해요. sleep 중 경과 시간은 포함하지 않아요. 프로세스 전체 기준이에요.
• time.sleep(seconds, /) — 호출 스레드의 실행을 주어진 초 수만큼 중단해요. 인자는 더 정밀한 sleep 시간을 나타내는 부동소수점 수일 수 있어요. sleep이 신호로 중단되고 신호 처리기가 예외를 일으키지 않으면, sleep은 시간 초과를 다시 계산해 재시작돼요. Windows 10 이상에서는 100나노초 분해능의 고해상도 타이머를 사용해요.
• time.strftime(format[, time_tuple]) — gmtime()이나 localtime()이 반환한 시간을 나타내는 튜플이나 struct_time을 format 인자가 지정한 문자열로 변환해요. time_tuple이 주어지지 않으면 현재 시간을 사용해요. format은 문자열이어야 해요.
• time.strptime(string[, format]) — 형식에 따라 시간을 나타내는 문자열을 파싱해요. 반환값은 gmtime()이나 localtime()이 반환한 것과 같은 struct_time이에요. format은 strftime()이 사용하는 것과 같은 지시어를 사용하고, 기본값은 "%a %b %d %H:%M:%S %Y"예요. 파싱할 수 없으면 ValueError가 발생해요.

classtime.struct_time

gmtime(), localtime(), strptime()이 반환하는 시간 값 시퀀스의 타입이에요. named tuple 인터페이스를 가진 객체로, 값은 인덱스와 속성 이름으로 모두 접근할 수 있어요. 다음 값들이 존재해요:

C 구조체와 달리 월 값은 [1, 12] 범위라는 점을 주의하세요.

기타 함수와 상수

• time.time() → float — 에포크 이후 초 단위 시간을 부동소수점 수로 반환해요. 윤초 처리는 플랫폼에 따라 다르며, Windows와 대부분의 Unix 시스템에서는 에포크 이후 초에 윤초를 세지 않아요(Unix time).
• time.time_ns() → int — time()과 비슷하지만 에포크 이후 나노초를 정수로 반환해요.
• time.thread_time() → float — 현재 스레드의 시스템 및 사용자 CPU 시간 합계(소수 초)를 반환해요. sleep 중 경과 시간은 포함하지 않아요. 스레드별 기준이에요. (Linux, Unix, Windows)
• time.tzset() — 라이브러리 루틴이 사용하는 시간 변환 규칙을 재설정해요. TZ 환경 변수가 이를 지정해요. (Unix)

Clock ID Constants (시계 ID 상수)

clock_getres()와 clock_gettime()의 매개변수로 사용되는 상수들이에요:

• time.CLOCK_BOOTTIME — CLOCK_MONOTONIC과 동일하지만 시스템이 일시 중단된 시간도 포함해요. (Linux >= 2.6.39)
• time.CLOCK_HIGHRES — Solaris OS의 고해상도 시계로, 최적의 하드웨어 소스를 사용하고 나노초에 가까운 분해능을 줄 수 있어요. (Solaris)
• time.CLOCK_MONOTONIC — 설정할 수 없고 어떤 지정되지 않은 시작점 이후의 단조 시간을 나타내는 시계예요. (Unix)
• time.CLOCK_MONOTONIC_RAW — CLOCK_MONOTONIC과 비슷하지만 NTP 조정을 받지 않는 원시 하드웨어 기반 시간에 접근해요. (Linux >= 2.6.28, macOS >= 10.12)
• time.CLOCK_PROCESS_CPUTIME_ID — CPU의 고해상도 프로세스별 타이머예요. (Unix)
• time.CLOCK_THREAD_CPUTIME_ID — 스레드별 CPU 시간 시계예요. (Unix)

clock_settime()에 보낼 수 있는 유일한 상수는 다음과 같아요:

• time.CLOCK_REALTIME — 실시간 시계예요. 이 시계를 설정하려면 적절한 권한이 필요하고, 모든 프로세스에서 같아요. (Unix)

Timezone Constants (시간대 상수)

• time.altzone — 정의된 경우 지역 DST 시간대의 UTC 서쪽 오프셋(초)이에요. daylight가 0이 아닐 때만 사용하세요.
• time.daylight — DST 시간대가 정의되어 있으면 0이 아닌 값이에요.
• time.timezone — 지역(비-DST) 시간대의 UTC 서쪽 오프셋(초)이에요.
• time.tzname — 두 문자열의 튜플로, 첫 번째는 지역 비-DST 시간대 이름, 두 번째는 지역 DST 시간대 이름이에요.

위 시간대 상수의 값은 모듈 로드 시점이나 마지막 tzset() 호출 시점에 적용된 시간대 규칙에 따라 결정되며, 과거 시간에 대해서는 올바르지 않을 수 있어요. 시간대 정보를 얻으려면 localtime()의 tm_gmtoff와 tm_zone 결과를 사용하는 것이 권장돼요.

더 알아보기 (Learn more)

• Python 공식 문서