ciso8601

ciso8601

ciso8601 mengonversi ISO 8601 atau RFC 3339 string waktu tanggal menjadi objek datetime Python.

Karena ditulis sebagai modul C, itu jauh lebih cepat daripada perpustakaan Python lainnya. Diuji dengan CPYTHON 2.7, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12, 3.13.

(Tertarik mengerjakan proyek seperti ini? Tutup mencari insinyur hebat untuk bergabung dengan tim kami)

Isi

• Awal yang cepat
• Migrasi ke V2
• Kapan saya tidak harus menggunakan ciso8601 ?
• Penanganan kesalahan
• Benchmark
• Subset yang didukung dari ISO 8601
  • Format tanggal
  • Format waktu
  • Informasi zona waktu
• Parsing RFC 3339 yang ketat
• Mengabaikan informasi zona waktu saat parsing

Awal yang cepat

% pip install ciso8601

 In [ 1 ]: import ciso8601

In [ 2 ]: ciso8601 . parse_datetime ( '2014-12-05T12:30:45.123456-05:30' )
Out [ 2 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 , 123456 , tzinfo = pytz . FixedOffset ( 330 ))

In [ 3 ]: ciso8601 . parse_datetime ( '20141205T123045' )
Out [ 3 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 )

Migrasi ke V2

Versi 2.0.0 dari ciso8601 mengubah implementasi inti. Ini tidak sepenuhnya kompatibel ke belakang, dan perawatan harus diambil ketika bermigrasi melihat changelog untuk panduan migrasi.

Kapan saya tidak harus menggunakan ciso8601 ?

ciso8601 belum tentu merupakan solusi terbaik untuk setiap kasus penggunaan (terutama karena Python 3.11). Lihat haruskah saya menggunakan ciso8601?

Penanganan kesalahan

Mulai di v2.0.0, ciso8601 menawarkan jaminan yang kuat ketika datang ke string parsing.

parse_datetime(dt: String): datetime adalah fungsi yang mengambil string dan baik:

• Mengembalikan datetime Python yang diuraikan dengan benar, jika dan hanya jika seluruh string sesuai dengan subset yang didukung dari ISO 8601
• Meningkatkan ValueError dengan deskripsi alasan mengapa string tidak sesuai dengan subset yang didukung dari ISO 8601

Jika informasi zona waktu disediakan, objek datetime yang sadar akan dikembalikan. Kalau tidak, datetime yang naif dikembalikan.

Benchmark

Mengurai cap waktu tanpa informasi zona waktu (misalnya, 2014-01-09T21:48:00 ):

Modul	Python 3.13	Python 3.12	Python 3.11	Python 3.10	Perlambatan Relatif (versus CISO8601, Python terbaru)	...	Python 3.9	Python 3.8
ciso8601	64.8 NSEC	62.8 NSEC	60.1 NSEC	91.7 NSEC	N/a	...	86 NSEC	92.9 NSEC
backports.datetime_fromisoformat	N/a	N/a	N/a	73.6 NSEC	0.8x	...	70 NSEC	75.9 NSEC
datetime (builtin)	147 NSEC	138 NSEC	123 NSEC	N/a	2.3x	...	N/a	N/a
bandul	171 NSEC	181 NSEC	175 NSEC	214 NSEC	2.6x	...	179 NSEC	180 NSEC
udatetime	542 NSEC	563 NSEC	525 NSEC	555 NSEC	8.4x	...	551 NSEC	553 NSEC
str2date	3.29 Usec	3.53 USEC	3.52 Usec	3.85 Usec	50.8x	...	3.72 Usec	3.9 Usec
ISO8601utils	N/a	N/a	N/a	N/a	56.9x	...	4.89 Usec	4.89 Usec
ISO8601	5.1 Usec	5.4 Usec	5.18 USEC	5.38 USEC	78.8x	...	5.36 Usec	5.55 USEC
isodate	5.76 USEC	5.85 Usec	5.21 Usec	5.91 Usec	89.0x	...	5.97 USEC	6.07 USEC
Pyso8601	10 Usec	11.5 USEC	7.99 Usec	10.9 Usec	155.0x	...	9.83 Usec	9.81 Usec
aniso8601	12.1 Usec	12.5 Usec	11.1 Usec	15.1 Usec	186.9x	...	15.4 USEC	15.6 USEC
Zulu	12.3 Usec	13.6 USEC	12.6 USEC	14.2 Usec	189.4x	...	14.5 USEC	14.2 Usec
Maya	35.9 USEC	N/a	40.6 USEC	46.7 USEC	554.3x	...	45.4 USEC	46.3 Usec
Python-Dateutil	36.2 Usec	36.9 Usec	36.1 Usec	44 USEC	558.5x	...	46.4 USEC	45.2 USEC
anak panah	42.9 Usec	43.8 USEC	41.2 Usec	48.8 USEC	662.7x	...	50.7 Usec	50.1 Usec
metomi-isodateTime	828 USEC	822 USEC	791 USEC	1.09 msec	12781.0x	...	1.1 msec	1.11 msec
momen	1.28 msec	1.32 msec	1.29 msec	1.36 msec	19696.9x	...	1.37 msec	1.34 msec

CISO8601 mengambil 64,8 NSEC, yang 2,3x lebih cepat dari DateTime (builtin) , parser Python 3.13 tercepat berikutnya dalam perbandingan ini.

Parsing stempel waktu dengan informasi zona waktu (mis., 2014-01-09T21:48:00-05:30 ):

Modul	Python 3.13	Python 3.12	Python 3.11	Python 3.10	Perlambatan Relatif (versus CISO8601, Python terbaru)	...	Python 3.9	Python 3.8
ciso8601	73.9 NSEC	71 NSEC	65.6 NSEC	97.5 NSEC	N/a	...	92.9 NSEC	96.6 NSEC
backports.datetime_fromisoformat	N/a	N/a	N/a	99.2 NSEC	1.0x	...	93 NSEC	99.4 NSEC
datetime (builtin)	205 NSEC	198 NSEC	178 NSEC	N/a	2.8x	...	N/a	N/a
bandul	251 NSEC	259 NSEC	251 NSEC	262 NSEC	3.4x	...	264 NSEC	264 NSEC
udatetime	684 NSEC	700 NSEC	646 NSEC	684 NSEC	9.3x	...	688 NSEC	676 NSEC
str2date	5.95 Usec	4.34 USEC	4.11 Usec	4.58 USEC	80.5x	...	4.6 Usec	4.82 Usec
ISO8601	7.68 USEC	8.56 USEC	7.62 Usec	7.99 Usec	103.9x	...	7.83 Usec	8.16 USEC
isodate	7.77 USEC	8.53 Usec	7.54 USEC	7.88 USEC	105.0x	...	8.12 Usec	8.4 Usec
ISO8601utils	N/a	N/a	N/a	N/a	152.2x	...	14.1 Usec	14.6 USEC
Zulu	17.8 USEC	16.9 Usec	15.7 USEC	17.3 Usec	241.3x	...	17.3 Usec	17.6 USEC
aniso8601	18 Usec	18.7 USEC	16.4 USEC	21.5 USEC	243.1x	...	22.5 Usec	22.8 USEC
Pyso8601	18.3 USEC	16.6 USEC	14.3 Usec	15.8 USEC	247.5x	...	16.2 Usec	16.4 USEC
Maya	46.2 Usec	N/a	41 Usec	47.5 USEC	625.0x	...	45.2 USEC	47 USEC
Python-Dateutil	47.1 Usec	48.2 Usec	47.1 Usec	57.3 Usec	636.5x	...	60.4 USEC	58.9 Usec
anak panah	57.7 USEC	53.8 USEC	50.8 Usec	60.2 Usec	780.2x	...	59.4 USEC	60.1 Usec
metomi-isodateTime	876 USEC	823 USEC	795 USEC	1.09 msec	11846.4x	...	1.09 msec	1.13 msec
momen					2070678.8x	...

CISO8601 mengambil 73,9 NSEC, yang 2,8x lebih cepat dari DateTime (builtin) , parser Python 3.13 tercepat berikutnya dalam perbandingan ini.

Diuji di Linux 6.11.5-OrbStack-00280-G96D99C92A42B menggunakan modul berikut:

 aniso8601 == 9.0 . 1
arrow == 1.3 . 0
backports . datetime_fromisoformat == 2.0 . 2
ciso8601 == 2.3 . 1
iso8601 == 2.1 . 0
iso8601utils == 0.1 . 2
isodate == 0.7 . 2
maya == 0.6 . 1
metomi - isodatetime == 1 ! 3.1 . 0
moment == 0.12 . 1
pendulum == 3.0 . 0
PySO8601 == 0.2 . 0
python - dateutil == 2.9 . 0. post0
str2date == 0.905
udatetime == 0.0 . 17
zulu == 2.0 . 1

Untuk rincian benchmarking lengkap (atau untuk menjalankan benchmark sendiri), lihat Benchmarking/ReadMe.RST

Subset yang didukung dari ISO 8601

ciso8601 hanya mendukung subset ISO 8601, tetapi mendukung superset dari apa yang didukung oleh Python itu sendiri ( datetime.fromisoformat ), dan mendukung keseluruhan spesifikasi RFC 3339.

Format tanggal

Format tanggal berikut didukung:

Format	Contoh	Didukung
YYYY-MM-DD (diperpanjang)	2018-04-29	✅
YYYY-MM (diperpanjang)	2018-04	✅
YYYYMMDD (dasar)	20180429	✅
YYYY-Www-D (tanggal minggu)	2009-W01-1	✅
YYYY-Www (tanggal minggu)	2009-W01	✅
YYYYWwwD (tanggal minggu)	2009W011	✅
YYYYWww (tanggal minggu)	2009W01	✅
YYYY-DDD (tanggal ordinal)	1981-095	✅
YYYYDDD (tanggal ordinal)	1981095	✅

Format tanggal ISO 8601 yang tidak umum tidak didukung:

Format	Contoh	Didukung
--MM-DD (tahun dihilangkan)	--04-29
--MMDD (tahun dihilangkan)	--0429
±YYYYY-MM (> 4 digit tahun)	+10000-04
+YYYY-MM (terkemuka +)	+2018-04
-YYYY-MM (negatif -)	-2018-04

Format waktu

Waktu opsional dan dipisahkan dari tanggal dengan huruf T .

Konsisten dengan RFC 3339, ciso8601 juga memungkinkan baik karakter ruang, atau T terbalik t , untuk digunakan sebagai pengganti T .

Format waktu berikut didukung:

Format	Contoh	Didukung
hh	11	✅
hhmm	1130	✅
hh:mm	11:30	✅
hhmmss	113059	✅
hh:mm:ss	11:30:59	✅
hhmmss.ssssss	113059.123456	✅
hh:mm:ss.ssssss	11:30:59.123456	✅
hhmmss,ssssss	113059,123456	✅
hh:mm:ss,ssssss	11:30:59,123456	✅
Tengah malam (kasus khusus)	24:00:00	✅
hh.hhh (jam pecahan)	11.5
hh:mm.mmm (menit pecahan)	11:30.5

CATATAN: Objek datetime Python hanya memiliki presisi mikrodetik (6 digit). Setiap presisi tambahan akan terpotong.

Informasi zona waktu

Informasi zona waktu dapat disediakan dalam salah satu format berikut:

Format	Contoh	Didukung
Z	Z	✅
z	z	✅
±hh	+11	✅
±hhmm	+1130	✅
±hh:mm	+11:30	✅

Sementara spesifikasi ISO 8601 memungkinkan penggunaan tanda minus (U+2212) dalam pemisah zona waktu, ciso8601 hanya mendukung penggunaan karakter hiphen-minus (U+002D).

Konsisten dengan RFC 3339, ciso8601 juga memungkinkan z yang rendah untuk digunakan sebagai ganti Z .

Parsing RFC 3339 yang ketat

ciso8601 Parses ISO 8601 Datetimes, yang dapat dianggap sebagai superset RFC 3339 (secara kasar). Dalam kasus di mana Anda mungkin menginginkan parsing RFC 3339 yang ketat, ciso8601 menawarkan metode parse_rfc3339 , yang berperilaku dengan cara yang mirip dengan parse_datetime :

parse_rfc3339(dt: String): datetime adalah fungsi yang mengambil string dan baik:

• Mengembalikan datetime python yang diuraikan dengan benar, jika dan hanya jika seluruh string sesuai dengan RFC 3339.
• Meningkatkan ValueError dengan deskripsi alasan mengapa string tidak sesuai dengan RFC 3339.

Mengabaikan informasi zona waktu saat parsing

Dibutuhkan lebih banyak waktu untuk menguraikan cap waktu dengan informasi zona waktu, terutama jika mereka tidak di UTC. Namun, ada kalanya Anda tidak peduli tentang informasi zona waktu, dan ingin menghasilkan datetime yang naif sebagai gantinya. Misalnya, jika Anda yakin bahwa program Anda hanya akan menguraikan cap waktu dari zona waktu tunggal, Anda mungkin ingin melepaskan informasi zona waktu dan hanya menghasilkan datetime yang naif.

Dalam kasus terbatas ini, ada fungsi kedua yang disediakan. parse_datetime_as_naive akan mengabaikan informasi zona waktu yang ditemukan dan, sebagai hasilnya, lebih cepat untuk cap waktu yang berisi informasi zona waktu.

 In [ 1 ]: import ciso8601

In [ 2 ]: ciso8601 . parse_datetime_as_naive ( '2014-12-05T12:30:45.123456-05:30' )
Out [ 2 ]: datetime . datetime ( 2014 , 12 , 5 , 12 , 30 , 45 , 123456 )

Catatan: parse_datetime_as_naive hanya berguna dalam kasus di mana cap waktu Anda memiliki informasi zona waktu, tetapi Anda ingin mengabaikannya. Ini agak tidak biasa. Jika cap waktu Anda tidak memiliki informasi zona waktu (yaitu naif), cukup gunakan parse_datetime . Itu sama cepatnya.