datetime dan time

Modul datetime dan time adalah pasangan bawaan Python untuk pekerjaan tanggal dan waktu. Modul datetime menyediakan tipe date, time, dan datetime yang menyimpan titik waktu secara terstruktur, sedangkan modul time bekerja pada tingkat detik sejak sebuah titik acuan bernama epoch. Topik ini membahas pembuatan objek tanggal-waktu, aritmetika dengan timedelta, pemformatan dengan strftime dan strptime, peran modul time, serta kesalahan yang lazim muncul saat membandingkan waktu.

Membuat objek date, time, dan datetime#

Kelas date menyimpan tanggal tanpa jam, kelas time menyimpan jam tanpa tanggal, dan kelas datetime menggabungkan keduanya. Ketiganya dibangun dengan argumen eksplisit berupa angka tahun, bulan, dan seterusnya, tanpa string sama sekali. Konstruksi eksplisit seperti ini meniadakan keraguan mengenai format karena setiap komponen langsung tersimpan sebagai bilangan bulat.

from datetime import date, time, datetime

tanggal = date(2026, 11, 2)
jam = time(9, 30, 0)
acara = datetime(2026, 11, 2, 9, 30, 0)

print(tanggal.year, tanggal.month, tanggal.day)
print(jam.hour, jam.minute, jam.second)
print(acara)
print(acara.date(), acara.time())
print(acara.isoformat())

2026 11 2
9 30 0
2026-11-02 09:30:00
2026-11-02 09:30:00
2026-11-02T09:30:00

Atribut seperti year dan hour dapat dibaca langsung dari objeknya, sehingga komponen tertentu tidak perlu diurai dari string. Metode date() dan time() pada objek datetime memisahkan bagian tanggal dan bagian jam dari satu objek yang sama. Metode isoformat() menghasilkan bentuk standar ISO 8601, yaitu format yang paling umum dipakai untuk pertukaran data antar sistem.

Kelas yang sama juga menyediakan datetime.now() dan date.today() untuk membaca waktu saat ini. Nilai keduanya bergantung pada saat eksekusi, sehingga tidak disertakan blok keluaran pada topik ini dan pembahasannya ada pada bagian modul time.

Aritmetika dengan timedelta#

Kelas timedelta mewakili durasi, yaitu selisih antara dua titik waktu, dan menjadi kunci aritmetika tanggal. Penjumlahan atau pengurangan timedelta pada objek date atau datetime menggeser waktunya, sedangkan pengurangan dua objek tanggal menghasilkan timedelta baru. Durasi yang kompleks dapat disusun dari kombinasi argumen seperti days, hours, minutes, dan seconds.

from datetime import date, timedelta

mulai = date(2026, 11, 2)
batas = mulai + timedelta(days=30)
print(batas)

akhir = date(2027, 1, 20)
jarak = akhir - mulai
print(jarak)
print(jarak.days)

2026-12-02
79 days, 0:00:00
79

Tanggal jatuh tempo dihitung dengan menambahkan tiga puluh hari ke tanggal mulai, dan timedelta menangani batas bulan serta batas tahun secara otomatis. Selisih dua tanggal dicetak sebagai objek timedelta yang menyatakan 79 hari, dan atribut days mengambil komponen harinya sebagai bilangan bulat. Aritmetika jenis ini menggantikan penghitungan manual yang rentan keliru, misalnya menghitung mundur jumlah hari tiap bulan.

Pemformatan dengan strftime dan strptime#

Metode strftime memformat objek tanggal-waktu menjadi string menurut penentu (%-directive) yang masing-masing mewakili satu komponen, sedangkan strptime bekerja sebaliknya, yaitu membaca string menjadi objek datetime menurut pola yang diberikan. Penentu yang paling sering dipakai dirangkum pada tabel berikut.

from datetime import datetime

acara = datetime(2026, 11, 2, 9, 5)
print(acara.strftime("%d/%m/%Y"))
print(acara.strftime("%Y-%m-%d %H:%M"))
print(acara.strftime("%H:%M:%S"))

teks = "2026-11-02 14:05"
hasil = datetime.strptime(teks, "%Y-%m-%d %H:%M")
print(hasil)

02/11/2026
2026-11-02 09:05
09:05:00
2026-11-02 14:05:00

Setiap pemanggilan strftime mengembalikan string yang bentuknya sepenuhnya ditentukan pola, sehingga format tampilan dapat dibuat sesuai kebutuhan laporan. Pada strptime, pola wajib cocok dengan teks yang dibaca, dan ketidakcocokan menimbulkan error ValueError yang menyebut data yang tidak sesuai. Untuk format ISO 8601 yang dihasilkan isoformat(), metode datetime.fromisoformat() membacanya kembali tanpa perlu pola eksplisit.

Peran modul time#

Modul time bekerja pada tingkat detik sejak epoch, yaitu titik acuan 1 Januari 1970 pukul 00.00.00 UTC. Fungsi time.time() membaca jumlah detik hingga saat eksekusi sebagai bilangan desimal, sedangkan fungsi time.gmtime() mengonversi detik epoch menjadi struct_time, yaitu objek berisi sembilan komponen waktu. Karena nilainya berbasis detik, format ini mudah disimpan, diurutkan, dan dibandingkan.

import time
from datetime import datetime, timezone

print(time.gmtime(0))
print(datetime.fromtimestamp(0, tz=timezone.utc))
print(datetime.fromtimestamp(1700000000, tz=timezone.utc))

time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)
1970-01-01 00:00:00+00:00
2023-11-14 22:13:20+00:00

Pemanggilan time.gmtime(0) menampilkan komponen-komponen epoch, dan bidang tm_wday bernilai 3 karena hari Kamis dihitung dari 0 untuk Senin. Fungsi datetime.fromtimestamp() mengubah detik epoch menjadi objek datetime, dan argumen tz=timezone.utc membuat hasilnya sadar zona waktu (timezone-aware), yaitu membawa informasi offset secara eksplisit.

Dua fungsi berikut membaca waktu saat ini sehingga keluarannya selalu berubah pada setiap eksekusi.

# tidak-dijalankan: time.time() dan datetime.now() berubah setiap eksekusi
import time
from datetime import datetime

print(time.time())
print(datetime.now())

time.time() mengembalikan jumlah detik epoch hingga saat eksekusi, sedangkan datetime.now() mengembalikan datetime lokal saat itu. Fungsi time.sleep(detik) melengkapi modul ini dengan menghentikan eksekusi sementara selama jumlah detik yang diberikan, dan sering digunakan dalam perulangan yang menunggu sumber daya eksternal.

Kesalahan umum#

Kesalahan pertama adalah membandingkan objek datetime naif dengan objek yang sadar zona waktu. Objek naif tidak membawa informasi offset, sehingga Python menolak perbandingannya karena hasilnya tidak bermakna.

from datetime import datetime, timezone

naif = datetime(2026, 11, 2, 9, 0)
sadar = datetime(2026, 11, 2, 9, 0, tzinfo=timezone.utc)
try:
    print(naif < sadar)
except TypeError as e:
    print("TypeError:", e)

TypeError: can't compare offset-naive and offset-aware datetimes

Perbaikannya adalah menyeragamkan status zona waktu, misalnya melengkapi objek naif dengan replace(tzinfo=timezone.utc) sebelum perbandingan. Kesalahan kedua adalah mencampur date dan datetime dalam satu operasi aritmetika, karena keduanya bertipe berbeda meskipun menyimpan tanggal yang sama.

from datetime import date, datetime

d = date(2026, 11, 2)
dt = datetime(2026, 11, 2, 9, 0)
try:
    print(dt - d)
except TypeError as e:
    print("TypeError:", e)

TypeError: unsupported operand type(s) for -: 'datetime.datetime' and 'datetime.date'

Menyeragamkan tipe dengan dt.date() menyelesaikan masalah ini, karena pengurangan kemudian berlangsung antara dua objek date. Kesalahan ketiga adalah menukar penentu %m untuk bulan dengan %M untuk menit. Keduanya hanya berbeda pada huruf besar kecilnya. Penukaran tidak menimbulkan error apa pun, tetapi menghasilkan tanggal yang salah, sehingga pola pemformatan perlu diperiksa karakter demi karakter saat keluaran tampak janggal.

Ringkasan#

• Kelas date, time, dan datetime menyimpan komponen tanggal-waktu sebagai atribut yang dapat dibaca langsung, dan isoformat() menghasilkan format ISO 8601 yang standar.
• timedelta mewakili durasi, pengurangan dua tanggal menghasilkan timedelta, dan penambahan timedelta menggeser tanggal dengan penanganan batas bulan otomatis.
• strftime memformat objek menjadi string menurut penentu seperti %Y dan %H, sedangkan strptime membaca string menurut pola yang wajib cocok.
• Modul time bekerja pada detik epoch melalui time.time() dan time.gmtime(), sedangkan time.sleep() menghentikan eksekusi sementara.

Referensi#

• datetime — Python Software Foundation — Dokumentasi lengkap kelas date, time, datetime, dan timedelta beserta format penentunya.
• time — Python Software Foundation — Dokumentasi modul time untuk detik epoch, struct_time, dan fungsi sleep.