timeモジュールは、時刻に関するさまざまなクラスメソッドを提供しています。それらはUNIX時間（カレンダー時間）を扱うメソッドとシステムクロックを扱うメソッドに大別できます。そのほか一定時間スリープするためのsleep()メソッドもこのモジュールで提供されています。
関連する機能にはdatetimeモジュールがあります。datetimeモジュールはカレンダー（グレゴリオ暦）を扱う便利な機能が数多くあります。1つのマシン上でカレンダーを扱う場合はdatetimeモジュールを使った方が便利な場合が多いでしょう。datetimeモジュールについては次の記事で詳しく解説していますので、興味があればご参照ください。
一方、timeモジュールはUNIX時間という絶対時間を扱うので、他のマシンとのデータ交換に適しています。
timeモジュールのほとんどのメソッドはOSのシステムコールを呼び出すため、すべてのメソッドが常に利用できるわけではないことに注意してください。この記事では多くのOSで利用可能なメソッドについて詳しく解説します。
なお、この記事の例は日本標準時（JST）のシステム上で実行していますので、ローカル時刻はUTCより9時間進んだ時刻になります（UTC時刻が午前0時の場合、ローカル時刻は午前9時になる）。
スレッドをスリープする
はじめに使う機会も多く、説明も簡単なクラスメソッドsleep()から紹介します。
クラスメソッドsleep()は引数に与えられた秒数の間、呼び出したスレッドの実行を一時停止します。引数には整数または浮動小数点数を渡すことができます。
>>> time.sleep(3)
>>> time.sleep(1.384)一時停止する時間は、システムのスケジューリングにより指定された時間よりも長くなる場合があります。
UNIX時間とstruct_timeオブジェクトを扱うクラスメソッド
UNIX時間はUTCの1970年1月1日午前0時0分0秒からの経過時間で、ある時点の時刻を表します。struct_timeオブジェクトはUNIX時間よりもわかりやすい形式である時点の時刻を表します。struct_timeオブジェクトの詳細は後述します。
ここではこの2つの形式の時刻を扱うクラスメソッドについて解説します。
現在の時刻を取得する — time()、gmtime()、localtime()
現在時刻をUNIX時間で取得するにはクラスメソッドtime()を使います。time()は1970年1月1日午前0時0分0秒からの経過時間（UNIX時間）の秒数を浮動小数点数で返します。
>>> import time
>>> now = time.time()
>>> now
1685506832.767415gmtime()とlocaltime()クラスメソッドは、現在時刻をstruct_timeオブジェクトで返します。gmtime()はUTCの時刻を返し、localtime()はシステムのローカル時刻を返します。
>>> gm_now = time.gmtime()
>>> gm_now
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=4, tm_min=20, tm_sec=45, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> local_now = time.localtime()
>>> local_now
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=13, tm_min=20, tm_sec=56, tm_wday=2, tm_yday=151, tm_isdst=0)UNIX時間とstruct_timeオブジェクトの変換 — gmtime()、localtime()、mktime()
gmtime()とlocaltime()クラスメソッドの引数にtime()が返すようなUNIX時間を渡すと、その時間を表すstruct_timeオブジェクトを返します。
gmtime()はUTCの時刻を返し、localtime()はシステムのローカル時刻を返します。
>>> now = time.time()
>>> now
1685506832.767415
>>> time.gmtime(now)
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=4, tm_min=20, tm_sec=32, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> time.localtime(now)
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=13, tm_min=20, tm_sec=32, tm_wday=2, tm_yday=151, tm_isdst=0)UNIX時間とstruct_timeオブジェクトは精度が異なるため、完全に等価にはならないことに注意してください。
クラスメソッドmktime()はlocaltime()の逆を行います。引数にstruct_timeオブジェクトを渡して呼び出すとUNIX時間を浮動小数点数で返します。
>>> now
1685506832.767415
>>> st = time.localtime(now)
>>> st
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=13, tm_min=20, tm_sec=32, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> time.mktime(st)
1685506832.0時刻の文字列表現 — ctime()、asctime()
クラスメソッドctime()を使えば、Unix時間をローカル時刻の文字列表現に変換できます。
>>> time.ctime(now)
'Tue May 23 22:12:22 2023'クラスメソッドasctime()は、struct_timeオブジェクトを文字列表現を返します。
>>> gm_now
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=4, tm_min=20, tm_sec=45, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> local_now
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=13, tm_min=20, tm_sec=56, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> time.asctime(gm_now)
'Wed May 31 04:20:45 2023'
>>> time.asctime(local_now)
'Wed May 31 13:20:56 2023'ctime()とasctime()の引数を省略すると現在のローカル時刻の文字列表現を返します。
>>> time.ctime()
'Wed May 31 13:30:39 2023'
>>> time.asctime()
'Wed May 31 13:30:44 2023'時刻を整形した文字列に変換するにはクラスメソッドstrftime()を使います。これについてはこの後すぐ説明します。
strftime()とstrptime()
クラスメソッドstrftime()は、struct_timeオブジェクトを書式指定文字列にしたがって文字列に変換して返します。struct_timeオブジェクトの引数を省略すると、現在のローカル時刻を書式指定文字列にしたがって文字列に変換します。
書式指定文字列に使用できる主な書式指定子には次のものがあります。書式指定文字列の中の書式指定子はオブジェクトの対応する値で置き換えられます。
| 書式指定子 | 意味 | 例 |
|---|---|---|
| %Y | 年（4桁） | 2020, 2021, … |
| %y | 年（下2桁） | 20,21, … |
| %m | 月（1桁の場合は0が先行） | 01-12 |
| %d | 日（1桁の場合は0が先行） | 01-31 |
| %H | 時（24時間表記。1桁の場合は0が先行） | 00-23 |
| %I | 時（12時間表記。1桁の場合は0が先行） | 01-12 |
| %M | 分 | 00-59 |
| %S | 秒 | 00-61 |
| %p | ロケールのAM/PMを表す文字列 | AM, PM |
| %a | ロケールの曜日の短縮形 | Sun, …, Sat |
| %A | ロケールの曜日 | Sunday, …, Saturday |
| %b | ロケールの月名の短縮形 | Jan, …, Dec |
| %B | ロケールの月名 | January, …, December |
strftime()の使用例を次に示します。
>>> time.strftime('%Y/%m/%d', local_now)
'2023/05/31'
>>> time.strftime('%H:%M', gm_now)
'04:20'strftime()とは反対に、クラスメソッドstrptime()は時刻を表す文字列を書式指定文字列にしたがって解析し、struct_timeオブジェクトを返します。
書式指定文字列には前述の書式指定子を使用します。
>>> time.strptime('2023/04/21 19:30:24', '%Y/%m/%d %H:%M:%S')
time.struct_time(tm_year=2023, tm_mon=4, tm_mday=21, tm_hour=19, tm_min=30, tm_sec=24, tm_wday=4, tm_yday=111, tm_isdst=-1)strptime()で取得できなかったstruct_timeオブジェクトの属性はデフォルト値に設定されます。次の例の最初は、そのデフォルト値を示しています。strptime()から値が取得できなかったため、すべての属性はデフォルト値に設定されています。
# strptime()が返すstruct_timeオブジェクトのデフォルト値
>>> time.strptime('', '')
time.struct_time(tm_year=1900, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=0, tm_yday=1, tm_isdst=-1)
# 時と分以外はデフォルト値
>>> time.strptime('19:30', '%H:%M')
time.struct_time(tm_year=1900, tm_mon=1, tm_mday=1, tm_hour=19, tm_min=30, tm_sec=0, tm_wday=0, tm_yday=1, tm_isdst=-1)struct_timeオブジェクト
struct_timeオブジェクトはgmtime()、 localtime()、strptime() が返す時刻を表すシーケンス型オブジェクトです。これは名前付きタプル のインターフェースも持っているため、属性はインデックスでも属性名でもアクセスできます。
struct_timeオブジェクトの属性には以下があります。
| インデックス | 属性 | 値の例 |
|---|---|---|
| 0 | tm_year | 2020, 2021, … |
| 1 | tm_mon | 1-12 |
| 2 | tm_mday | 1-31 |
| 3 | tm_hour | 0-23 |
| 4 | tm_min | 0-59 |
| 5 | tm_sec | 0-61 60はうるう秒を表し、61は歴史的理由によりサポートされている。 |
| 6 | tm_wday | 0-6 |
| 7 | tm_yday | 1-366 |
| 8 | tm_isdst | 0、1 または-1 夏時間が有効な場合は1、無効な場合は0、夏時間について不明な場合は-1です。 |
| – | tm_zone | タイムゾーンの短縮名 |
| – | tm_gmtoff | UTC から東方向へのオフセット (秒) |
>>> local_now
time.struct_time(tm_year=2023, tm_mon=5, tm_mday=31, tm_hour=13, tm_min=20, tm_sec=56, tm_wday=2, tm_yday=151, tm_isdst=0)
>>> local_now[2]
31
>>> local_now.tm_mday
31システムクロックを利用する
timeモジュールは、システムクロックを扱う次のようなクラスメソッドを提供します。
| クラスメソッド | 説明 |
|---|---|
| time.monotonic() time.monotonic_ns() | モノトニッククロック、すなわち後戻りしないクロックの値を (小数秒で) 返します。このクロックはシステムクロックの更新の影響を受けません。 |
| time.perf_counter() time.perf_counter_ns() | パフォーマンスカウンター、すなわち短い時間を計測するための可能な限り高い分解能を持つクロックの値を (小数秒で) 返します。これはスリープ中の経過時間を含みます。、システムワイドです。戻り値の基準点は定義されていないので、二回の呼び出しの結果の差だけが有効です。 |
| time.process_time() time.process_time_ns() | 現在のプロセスのシステムCPU時間とユーザーCPU時間の合計時間の値を返します。これはスリープ中の経過時間を含みません。 |
| time.thread_time() time.thread_time_ns() | 現在のスレッドのシステムCPU時間とユーザーCPU時間の合計時間の値を返します。これはスリープ中の経過時間を含みません。 |
これらのメソッドには以下の共通点があります。
- これらのメソッドは基準点からの時間を返しますが、基準点の時刻は定義されていないので、複数回計測した結果の差だけが意味があります。
- これらのメソッドには浮動小数点数で秒数を返すバージョンと、ナノ秒を整数で返すバージョン（_nsで終わるメソッド）があります。
これらのメソッドは何かしらの処理の前後で呼び出し、その間の処理時間を計測するために利用します。
t1 = time.monotonic()
何らかの処理
t2 = time.monotonic()
処理時間 = t2 - t1おわりに
カレンダーの時刻を扱う場合は、UNIX時間よりdatetimeモジュールのオブジェクトを使った方が便利なことが多いと思います。したがって、timeモジュールは、sleep()やシステムクロックへのアクセスで利用することがほとんどになるかと思います。
