Referensi API

Course ini melatih kita mengenali banyak fungsi, tetapi tidak ada yang menghafal semuanya. Kebiasaan yang benar-benar melayani dalam jangka panjang adalah kemampuan membuka API reference, menemukan fungsi yang tepat, lalu membaca halamannya sampai perilaku default dan batasannya paham. Bab ini melatih dua keterampilan itu: menavigasi pohon kategori referensi, dan membedah docstring yang menjadi sumber isi halaman tersebut.

Kita juga akan membaca signature fungsi secara programatik dengan modul inspect, sehingga kita bisa memeriksa daftar parameter tanpa meninggalkan interpreter.

Menjelajahi Pohon Routines #

Pintu masuk API reference adalah halaman Index routines . Halaman itu tersusun seperti pohon: setiap cabang mengelompokkan fungsi berdasarkan tujuannya. Cabang-cabang yang paling sering kita butuhkan:

Banyak cabang lain tersedia di pohon yang sama — array manipulation, sorting, set operations, dan sebagainya. Saat kita tahu tujuannya tetapi tidak tahu namanya, kebiasaan yang tepat adalah menyapu cabang yang relevan di halaman routines, bukan menebak-nebak nama fungsi.

Anatomi Docstring NumPy #

Setiap halaman fungsi di API reference digenerate dari docstring yang tertanam di kode NumPy. Docstring tersebut mengikuti satu standar penulisan yang sama di seluruh ekosistem SciPy. Mari kita lihat awal docstring np.linalg.solve, salah satu fungsi yang kita gunakan sejak bab Penyelesaian Sistem Persamaan Linear:

import numpy as np

baris = np.linalg.solve.__doc__.splitlines()[1:9]
for b in baris:
    print(b.strip())

Output yang Dihasilkan:

Solve a linear matrix equation, or system of linear scalar equations.

Computes the "exact" solution, `x`, of the well-determined, i.e., full
rank, linear matrix equation `ax = b`.

Parameters
----------
a : (..., M, M) array_like

Dua baris pertama adalah summary, lalu bagian Parameters dimulai dengan judul bergaris bawah. Standar penulisan ini menetapkan urutan bagian yang konsisten: summary, Parameters, Returns, Raises, See Also, Notes, References, Examples. Blok berikut memindai seluruh docstring dan mencetak setiap judul bagian yang ditemukan:

import numpy as np

baris = np.linalg.solve.__doc__.splitlines()
print("Jumlah baris docstring:", len(baris))
for i in range(1, len(baris)):
    if set(baris[i].strip()) == {"-"} and len(baris[i].strip()) >= 4:
        print("Bagian:", baris[i - 1].strip())

Output yang Dihasilkan:

Jumlah baris docstring: 75
Bagian: Parameters
Bagian: Returns
Bagian: Raises
Bagian: See Also
Bagian: Notes
Bagian: References
Bagian: Examples

Mari kita bedah baris demi baris:

1. Baris 3 (__doc__.splitlines()): atribut __doc__ memuat docstring utuh sebagai satu teks; splitlines() mengubahnya menjadi list baris.
2. Baris 4 (print(...)): mencetak panjang total docstring — fungsi sederhana saja bisa membawa dokumentasi sepanjang 75 baris.
3. Baris 5-7 (pemindaian): kode memeriksa setiap baris; bila isinya hanya tanda hubung (-) dan panjangnya cukup, baris tersebut adalah garis bawah judul bagian, sehingga baris di atasnya adalah nama bagian.

Pola bagian-bagian itu menjadi peta membaca: Parameters menjelaskan input, Returns output, Raises error yang mungkin terjadi, See Also fungsi pengganti atau pendamping, Notes detail perilaku, dan Examples contoh yang bisa dijalankan ulang.

Membaca Signature Secara Programatik #

Signature menampilkan daftar parameter beserta defaultnya dalam satu baris. Modul inspect dari pustaka standar Python menampilkannya sebagai teks:

import numpy as np
import inspect

print(inspect.signature(np.mean))
print(np.mean.__module__)
print(np.linalg.solve.__module__)

Output yang Dihasilkan:

(a, axis=None, dtype=None, out=None, keepdims=<no value>, *, where=<no value>)
numpy
numpy.linalg

Yang perlu kita pahami dari output di atas:

• a tidak memiliki default sehingga wajib diisi; inilah array yang dirata-rata.
• axis=None menunjukkan default None, artinya rata-rata dihitung atas seluruh elemen kecuali kita menentukan axis.
• Tanda * adalah batas: parameter setelahnya bersifat keyword-only, sehingga where=... wajib ditulis dengan namanya.
• keepdims=<no value> menampilkan sentinel internal, bukan None; kita tetap boleh mengisinya dengan True atau False.
• Atribut __module__ menunjukkan modul asal fungsi — berguna saat kita ingin memastikan np.mean dan scipy.mean itu bukan fungsi yang sama.

Notasi Tipe di Halaman Referensi #

Halaman referensi memakai notasi ringkas yang perlu kita biasakan:

• array_like — parameter menerima apa pun yang dapat dikonversi NumPy: list, tuple, ndarray, atau scalar.
• (..., M, M) — notasi bentuk; tiga titik berarti dimensi tambahan bebas, jadi np.linalg.solve menerima satu matriks maupun tumpukan matriks sekaligus.
• float64, int64 — tipe nilai kembali; halaman arrays.scalars merinci jenis-jenis scalar NumPy.

Membiasakan diri dengan notasi ini membuat halaman referensi terasa seperti bahasa kedua, bukan dinding teks asing.