Stabilitas API Pandas

Section ini menutup dengan pertanyaan yang muncul setiap kali kita mengandalkan API seluas pandas: seberapa lama kode yang ditulis hari ini tetap berjalan? Jawaban pandas adalah kebijakan deprecation yang jelas — fitur tidak pernah dihapus tiba-tiba; ia diumumkan lewat warning selama satu atau lebih siklus rilis, dicantumkan di halaman whatsnew, dan baru dilepas pada rilis mayor. pandas 3.0 adalah momen pelepasan besar terbaru: sejumlah API yang sudah lama diberi warning kini benar-benar hilang, dan kelas warning baru bernama Pandas4Warning menandai perubahan berikutnya yang akan terjadi di pandas 4.0. Chapter ini melatih pola kerja yang menjaga kode tetap kompatibel: menangkap warning secara deterministik, membaca error pengganti API yang dihapus, dan membiasakan diri membaca whatsnew sebelum upgrade.

Menangkap Warning secara Deterministik #

Warning Python secara default hanya tampil sekali di stderr dan tidak masuk stdout — kondisi yang menyulitkan pengujian. Modul warnings bawaan Python menyediakan pola penangkapan yang rapi, dan script berikut memakainya untuk mengamati satu warning deprecation milik pandas.

import warnings

import pandas as pd

# tangkap warning agar output skrip tetap deterministik
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    pd.api.types.is_categorical_dtype(pd.Series(["a"]))
w = caught[0]
print("kategori :", type(w.message).__name__)
print("pesan    :", str(w.message))
print()

# Pandas4Warning adalah subclass DeprecationWarning
print("subclass DeprecationWarning:", issubclass(pd.errors.Pandas4Warning, DeprecationWarning))
print()

# API yang dihapus di 3.0 melempar error yang informatif
df = pd.DataFrame({"a": [1, 2, 3]})
uji = [
    ("df.applymap", lambda: df.applymap(str)),
    ("Series.view", lambda: df["a"].view),
    ("fillna(method=)", lambda: df["a"].fillna(method="ffill")),
    ("freq 'M'", lambda: pd.date_range("2026-01-01", periods=1, freq="M")),
]
for nama, panggil in uji:
    try:
        panggil()
        print(f"{nama:16s} -> masih tersedia")
    except Exception as e:
        print(f"{nama:16s} -> {type(e).__name__}")
try:
    pd.date_range("2026-01-01", periods=1, freq="M")
except ValueError as e:
    print("pesan freq M :", str(e))
print()

# pengganti resminya di 3.0
print("map    :", df["a"].map(lambda v: v + 1).tolist())
print("ffill  :", df["a"].ffill().tolist())
print("freq ME:", pd.date_range("2026-01-01", periods=2, freq="ME").strftime("%Y-%m-%d").tolist())
print("freq YE:", pd.date_range("2026-01-01", periods=1, freq="YE").strftime("%Y-%m-%d").tolist())

Output yang Dihasilkan:

kategori : Pandas4Warning
pesan    : is_categorical_dtype is deprecated and will be removed in a future version. Use isinstance(dtype, pd.CategoricalDtype) instead

subclass DeprecationWarning: True

df.applymap      -> AttributeError
Series.view      -> AttributeError
fillna(method=)  -> TypeError
freq 'M'         -> ValueError
pesan freq M : Invalid frequency: M. Failed to parse with error message: ValueError("'M' is no longer supported for offsets. Please use 'ME' instead.")

map    : [2, 3, 4]
ffill  : [1, 2, 3]
freq ME: ['2026-01-31', '2026-02-28']
freq YE: ['2026-12-31']

Mari kita bedah bagian pentingnya:

1. Baris 6-8 (penangkapan): warnings.catch_warnings(record=True) menyimpan setiap warning yang muncul di dalam blok ke list caught, dan warnings.simplefilter("always") memastikan warning muncul setiap kali (tanpa penyaringan “sekali saja”). Kombinasi ini membuat output skrip deterministik — jalankan dua kali, hasilnya identik.
2. Baris 10-11 (pembacaan): type(w.message).__name__ membuka kategori warning (Pandas4Warning), dan str(w.message) membuka pesannya lengkap dengan saran penggantinya: gunakan isinstance(dtype, pd.CategoricalDtype).
3. Baris 15 (silsilah kelas): pd.errors.Pandas4Warning adalah subclass DeprecationWarning bawaan Python. Filter warning apa pun yang bekerja pada DeprecationWarning otomatis ikut menangkapnya.
4. Baris 20-31 (uji API lama): empat panggilan pada API yang sudah dilepas di 3.0 masing-masing melempar error — AttributeError, AttributeError, TypeError, dan ValueError — bukan warning lagi.
5. Baris 32-35 (pesan informatif): error ValueError untuk freq "M" memuat kalimat pengarah eksplisit: 'M' is no longer supported for offsets. Please use 'ME' instead.
6. Baris 39-42 (pengganti): versi 3.0 menyediakan pengganti langsung untuk setiap API yang dilepas, dan semuanya menghasilkan nilai yang benar.

API yang Dihapus di 3.0 dan Penggantinya #

Tabel berikut merangkum empat pelepasan yang paling sering ditemui saat migrasi ke pandas 3.0, beserta bentuk error dan pengganti resminya.

Pola pelepasannya konsisten: perubahan yang memengaruhi hasil diumumkan dengan warning terlebih dahulu di rilis sebelumnya, lalu penghapusan terjadi pada rilis mayor. Pesan error penggantinya juga dirancang membantu — sebagaimana pesan freq "M" di output, biasanya kalimat pertama error sudah menyebut nama API pengganti. Membaca pesan error dengan teliti sering kali adalah langkah migrasi tercepat.

Membaca whatsnew Saat Migrasi #

Sumber kebenaran tentang perubahan antar versi adalah halaman whatsnew, misalnya v3.0.0 . Halaman itu disusun per kategori — enhancements, deprecations, removals — sehingga sebelum upgrade Anda cukup membaca dua bagian terakhir untuk mendaftar API yang akan berperilaku berbeda atau hilang. Kebiasaan sehatnya: catat versi pandas yang dipakai proyek, jalankan rangkaian pengujian dengan filter warning diaktifkan, lalu serap saran pengganti dari pesan warning sebelum berpindah versi.

Sudut pandang chapter ini memang sudah condong ke pengujian: menangkap warning, mengubah warning menjadi error, dan menutup semua jalur kode dengan tes. Chapter berikutnya membahas aturan perilaku terpenting era ini secara penuh: Copy-on-Write, mulai dari chained assignment yang kini berhenti bekerja. Setelah itu, opsi dan pengaturan pandas menutup section ini sebelum Pengujian dan Debugging mengambil alih tema pemeriksaan kode.

Referensi resmi untuk chapter ini: whatsnew v3.0.0 , pandas.errors.Pandas4Warning , dan pandas.DataFrame.map .