Python Project Structure: venv, pip, Requirements, dan Testing

Script satu file bagus untuk mulai belajar. Tapi setelah kode mulai punya beberapa function, module, file data, dependency, dan test, kamu butuh struktur project yang lebih rapi.

Struktur project bukan soal terlihat profesional saja. Struktur yang jelas membuat project mudah dijalankan ulang, mudah dibaca orang lain, dan lebih aman saat dependency bertambah.

Anggap struktur sebagai peta kerja. Source code punya tempat sendiri, test punya tempat sendiri, dependency tercatat, dan README menjelaskan command yang perlu dijalankan. Dengan pembagian ini, orang lain tidak perlu menebak file mana yang harus dibuka lebih dulu.

Struktur folder sederhana

Untuk project kecil, gunakan struktur seperti ini:

expense-tracker/
  src/
    expense_tracker/
      __init__.py
      app.py
      storage.py
  tests/
    test_app.py
  requirements.txt
  README.md

Folder src/expense_tracker/ berisi source code utama. Folder tests/ berisi test. requirements.txt mencatat dependency. README.md menjelaskan cara menjalankan project.

Kamu tidak harus selalu memakai struktur ini untuk latihan kecil, tapi ini pola yang bagus saat project mulai lebih serius.

Membuat virtual environment

Virtual environment memisahkan dependency project dari instalasi Python global. Ini penting agar satu project tidak merusak project lain.

Virtual environment bukan Python versi baru. Ia adalah ruang kerja terisolasi yang memiliki lokasi package dan executable sendiri, sehingga pytest atau package lain untuk project ini tidak tercampur dengan project berbeda.

python -m venv .venv

Aktifkan di macOS atau Linux:

source .venv/bin/activate

Aktifkan di Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Setelah aktif, biasanya terminal menampilkan (.venv) di awal prompt.

Install package dengan pip

Gunakan pip untuk menginstall package.

pip install pytest

Untuk melihat package yang terpasang:

pip list

Hindari menginstall dependency project ke Python global. Biasakan aktifkan .venv dulu.

requirements.txt

Setelah dependency terpasang, simpan daftarnya:

pip freeze > requirements.txt

Orang lain bisa menginstall dependency yang sama dengan:

pip install -r requirements.txt

Untuk project pemula, requirements.txt sudah cukup. Nanti saat masuk packaging yang lebih modern, kamu bisa belajar pyproject.toml.

.env dan konfigurasi

File .env biasanya dipakai untuk konfigurasi yang berbeda antar environment, seperti API key, database URL, atau mode aplikasi.

Contoh .env:

APP_ENV=development
DATA_FILE=expenses.json

Jangan commit secret asli ke repository. Untuk project latihan, kamu bisa membuat .env.example agar orang lain tahu variable apa yang dibutuhkan.

Memisahkan source code dan test

Misalnya di src/expense_tracker/app.py:

# File: app-total.py
def calculate_total(expenses):
    return sum(expense["amount"] for expense in expenses)

Lalu di tests/test_app.py:

# File: test_app.py
from expense_tracker.app import calculate_total

def test_calculate_total():
    expenses = [
        {"title": "Coffee", "amount": 25_000},
        {"title": "Lunch", "amount": 50_000},
    ]

    assert calculate_total(expenses) == 75_000

Test membantu memastikan logic penting tetap benar saat kamu mengubah kode.

Mulailah dari test untuk perilaku yang paling penting. Test normal memastikan alur utama berjalan, sedangkan test kosong atau invalid memastikan batas program dipahami. Nama test sebaiknya menjelaskan perilaku, bukan detail implementasi, supaya tetap relevan saat kode di dalamnya berubah.

Menjalankan pytest

Install pytest:

pip install pytest

Jalankan test:

pytest

Jika memakai struktur src/, kadang kamu perlu menginstall project dalam mode editable atau mengatur PYTHONPATH. Untuk project pemula, cara paling sederhana adalah menjalankan command dari root project dan memastikan nama package bisa diimport.

Entry point sederhana

Gunakan function main() agar file utama tetap rapi.

# File: main.py
def main():
    print("Expense tracker")

if __name__ == "__main__":
    main()

Pola ini membuat file bisa dijalankan langsung, tapi tetap aman di-import dari test atau module lain.

Contoh mini structure

src/expense_tracker/app.py:

# File: app-helpers.py
def calculate_total(expenses):
    return sum(expense["amount"] for expense in expenses)

def format_currency(amount):
    return f"IDR {amount:,}".replace(",", ".")

src/expense_tracker/storage.py:

# File: storage.py
import json
from pathlib import Path

def load_expenses(path):
    file_path = Path(path)

    if not file_path.exists():
        return []

    with file_path.open("r", encoding="utf-8") as file:
        return json.load(file)

src/expense_tracker/main.py:

# File: main-report.py
from expense_tracker.app import calculate_total, format_currency
from expense_tracker.storage import load_expenses

def main():
    expenses = load_expenses("expenses.json")
    total = calculate_total(expenses)
    print(format_currency(total))

if __name__ == "__main__":
    main()

Struktur ini kecil, tapi sudah punya batas yang jelas: app.py untuk logic, storage.py untuk file, dan main.py untuk alur program.

Kesalahan umum

Kesalahan pertama adalah commit folder .venv. Tambahkan .venv/ ke .gitignore.

Kesalahan kedua adalah lupa mencatat dependency. Kalau project butuh pytest, requests, atau package lain, pastikan masuk ke requirements.txt.

Kesalahan ketiga adalah semua logic diletakkan di main.py. Untuk awal tidak masalah, tapi segera pecah saat file mulai terlalu panjang.

Kesalahan keempat adalah test hanya ditulis setelah project rusak. Mulai dari test kecil untuk function yang paling penting.

Checklist project Python kecil

Sebelum membagikan project, cek:

• Project punya README.md.
• Dependency tercatat di requirements.txt.
• .venv/ tidak ikut commit.
• Ada folder src/ atau package yang jelas.
• Ada folder tests/.
• Command menjalankan project ditulis di README.
• Logic penting punya minimal satu test.

Latihan mini

Buat project expense-tracker dengan:

• Virtual environment .venv.
• Package expense_tracker.
• Function calculate_total(expenses).
• Function format_currency(amount).
• Test untuk kedua function.
• README.md berisi cara install dan menjalankan test.

Checklist sebelum lanjut

Coba clone atau salin project ke folder lain lalu ikuti README dari awal. Jika project hanya berjalan karena setting terminal pribadi, dokumentasinya belum cukup. Pastikan command aktivasi environment, instal dependency, dan menjalankan test tertulis jelas.

Sebelum lanjut ke mini project, hapus satu dependency yang tidak dipakai dan jalankan test lagi. Latihan ini membantu memahami bahwa requirements.txt adalah deklarasi kebutuhan project, bukan daftar semua package yang pernah terpasang di komputer.

Lanjut ke mini project CLI

Sekarang semua potongan sudah siap: basic syntax, function, file, error handling, module, OOP, struktur project, dan test. Di artikel terakhir seri ini, kita akan menggabungkannya menjadi aplikasi CLI expense tracker. Lanjut ke Mini Project Python: Build CLI Expense Tracker dari Nol.

Kalau ingin mengulang OOP, buka Object-Oriented Python untuk Pemula.