https://github.com/dzakwanalifi/stadata-x
Terminal UI untuk menjelajahi dan mengunduh data BPS Indonesia secara interaktif
https://github.com/dzakwanalifi/stadata-x
bps-api cli-app data-analysis data-visualization indonesia-statistics indonesian-data open-data python statistics terminal-ui textual tui
Last synced: 5 months ago
JSON representation
Terminal UI untuk menjelajahi dan mengunduh data BPS Indonesia secara interaktif
- Host: GitHub
- URL: https://github.com/dzakwanalifi/stadata-x
- Owner: dzakwanalifi
- License: mit
- Created: 2025-09-24T09:25:47.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-06T02:15:49.000Z (9 months ago)
- Last Synced: 2025-10-06T02:21:22.500Z (9 months ago)
- Topics: bps-api, cli-app, data-analysis, data-visualization, indonesia-statistics, indonesian-data, open-data, python, statistics, terminal-ui, textual, tui
- Language: Python
- Homepage: https://github.com/dzakwanalifi/stadata-x
- Size: 520 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# STADATA-X
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/stadata-x/)
[](https://github.com/dzakwanalifi/stadata-x/actions)
[](https://codecov.io/gh/dzakwanalifi/stadata-x)
[](https://github.com/dzakwanalifi/stadata-x/releases)
**Membuka Data Statistik Indonesia, Satu Perintah Sekaligus.**
`stadata-x` adalah sebuah aplikasi terminal (TUI) modern yang dirancang untuk menjelajahi, melihat, dan mengunduh data dari Badan Pusat Statistik (BPS) Indonesia secara interaktif. Dibangun dengan Python dan [Textual](https://github.com/textualize/textual), aplikasi ini menyediakan antarmuka yang cepat dan efisien untuk mengakses kekayaan data publik BPS langsung dari command line Anda.
Lupakan mengunduh file secara manual. Dengan `stadata-x`, Anda dapat dengan mudah menavigasi data berdasarkan wilayah, mencari tabel statistik, melihat pratinjau, dan mengunduhnya dalam berbagai format (CSV, Excel, JSON).
## 📸 Screenshots
### Layar Selamat Datang
### Pemilihan Wilayah
---
## ✨ Fitur Utama
- 🎯 **Navigasi Interaktif**: Jelajahi data BPS berdasarkan wilayah (Provinsi/Kabupaten/Kota) melalui antarmuka yang responsif.
- 📊 **Pratinjau Tabel**: Lihat isi tabel statistik langsung di terminal sebelum mengunduh, dengan pewarnaan dan perataan kolom otomatis untuk keterbacaan maksimal.
- 📥 **Unduhan Multi-Format**: Unduh data yang Anda butuhkan dalam format CSV, Excel (.xlsx), atau JSON.
- ⚙️ **Manajemen Konfigurasi**: Simpan Token API BPS dan atur folder unduhan default dengan mudah.
- 🔄 **Penanganan Error Cerdas**: Dilengkapi dengan mekanisme *retry* otomatis untuk mengatasi *rate limiting* API dan penanganan error koneksi yang tangguh.
- 🚀 **Caching**: Permintaan data yang sering diakses (seperti daftar wilayah) disimpan dalam cache untuk mempercepat waktu muat.
- 🎨 **Antarmuka Modern**: Pengalaman pengguna yang mulus dan modern di dalam terminal Anda.
## 📋 Persyaratan Sistem
- **Python**: 3.9 atau yang lebih baru
- **Terminal**: Terminal modern yang mendukung ANSI colors (Windows Terminal, iTerm2, GNOME Terminal, dll.)
- **Token API BPS**: Diperlukan untuk mengakses data (gratis dari portal developer BPS)
## 📈 Status & Coverage
- ✅ **113 Tests Passed** - Test suite lengkap dengan coverage tinggi
- ✅ **Cross-platform** - Kompatibel Windows, Linux, dan macOS (Python 3.9-3.13)
- ✅ **CI/CD Active** - GitHub Actions dengan testing multi-platform
- ✅ **PyPI Published** - Tersedia untuk instalasi global via `pip install stadata-x`
## 🚀 Instalasi
Pastikan Anda memiliki Python 3.9 atau yang lebih baru. `stadata-x` dapat diinstal dengan mudah menggunakan `pip`, `pipx`, atau `uv`.
### Menggunakan `pipx` (Direkomendasikan)
`pipx` menginstal paket Python dalam lingkungan terisolasi, yang merupakan cara terbaik untuk menginstal aplikasi command-line.
```bash
pipx install stadata-x
```
### Menggunakan `pip`
```bash
pip install stadata-x
```
### Menggunakan `uv`
```bash
uv pip install stadata-x
```
### Verifikasi Instalasi
Setelah instalasi, verifikasi bahwa aplikasi terinstal dengan benar:
```bash
stadata-x --version
```
## 🔧 Troubleshooting
### Masalah Instalasi Umum
#### **1. Build Error dengan `lxml`**
**Error**: `fatal error C1083: Cannot open include file: 'libxml/xmlversion.h'`
**Solusi**:
```bash
# Gunakan wheel-only installation
pip install stadata-x --only-binary=all
# Atau gunakan uv
uv pip install stadata-x --only-binary=all
```
**Penjelasan**: `stadata-x` menggunakan `lxml>=6.0.0` yang sudah include libxml2 binaries.
#### **2. Python Version Compatibility**
**Error**: `TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'`
**Solusi**:
- Pastikan menggunakan Python 3.9 atau yang lebih baru
- `stadata-x` mendukung Python 3.9-3.13
#### **3. Permission Error (Windows)**
**Error**: `PermissionError: [Errno 13] Permission denied`
**Solusi**:
```bash
# Jalankan sebagai administrator atau gunakan virtual environment
python -m venv venv
venv\Scripts\activate
pip install stadata-x
```
#### **4. SSL/Connection Error**
**Error**: `ssl.SSLCertVerificationError` atau connection timeout
**Solusi**:
```bash
# Update pip dan certificates
pip install --upgrade pip certifi
# Atau gunakan HTTP instead HTTPS
pip install stadata-x --trusted-host pypi.org --trusted-host files.pythonhosted.org
```
#### **5. Dependency Conflict**
**Error**: `ERROR: Cannot install stadata-x because these package versions have conflicting dependencies`
**Solusi**:
```bash
# Gunakan virtual environment terisolasi
python -m venv isolated_env
isolated_env\Scripts\activate
pip install stadata-x
# Atau gunakan pip-tools untuk resolve dependencies
pip install pip-tools
pip-compile --output-file=requirements.txt pyproject.toml
pip-sync
```
### Alternative Installation Methods
#### **Menggunakan Conda (Windows Recommended)**
```bash
# Install Miniconda atau Anaconda
# Buat environment baru
conda create -n stadata-env python=3.11
conda activate stadata-env
# Install package
pip install stadata-x
```
#### **Menggunakan pipx (Isolated Environment)**
```bash
pipx install stadata-x
```
#### **Manual Installation dari Source**
```bash
# Clone repository
git clone https://github.com/dzakwanalifi/stadata-x.git
cd stadata-x
# Install dengan uv
uv sync --dev
uv run stadata-x --version
```
### Debug dan Logging
#### **Enable Verbose Output**
```bash
# Untuk pip
pip install stadata-x -v
# Untuk uv
uv pip install stadata-x --verbose
```
#### **Check System Information**
```bash
# Python version
python --version
# pip version
pip --version
# OS information
python -c "import platform; print(platform.platform())"
# Check installed packages
pip list | grep -E "(stadata|lxml|textual)"
```
### Masalah Runtime
#### **API Token Error**
```
ApiTokenError: Token API tidak diatur
```
**Solusi**:
1. Jalankan `stadata-x`
2. Tekan `s` untuk Settings
3. Masukkan Token API BPS Anda
4. Test koneksi dengan tombol "Tes Koneksi"
#### **Network/Connection Error**
```
NoInternetError: Tidak ada koneksi internet
```
**Solusi**:
- Check koneksi internet
- Coba lagi dalam beberapa saat (rate limiting)
- Gunakan VPN jika diperlukan
#### **Cache Issues**
```bash
# Clear cache
# Windows
rmdir /s %USERPROFILE%\.stadata-x
# Linux/Mac
rm -rf ~/.stadata-x
```
### Getting Help
Jika masalah berlanjut:
1. **Check GitHub Issues**: https://github.com/dzakwanalifi/stadata-x/issues
2. **Create New Issue**: Sertakan:
- Python version (`python --version`)
- OS information
- Full error traceback
- Installation method used
3. **Contact**: dzakwan624@gmail.com
## ⚡ Quick Start
1. **Konfigurasi Token API BPS**:
```bash
stadata-x
# Tekan 's' untuk masuk ke pengaturan
# Tempel token API BPS Anda
```
2. **Jelajahi Data**:
```bash
stadata-x
# Pilih wilayah → Pilih tabel → Lihat pratinjau → Unduh
```
## Konfigurasi Awal: API Key BPS
Untuk menggunakan aplikasi ini, Anda memerlukan Token API dari BPS. Token ini gratis dan berfungsi sebagai kunci untuk mengakses data.
#### Cara Mendapatkan Token API
1. **Kunjungi Portal WebAPI BPS**: Buka [webapi.bps.go.id/developer/](https://webapi.bps.go.id/developer/).
2. **Daftar/Masuk**: Buat akun baru atau masuk jika Anda sudah memilikinya.
3. **Salin Token**: Setelah masuk, salin Token API yang ditampilkan di dashboard Anda.
4. **Konfigurasi di `stadata-x`**:
- Jalankan aplikasi: `stadata-x`
- Tekan `s` untuk masuk ke menu Pengaturan.
- Tempel Token API Anda, lalu simpan.
- Gunakan tombol "Tes Koneksi" untuk memvalidasi token Anda.
## Penggunaan
Jalankan aplikasi dari terminal Anda:
```bash
stadata-x
```
### ⌨️ Navigasi Dasar
| Tombol | Fungsi |
|--------|--------|
| `↑/↓` atau `j/k` | Bergerak di dalam daftar |
| `Enter` | Pilih item (wilayah atau tabel) |
| `Escape` | Kembali ke level sebelumnya |
| `s` | Buka halaman Pengaturan |
| `d` | Buka dialog unduhan (saat di pratinjau tabel) |
| `q` | Keluar dari aplikasi |
### 📁 Struktur Proyek
```
stadata-x/
├── stadata_x/ # Kode aplikasi utama
│ ├── assets/ # CSS dan asset statis
│ ├── screens/ # Layar-layar aplikasi
│ ├── widgets/ # Komponen UI kustom
│ └── *.py # Modul utama
├── assets/ # Screenshot dan gambar dokumentasi
├── .gitignore # File yang diabaikan Git
├── LICENSE # Lisensi MIT
├── pyproject.toml # Konfigurasi proyek Python
└── README.md # Dokumentasi ini
```
## 🤝 Kontribusi
Kontribusi, laporan bug, dan permintaan fitur sangat kami hargai! 🎉
### Cara Berkontribusi
1. **Fork** repositori ini
2. **Buat branch** untuk fitur Anda (`git checkout -b feature/AmazingFeature`)
3. **Commit** perubahan Anda (`git commit -m 'Add some AmazingFeature'`)
4. **Push** ke branch (`git push origin feature/AmazingFeature`)
5. **Buka Pull Request**
### Pengembangan Lokal
Untuk pengembangan lokal, kloning repositori dan instal dependensi:
```bash
git clone https://github.com/dzakwanalifi/stadata-x.git
cd stadata-x
pip install -e ".[dev]"
```
Jalankan aplikasi dalam mode pengembangan dengan *hot-reloading*:
```bash
textual run --dev stadata_x/main.py
```
### Panduan Pengembangan
- Gunakan `ruff` untuk linting dan formatting
- Ikuti konvensi penamaan PEP 8
- Tambahkan docstring untuk fungsi baru
- Update dokumentasi jika diperlukan
## 🙏 Acknowledgments
- **Badan Pusat Statistik (BPS)** - Untuk menyediakan data publik yang berharga
- **[Textual](https://github.com/textualize/textual)** - Framework TUI yang powerful
- **[stadata](https://github.com/bps-statistics/stadata)** - Library Python resmi untuk API BPS
## 📞 Dukungan
Jika Anda mengalami masalah atau memiliki pertanyaan:
- 📧 **Email**: dzakwan624@gmail.com
- 🐛 **Issues**: [GitHub Issues](https://github.com/dzakwanalifi/stadata-x/issues)
- 📖 **Dokumentasi**: [README ini](README.md)
## 📄 Lisensi
Proyek ini dilisensikan di bawah [Lisensi MIT](LICENSE) - lihat file [LICENSE](LICENSE) untuk detail lebih lanjut.
---
**Dibuat dengan ❤️ untuk komunitas data Indonesia**
⭐ Jika Anda menyukai proyek ini, berikan bintang di GitHub!