Python Poetry: Manajemen Dependency

1. Pengenalan Poetry

Poetry adalah tool manajemen dependency dan packaging untuk Python yang modern, all-in-one. Poetry menggabungkan fungsi pip, virtualenv, pip-tools, dan setuptools dalam satu solusi yang terintegrasi. Dirilis pertama kali oleh Sébastien Eustace pada tahun 2018, Poetry kini menjadi standar de facto untuk proyek Python modern.

Dengan Poetry, Anda tidak perlu lagi memisahkan antara requirements.txt dan setup.py. Semua dikonfigurasi dalam satu file pyproject.toml yang mengikuti standar PEP 517 dan PEP 518.

Mengapa Menggunakan Poetry?

┌─────────────────────────────────────────────────────────────┐
│              WORKFLOW: pip vs Poetry                         │
│                                                             │
│  pip + venv (tradisional):                                  │
│  ┌─────────┐   ┌──────────┐   ┌───────────┐   ┌────────┐  │
│  │ python   │──▶│ pip      │──▶│ requirements│──▶│ manual │  │
│  │ -m venv  │   │ install  │   │ .txt       │   │ resolve│  │
│  └─────────┘   └──────────┘   └───────────┘   └────────┘  │
│                                                             │
│  Poetry (modern):                                           │
│  ┌──────────┐   ┌───────────┐   ┌──────────┐   ┌────────┐ │
│  │ poetry   │──▶│ pyproject │──▶│ poetry   │──▶│ auto   │ │
│  │ init     │   │ .toml     │   │ lock     │   │ resolve│ │
│  └──────────┘   └───────────┘   └──────────┘   └────────┘ │
└─────────────────────────────────────────────────────────────┘

2. Instalasi Poetry

Ada beberapa cara untuk menginstal Poetry di sistem Anda. Cara yang paling direkomendasikan adalah menggunakan installer resmi mereka.

Instalasi di Linux / macOS

# Instalasi menggunakan installer resmi
curl -sSL https://install.python-poetry.org | python3 -

# Verifikasi instalasi
poetry --version

# Output: Poetry (version 1.8.x)

# Jika ingin menginstal versi terbaru
curl -sSL https://install.python-poetry.org | python3 - --version 1.8.3

Instalasi di Windows

# Menggunakan PowerShell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -

# Atau menggunakan pip (metode alternatif)
pip install poetry

# Verifikasi
poetry --version

Instalasi via pipx (Direkomendasikan)

# Install pipx terlebih dahulu jika belum ada
pip install pipx

# Install Poetry terisolasi menggunakan pipx
pipx install poetry

# Update Poetry
pipx upgrade poetry

Konfigurasi PATH

Setelah instalasi, pastikan direktori bin Poetry sudah ada di PATH sistem Anda. Untuk Linux/macOS, tambahkan baris berikut ke ~/.bashrc atau ~/.zshrc:

# Tambahkan ke ~/.bashrc atau ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

# Reload shell
source ~/.bashrc

3. Membuat Proyek Baru

Poetry menyediakan dua cara utama untuk memulai proyek baru: menggunakan poetry new untuk proyek baru atau poetry init untuk proyek yang sudah ada.

Membuat Proyek Baru dengan poetry new

# Membuat proyek baru dengan struktur direktori
poetry new my-awesome-project

# Struktur yang dihasilkan:
# my-awesome-project/
# ├── pyproject.toml
# ├── README.md
# ├── my_awesome_project/
# │   └── __init__.py
# └── tests/
#     └── __init__.py

# Dengan struktur src/
poetry new my-project --name my_package --src

# Struktur yang dihasilkan:
# my-project/
# ├── pyproject.toml
# ├── README.md
# ├── src/
# │   └── my_package/
# │       └── __init__.py
# └── tests/
#     └── __init__.py

Inisialisasi Proyek yang Sudah Ada

# Masuk ke direktori proyek yang sudah ada
cd existing-project

# Inisialisasi Poetry (akan menanya beberapa konfigurasi)
poetry init

# Jawab pertanyaan yang muncul:
# Package name [existing-project]: my-api-server
# Version [0.1.0]:
# Description []:
# Author [Your Name , n to skip]:
# License []:
# Compatible Python versions [^3.11]:
# Would you like to define your main dependencies interactively? (yes/no) [yes]
# Would you like to define your development dependencies interactively? (yes/no) [yes]

4. Memahami pyproject.toml

File pyproject.toml adalah jantung dari setiap proyek Poetry. File ini mengikuti standar PEP 518 dan berisi semua konfigurasi proyek Anda dalam format TOML (Tom's Obvious, Minimal Language).

Struktur Lengkap pyproject.toml

[tool.poetry]
name = "my-awesome-project"
version = "0.1.0"
description = "Deskripsi singkat proyek Anda"
authors = ["Nama Anda <email@domain.com>"]
license = "MIT"
readme = "README.md"
homepage = "https://myproject.com"
repository = "https://github.com/username/my-awesome-project"
documentation = "https://myproject.com/docs"
keywords = ["api", "web", "async"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
]

# Struktur package (src layout)
packages = [{include = "my_awesome_project", from = "src"}]

# Python version yang didukung
python = "^3.11"

# Dependency utama
[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.104.0"
uvicorn = {version = "^0.24.0", extras = ["standard"]}
pydantic = "^2.5.0"
sqlalchemy = "^2.0.23"
httpx = "^0.25.0"

# Dependency untuk development
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
pytest-cov = "^4.1.0"
black = "^23.10.0"
ruff = "^0.1.6"
mypy = "^1.7.0"
pre-commit = "^3.6.0"

# Dependency opsional (contoh: untuk docs)
[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "^1.5.0"
mkdocs-material = "^9.4.0"

# Build system
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

# Konfigurasi tools tambahan
[tool.black]
line-length = 88
target-version = ['py311']

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N", "UP", "B"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=my_awesome_project"

[tool.mypy]
python_version = "3.11"
strict = true

Sintaks Versi Dependency

5. Mengelola Dependency

Poetry menyediakan berbagai perintah untuk menambahkan, menghapus, dan memperbarui dependency proyek Anda dengan mudah.

Menambahkan Dependency

# Menambahkan dependency utama
poetry add requests
poetry add fastapi uvicorn[standard]
poetry add sqlalchemy[asyncio]

# Menambahkan dengan versi spesifik
poetry add "django>=4.2,<5.0"
poetry add "celery~=5.3"

# Menambahkan dependency dari Git repository
poetry add git+https://github.com/user/repo.git

# Menambahkan dari branch tertentu
poetry add git+https://github.com/user/repo.git#branch-name

# Menambahkan dari tag
poetry add git+https://github.com/user/repo.git#v1.2.0

# Menambahkan dependency development
poetry add --group dev pytest
poetry add --group dev black ruff mypy

# Menambahkan dependency optional
poetry add --group docs mkdocs

# Menambahkan dependency yang tidak di-cache (tidak meng-update lock)
poetry add --no-update requests

# Menambahkan dengan extras
poetry add "requests[security,socks]"

Menghapus Dependency

# Menghapus dependency utama
poetry remove requests

# Menghapus dependency development
poetry remove --group dev pytest-cov

# Menghapus dependency dari grup tertentu
poetry remove --group docs mkdocs-material

Memperbarui Dependency

# Memperbarui semua dependency sesuai constraint di pyproject.toml
poetry update

# Memperbarui dependency spesifik
poetry update requests fastapi

# Memperbarui semua dependency ke versi terbaru (mengubah pyproject.toml)
poetry add --latest requests

# Menampilkan dependency yang bisa di-update
poetry show --outdated

# Output:
#  package    current  latest   type    update
# ────────────────────────────────────────────
#  requests   2.31.0   2.32.0   major   update
#  fastapi    0.104.0  0.104.1  patch   update

# Dry run (lihat apa yang akan di-update tanpa mengubah)
poetry update --dry-run

Menampilkan Dependency

# Menampilkan semua dependency (dari lock file)
poetry show

# Menampilkan dependency dengan detail
poetry show --tree

# Output:
#  my-awesome-project 0.1.0 my-awesome-project
# ├── fastapi ^0.104.0
# │   ├── pydantic >=1.6.2,<3.0.0
# │   └── starlette 0.27.0
# └── requests ^2.31.0
#     ├── certifi >=2017.4.17
#     └── urllib3 >=1.21.1,<3

# Menampilkan hanya package tertentu
poetry show requests

# Menampilkan hanya package yang outdated
poetry show --outdated

# Menampilkan dependency tree untuk grup tertentu
poetry show --tree --without dev

Debugging Dependency

# Melihat dependency dari pyproject.toml (bukan lock file)
poetry show --top-level

# Mengecek apakah lock file konsisten dengan pyproject.toml
poetry check

# Output:
# All set! pyproject.toml is valid and poetry.lock is consistent.

# Menampilkan path ke virtual environment
poetry env info --path

# Menampilkan info environment
poetry env info

6. Virtual Environment

Poetry secara otomatis membuat dan mengelola virtual environment untuk setiap proyek. Anda tidak perlu lagi membuat venv secara manual.

Perintah Virtual Environment

# Membuat virtual environment secara manual
poetry env use python3.11

# Menggunakan python spesifik
poetry env use /usr/bin/python3.12

# Menampilkan semua virtual environment yang ada
poetry env list

# Output:
#   my-project-py3.11 (Activated)
#   my-project-py3.10

# Menghapus virtual environment
poetry env remove my-project-py3.11
poetry env remove --all

# Mengaktifkan virtual environment di shell
poetry shell

# Menjalankan perintah di dalam virtual environment
poetry run python --version
poetry run pytest
poetry run black --check src/

# Menjalankan script
poetry run python src/main.py
poetry run python -m my_module

Konfigurasi Virtual Environment

# Tambahkan di pyproject.toml untuk mengontrol perilaku venv

[tool.poetry.virtualenvs]
create = true             # Buat venv otomatis (default: true)
in-project = true         # Buat venv di dalam proyek (.venv/)
prefer-active-python = true  # Gunakan Python aktif di shell

Menggunakan poetry shell vs poetry run

7. Lock File & Reproducibility

File poetry.lock adalah kunci dari reproducibility dalam manajemen dependency. Lock file berisi versi tepat dari semua dependency (termasuk dependency transitive) yang sudah di-resolve oleh Poetry.

Mengapa Lock File Penting?

# Saat pertama kali install dependency
poetry install

# Poetry akan:
# 1. Membaca pyproject.toml
# 2. Resolve semua dependency (termasuk yang transitive)
# 3. Menulis versi tepat ke poetry.lock
# 4. Install semua paket sesuai versi di lock file

# Saat developer lain clone proyek dan menjalankan:
poetry install

# Mereka akan mendapat versi PERSIS SAMA dengan yang Anda gunakan
# Karena poetry.lock sudah terenkripsi versi tepat

Apa yang Ada di poetry.lock?

# Contoh isi poetry.lock (simplified)

[[package]]
name = "requests"
version = "2.31.0"
description = "Python HTTP for Humans."
optional = false
python-versions = ">=3.7"
files = [
    {file = "requests-2.31.0-py3-none-any.whl", hash = "sha256:..."},
    {file = "requests-2.31.0.tar.gz", hash = "sha256:..."},
]

[package.dependencies]
certifi = ">=2017.4.17"
charset-normalizer = "<4,>=2"
idna = ">=2.5,<4"
urllib3 = ">=1.21.1,<3"

[package.extras]
socks = ["PySocks (>=1.5.6,<2.0.0)"]
use-chardet-on-py3 = ["chardet (>=3.0.2,<6)"]

Mengelola Lock File

# Update lock file tanpa install
poetry lock

# Update lock file DAN install
poetry update

# Update lock file untuk dependency spesifik
poetry lock --no-update  # Kunci semua versi saat ini

# Cek apakah lock file konsisten dengan pyproject.toml
poetry check

# Import dependency dari requirements.txt ke pyproject.toml
poetry add $(cat requirements.txt)

# Export lock file ke requirements.txt format
poetry export -f requirements.txt --output requirements.txt
poetry export -f requirements.txt --output requirements-dev.txt --with dev

8. Script & Command

Poetry memungkinkan Anda mendefinisikan custom script di pyproject.toml, mirip dengan npm scripts di Node.js.

Mendefinisikan Script

# Tambahkan di pyproject.toml
[tool.poetry.scripts]
# Script yang akan terinstall saat paket di-install
serve = "my_app.cli:run_server"
migrate = "my_app.cli:migrate"
celery-worker = "my_app.celery:worker_start"

Contoh Script CLI

# my_app/cli.py
"""CLI entry points untuk aplikasi."""
import argparse
import uvicorn


def run_server():
    """Menjalankan server FastAPI."""
    parser = argparse.ArgumentParser(description="Run the API server")
    parser.add_argument("--host", default="127.0.0.1")
    parser.add_argument("--port", type=int, default=8000)
    parser.add_argument("--reload", action="store_true")
    args = parser.parse_args()

    print(f"🚀 Starting server at http://{args.host}:{args.port}")
    uvicorn.run(
        "my_app.main:app",
        host=args.host,
        port=args.port,
        reload=args.reload,
    )


def migrate():
    """Menjalankan database migration."""
    print("📦 Running database migrations...")
    # Kode migrasi di sini
    print("✅ Migration complete!")


# Untuk menjalankan script
# poetry run serve --host 0.0.0.0 --port 8000 --reload
# poetry run migrate

Makefile Integration

# Makefile - wrapper untuk perintah Poetry
.PHONY: install test lint format serve clean

install:
	poetry install

test:
	poetry run pytest tests/ -v --cov=src/

test-cov:
	poetry run pytest tests/ -v --cov=src/ --cov-report=html
	poetry run python -m webbrowser htmlcov/index.html

lint:
	poetry run ruff check src/ tests/
	poetry run mypy src/

format:
	poetry run black src/ tests/
	poetry run ruff format src/ tests/

serve:
	poetry run serve --reload

clean:
	poetry env remove --all
	rm -rf .pytest_cache htmlcov .mypy_cache dist build *.egg-info
	find . -type d -name __pycache__ -exec rm -rf {} +

build:
	poetry build

publish-test:
	poetry publish --build --repository testpypi

publish:
	poetry publish --build

9. Build & Publish ke PyPI

Poetry memudahkan proses build dan publish paket Python ke PyPI atau repository private.

Build Paket

# Build paket (menghasilkan .whl dan .tar.gz)
poetry build

# Output:
# Building my-awesome-project (0.1.0)
#   - Building sdist
#   - Built my-awesome-project-0.1.0.tar.gz
#   - Building wheel
#   - Built my-awesome_project-0.1.0-py3-none-any.whl

# File hasil build ada di direktori dist/
ls dist/
# my-awesome_project-0.1.0-py3-none-any.whl
# my-awesome-project-0.1.0.tar.gz

Konfigurasi PyPI

# Mengatur kredensial PyPI (akan disimpan di keyring)
poetry config pypi-token.pypi your-api-token-here

# Mengatur repository test PyPI
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry config pypi-token.testpypi your-testpypi-token-here

# Cek konfigurasi
poetry config --list

# Output:
# cache-dir = "/home/user/.cache/pypoetry"
# virtualenvs.create = true
# virtualenvs.in-project = false
# pypi-token.pypi = "pypi-***"

Publish

# Publish ke PyPI (production)
poetry publish --build

# Publish ke Test PyPI (untuk testing)
poetry publish --build --repository testpypi

# Publish tanpa build (jika sudah build sebelumnya)
poetry publish

# Publish dengan credential tertentu
poetry publish --build --username __token__ --password pypi-your-token

Proses Publish Lengkap

# Langkah lengkap dari awal hingga publish

# 1. Update versi
poetry version 0.2.0
# Atau increment otomatis
poetry version patch   # 0.1.0 → 0.1.1
poetry version minor   # 0.1.0 → 0.2.0
poetry version major   # 0.1.0 → 1.0.0

# 2. Jalankan test
poetry run pytest

# 3. Build
poetry build

# 4. Test install dari file local
pip install dist/my_awesome_project-0.2.0-py3-none-any.whl

# 5. Publish
poetry publish

10. Best Practice

Struktur Proyek yang Direkomendasikan

my-project/
├── pyproject.toml          # Konfigurasi utama
├── poetry.lock             # Lock file (di-commit)
├── README.md               # Dokumentasi
├── LICENSE                  # Lisensi
├── .gitignore              # Git ignore
├── .python-version         # Python version untuk pyenv
├── src/                    # Source code (src layout)
│   └── my_package/
│       ├── __init__.py
│       ├── main.py
│       ├── config.py
│       ├── models/
│       │   ├── __init__.py
│       │   └── user.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── routes.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_main.py
│   └── test_api/
│       ├── __init__.py
│       └── test_routes.py
├── docs/
│   └── index.md
└── .github/
    └── workflows/
        └── ci.yml

CI/CD dengan Poetry

# .github/workflows/ci.yml
name: CI/CD Pipeline

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install Poetry
        uses: snok/install-poetry@v1
        with:
          virtualenvs-create: true
          virtualenvs-in-project: true

      - name: Load cached venv
        id: cached-poetry-dependencies
        uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}

      - name: Install dependencies
        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
        run: poetry install --no-interaction --no-root

      - name: Run linters
        run: |
          poetry run ruff check src/ tests/
          poetry run mypy src/

      - name: Run tests
        run: poetry run pytest --cov=src --cov-report=xml

      - name: Upload coverage
        uses: codecov/codecov-action@v3

  publish:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - name: Install Poetry
        uses: snok/install-poetry@v1

      - name: Build and Publish
        env:
          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
        run: |
          poetry version patch
          poetry build
          poetry publish

.gitignore untuk Proyek Poetry

# Python
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
dist/
build/
.eggs/

# Virtual Environment
.venv/
venv/
env/

# Poetry
# JANGAN ignore poetry.lock!

# IDE
.vscode/
.idea/
*.swp
*.swo

# Testing
.pytest_cache/
htmlcov/
.coverage
coverage.xml

# MyPy
.mypy_cache/

# Ruff
.ruff_cache/

# OS
.DS_Store
Thumbs.db

11. Migrasi dari pip & venv

Jika proyek Anda masih menggunakan pip + requirements.txt, berikut panduan migrasi ke Poetry.

Langkah Migrasi

# 1. Install Poetry
pip install poetry

# 2. Masuk ke direktori proyek
cd my-existing-project

# 3. Inisialisasi Poetry
poetry init

# 4. Import dependency dari requirements.txt
# Eksekusi perintah berikut untuk menambahkan semua dependency
poetry add $(cat requirements.txt | tr '\n' ' ')

# 5. Jika ada requirements-dev.txt
poetry add --group dev $(cat requirements-dev.txt | tr '\n' ' ')

# 6. Hapus file lama
rm requirements.txt
rm requirements-dev.txt
rm setup.py
rm setup.cfg

# 7. Verifikasi
poetry check
poetry install
poetry run pytest

# 8. Commit file baru
git add pyproject.toml poetry.lock
git commit -m "chore: migrate to Poetry"

Migrasi yang Lebih Terstruktur

# Buat script migrasi
cat > migrate_to_poetry.sh <<'EOF'
#!/bin/bash
set -e

echo "🚀 Memulai migrasi ke Poetry..."

# Backup
cp requirements.txt requirements.txt.bak 2>/dev/null || true

# Init
poetry init --no-interaction

# Tambahkan semua dependency dari requirements.txt
while IFS= read -r line; do
    # Skip comment dan baris kosong
    [[ "$line" =~ ^#.*$ ]] && continue
    [[ -z "$line" ]] && continue
    # Skip -r dan -e flags
    [[ "$line" =~ ^-[re] ]] && continue

    echo "📦 Adding: $line"
    poetry add "$line" 2>/dev/null || echo "⚠️ Gagal menambahkan: $line"
done < requirements.txt

echo "✅ Migrasi selesai!"
echo "📋 Jangan lupa untuk:"
echo "   1. Cek pyproject.toml"
echo "   2. Jalankan poetry install"
echo "   3. Jalankan poetry run pytest"
EOF

chmod +x migrate_to_poetry.sh

12. Quiz Pemahaman

Uji pemahaman Anda tentang Python Poetry dengan quiz berikut: