datetime
--- 基本的な日付型および時間型¶
ソースコード: Lib/datetime.py
The datetime
module supplies classes for manipulating dates and times.
日付や時刻に対する算術がサポートされている一方、実装では出力のフォーマットや操作のための効率的な属性の抽出に重点を置いています。
Tip
書式コード に飛ぶ。
参考
calendar
モジュール汎用のカレンダー関連関数。
time
モジュール時刻へのアクセスと変換。
zoneinfo
モジュールIANAタイムゾーンデータベースを表す具体的なタイムゾーン。
- dateutil パッケージ
拡張タイムゾーンと構文解析サポートのあるサードパーティーライブラリ。
- DateType パッケージ
Third-party library that introduces distinct static types to e.g. allow static type checkers to differentiate between naive and aware datetimes.
Aware オブジェクトと Naive オブジェクト¶
日時のオブジェクトは、それらがタイムゾーンの情報を含んでいるかどうかによって "aware" あるいは "naive" に分類されます。
タイムゾーンや夏時間の情報のような、アルゴリズム的で政治的な適用可能な時間調節に関する知識を持っているため、 aware オブジェクトは他の aware オブジェクトとの相対関係を特定できます。 aware オブジェクトは解釈の余地のない特定の実時刻を表現します。 [1]
naive オブジェクトには他の日付時刻オブジェクトとの相対関係を把握するのに足る情報が含まれません。あるプログラム内の数字がメートルを表わしているのか、マイルなのか、それとも質量なのかがプログラムによって異なるように、naive オブジェクトが協定世界時 (UTC) なのか、現地時間なのか、それとも他のタイムゾーンなのかはそのプログラムに依存します。Naive オブジェクトはいくつかの現実的な側面を無視してしまうというコストを無視すれば、簡単に理解でき、うまく利用することができます。
aware オブジェクトを必要とするアプリケーションのために、 datetime
と time
オブジェクトは追加のタイムゾーン情報の属性 tzinfo
を持ちます。
tzinfo
には抽象クラス tzinfo
のサブクラスのインスタンスを設定できます。
これらの tzinfo
オブジェクトは UTC 時間からのオフセットやタイムゾーンの名前、夏時間が実施されるかどうかの情報を保持しています。
Only one concrete tzinfo
class, the timezone
class, is
supplied by the datetime
module. The timezone
class can
represent simple timezones with fixed offsets from UTC, such as UTC itself or
North American EST and EDT timezones. Supporting timezones at deeper levels of
detail is up to the application. The rules for time adjustment across the
world are more political than rational, change frequently, and there is no
standard suitable for every application aside from UTC.
定数¶
The datetime
module exports the following constants:
- datetime.UTC¶
UTCタイムゾーンシングルトン
datetime.timezone.utc
の別名。バージョン 3.11 で追加.
利用可能なデータ型¶
- class datetime.date
理想的な naive な日付で、これまでもこれからも現在のグレゴリオ暦 (Gregorian calender) が有効であることを仮定しています。 属性は
year
,month
,およびday
です。
- class datetime.time
理想的な時刻で、特定の日から独立しており、毎日が厳密に 24*60*60 秒であると仮定しています。("うるう秒: leap seconds" の概念はありません。) 属性は
hour
,minute
,second
,microsecond
, およびtzinfo
です。
- class datetime.datetime
日付と時刻を組み合わせたものです。 属性は
year
,month
,day
,hour
,minute
,second
,microsecond
, およびtzinfo
です。
- class datetime.timedelta
A duration expressing the difference between two
datetime
ordate
instances to microsecond resolution.
- class datetime.tzinfo
タイムゾーン情報オブジェクトの抽象基底クラスです。
datetime
およびtime
クラスで用いられ、カスタマイズ可能な時刻修正の概念 (たとえばタイムゾーンや夏時間の計算) を提供します。
- class datetime.timezone
tzinfo
抽象基底クラスを UTC からの固定オフセットとして実装するクラスです。バージョン 3.2 で追加.
これらの型のオブジェクトは変更不可能 (immutable) です。
サブクラスの関係は以下のようになります:
object
timedelta
tzinfo
timezone
time
date
datetime
共通の特徴¶
オブジェクトが Aware なのか Naive なのかの判断¶
date
型のオブジェクトは常に naive です。
time
型あるいは datetime
型のオブジェクトは aware か naive のどちらかです。
次の条件を両方とも満たす場合、 datetime
オブジェクト d は aware です:
d.tzinfo
がNone
でないd.tzinfo.utcoffset(d)
がNone
を返さない
どちらかを満たさない場合は、 d は naive です。
次の条件を両方とも満たす場合、 time
オブジェクト t は aware です:
t.tzinfo
がNone
でないt.tzinfo.utcoffset(None)
がNone
を返さない
どちらかを満たさない場合は、 t は naive です。
aware なオブジェクトと naive なオブジェクトの区別は timedelta
オブジェクトにはあてはまりません。
timedelta
オブジェクト¶
A timedelta
object represents a duration, the difference between two
datetime
or date
instances.
- class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)¶
全ての引数がオプションで、デフォルト値は
0
です。 引数は整数、浮動小数点数でもよく、正でも負でもかまいません。days, seconds, microseconds だけが内部的に保持されます。 引数は以下のようにして変換されます:
1 ミリ秒は 1000 マイクロ秒に変換されます。
1 分は 60 秒に変換されます。
1 時間は 3600 秒に変換されます。
1 週間は 7 日に変換されます。
さらに、値が一意に表されるように days, seconds, microseconds が以下のように正規化されます
0 <= microseconds < 1000000
0 <= seconds < 3600*24
(一日中の秒数)-999999999 <= days <= 999999999
次の例は、 days, seconds, microseconds に加えて任意の引数がどう "集約" され、最終的に3つの属性に正規化されるかの説明をしています:
>>> from datetime import timedelta >>> delta = timedelta( ... days=50, ... seconds=27, ... microseconds=10, ... milliseconds=29000, ... minutes=5, ... hours=8, ... weeks=2 ... ) >>> # Only days, seconds, and microseconds remain >>> delta datetime.timedelta(days=64, seconds=29156, microseconds=10)
引数のいずれかが浮動小数点であり、小数のマイクロ秒が存在する場合、小数のマイクロ秒は全ての引数から一度取り置かれ、それらの和は最近接偶数のマイクロ秒に丸められます。浮動小数点の引数がない場合、値の変換と正規化の過程は厳密な (失われる情報がない) ものとなります。
日の値を正規化した結果、指定された範囲の外側になった場合には、
OverflowError
が送出されます。負の値を正規化すると、最初は混乱するような値になります。例えば:
>>> from datetime import timedelta >>> d = timedelta(microseconds=-1) >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999)
以下にクラス属性を示します:
- timedelta.max¶
最大の値を表す
timedelta
オブジェクトで、timedelta(days=999999999, hours=23, minutes=59, seconds=59, microseconds=999999)
です。
正規化のために、 timedelta.max
> -timedelta.min
となるので注意してください。 -timedelta.max
は timedelta
オブジェクトとして表現することができません。
インスタンスの属性 (読み出しのみ):
属性 |
値 |
---|---|
|
両端値を含む -999999999 から 999999999 の間 |
|
両端値を含む 0 から 86399 の間 |
|
両端値を含む 0 から 999999 の間 |
サポートされている演算を以下に示します:
演算 |
結果 |
---|---|
|
t2 と t3 の和。演算後、t1-t2 == t3 および t1-t3 == t2 は真になります。(1) |
|
t2 と t3 の差分です。演算後、 t1 == t2 - t3 および t2 == t1 + t3 は真になります。 (1)(6) |
|
時間差と整数の積。演算後、t1 // i == t2 は |
一般的に、t1 * i == t1 * (i-1) + t1 は真となります。(1) |
|
|
時間差と浮動小数点の積。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。 |
|
t2 を t3 で除算 (3) したもの。 |
|
時間差を浮動小数点や整数で除したもの。結果は最近接偶数への丸めを利用して最も近い timedelta.resolution の倍数に丸められます。 |
|
floor が計算され、余りは (もしあれば) 捨てられます。後者の場合、整数が返されます。(3) |
|
剰余が |
|
商と剰余が計算されます: |
|
同じ値を持つ |
|
|
|
|
|
|
|
|
注釈:
この演算は正確ですが、オーバフローするかもしれません。
この演算は正確であり、オーバフローし得ません。
0 による除算は
ZeroDivisionError
を送出します。-timedelta.max は
timedelta
オブジェクトで表現することができません。timedelta
オブジェクトの文字列表現は内部表現に類似した形に正規化されます。そのため負の timedelta は少し変な結果になります。例えば:>>> timedelta(hours=-5) datetime.timedelta(days=-1, seconds=68400) >>> print(_) -1 day, 19:00:00
t3 が
timedelta.max
のときを除けば、式t2 - t3
は常に、式t2 + (-t3)
と同等です。t3 がtimedelta.max
の場合、前者の式は結果の値が出ますが、後者はオーバーフローを起こします。
上に列挙した操作に加え timedelta
オブジェクトは date
および datetime
オブジェクトとの間で加減算をサポートしています (下を参照してください)。
バージョン 3.2 で変更: timedelta
オブジェクトの別の timedelta
オブジェクトによる、切り捨て除算と真の除算、および剰余演算と divmod()
関数がサポートされるようになりました。 timedelta
オブジェクトと float
オブジェクトの真の除算と掛け算がサポートされるようになりました。
timedelta
objects support equality and order comparisons.
ブール演算コンテキストでは、 timedelta
オブジェクトは timedelta(0)
に等しくない場合かつそのときに限り真となります。
インスタンスメソッド:
- timedelta.total_seconds()¶
この期間に含まれるトータルの秒数を返します。
td / timedelta(seconds=1)
と等価です。 秒以外の期間の単位では、直接に除算する形式 (例えばtd / timedelta(microseconds=1)
) が使われます。非常に長い期間 (多くのプラットフォームでは270年以上) については、このメソッドはマイクロ秒の精度を失うことがあることに注意してください。
バージョン 3.2 で追加.
使用例: timedelta
¶
正規化の追加の例です:
>>> # Components of another_year add up to exactly 365 days
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> another_year = timedelta(weeks=40, days=84, hours=23,
... minutes=50, seconds=600)
>>> year == another_year
True
>>> year.total_seconds()
31536000.0
timedelta
の計算の例です:
>>> from datetime import timedelta
>>> year = timedelta(days=365)
>>> ten_years = 10 * year
>>> ten_years
datetime.timedelta(days=3650)
>>> ten_years.days // 365
10
>>> nine_years = ten_years - year
>>> nine_years
datetime.timedelta(days=3285)
>>> three_years = nine_years // 3
>>> three_years, three_years.days // 365
(datetime.timedelta(days=1095), 3)
date
オブジェクト¶
date
オブジェクトは、両方向に無期限に拡張された現在のグレゴリオ暦という理想化された暦の日付 (年月日) を表します。
1 年 1 月 1 日は日番号 1、1 年 1 月 2 日は日番号 2 と呼ばれ、他も同様です。 [2]
- class datetime.date(year, month, day)¶
全ての引数が必須です。 引数は整数で、次の範囲に収まっていなければなりません:
MINYEAR <= year <= MAXYEAR
1 <= month <= 12
1 <= day <= 指定された月と年における日数
範囲を超えた引数を与えた場合、
ValueError
が送出されます。
他のコンストラクタ、および全てのクラスメソッドを以下に示します:
- classmethod date.today()¶
現在のローカルな日付を返します。
date.fromtimestamp(time.time())
と等価です。
- classmethod date.fromtimestamp(timestamp)¶
time.time()
で返されるような POSIX タイムスタンプに対応するローカルな日付を返します。timestamp がプラットフォームの C 関数
localtime()
がサポートする値の範囲から外れていた場合、OverflowError
を送出するかもしれません。またlocaltime()
呼び出しが失敗した場合にはOSError
を送出するかもしれません。この範囲は通常は 1970 年から 2038 年までに制限されています。タイムスタンプの表記にうるう秒を含める非 POSIX なシステムでは、うるう秒はfromtimestamp()
では無視されます。バージョン 3.3 で変更: timestamp がプラットフォームの C 関数
localtime()
のサポートする値の範囲から外れていた場合、ValueError
ではなくOverflowError
を送出するようになりました。localtime()
の呼び出し失敗でValueError
ではなくOSError
を送出するようになりました。
- classmethod date.fromordinal(ordinal)¶
先発グレゴリオ暦による序数に対応する日付を返します。 1 年 1 月 1 日が序数 1 となります。
1 <= ordinal <= date.max.toordinal()
でない場合、ValueError
が送出されます。 任意の日付 d に対し、date.fromordinal(d.toordinal()) == d
となります。
- classmethod date.fromisoformat(date_string)¶
Return a
date
corresponding to a date_string given in any valid ISO 8601 format, with the following exceptions:Reduced precision dates are not currently supported (
YYYY-MM
,YYYY
).Extended date representations are not currently supported (
±YYYYYY-MM-DD
).Ordinal dates are not currently supported (
YYYY-OOO
).
例:
>>> from datetime import date >>> date.fromisoformat('2019-12-04') datetime.date(2019, 12, 4) >>> date.fromisoformat('20191204') datetime.date(2019, 12, 4) >>> date.fromisoformat('2021-W01-1') datetime.date(2021, 1, 4)
バージョン 3.7 で追加.
バージョン 3.11 で変更: 以前はこのメソッドは
YYYY-MM-DD
フォーマットのみをサポートしていました。
- classmethod date.fromisocalendar(year, week, day)¶
年月日で指定された ISO 暦の日付に対応する
date
を返します。 この関数はdate.isocalendar()
関数の逆関数です。バージョン 3.8 で追加.
以下にクラス属性を示します:
- date.min¶
表現できる最も古い日付で、
date(MINYEAR, 1, 1)
です。
- date.max¶
表現できる最も新しい日付で、
date(MAXYEAR, 12, 31)
です。
- date.resolution¶
等しくない日付オブジェクト間の最小の差で、
timedelta(days=1)
です。
インスタンスの属性 (読み出しのみ):
- date.month¶
両端値を含む 1 から 12 までの値です。
- date.day¶
1 から与えられた月と年における日数までの値です。
サポートされている演算を以下に示します:
演算 |
結果 |
---|---|
|
date2 は date1 の |
|
|
|
(3) |
date1 == date2 date1 != date2 |
Equality comparison. (4) |
date1 < date2 date1 > date2 date1 <= date2 date1 >= date2 |
Order comparison. (5) |
注釈:
date2 は、
timedelta.days > 0
の場合は進む方向に、timedelta.days < 0
の場合は戻る方向に移動します。 演算後はdate2 - date1 == timedelta.days
が成立します。timedelta.seconds
およびtimedelta.microseconds
は無視されます。date2.year
がMINYEAR
になってしまったり、MAXYEAR
より大きくなってしまう場合にはOverflowError
が送出されます。timedelta.seconds
とtimedelta.microseconds
は無視されます。この演算は厳密で、オーバフローしません。timedelta.seconds および timedelta.microseconds は 0 で、演算後には date2 + timedelta == date1 となります。
date
objects are equal if they represent the same date.date1 is considered less than date2 when date1 precedes date2 in time. In other words,
date1 < date2
if and only ifdate1.toordinal() < date2.toordinal()
.
ブール演算コンテキストでは、全ての time
オブジェクトは真とみなされます。
インスタンスメソッド:
- date.replace(year=self.year, month=self.month, day=self.day)¶
キーワード引数で指定されたパラメータが置き換えられることを除き、同じ値を持つ
date
オブジェクトを返します。以下はプログラム例です:
>>> from datetime import date >>> d = date(2002, 12, 31) >>> d.replace(day=26) datetime.date(2002, 12, 26)
- date.timetuple()¶
time.localtime()
が返すようなtime.struct_time
を返します。時分秒が 0 で、 DST フラグが -1 です。
d.timetuple()
は次の式と等価です:time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))
ここで、
yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1
は本年の 1 月 1 日を1
としたときの日付番号です。
- date.toordinal()¶
先発グレゴリオ暦における日付序数を返します。 1 年の 1 月 1 日が序数 1 となります。任意の
date
オブジェクト d について、date.fromordinal(d.toordinal()) == d
となります。
- date.weekday()¶
月曜日を 0、日曜日を 6 として、曜日を整数で返します。例えば、
date(2002, 12, 4).weekday() == 2
であり、水曜日を示します。isoweekday()
も参照してください。
- date.isoweekday()¶
月曜日を 1,日曜日を 7 として、曜日を整数で返します。例えば、
date(2002, 12, 4).isoweekday() == 3
であり、水曜日を示します。weekday()
,isocalendar()
も参照してください。
- date.isocalendar()¶
year
、week
、weekday
の3つで構成された named tuple を返します。ISO 暦はグレゴリオ暦の変種として広く用いられています。 [3]
ISO 年は完全な週が 52 週または 53 週あり、週は月曜から始まって日曜に終わります。ISO 年でのある年における最初の週は、その年の木曜日を含む最初の (グレゴリオ暦での) 週となります。この週は週番号 1 と呼ばれ、この木曜日での ISO 年はグレゴリオ暦における年と等しくなります。
例えば、2004 年は木曜日から始まるため、ISO 年の最初の週は 2003 年 12 月 29 日、月曜日から始まり、2004 年 1 月 4 日、日曜日に終わります
>>> from datetime import date >>> date(2003, 12, 29).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=1) >>> date(2004, 1, 4).isocalendar() datetime.IsoCalendarDate(year=2004, week=1, weekday=7)
バージョン 3.9 で変更: 結果が タプル から named tuple へ変更されました。
- date.isoformat()¶
日付を ISO 8601 書式の
YYYY-MM-DD
で表した文字列を返します:>>> from datetime import date >>> date(2002, 12, 4).isoformat() '2002-12-04'
- date.ctime()¶
日付を表す文字列を返します:
>>> from datetime import date >>> date(2002, 12, 4).ctime() 'Wed Dec 4 00:00:00 2002'
d.ctime()
は次の式と等価です:time.ctime(time.mktime(d.timetuple()))
これが等価になるのは、 (
time.ctime()
に呼び出され、date.ctime()
に呼び出されない) ネイティブの C 関数ctime()
が C 標準に準拠しているプラットフォーム上でです。
- date.strftime(format)¶
明示的な書式文字列で制御された、日付を表現する文字列を返します。 時間、分、秒を表す書式コードは値 0 になります。 strftime() and strptime() Behavior および
date.isoformat()
も参照してください。
- date.__format__(format)¶
date.strftime()
と等価です。 これにより、 フォーマット済み文字列リテラル の中やstr.format()
を使っているときにdate
オブジェクトの書式文字列を指定できます。 strftime() and strptime() Behavior およびdate.isoformat()
も参照してください。
使用例: date
¶
イベントまでの日数を数える例を示します:
>>> import time
>>> from datetime import date
>>> today = date.today()
>>> today
datetime.date(2007, 12, 5)
>>> today == date.fromtimestamp(time.time())
True
>>> my_birthday = date(today.year, 6, 24)
>>> if my_birthday < today:
... my_birthday = my_birthday.replace(year=today.year + 1)
...
>>> my_birthday
datetime.date(2008, 6, 24)
>>> time_to_birthday = abs(my_birthday - today)
>>> time_to_birthday.days
202
さらなる date
を使う例:
>>> from datetime import date
>>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
>>> d
datetime.date(2002, 3, 11)
>>> # Methods related to formatting string output
>>> d.isoformat()
'2002-03-11'
>>> d.strftime("%d/%m/%y")
'11/03/02'
>>> d.strftime("%A %d. %B %Y")
'Monday 11. March 2002'
>>> d.ctime()
'Mon Mar 11 00:00:00 2002'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}.'.format(d, "day", "month")
'The day is 11, the month is March.'
>>> # Methods for to extracting 'components' under different calendars
>>> t = d.timetuple()
>>> for i in t:
... print(i)
2002 # year
3 # month
11 # day
0
0
0
0 # weekday (0 = Monday)
70 # 70th day in the year
-1
>>> ic = d.isocalendar()
>>> for i in ic:
... print(i)
2002 # ISO year
11 # ISO week number
1 # ISO day number ( 1 = Monday )
>>> # A date object is immutable; all operations produce a new object
>>> d.replace(year=2005)
datetime.date(2005, 3, 11)
datetime
オブジェクト¶
datetime
オブジェクトは date
オブジェクトおよび time
オブジェクトの全ての情報が入っている単一のオブジェクトです。
date
オブジェクトと同様に、 datetime
は現在のグレゴリオ暦が両方向に延長されているものと仮定します。また、 time
オブジェクトと同様に、 datetime
は毎日が厳密に 3600*24 秒であると仮定します。
以下にコンストラクタを示します:
- class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶
year, month, day 引数は必須です。 tzinfo は
None
またはtzinfo
サブクラスのインスタンスです。 残りの引数は次の範囲の整数でなければなりません:MINYEAR <= year <= MAXYEAR
,1 <= month <= 12
,1 <= day <= 指定された月と年における日数
,0 <= hour < 24
,0 <= minute < 60
,0 <= second < 60
,0 <= microsecond < 1000000
,fold in [0, 1]
.
範囲を超えた引数を与えた場合、
ValueError
が送出されます。バージョン 3.6 で変更: Added the fold parameter.
他のコンストラクタ、および全てのクラスメソッドを以下に示します:
- classmethod datetime.today()¶
tzinfo
をNone
にして、現在のローカルな日時を返します。次と等価です:
datetime.fromtimestamp(time.time())
now()
,fromtimestamp()
も参照してください。このメソッドの機能は
now()
と等価ですが、tz
引数はありません。
- classmethod datetime.now(tz=None)¶
現在のローカルな日時を返します。
オプションの引数 tz が
None
であるか指定されていない場合、このメソッドはtoday()
と同様ですが、可能ならばtime.time()
タイムスタンプを通じて得ることができる、より高い精度で時刻を提供します (例えば、プラットフォームが C 関数gettimeofday()
をサポートする場合には可能なことがあります)。tz が
None
でない場合、 tz はtzinfo
のサブクラスのインスタンスでなければならず、現在の日付および時刻は tz のタイムゾーンに変換されます。
- classmethod datetime.utcnow()¶
tzinfo
がNone
である現在の UTC の日付および時刻を返します。このメソッドは
now()
と似ていますが、 naive なdatetime
オブジェクトとして現在の UTC 日付および時刻を返します。 aware な現在の UTC datetime はdatetime.now(timezone.utc)
を呼び出すことで取得できます。now()
も参照してください。警告
naive な
datetime
オブジェクトは多くのdatetime
メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。 そのため、 UTC での現在の時刻を表すオブジェクトの作成ではdatetime.now(timezone.utc)
を呼び出す方法が推奨されます。バージョン 3.12 で非推奨: 代わりに
UTC
でdatetime.now()
を使用してください。
- classmethod datetime.fromtimestamp(timestamp, tz=None)¶
time.time()
が返すような、 POSIX タイムスタンプに対応するローカルな日付と時刻を返します。オプションの引数 tz がNone
であるか、指定されていない場合、タイムスタンプはプラットフォームのローカルな日付および時刻に変換され、返されるdatetime
オブジェクトは naive なものになります。tz が
None
でない場合、 tz はtzinfo
のサブクラスのインスタンスでなければならず、タイムスタンプは tz のタイムゾーンに変換されます。タイムスタンプがプラットフォームの C 関数
localtime()
やgmtime()
でサポートされている範囲を超えた場合、fromtimestamp()
はOverflowError
を送出することがあります。この範囲はよく 1970 年から 2038 年に制限されています。 またlocaltime()
やgmtime()
が失敗した際はOSError
を送出します。 うるう秒がタイムスタンプの概念に含まれている非 POSIX システムでは、fromtimestamp()
はうるう秒を無視します。 このため、秒の異なる二つのタイムスタンプが同一のdatetime
オブジェクトとなることが起こり得ます。utcfromtimestamp()
よりも、このメソッドの方が好ましいです。バージョン 3.3 で変更: timestamp がプラットフォームの C 関数
localtime()
もしくはgmtime()
のサポートする値の範囲から外れていた場合、ValueError
ではなくOverflowError
を送出するようになりました。localtime()
もしくはgmtime()
の呼び出し失敗でValueError
ではなくOSError
を送出するようになりました。バージョン 3.6 で変更:
fromtimestamp()
はfold
を1にしてインスタンスを返します。
- classmethod datetime.utcfromtimestamp(timestamp)¶
POSIX タイムスタンプに対応する、
tzinfo
がNone
の UTC でのdatetime
を返します。(返されるオブジェクトは naive です。)タイムスタンプがプラットフォームにおける C 関数
localtime()
でサポートされている範囲を超えている場合にはOverflowError
を、gmtime()
が失敗した場合にはOSError
を送出します。 これはたいてい 1970 年から 2038 年に制限されています。aware な
datetime
オブジェクトを得るにはfromtimestamp()
を呼んでください:datetime.fromtimestamp(timestamp, timezone.utc)
POSIX 互換プラットフォームでは、これは以下の表現と等価です:
datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)
後者を除き、式は常に年の全範囲 (
MINYEAR
からMAXYEAR
を含みます) をサポートします。警告
naive な
datetime
オブジェクトは多くのdatetime
メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。 そのため、 UTC でのある特定のタイムスタンプを表すオブジェクトの作成ではdatetime.fromtimestamp(timestamp, tz=timezone.utc)
を呼び出す方法が推奨されます。バージョン 3.3 で変更: timestamp がプラットフォームの C 関数
gmtime()
のサポートする値の範囲から外れていた場合、ValueError
ではなくOverflowError
を送出するようになりました。gmtime()
の呼び出し失敗でValueError
ではなくOSError
を送出するようになりました。バージョン 3.12 で非推奨: 代わりに
UTC
でdatetime.fromtimestamp()
を使用してください。
- classmethod datetime.fromordinal(ordinal)¶
1 年 1 月 1 日を序数 1 とする早期グレゴリオ暦序数に対応する
datetime
オブジェクトを返します。1 <= ordinal <= datetime.max.toordinal()
でなければValueError
が送出されます。 返されるオブジェクトの時間、分、秒、およびマイクロ秒はすべて 0 で、tzinfo
はNone
となっています。
- classmethod datetime.combine(date, time, tzinfo=time.tzinfo)¶
Return a new
datetime
object whose date components are equal to the givendate
object's, and whose time components are equal to the giventime
object's. If the tzinfo argument is provided, its value is used to set thetzinfo
attribute of the result, otherwise thetzinfo
attribute of the time argument is used. If the date argument is adatetime
object, its time components andtzinfo
attributes are ignored.For any
datetime
object d,d == datetime.combine(d.date(), d.time(), d.tzinfo)
.バージョン 3.6 で変更: tzinfo 引数が追加されました。
- classmethod datetime.fromisoformat(date_string)¶
以下の例外を除く、有効な ISO 8601 フォーマットで与えられた date_string に対応する
date
を返します :小数の秒があるタイムゾーンオフセット。
T
セパレーターを他の1文字のユニコードに置き換えたもの。少数の時と分はサポートされていません。
Reduced precision dates are not currently supported (
YYYY-MM
,YYYY
).Extended date representations are not currently supported (
±YYYYYY-MM-DD
).Ordinal dates are not currently supported (
YYYY-OOO
).
例:
>>> from datetime import datetime >>> datetime.fromisoformat('2011-11-04') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('20111104') datetime.datetime(2011, 11, 4, 0, 0) >>> datetime.fromisoformat('2011-11-04T00:05:23') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-11-04T00:05:23Z') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('20111104T000523') datetime.datetime(2011, 11, 4, 0, 5, 23) >>> datetime.fromisoformat('2011-W01-2T00:05:23.283') datetime.datetime(2011, 1, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000) >>> datetime.fromisoformat('2011-11-04 00:05:23.283+00:00') datetime.datetime(2011, 11, 4, 0, 5, 23, 283000, tzinfo=datetime.timezone.utc) >>> datetime.fromisoformat('2011-11-04T00:05:23+04:00') datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400)))
バージョン 3.7 で追加.
バージョン 3.11 で変更: 以前は、このメソッドは
date.isoformat()
またはdatetime.isoformat()
から出力されるフォーマットのみをサポートしていました。
- classmethod datetime.fromisocalendar(year, week, day)¶
年月日で指定された ISO 暦の日付に対応する
datetime
を返します。 datetime の日付でない部分は、標準のデフォルト値で埋められます。 この関数はdatetime.isocalendar()
の逆関数です。バージョン 3.8 で追加.
- classmethod datetime.strptime(date_string, format)¶
date_string に対応した
datetime
を返します。 format にしたがって構文解析されます。format がマイクロ秒やタイムゾーン情報を含まない場合は、以下と等価です:
datetime(*(time.strptime(date_string, format)[0:6]))
date_string と format が
time.strptime()
で構文解析できない場合や、この関数が時刻タプルを返してこない場合にはValueError
を送出します。strftime() and strptime() Behavior およびdatetime.fromisoformat()
も参照してください。
以下にクラス属性を示します:
インスタンスの属性 (読み出しのみ):
- datetime.month¶
両端値を含む 1 から 12 までの値です。
- datetime.day¶
1 から与えられた月と年における日数までの値です。
- datetime.hour¶
in
range(24)
を満たします。
- datetime.minute¶
in
range(60)
を満たします。
- datetime.second¶
in
range(60)
を満たします。
- datetime.microsecond¶
in
range(1000000)
を満たします。
- datetime.fold¶
[0, 1]
のどちらかです。 繰り返し期間中の実時間の曖昧さ除去に使われます。 (繰り返し期間は、夏時間の終わりに時計が巻き戻るときや、現在のゾーンの UTC オフセットが政治的な理由で減少するときに発生します。) 0 (1) という値は、同じ実時間で表現される 2 つの時刻のうちの早い方 (遅い方) を表します。バージョン 3.6 で追加.
サポートされている演算を以下に示します:
演算 |
結果 |
---|---|
|
(1) |
|
(2) |
|
(3) |
datetime1 == datetime2 datetime1 != datetime2 |
Equality comparison. (4) |
datetime1 < datetime2 datetime1 > datetime2 datetime1 <= datetime2 datetime1 >= datetime2 |
Order comparison. (5) |
datetime2 は datetime1 から時間 timedelta 移動したもので、
timedelta.days
> 0 の場合未来へ、timedelta.days
< 0 の場合過去へ移動します。 結果は入力の datetime と同じtzinfo
属性を持ち、演算後には datetime2 - datetime1 == timedelta となります。 datetime2.year がMINYEAR
よりも小さいか、MAXYEAR
より大きい場合にはOverflowError
が送出されます。 入力が aware なオブジェクトの場合でもタイムゾーン修正は全く行われません。datetime2 + timedelta == datetime1 となるような datetime2 を計算します。 ちなみに、結果は入力の datetime と同じ
tzinfo
属性を持ち、入力が aware だとしてもタイムゾーン修正は全く行われません。 この操作は date1 + (-timedelta) と等価ではありません。 なぜならば、 date1 - timedelta がオーバフローしない場合でも、-timedelta 単体がオーバフローする可能性があるからです。datetime
からdatetime
の減算は両方の被演算子が naive であるか、両方とも aware である場合にのみ定義されています。片方が aware でもう一方が naive の場合、TypeError
が送出されます。両方とも naive か、両方とも aware で同じ
tzinfo
属性を持つ場合、tzinfo
属性は無視され、結果はdatetime2 + t == datetime1
であるようなtimedelta
オブジェクト t となります。 この場合タイムゾーン修正は全く行われません。If both are aware and have different
tzinfo
attributes,a-b
acts as if a and b were first converted to naive UTC datetimes. The result is(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())
except that the implementation never overflows.datetime
objects are equal if they represent the same date and time, taking into account the time zone.Naive and aware
datetime
objects are never equal.datetime
objects are never equal todate
objects that are not alsodatetime
instances, even if they represent the same date.If both comparands are aware, and have the same
tzinfo
attribute, thetzinfo
andfold
attributes are ignored and the base datetimes are compared. If both comparands are aware and have differenttzinfo
attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows.datetime
instances in a repeated interval are never equal todatetime
instances in other time zone.datetime1 is considered less than datetime2 when datetime1 precedes datetime2 in time, taking into account the time zone.
Order comparison between naive and aware
datetime
objects, as well as adatetime
object and adate
object that is not also adatetime
instance, raisesTypeError
.If both comparands are aware, and have the same
tzinfo
attribute, thetzinfo
andfold
attributes are ignored and the base datetimes are compared. If both comparands are aware and have differenttzinfo
attributes, the comparison acts as comparands were first converted to UTC datetimes except that the implementation never overflows.
インスタンスメソッド:
- datetime.time()¶
同じhour、minute、second、microsecond 及び foldを持つ
time
オブジェクトを返します。tzinfo
はNone
です。timetz()
も参照してください。バージョン 3.6 で変更: 値 foldは返される
time
オブジェクトにコピーされます。
- datetime.timetz()¶
同じhour、minute、second、microsecond、fold および tzinfo 属性を持つ
time
オブジェクトを返します。time()
メソッドも参照してください。バージョン 3.6 で変更: 値 foldは返される
time
オブジェクトにコピーされます。
- datetime.replace(year=self.year, month=self.month, day=self.day, hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶
キーワード引数で指定した属性の値を除き、同じ属性をもつ datetime オブジェクトを返します。メンバに対する変換を行わずに aware な datetime オブジェクトから naive な datetime オブジェクトを生成するために、
tzinfo=None
を指定することもできます。バージョン 3.6 で変更: Added the fold parameter.
- datetime.astimezone(tz=None)¶
tz を新たに
tzinfo
属性 として持つdatetime
オブジェクトを返します。 日付および時刻データを調整して、返り値が self と同じ UTC 時刻を持ち、 tz におけるローカルな時刻を表すようにします。もし与えられた場合、 tz は
tzinfo
のサブクラスのインスタンスでなければならず、 インスタンスのutcoffset()
およびdst()
メソッドはNone
を返してはなりません。もし self が naive ならば、おそらくシステムのタイムゾーンで時間を表現します。引数無し (もしくは
tz=None
の形 ) で呼び出された場合、システムのローカルなタイムゾーンが変更先のタイムゾーンだと仮定されます。 変換後の datetime インスタンスの.tzinfo
属性には、 OS から取得したゾーン名とオフセットを持つtimezone
インスタンスが設定されます。self.tzinfo
が tz の場合、self.astimezone(tz)
は self に等しくなります。つまり、date および time に対する調整は行われません。そうでない場合、結果はタイムゾーン tz におけるローカル時刻で、 self と同じ UTC 時刻を表すようになります。これは、astz = dt.astimezone(tz)
とした後、astz - astz.utcoffset()
は通常dt - dt.utcoffset()
と同じ date および time を持つことを示します。単にタイムゾーンオブジェクト tz を
datetime
オブジェクト dt に追加したいだけで、日付や時刻データへの調整を行わないのなら、dt.replace(tzinfo=tz)
を使ってください。単に aware なdatetime
オブジェクト dt からタイムゾーンオブジェクトを除去したいだけで、日付や時刻データの変換を行わないのなら、dt.replace(tzinfo=None)
を使ってください。デフォルトの
tzinfo.fromutc()
メソッドをtzinfo
のサブクラスで上書きして,astimezone()
が返す結果に影響を及ぼすことができます。エラーの場合を無視すると、astimezone()
は以下のように動作します:def astimezone(self, tz): if self.tzinfo is tz: return self # Convert self to UTC, and attach the new time zone object. utc = (self - self.utcoffset()).replace(tzinfo=tz) # Convert from UTC to tz's local time. return tz.fromutc(utc)
バージョン 3.3 で変更: tz が省略可能になりました。
バージョン 3.6 で変更:
datetime.datetime.astimezone()
メソッドを naive なインスタンスに対して呼び出せるようになりました。これは、システムのローカルな時間を表現していると想定されます。
- datetime.utcoffset()¶
tzinfo
がNone
の場合、None
を返し、そうでない場合にはself.tzinfo.utcoffset(self)
を返します。 後者の式がNone
あるいは 1 日以下の大きさを持つtimedelta
オブジェクトのいずれかを返さない場合には例外を送出します。バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
- datetime.dst()¶
tzinfo
がNone
の場合None
を返し、そうでない場合にはself.tzinfo.dst(self)
を返します。 後者の式がNone
もしくは、1 日未満の大きさを持つtimedelta
オブジェクトのいずれかを返さない場合には例外を送出します。バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。
- datetime.tzname()¶
tzinfo
がNone
の場合None
を返し、そうでない場合にはself.tzinfo.tzname(self)
を返します。 後者の式がNone
か文字列オブジェクトのいずれかを返さない場合には例外を送出します。
- datetime.timetuple()¶
time.localtime()
が返すようなtime.struct_time
を返します。d.timetuple()
は次の式と等価です:time.struct_time((d.year, d.month, d.day, d.hour, d.minute, d.second, d.weekday(), yday, dst))
where
yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1
is the day number within the current year starting with1
for January 1st. Thetm_isdst
flag of the result is set according to thedst()
method:tzinfo
isNone
ordst()
returnsNone
,tm_isdst
is set to-1
; else ifdst()
returns a non-zero value,tm_isdst
is set to1
; elsetm_isdst
is set to0
.
- datetime.utctimetuple()¶
If
datetime
instance d is naive, this is the same asd.timetuple()
except thattm_isdst
is forced to 0 regardless of whatd.dst()
returns. DST is never in effect for a UTC time.If d is aware, d is normalized to UTC time, by subtracting
d.utcoffset()
, and atime.struct_time
for the normalized time is returned.tm_isdst
is forced to 0. Note that anOverflowError
may be raised if d.year wasMINYEAR
orMAXYEAR
and UTC adjustment spills over a year boundary.警告
naive な
datetime
オブジェクトは多くのdatetime
メソッドでローカルな時間として扱われるため、 aware な datetime を使って UTC の時刻を表すのが好ましいです。結果として、datetime.utctimetuple()
は誤解を招きやすい返り値を返すかもしれません。 UTC を表す naive なdatetime
があった場合、datetime.timetuple()
が使えるところではdatetime.replace(tzinfo=timezone.utc)
で aware にします。
- datetime.toordinal()¶
先発グレゴリオ暦における日付序数を返します。
self.date().toordinal()
と同じです。
- datetime.timestamp()¶
datetime
インスタンスに対応する POSIX タイムスタンプを返します。 返り値はtime.time()
で返される値に近いfloat
です。このメソッドでは naive な
datetime
インスタンスはローカル時刻とし、プラットフォームの C 関数mktime()
に頼って変換を行います。datetime
は多くのプラットフォームのmktime()
より広い範囲の値をサポートしているので、遥か過去の時刻や遥か未来の時刻に対し、このメソッドはOverflowError
またはOSError
を送出するかもしれません。aware な
datetime
インスタンスに対しては以下のように返り値が計算されます:(dt - datetime(1970, 1, 1, tzinfo=timezone.utc)).total_seconds()
バージョン 3.3 で追加.
バージョン 3.6 で変更: The
timestamp()
method uses thefold
attribute to disambiguate the times during a repeated interval.注釈
UTC 時刻を表す naive な
datetime
インスタンスから直接 POSIX タイムスタンプを取得するメソッドはありません。 アプリケーションがその変換を使っており、システムのタイムゾーンが UTC に設定されていなかった場合、tzinfo=timezone.utc
を引数に与えることで POSIX タイムスタンプを取得できます:timestamp = dt.replace(tzinfo=timezone.utc).timestamp()
もしくは直接タイムスタンプを計算することもできます:
timestamp = (dt - datetime(1970, 1, 1)) / timedelta(seconds=1)
- datetime.weekday()¶
月曜日を 0、日曜日を 6 として、曜日を整数で返します。
self.date().weekday()
と同じです。isoweekday()
も参照してください。
- datetime.isoweekday()¶
月曜日を 1、日曜日を 7 として、曜日を整数で返します。
self.date().isoweekday()
と等価です。weekday()
、isocalendar()
も参照してください。
- datetime.isocalendar()¶
year
、week
、weekday
の3つで構成された named tuple を返します。self.date().isocalendar()
と等価です。
- datetime.isoformat(sep='T', timespec='auto')¶
日時を ISO 8601 書式で表した文字列で返します:
microsecond
が 0 でない場合はYYYY-MM-DDTHH:MM:SS.ffffff
microsecond
が 0 の場合はYYYY-MM-DDTHH:MM:SS
utcoffset()
がNone
を返さない場合は、文字列の後ろに UTC オフセットが追記されます:microsecond
が 0 でない場合はYYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
microsecond
が 0 の場合はYYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]
例:
>>> from datetime import datetime, timezone >>> datetime(2019, 5, 18, 15, 17, 8, 132263).isoformat() '2019-05-18T15:17:08.132263' >>> datetime(2019, 5, 18, 15, 17, tzinfo=timezone.utc).isoformat() '2019-05-18T15:17:00+00:00'
オプションの引数 sep (デフォルトでは
'T'
です) は 1 文字のセパレータで、結果の文字列の日付と時刻の間に置かれます。例えば:>>> from datetime import tzinfo, timedelta, datetime >>> class TZ(tzinfo): ... """A time zone with an arbitrary, constant -06:39 offset.""" ... def utcoffset(self, dt): ... return timedelta(hours=-6, minutes=-39) ... >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ') '2002-12-25 00:00:00-06:39' >>> datetime(2009, 11, 27, microsecond=100, tzinfo=TZ()).isoformat() '2009-11-27T00:00:00.000100-06:39'
オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは
'auto'
です)。以下の内一つを指定してください。'auto'
:microsecond
が0である場合'seconds'
と等しく、そうでない場合は'microseconds'
と等しくなります。'hours'
:hour
を2桁のHH
書式で含めます。'milliseconds'
: 全ての時刻を含みますが、小数第二位をミリ秒に切り捨てます。HH:MM:SS.sss
の書式で表現します。'microseconds'
: 全ての時刻をHH:MM:SS.mmmmmm
の書式で含めます。
注釈
除外された要素は丸め込みではなく、切り捨てされます。
不正な timespec 引数には
ValueError
があげられます:>>> from datetime import datetime >>> datetime.now().isoformat(timespec='minutes') '2002-12-25T00:00' >>> dt = datetime(2015, 1, 1, 12, 30, 59, 0) >>> dt.isoformat(timespec='microseconds') '2015-01-01T12:30:59.000000'
バージョン 3.6 で変更: Added the timespec parameter.
- datetime.ctime()¶
日付および時刻を表す文字列を返します:
>>> from datetime import datetime >>> datetime(2002, 12, 4, 20, 30, 40).ctime() 'Wed Dec 4 20:30:40 2002'
出力文字列は入力が aware であれ naive であれ、タイムゾーン情報を含み ません。
d.ctime()
は次の式と等価です:time.ctime(time.mktime(d.timetuple()))
これが等価になるのは、 (
time.ctime()
に呼び出され、datetime.ctime()
に呼び出されない) ネイティブの C 関数ctime()
が C 標準に準拠しているプラットフォーム上でです。
- datetime.strftime(format)¶
明示的な書式文字列で制御された、日付および時刻を表現する文字列を返します。strftime() and strptime() Behavior および
datetime.isoformat()
も参照してください。
- datetime.__format__(format)¶
datetime.strftime()
と等価です。 これにより、 フォーマット済み文字列リテラル の中やstr.format()
を使っているときにdatetime
オブジェクトの書式文字列を指定できます。 strftime() and strptime() Behavior およびdatetime.isoformat()
も参照してください。
使用例: datetime
¶
Examples of working with datetime
objects:
>>> from datetime import datetime, date, time, timezone
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
>>> t = time(12, 30)
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
>>> # Using datetime.now()
>>> datetime.now()
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
>>> datetime.now(timezone.utc)
datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
>>> dt
datetime.datetime(2006, 11, 21, 16, 30)
>>> # Using datetime.timetuple() to get tuple of all attributes
>>> tt = dt.timetuple()
>>> for it in tt:
... print(it)
...
2006 # year
11 # month
21 # day
16 # hour
30 # minute
0 # second
1 # weekday (0 = Monday)
325 # number of days since 1st January
-1 # dst - method tzinfo.dst() returned None
>>> # Date in ISO format
>>> ic = dt.isocalendar()
>>> for it in ic:
... print(it)
...
2006 # ISO year
47 # ISO week
2 # ISO weekday
>>> # Formatting a datetime
>>> dt.strftime("%A, %d. %B %Y %I:%M%p")
'Tuesday, 21. November 2006 04:30PM'
>>> 'The {1} is {0:%d}, the {2} is {0:%B}, the {3} is {0:%I:%M%p}.'.format(dt, "day", "month", "time")
'The day is 21, the month is November, the time is 04:30PM.'
下にある例では、1945年までは +4 UTC 、それ以降は +4:30 UTC を使用しているアフガニスタンのカブールのタイムゾーン情報を表現する tzinfo
のサブクラスを定義しています:
from datetime import timedelta, datetime, tzinfo, timezone
class KabulTz(tzinfo):
# Kabul used +4 until 1945, when they moved to +4:30
UTC_MOVE_DATE = datetime(1944, 12, 31, 20, tzinfo=timezone.utc)
def utcoffset(self, dt):
if dt.year < 1945:
return timedelta(hours=4)
elif (1945, 1, 1, 0, 0) <= dt.timetuple()[:5] < (1945, 1, 1, 0, 30):
# An ambiguous ("imaginary") half-hour range representing
# a 'fold' in time due to the shift from +4 to +4:30.
# If dt falls in the imaginary range, use fold to decide how
# to resolve. See PEP495.
return timedelta(hours=4, minutes=(30 if dt.fold else 0))
else:
return timedelta(hours=4, minutes=30)
def fromutc(self, dt):
# Follow same validations as in datetime.tzinfo
if not isinstance(dt, datetime):
raise TypeError("fromutc() requires a datetime argument")
if dt.tzinfo is not self:
raise ValueError("dt.tzinfo is not self")
# A custom implementation is required for fromutc as
# the input to this function is a datetime with utc values
# but with a tzinfo set to self.
# See datetime.astimezone or fromtimestamp.
if dt.replace(tzinfo=timezone.utc) >= self.UTC_MOVE_DATE:
return dt + timedelta(hours=4, minutes=30)
else:
return dt + timedelta(hours=4)
def dst(self, dt):
# Kabul does not observe daylight saving time.
return timedelta(0)
def tzname(self, dt):
if dt >= self.UTC_MOVE_DATE:
return "+04:30"
return "+04"
上に出てきた KabulTz
の使い方:
>>> tz1 = KabulTz()
>>> # Datetime before the change
>>> dt1 = datetime(1900, 11, 21, 16, 30, tzinfo=tz1)
>>> print(dt1.utcoffset())
4:00:00
>>> # Datetime after the change
>>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=tz1)
>>> print(dt2.utcoffset())
4:30:00
>>> # Convert datetime to another time zone
>>> dt3 = dt2.astimezone(timezone.utc)
>>> dt3
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
>>> dt2 == dt3
True
time
オブジェクト¶
A time
object represents a (local) time of day, independent of any particular
day, and subject to adjustment via a tzinfo
object.
- class datetime.time(hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)¶
全ての引数はオプションです。 tzinfo は
None
またはtzinfo
クラスのサブクラスのインスタンスにすることができます。残りの引数は整数で、以下のような範囲に入らなければなりません:0 <= hour < 24
,0 <= minute < 60
,0 <= second < 60
,0 <= microsecond < 1000000
,fold in [0, 1]
.
引数がこれらの範囲外にある場合、
ValueError
が送出されます。 tzinfo のデフォルト値がNone
である以外のデフォルト値は0
です。
以下にクラス属性を示します:
- time.resolution¶
等しくない
time
オブジェクト間の最小の差で、timedelta(microseconds=1)
ですが,time
オブジェクト間の四則演算はサポートされていないので注意してください。
インスタンスの属性 (読み出しのみ):
- time.hour¶
in
range(24)
を満たします。
- time.minute¶
in
range(60)
を満たします。
- time.second¶
in
range(60)
を満たします。
- time.microsecond¶
in
range(1000000)
を満たします。
- time.fold¶
[0, 1]
のどちらかです。 繰り返し期間中の実時間の曖昧さ除去に使われます。 (繰り返し期間は、夏時間の終わりに時計が巻き戻るときや、現在のゾーンの UTC オフセットが政治的な理由で減少するときに発生します。) 0 (1) という値は、同じ実時間で表現される 2 つの時刻のうちの早い方 (遅い方) を表します。バージョン 3.6 で追加.
time
objects support equality and order comparisons,
where a is considered less than b when a precedes b in time.
Naive and aware time
objects are never equal.
Order comparison between naive and aware time
objects raises
TypeError
.
If both comparands are aware, and have the same tzinfo
attribute, the tzinfo
and fold
attributes are
ignored and the base times are compared. If both comparands are aware and
have different tzinfo
attributes, the comparands are first adjusted by
subtracting their UTC offsets (obtained from self.utcoffset()
).
ブール値の文脈では、 time
オブジェクトは常に真とみなされます。
バージョン 3.5 で変更: Python 3.5 以前は、 time
オブジェクトは UTC で深夜を表すときに偽とみなされていました。
この挙動は分かりにくく、エラーの元となると考えられ、Python 3.5 で削除されました。
全詳細については bpo-13936 を参照してください。
その他のコンストラクタ:
- classmethod time.fromisoformat(time_string)¶
以下の例外を除く、有効な ISO 8601 フォーマットで与えられた time_string に対応する
time
を返します :小数の秒があるタイムゾーンオフセット。
The leading
T
, normally required in cases where there may be ambiguity between a date and a time, is not required.Fractional seconds may have any number of digits (anything beyond 6 will be truncated).
少数の時と分はサポートされていません。
例:
>>> from datetime import time >>> time.fromisoformat('04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T04:23:01') datetime.time(4, 23, 1) >>> time.fromisoformat('T042301') datetime.time(4, 23, 1) >>> time.fromisoformat('04:23:01.000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01,000384') datetime.time(4, 23, 1, 384) >>> time.fromisoformat('04:23:01+04:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone(datetime.timedelta(seconds=14400))) >>> time.fromisoformat('04:23:01Z') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc) >>> time.fromisoformat('04:23:01+00:00') datetime.time(4, 23, 1, tzinfo=datetime.timezone.utc)
バージョン 3.7 で追加.
バージョン 3.11 で変更: 以前は、このメソっどは
time.isoformat()
から出力されるフォーマットのみをサポートしていました。
インスタンスメソッド:
- time.replace(hour=self.hour, minute=self.minute, second=self.second, microsecond=self.microsecond, tzinfo=self.tzinfo, *, fold=0)¶
キーワード引数で指定したメンバの値を除き、同じ値をもつ
time
オブジェクトを返します。データに対する変換を行わずに aware なtime
オブジェクトから naive なtime
オブジェクトを生成するために、tzinfo=None
を指定することもできます。バージョン 3.6 で変更: Added the fold parameter.
- time.isoformat(timespec='auto')¶
時刻を ISO 8601 書式で表した次の文字列のうち1つを返します:
microsecond
が 0 でない場合はHH:MM:SS.ffffff
microsecond
が 0 の場合はHH:MM:SS
utcoffset()
がNone
を返さない場合、HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]
microsecond
が 0 でutcoffset()
がNone
を返さない場合、HH:MM:SS+HH:MM[:SS[.ffffff]]
オプション引数 timespec は、含める追加の時間の要素の数を指定します(デフォルトでは
'auto'
です)。以下の内一つを指定してください。'auto'
:microsecond
が0である場合'seconds'
と等しく、そうでない場合は'microseconds'
と等しくなります。'hours'
:hour
を2桁のHH
書式で含めます。'milliseconds'
: 全ての時刻を含みますが、小数第二位をミリ秒に切り捨てます。HH:MM:SS.sss
の書式で表現します。'microseconds'
: 全ての時刻をHH:MM:SS.mmmmmm
の書式で含めます。
注釈
除外された要素は丸め込みではなく、切り捨てされます。
不正な timespec 引数には
ValueError
があげられます。以下はプログラム例です:
>>> from datetime import time >>> time(hour=12, minute=34, second=56, microsecond=123456).isoformat(timespec='minutes') '12:34' >>> dt = time(hour=12, minute=34, second=56, microsecond=0) >>> dt.isoformat(timespec='microseconds') '12:34:56.000000' >>> dt.isoformat(timespec='auto') '12:34:56'
バージョン 3.6 で変更: Added the timespec parameter.
- time.strftime(format)¶
明示的な書式文字列で制御された、時刻を表現する文字列を返します。strftime() and strptime() Behavior および
time.isoformat()
も参照してください。
- time.__format__(format)¶
time.strftime()
と等価です。 これにより、 フォーマット済み文字列リテラル の中やstr.format()
を使っているときにtime
オブジェクトの書式文字列を指定できます。 strftime() and strptime() Behavior およびtime.isoformat()
も参照してください。
- time.utcoffset()¶
tzinfo
がNone
の場合、None
を返し、そうでない場合にはself.tzinfo.utcoffset(None)
を返します。 後者の式がNone
あるいは 1 日以下の大きさを持つtimedelta
オブジェクトのいずれかを返さない場合には例外を送出します。バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
- time.dst()¶
tzinfo
がNone
の場合None
を返し、そうでない場合にはself.tzinfo.dst(None)
を返します。 後者の式がNone
もしくは、1 日未満の大きさを持つtimedelta
オブジェクトのいずれかを返さない場合には例外を送出します。バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。
- time.tzname()¶
tzinfo
がNone
の場合None
を返し、そうでない場合にはself.tzinfo.tzname(None)
を返します。 後者の式がNone
か文字列オブジェクトのいずれかを返さない場合には例外を送出します。
使用例: time
¶
time
オブジェクトを使う例:
>>> from datetime import time, tzinfo, timedelta
>>> class TZ1(tzinfo):
... def utcoffset(self, dt):
... return timedelta(hours=1)
... def dst(self, dt):
... return timedelta(0)
... def tzname(self,dt):
... return "+01:00"
... def __repr__(self):
... return f"{self.__class__.__name__}()"
...
>>> t = time(12, 10, 30, tzinfo=TZ1())
>>> t
datetime.time(12, 10, 30, tzinfo=TZ1())
>>> t.isoformat()
'12:10:30+01:00'
>>> t.dst()
datetime.timedelta(0)
>>> t.tzname()
'+01:00'
>>> t.strftime("%H:%M:%S %Z")
'12:10:30 +01:00'
>>> 'The {} is {:%H:%M}.'.format("time", t)
'The time is 12:10.'
tzinfo
オブジェクト¶
- class datetime.tzinfo¶
このクラスは抽象基底クラスで、直接インスタンス化すべきでないことを意味します。
tzinfo
のサブクラスを定義し、ある特定のタイムゾーンに関する情報を保持するようにしてください。tzinfo
(の具体的なサブクラス) のインスタンスはdatetime
およびtime
オブジェクトのコンストラクタに渡すことができます。後者のオブジェクトでは、データ属性をローカル時刻におけるものとして見ており、tzinfo
オブジェクトはローカル時刻の UTC からのオフセット、タイムゾーンの名前、 DST オフセットを、渡された日付および時刻オブジェクトからの相対で示すためのメソッドを提供します。You need to derive a concrete subclass, and (at least) supply implementations of the standard
tzinfo
methods needed by thedatetime
methods you use. Thedatetime
module providestimezone
, a simple concrete subclass oftzinfo
which can represent timezones with fixed offset from UTC such as UTC itself or North American EST and EDT.pickle 化についての特殊な要求事項:
tzinfo
のサブクラスは引数なしで呼び出すことのできる__init__()
メソッドを持たなければなりません。そうでなければ、 pickle 化することはできますがおそらく unpickle 化することはできないでしょう。これは技術的な側面からの要求であり、将来緩和されるかもしれません。A concrete subclass of
tzinfo
may need to implement the following methods. Exactly which methods are needed depends on the uses made of awaredatetime
objects. If in doubt, simply implement all of them.
- tzinfo.utcoffset(dt)¶
ローカル時間の UTC からのオフセットを、 UTC から東向きを正とした
timedelta
オブジェクトで返します。ローカル時間が UTC の西側にある場合、この値は負になります。このメソッドは UTC からのオフセットの 総計 を表しています。例えば、
tzinfo
オブジェクトがタイムゾーンと DST 修正の両方を表現する場合、utcoffset()
はそれらの合計を返さなければなりません。 UTC オフセットが未知である場合、None
を返します。 そうでない場合には、返される値は-timedelta(hours=24)
からtimedelta(hours=24)
までのtimedelta
境界を含まないオブジェクトでなければなりません (オフセットの大きさは 1 日より短くなければなりません)。 ほとんどのutcoffset()
実装は、おそらく以下の二つのうちの一つに似たものになるでしょう:return CONSTANT # fixed-offset class return CONSTANT + self.dst(dt) # daylight-aware class
utcoffset()
がNone
を返さない場合、dst()
もNone
を返してはなりません。utcoffset()
のデフォルトの実装はNotImplementedError
を送出します。バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
- tzinfo.dst(dt)¶
夏時間 (DST) 修正を、 class:timedelta オブジェクトで返します。 DST 情報が未知の場合、
None
が返されます。Return
timedelta(0)
if DST is not in effect. If DST is in effect, return the offset as atimedelta
object (seeutcoffset()
for details). Note that DST offset, if applicable, has already been added to the UTC offset returned byutcoffset()
, so there's no need to consultdst()
unless you're interested in obtaining DST info separately. For example,datetime.timetuple()
calls itstzinfo
attribute'sdst()
method to determine how thetm_isdst
flag should be set, andtzinfo.fromutc()
callsdst()
to account for DST changes when crossing time zones.標準および夏時間の両方をモデル化している
tzinfo
サブクラスのインスタンス tz は以下の式:tz.utcoffset(dt) - tz.dst(dt)
must return the same result for every
datetime
dt withdt.tzinfo == tz
For sanetzinfo
subclasses, this expression yields the time zone's "standard offset", which should not depend on the date or the time, but only on geographic location. The implementation ofdatetime.astimezone()
relies on this, but cannot detect violations; it's the programmer's responsibility to ensure it. If atzinfo
subclass cannot guarantee this, it may be able to override the default implementation oftzinfo.fromutc()
to work correctly withastimezone()
regardless.ほとんどの
dst()
実装は、おそらく以下の二つのうちの一つに似たものになるでしょう:def dst(self, dt): # a fixed-offset class: doesn't account for DST return timedelta(0)
もしくは:
def dst(self, dt): # Code to set dston and dstoff to the time zone's DST # transition times based on the input dt.year, and expressed # in standard local time. if dston <= dt.replace(tzinfo=None) < dstoff: return timedelta(hours=1) else: return timedelta(0)
デフォルトの
dst()
実装はNotImplementedError
を送出します。バージョン 3.7 で変更: DST オフセットが分単位でなければならない制限が無くなりました。
- tzinfo.tzname(dt)¶
Return the time zone name corresponding to the
datetime
object dt, as a string. Nothing about string names is defined by thedatetime
module, and there's no requirement that it mean anything in particular. For example, "GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all valid replies. ReturnNone
if a string name isn't known. Note that this is a method rather than a fixed string primarily because sometzinfo
subclasses will wish to return different names depending on the specific value of dt passed, especially if thetzinfo
class is accounting for daylight time.デフォルトの
tzname()
実装はNotImplementedError
を送出します。
以下のメソッドは datetime
や time
オブジェクトにおいて、同名のメソッドが呼び出された際に応じて呼び出されます。 datetime
オブジェクトは自身を引数としてメソッドに渡し、 time
オブジェクトは引数として None
をメソッドに渡します。従って、 tzinfo
のサブクラスにおけるメソッドは引数 dt が None
の場合と、 datetime
の場合を受理するように用意しなければなりません。
None
が渡された場合、最良の応答方法を決めるのはクラス設計者次第です。例えば、このクラスが tzinfo
プロトコルと関係をもたないということを表明させたければ、 None
が適切です。標準時のオフセットを見つける他の手段がない場合には、標準 UTC オフセットを返すために utcoffset(None)
を使うともっと便利かもしれません。
datetime
オブジェクトが datetime()
メソッドの応答として返された場合、 dt.tzinfo
は self と同じオブジェクトになります。ユーザが直接 tzinfo
メソッドを呼び出さないかぎり、 tzinfo
メソッドは dt.tzinfo
と self が同じであることに依存します。その結果 tzinfo
メソッドは dt がローカル時間であると解釈するので、他のタイムゾーンでのオブジェクトの振る舞いについて心配する必要がありません。
サブクラスでオーバーライドすると良い、もう 1 つの tzinfo
のメソッドがあります:
- tzinfo.fromutc(dt)¶
デフォルトの
datetime.astimezone()
実装で呼び出されます。datetime.astimezone()
から呼ばれた場合、dt.tzinfo
は self であり、 dt の日付および時刻データは UTC 時刻を表しているものとして見えます。fromutc()
の目的は、 self のローカル時刻に等しいdatetime
オブジェクトを返すことにより日付と時刻データメンバを修正することにあります。Most
tzinfo
subclasses should be able to inherit the defaultfromutc()
implementation without problems. It's strong enough to handle fixed-offset time zones, and time zones accounting for both standard and daylight time, and the latter even if the DST transition times differ in different years. An example of a time zone the defaultfromutc()
implementation may not handle correctly in all cases is one where the standard offset (from UTC) depends on the specific date and time passed, which can happen for political reasons. The default implementations ofastimezone()
andfromutc()
may not produce the result you want if the result is one of the hours straddling the moment the standard offset changes.エラーの場合のためのコードを除き、デフォルトの
fromutc()
の実装は以下のように動作します:def fromutc(self, dt): # raise ValueError error if dt.tzinfo is not self dtoff = dt.utcoffset() dtdst = dt.dst() # raise ValueError if dtoff is None or dtdst is None delta = dtoff - dtdst # this is self's standard offset if delta: dt += delta # convert to standard local time dtdst = dt.dst() # raise ValueError if dtdst is None if dtdst: return dt + dtdst else: return dt
次の tzinfo_examples.py
ファイルには、 tzinfo
クラスの例がいくつか載っています:
from datetime import tzinfo, timedelta, datetime
ZERO = timedelta(0)
HOUR = timedelta(hours=1)
SECOND = timedelta(seconds=1)
# A class capturing the platform's idea of local time.
# (May result in wrong values on historical times in
# timezones where UTC offset and/or the DST rules had
# changed in the past.)
import time as _time
STDOFFSET = timedelta(seconds = -_time.timezone)
if _time.daylight:
DSTOFFSET = timedelta(seconds = -_time.altzone)
else:
DSTOFFSET = STDOFFSET
DSTDIFF = DSTOFFSET - STDOFFSET
class LocalTimezone(tzinfo):
def fromutc(self, dt):
assert dt.tzinfo is self
stamp = (dt - datetime(1970, 1, 1, tzinfo=self)) // SECOND
args = _time.localtime(stamp)[:6]
dst_diff = DSTDIFF // SECOND
# Detect fold
fold = (args == _time.localtime(stamp - dst_diff))
return datetime(*args, microsecond=dt.microsecond,
tzinfo=self, fold=fold)
def utcoffset(self, dt):
if self._isdst(dt):
return DSTOFFSET
else:
return STDOFFSET
def dst(self, dt):
if self._isdst(dt):
return DSTDIFF
else:
return ZERO
def tzname(self, dt):
return _time.tzname[self._isdst(dt)]
def _isdst(self, dt):
tt = (dt.year, dt.month, dt.day,
dt.hour, dt.minute, dt.second,
dt.weekday(), 0, 0)
stamp = _time.mktime(tt)
tt = _time.localtime(stamp)
return tt.tm_isdst > 0
Local = LocalTimezone()
# A complete implementation of current DST rules for major US time zones.
def first_sunday_on_or_after(dt):
days_to_go = 6 - dt.weekday()
if days_to_go:
dt += timedelta(days_to_go)
return dt
# US DST Rules
#
# This is a simplified (i.e., wrong for a few cases) set of rules for US
# DST start and end times. For a complete and up-to-date set of DST rules
# and timezone definitions, visit the Olson Database (or try pytz):
# http://www.twinsun.com/tz/tz-link.htm
# https://sourceforge.net/projects/pytz/ (might not be up-to-date)
#
# In the US, since 2007, DST starts at 2am (standard time) on the second
# Sunday in March, which is the first Sunday on or after Mar 8.
DSTSTART_2007 = datetime(1, 3, 8, 2)
# and ends at 2am (DST time) on the first Sunday of Nov.
DSTEND_2007 = datetime(1, 11, 1, 2)
# From 1987 to 2006, DST used to start at 2am (standard time) on the first
# Sunday in April and to end at 2am (DST time) on the last
# Sunday of October, which is the first Sunday on or after Oct 25.
DSTSTART_1987_2006 = datetime(1, 4, 1, 2)
DSTEND_1987_2006 = datetime(1, 10, 25, 2)
# From 1967 to 1986, DST used to start at 2am (standard time) on the last
# Sunday in April (the one on or after April 24) and to end at 2am (DST time)
# on the last Sunday of October, which is the first Sunday
# on or after Oct 25.
DSTSTART_1967_1986 = datetime(1, 4, 24, 2)
DSTEND_1967_1986 = DSTEND_1987_2006
def us_dst_range(year):
# Find start and end times for US DST. For years before 1967, return
# start = end for no DST.
if 2006 < year:
dststart, dstend = DSTSTART_2007, DSTEND_2007
elif 1986 < year < 2007:
dststart, dstend = DSTSTART_1987_2006, DSTEND_1987_2006
elif 1966 < year < 1987:
dststart, dstend = DSTSTART_1967_1986, DSTEND_1967_1986
else:
return (datetime(year, 1, 1), ) * 2
start = first_sunday_on_or_after(dststart.replace(year=year))
end = first_sunday_on_or_after(dstend.replace(year=year))
return start, end
class USTimeZone(tzinfo):
def __init__(self, hours, reprname, stdname, dstname):
self.stdoffset = timedelta(hours=hours)
self.reprname = reprname
self.stdname = stdname
self.dstname = dstname
def __repr__(self):
return self.reprname
def tzname(self, dt):
if self.dst(dt):
return self.dstname
else:
return self.stdname
def utcoffset(self, dt):
return self.stdoffset + self.dst(dt)
def dst(self, dt):
if dt is None or dt.tzinfo is None:
# An exception may be sensible here, in one or both cases.
# It depends on how you want to treat them. The default
# fromutc() implementation (called by the default astimezone()
# implementation) passes a datetime with dt.tzinfo is self.
return ZERO
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
# Can't compare naive to aware objects, so strip the timezone from
# dt first.
dt = dt.replace(tzinfo=None)
if start + HOUR <= dt < end - HOUR:
# DST is in effect.
return HOUR
if end - HOUR <= dt < end:
# Fold (an ambiguous hour): use dt.fold to disambiguate.
return ZERO if dt.fold else HOUR
if start <= dt < start + HOUR:
# Gap (a non-existent hour): reverse the fold rule.
return HOUR if dt.fold else ZERO
# DST is off.
return ZERO
def fromutc(self, dt):
assert dt.tzinfo is self
start, end = us_dst_range(dt.year)
start = start.replace(tzinfo=self)
end = end.replace(tzinfo=self)
std_time = dt + self.stdoffset
dst_time = std_time + HOUR
if end <= dst_time < end + HOUR:
# Repeated hour
return std_time.replace(fold=1)
if std_time < start or dst_time >= end:
# Standard time
return std_time
if start <= std_time < end - HOUR:
# Daylight saving time
return dst_time
Eastern = USTimeZone(-5, "Eastern", "EST", "EDT")
Central = USTimeZone(-6, "Central", "CST", "CDT")
Mountain = USTimeZone(-7, "Mountain", "MST", "MDT")
Pacific = USTimeZone(-8, "Pacific", "PST", "PDT")
標準時および夏時間の両方を記述している tzinfo
のサブクラスでは、夏時間の移行のときに、回避不能の難解な問題が年に 2 度あるので注意してください。
具体的な例として、東部アメリカ時刻 (US Eastern, UTC -0500) を考えます。
EDT は 3 月の第二日曜日の 1:59 (EST) の 1 分後に開始し、11 月の最初の日曜日の (EDTの) 1:59 に終了します:
UTC 3:MM 4:MM 5:MM 6:MM 7:MM 8:MM
EST 22:MM 23:MM 0:MM 1:MM 2:MM 3:MM
EDT 23:MM 0:MM 1:MM 2:MM 3:MM 4:MM
start 22:MM 23:MM 0:MM 1:MM 3:MM 4:MM
end 23:MM 0:MM 1:MM 1:MM 2:MM 3:MM
DSTの開始 ("start" ライン) で、ローカルの実時間は 1:59 から 3:00 に飛びます。
この日には、 2:MM という形式の実時間は意味をなさないので、 DST が始まった日に astimezone(Eastern)
は hour == 2
となる結果を返すことはありません。
例として、 2016 年の春方向の移行では、次のような結果になります:
>>> from datetime import datetime, timezone
>>> from tzinfo_examples import HOUR, Eastern
>>> u0 = datetime(2016, 3, 13, 5, tzinfo=timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
... print(u.time(), 'UTC =', t.time(), t.tzname())
...
05:00:00 UTC = 00:00:00 EST
06:00:00 UTC = 01:00:00 EST
07:00:00 UTC = 03:00:00 EDT
08:00:00 UTC = 04:00:00 EDT
When DST ends (the "end" line), there's a potentially worse problem: there's an
hour that can't be spelled unambiguously in local wall time: the last hour of
daylight time. In Eastern, that's times of the form 5:MM UTC on the day
daylight time ends. The local wall clock leaps from 1:59 (daylight time) back
to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous.
astimezone()
mimics the local clock's behavior by mapping two adjacent UTC
hours into the same local hour then. In the Eastern example, UTC times of the
form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times
have the fold
attribute set to 0 and the later times have it set to 1.
For example, at the Fall back transition of 2016, we get:
>>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc)
>>> for i in range(4):
... u = u0 + i*HOUR
... t = u.astimezone(Eastern)
... print(u.time(), 'UTC =', t.time(), t.tzname(), t.fold)
...
04:00:00 UTC = 00:00:00 EDT 0
05:00:00 UTC = 01:00:00 EDT 0
06:00:00 UTC = 01:00:00 EST 1
07:00:00 UTC = 02:00:00 EST 0
Note that the datetime
instances that differ only by the value of the
fold
attribute are considered equal in comparisons.
Applications that can't bear wall-time ambiguities should explicitly check the
value of the fold
attribute or avoid using hybrid
tzinfo
subclasses; there are no ambiguities when using timezone
,
or any other fixed-offset tzinfo
subclass (such as a class representing
only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
参考
zoneinfo
The
datetime
module has a basictimezone
class (for handling arbitrary fixed offsets from UTC) and itstimezone.utc
attribute (a UTC timezone instance).
zoneinfo
は Python に IANA タイムゾーンデータベース (オルソンデータベースとしても知られています) を導入するもので、これを使うことが推奨されています。
- IANA タイムゾーンデータベース
(しばしば tz、tzdata や zoneinfo と呼ばれる) タイムゾーンデータベースはコードとデータを保持しており、それらは地球全体にわたる多くの代表的な場所のローカル時刻の履歴を表しています。政治団体によるタイムゾーンの境界、UTC オフセット、夏時間のルールの変更を反映するため、定期的にデータベースが更新されます。
timezone
オブジェクト¶
timezone
クラスは tzinfo
のサブクラスで、各インスタンスは UTC からの固定されたオフセットで定義されたタイムゾーンを表しています。
このクラスのオブジェクトは、一年のうち異なる日に異なるオフセットが使われていたり、常用時 (civil time) に歴史的な変化が起きた場所のタイムゾーン情報を表すのには使えないので注意してください。
- class datetime.timezone(offset, name=None)¶
ローカル時刻と UTC の差分を表す
timedelta
オブジェクトを offset 引数に指定しなくてはいけません。これは-timedelta(hours=24)
からtimedelta(hours=24)
までの両端を含まない範囲に収まっていなくてはなりません。そうでない場合ValueError
が送出されます。name 引数は必須ではありません。もし指定された場合、その値は
datetime.tzname()
メソッドの返り値として使われる文字列でなければなりません。バージョン 3.2 で追加.
バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
- timezone.utcoffset(dt)¶
timezone
インスタンスが構築されたときに指定された固定値を返します。dt 引数は無視されます。 返り値は、ローカル時刻と UTC の差分に等しい
timedelta
インスタンスです。バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
- timezone.tzname(dt)¶
timezone
インスタンスが構築されたときに指定された固定値を返します。name が構築時に与えられなかった場合、
tzname(dt)
によって返される name は以下の様にoffset
の値から生成されます。 offset がtimedelta(0)
であった場合、 name は "UTC"になります。 それ以外の場合、 'UTC±HH:MM' という書式の文字列になり、± はoffset
を、HH と MM はそれぞれ二桁のoffset.hours
とoffset.minutes
を表現します。バージョン 3.6 で変更:
offset=timedelta(0)
によって生成される名前はプレーンな 'UTC' であり'UTC+00:00'
ではありません。
- timezone.dst(dt)¶
常に
None
を返します。
- timezone.fromutc(dt)¶
dt + offset
を返します。 dt 引数はtzinfo
がself
になっている aware なdatetime
インスタンスでなければなりません。
以下にクラス属性を示します:
- timezone.utc¶
UTC タイムゾーン
timezone(timedelta(0))
です。
strftime()
and strptime()
Behavior¶
date
, datetime
, time
オブジェクトは全て strftime(format)
メソッドをサポートし、時刻を表現する文字列を明示的な書式文字列で統制して作成しています。
逆に datetime.strptime()
クラスメソッドは日付や時刻に対応する書式文字列から datetime
オブジェクトを生成します。
The table below provides a high-level comparison of strftime()
versus strptime()
:
|
|
|
---|---|---|
使用法 |
オブジェクトを与えられた書式に従って文字列に変換する |
指定された対応する書式で文字列を構文解析して |
メソッドの種類 |
インスタンスメソッド |
クラスメソッド |
メソッドを持つクラス |
||
シグネチャ |
|
|
strftime()
and strptime()
Format Codes¶
These methods accept format codes that can be used to parse and format dates:
>>> datetime.strptime('31/01/22 23:59:59.999999',
... '%d/%m/%y %H:%M:%S.%f')
datetime.datetime(2022, 1, 31, 23, 59, 59, 999999)
>>> _.strftime('%a %d %b %Y, %I:%M%p')
'Mon 31 Jan 2022, 11:59PM'
以下のリストは 1989 C 標準が要求する全ての書式コードで、標準 C 実装があれば全ての環境で動作します。
ディレクティブ |
意味 |
使用例 |
注釈 |
---|---|---|---|
|
ロケールの曜日名を短縮形で表示します。 |
Sun, Mon, ..., Sat
(en_US);
So, Mo, ..., Sa
(de_DE)
|
(1) |
|
ロケールの曜日名を表示します。 |
Sunday, Monday, ...,
Saturday (en_US);
Sonntag, Montag, ...,
Samstag (de_DE)
|
(1) |
|
曜日を10進表記した文字列を表示します。0 が日曜日で、6 が土曜日を表します。 |
0, 1, ..., 6 |
|
|
0埋めした10進数で表記した月中の日にち。 |
01, 02, ..., 31 |
(9) |
|
ロケールの月名を短縮形で表示します。 |
Jan, Feb, ..., Dec
(en_US);
Jan, Feb, ..., Dez
(de_DE)
|
(1) |
|
ロケールの月名を表示します。 |
January, February,
..., December (en_US);
Januar, Februar, ...,
Dezember (de_DE)
|
(1) |
|
0埋めした10進数で表記した月。 |
01, 02, ..., 12 |
(9) |
|
0埋めした10進数で表記した世紀無しの年。 |
00, 01, ..., 99 |
(9) |
|
西暦 ( 4桁) の 10 進表記を表します。 |
0001, 0002, ..., 2013, 2014, ..., 9998, 9999 |
(2) |
|
0埋めした10進数で表記した時 (24時間表記)。 |
00, 01, ..., 23 |
(9) |
|
0埋めした10進数で表記した時 (12時間表記)。 |
01, 02, ..., 12 |
(9) |
|
ロケールの AM もしくは PM と等価な文字列になります。 |
AM, PM (en_US);
am, pm (de_DE)
|
(1), (3) |
|
0埋めした10進数で表記した分。 |
00, 01, ..., 59 |
(9) |
|
0埋めした10進数で表記した秒。 |
00, 01, ..., 59 |
(4), (9) |
|
10進数で表記したマイクロ秒 (6桁に0埋めされます)。 |
000000, 000001, ..., 999999 |
(5) |
|
UTCオフセットを |
(空文字列), +0000, -0400, +1030, +063415, -030712.345216 |
(6) |
|
タイムゾーンの名前を表示します (オブジェクトがnaiveであれば空文字列)。 |
(空文字列), UTC, GMT |
(6) |
|
0埋めした10進数で表記した年中の日にち。 |
001, 002, ..., 366 |
(9) |
|
0埋めした10進数で表記した年中の週番号 (週の始まりは日曜日とする)。新年の最初の日曜日に先立つ日は 0週に属するとします。 |
00, 01, ..., 53 |
(7), (9) |
|
0埋めした10進数で表記した年中の週番号 (週の始まりは月曜日とする)。新年の最初の月曜日に先立つ日は 0週に属するとします。 |
00, 01, ..., 53 |
(7), (9) |
|
ロケールの日時を適切な形式で表します。 |
Tue Aug 16 21:30:00
1988 (en_US);
Di 16 Aug 21:30:00
1988 (de_DE)
|
(1) |
|
ロケールの日付を適切な形式で表します。 |
08/16/88 (None);
08/16/1988 (en_US);
16.08.1988 (de_DE)
|
(1) |
|
ロケールの時間を適切な形式で表します。 |
21:30:00 (en_US);
21:30:00 (de_DE)
|
(1) |
|
文字 |
% |
C89規格により要求されない幾つかの追加のコードが便宜上含まれています。これらのパラメータはすべてISO 8601の日付値に対応しています。
ディレクティブ |
意味 |
使用例 |
注釈 |
---|---|---|---|
|
ISO week( |
0001, 0002, ..., 2013, 2014, ..., 9998, 9999 |
(8) |
|
1 を月曜日を表す 10進数表記の ISO 8601 weekday です。 |
1, 2, ..., 7 |
|
|
週で最初の月曜日を始めとする ISO 8601 week です。Week 01 は 1月4日を含みます。 |
01, 02, ..., 53 |
(8), (9) |
|
UTCオフセットを |
(空文字列), +00:00, -04:00, +10:30, +06:34:15, -03:07:12.345216 |
(6) |
These may not be available on all platforms when used with the strftime()
method. The ISO 8601 year and ISO 8601 week directives are not interchangeable
with the year and week number directives above. Calling strptime()
with
incomplete or ambiguous ISO 8601 directives will raise a ValueError
.
The full set of format codes supported varies across platforms, because Python
calls the platform C library's strftime()
function, and platform
variations are common. To see the full set of format codes supported on your
platform, consult the strftime(3) documentation. There are also
differences between platforms in handling of unsupported format specifiers.
バージョン 3.6 で追加: %G
, %u
および %V
が追加されました。
バージョン 3.12 で追加: %:z
が追加されました。
技術詳細¶
Broadly speaking, d.strftime(fmt)
acts like the time
module's
time.strftime(fmt, d.timetuple())
although not all objects support a
timetuple()
method.
For the datetime.strptime()
class method, the default value is
1900-01-01T00:00:00.000
: any components not specified in the format string
will be pulled from the default value. [4]
datetime.strptime(date_string, format)
は次の式と等価です:
datetime(*(time.strptime(date_string, format)[0:6]))
ただし、 datetime.strptime
はサポートしているが time.strptime
には無い、秒未満の単位やタイムゾーンオフセットの情報が format に 含まれているときは除きます。
For time
objects, the format codes for year, month, and day should not
be used, as time
objects have no such values. If they're used anyway,
1900
is substituted for the year, and 1
for the month and day.
date
オブジェクトには、時、分、秒、マイクロ秒の値がないため、それらの書式コードを使うことができません。
無理矢理使った場合、これらの値は 0
に置き換えられます。
同じ理由で、現在のロケールの文字集合で表現できない Unicode コードポイントを含む書式文字列の対処もプラットフォーム依存です。
あるプラットフォームではそういったコードポイントはそのまま出力に出される一方、他のプラットフォームでは strftime
が UnicodeError
を送出したり、その代わりに空文字列を返したりするかもしれません。
注釈:
Because the format depends on the current locale, care should be taken when making assumptions about the output value. Field orderings will vary (for example, "month/day/year" versus "day/month/year"), and the output may contain non-ASCII characters.
The
strptime()
method can parse years in the full [1, 9999] range, but years < 1000 must be zero-filled to 4-digit width.バージョン 3.2 で変更: In previous versions,
strftime()
method was restricted to years >= 1900.バージョン 3.3 で変更: In version 3.2,
strftime()
method was restricted to years >= 1000.When used with the
strptime()
method, the%p
directive only affects the output hour field if the%I
directive is used to parse the hour.Unlike the
time
module, thedatetime
module does not support leap seconds.When used with the
strptime()
method, the%f
directive accepts from one to six digits and zero pads on the right.%f
is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available).naive オブジェクトでは、書式コード
%z
、%:z
および%Z
は空文字列に置き換えられます。aware オブジェクトでは次のようになります:
%z
utcoffset()
is transformed into a string of the form±HHMM[SS[.ffffff]]
, whereHH
is a 2-digit string giving the number of UTC offset hours,MM
is a 2-digit string giving the number of UTC offset minutes,SS
is a 2-digit string giving the number of UTC offset seconds andffffff
is a 6-digit string giving the number of UTC offset microseconds. Theffffff
part is omitted when the offset is a whole number of seconds and both theffffff
and theSS
part is omitted when the offset is a whole number of minutes. For example, ifutcoffset()
returnstimedelta(hours=-3, minutes=-30)
,%z
is replaced with the string'-0330'
.
バージョン 3.7 で変更: UTC オフセットが分単位でなければならない制限が無くなりました。
バージョン 3.7 で変更: When the
%z
directive is provided to thestrptime()
method, the UTC offsets can have a colon as a separator between hours, minutes and seconds. For example,'+01:00:00'
will be parsed as an offset of one hour. In addition, providing'Z'
is identical to'+00:00'
.%:z
Behaves exactly as
%z
, but has a colon separator added between hours, minutes and seconds.%Z
In
strftime()
,%Z
is replaced by an empty string iftzname()
returnsNone
; otherwise%Z
is replaced by the returned value, which must be a string.strptime()
only accepts certain values for%Z
:使用しているマシンのロケールによる
time.tzname
の任意の値ハードコードされた値
UTC
またはGMT
つまり、日本に住んでいる場合は
JST
,UTC
とGMT
が有効な値であり、EST
はおそらく無効な値となります。無効な値の場合はValueError
を送出します。
バージョン 3.2 で変更: When the
%z
directive is provided to thestrptime()
method, an awaredatetime
object will be produced. Thetzinfo
of the result will be set to atimezone
instance.When used with the
strptime()
method,%U
and%W
are only used in calculations when the day of the week and the calendar year (%Y
) are specified.Similar to
%U
and%W
,%V
is only used in calculations when the day of the week and the ISO year (%G
) are specified in astrptime()
format string. Also note that%G
and%Y
are not interchangeable.When used with the
strptime()
method, the leading zero is optional for formats%d
,%m
,%H
,%I
,%M
,%S
,%j
,%U
,%W
, and%V
. Format%y
does require a leading zero.
脚注