# Python modülleri ve paketleri: import, pip, venv ve kütüphaneler sade anlatımla

URL: https://skillaria.top/tr/guides/python/python-moduller-ve-paketler

Python'da modül, uzantısı .py olan bir dosyadır; paket, modülleri içeren bir klasördür; kütüphane ise bir araya getirilmiş paket setidir ve import komutuyla çağrılır. Üçüncü taraf kütüphaneler pip (ya da uv) ile venv sanal ortamına kurulur; bu, farklı projelerin sürümlerinin birbirini bozmasını önler.

Python'da modül, içinde kod bulunan bir dosyadır; `import` ise o dosyadan fonksiyon ve sınıf almanın yoludur. Modüllerden paketler, paketlerden kütüphaneler oluşur. Üçüncü taraf kütüphaneleri farklı projelerin birbirini bozmaması için sanal ortam (venv) içine kurarsınız. Bu yazıda tüm zinciri ele alıyoruz: import sırasında neler olduğunu, paketin nasıl yapılandığını, pip ve venv'in nasıl çalıştığını ve Python 3.15'in tembel (lazy) importlarını.

## Modül, paket, kütüphane: farkları nedir

| Kavram | Nedir | Örnek |
| --- | --- | --- |

| Modül | Tek bir `.py` dosyası; modül adı dosya adının uzantısız hâli | `kategoriler.py` → `import kategoriler` |

| Paket | İçinde modüller ve `__init__.py` dosyası bulunan klasör | `harcamalar/rapor.py` → `from harcamalar.rapor import olustur` |

| Kütüphane | Belirli bir işe yönelik hazır modül ve paketler bütünü | `requests`, `pandas`, standart `pathlib` |

| Dağıtım (PyPI paketi) | pip'in kurduğu arşiv | `pip install requests` |

Günlük konuşmada "kütüphane", "paket" ve "modül" kelimeleri sıkça birbirinin yerine kullanılır; bu normaldir. Teknik olarak `import` her zaman bir modül ya da paketi yükler; pip ise PyPI'dan bir dağıtım kurar ve bu dağıtımın içinde paketler bulunur.

## Python'da import nasıl çalışır

Gerçek kodda birkaç import biçimi görürsünüz:

```
import math                    # tüm modül, math.sqrt şeklinde kullanılır
from math import sqrt, pi      # yalnızca belirli adlar
import datetime as dt          # takma ad
from collections import Counter as C

print(math.sqrt(16), sqrt(9), pi)
print(dt.date.today())
```

Büyük kütüphaneler için takma adlar yaygındır: `import numpy as np`, `import pandas as pd`. `from modul import *` yazımından kaçının: ad alanını kirletir ve bir adın nereden geldiğini gizler.

### import aslında ne yapar

1. Modülü `sys.modules` önbelleğinde arar. Zaten yüklüyse onu döndürür.
2. Yoksa `sys.path` listesindeki klasörlerde dosyayı arar: çalıştırılan betiğin klasörü, standart kütüphane ve ortamın site-packages klasörü.
3. Bulunan dosyayı baştan sona, yukarıdan aşağıya çalıştırır.
4. Modül nesnesini önbelleğe koyar ve bir adla ilişkilendirir.

Bundan iki pratik sonuç çıkar. Aynı modülü ikinci kez import etmek neredeyse bedavadır, kod yeniden çalıştırılmaz. Modülün en üst düzeyindeki her kod, `print` ve ağır hesaplamalar dahil, import sırasında çalışır.

```
import sys
for p in sys.path:
    print(p)
print("math" in sys.modules)
```

### if __name__ == "__main__"

İmport dosyayı çalıştırdığına göre, "betik olarak çalıştırıldım" ile "içe aktarıldım" durumlarını ayırt etmek gerekir. Bunun için `__name__` değişkeni vardır: dosya doğrudan çalıştırıldığında `"__main__"`, import edildiğinde modül adına eşittir.

```
# kategoriler.py
def tahmin_et(baslik: str) -> str:
    return "yiyecek" if "kafe" in baslik.lower() else "diğer"

if __name__ == "__main__":
    print(tahmin_et("Evin yanındaki kafe"))   # yalnızca python kategoriler.py ile çalışır
```

Paketler için alternatif, içine `__main__.py` dosyası koyup `python -m harcamalar` komutuyla çalıştırmaktır.

## Standart modüller

Python "pillerle birlikte" gelir: yüzlerce yerleşik modül kurulum gerektirmeden kullanılabilir. En yaygın olanlar:

| Modül | Kullanım alanı |
| --- | --- |

| `os`, `sys`, `pathlib`, `shutil` | Sistem, yollar, dosyalar |

| `json`, `csv`, `pickle` | Veri formatları |

| `datetime`, `time`, `calendar` | Tarih ve saat |

| `math`, `random`, `statistics`, `fractions` | Sayılar |

| `re`, `string` | Metinle çalışma |

| `collections`, `itertools`, `functools` | Veri yapıları ve yineleyiciler |

| `logging`, `argparse`, `subprocess` | Günlük, komut satırı argümanları, program çalıştırma |

| `asyncio`, `threading` | Asenkron programlama ve iş parçacıkları |

Standart kütüphanenin modül listesi Python 3.10'dan beri `sys.stdlib_module_names` içinde tutulur. Bir modülde neler olduğunu `dir(math)` ve `help(math)` ile görebilirsiniz.

## Kendi paketinizin yapısı

Modüller çoğaldığında bunları bir pakette toplarsınız. Yaygın düzen src-layout'tur:

```
harcama-projesi/
├── pyproject.toml
└── src/
    └── harcamalar/
        ├── __init__.py
        ├── cli.py
        ├── ayristirma.py
        ├── kategoriler.py
        └── rapor.py
```

Paket içindeki modüller birbirini ya paket adıyla (`from harcamalar.kategoriler import tahmin_et`) ya da göreli olarak (`from .kategoriler import tahmin_et`) import eder. Göreli import yalnızca paket içinde çalışır; dosya doğrudan betik olarak çalıştırılıyorsa çalışmaz.

## pip ile Python kütüphanesi kurmak

Üçüncü taraf kütüphaneler PyPI deposunda bulunur; bunları Python ile birlikte gelen pip aracı kurar. En güvenli yol, pip'i doğrudan interpreter üzerinden çağırmaktır: kütüphane kodu çalıştırdığınız Python'a kesin olarak kurulur.

```
python -m pip install requests          # kur
python -m pip install "pandas>=2.3"     # sürüm sınırıyla
python -m pip install --upgrade requests
python -m pip uninstall requests        # kaldır
python -m pip list                      # kurulu paketleri listele
python -m pip show requests             # sürüm ve bağımlılıklar
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
```

Windows'ta `python` yerine çoğunlukla `py` başlatıcısı kullanılır. pip bulunamazsa, onu Python'un kendi modülü kurar: `python -m ensurepip --upgrade`.

### Popüler Python kütüphaneleri

PyPI'de yüz binlerce paket var, ama çoğu projede aynı kısa liste görülür. Egzotik paketlere bakmadan önce bu listeden başlamak iyidir.

| Görev | Kütüphaneler |
| --- | --- |

| HTTP istekleri ve API'ler | `requests`, `httpx` |

| Veri analizi ve tablolar | `pandas`, `numpy` |

| Grafikler | `matplotlib` |

| Web servisleri | `fastapi`, `django`, `flask` |

| Testler | `pytest` |

| Görseller | `pillow` (`PIL` adıyla içe aktarılır) |

Dikkat: kurulacak ad ile içe aktarma adı her zaman aynı değildir. `pip install pillow` deyip `from PIL import Image` yazarsınız; `opencv-python` kurulur, ama `cv2` olarak içe aktarılır. Kurulumdan hemen sonra `import` hata veriyorsa, paketin belgelerinde içe aktarma adına bakın.

### Linux'ta kütüphane kurulumu

Yeni Debian ve Ubuntu sürümlerinde sistem Python'una `pip install` yapmaya çalışırsanız `externally-managed-environment` hatası alırsınız (PEP 668). Bu bir korumadır: sistem Python'u işletim sisteminin paket yöneticisine aittir ve pip'in onu bozmaması gerekir. Doğru çözüm `--break-system-packages` değil, bir sanal ortamdır.

## venv: sanal ortam

Sanal ortam, kendi Python bağlantısına ve kendi site-packages klasörüne sahip ayrı bir klasördür. İçine kurulan kütüphaneler yalnızca o projede görünür. Böylece bir projede Django 4, diğerinde Django 5 kullanabilirsiniz; ikisi çakışmaz.

`venv` modülü Python ile birlikte gelir, ayrıca kurmanız gerekmez (Debian/Ubuntu'da bazen `python3-venv` sistem paketi gerekir).

```
# .venv klasöründe ortam oluştur
python -m venv .venv

# etkinleştir: Linux ve macOS
source .venv/bin/activate
# etkinleştir: Windows PowerShell
.venv\Scripts\Activate.ps1

# artık pip paketleri .venv içine kurar
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# ortamdan çık
deactivate
```

Etkinleştirdikten sonra terminal satırının başında `(.venv)` belirir. Ortam klasörünü git'e eklemeyin (`.gitignore` dosyasına `.venv/` yazın) ve makineler arasında taşımayın; bunun yerine bağımlılık listesini saklayıp ortamı yeniden kurun. PowerShell etkinleştirme betiğini engelliyorsa, kullanıcı için izin verin: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.

### uv ve pyproject.toml

Modern projeler bağımlılıklarını `pyproject.toml` dosyasında tanımlar. Kursta kullanılan uv yöneticisi ortam oluşturmayı ve kurulumu birleştirir: `uv add pandas` paketi indirir, `pyproject.toml` dosyasına yazar ve kesin sürümleri `uv.lock` dosyasına kaydeder. Bir meslektaşınız projeyi klonlayıp `uv sync` çalıştırdığında birebir aynı ortamı elde eder.

```
[project]
name = "harcamalar"
version = "0.1.0"
requires-python = ">=3.15"
dependencies = [
    "pandas>=2.3",
]

[project.scripts]
harcamalar = "harcamalar.cli:main"
```

## Python 3.15'te tembel importlar (PEP 810)

Bu konudaki en önemli yenilik 3.15'teki `lazy` anahtar sözcüğüdür. Ağır kütüphaneler yüklenmesi uzun süren modüllerdir: kursun ölçümünde `python:3.15-slim` imajında sıradan `import pandas` yaklaşık 415 ms sürdü, `lazy import pandas` ise yaklaşık 13 ms. `--help` için çalıştırılan bir komut satırı aracında bu fark çok büyüktür.

```
lazy import pandas as pd
lazy from harcamalar.rapor import rapor_olustur

def main() -> None:
    ...
    df = pd.read_csv(path)   # pandas gerçekten yüklenir — yalnızca burada
```

Modül yerine ad, bir vekil nesneye (`types.LazyImportType`) bağlanır; gerçek import ilk kullanımda yapılır. O ada hiç dokunulmazsa zaman hiç harcanmaz.

### Tembel importların kısıtları

- Yalnızca modülün en üst düzeyinde kullanılabilir: fonksiyon, sınıf ya da `try/except` içinde yazılırsa `SyntaxError` alırsınız.
- `lazy from x import *` yasaktır.
- `ModuleNotFoundError` başlangıçta değil, adın ilk kullanımında ortaya çıkar.
- Modülün yan etkileri (eklenti kaydı vb.) zamanda kayar.

Tüm importları tembel yapmak için `-X lazy_imports=all` bayrağı ya da `PYTHON_LAZY_IMPORTS=all` ortam değişkeni kullanılabilir; istisnalar `sys.set_lazy_imports_filter()` ile belirlenir. Eski sürümlerde de çalışması gereken kod için modülde `__lazy_modules__ = ["pandas"]` tanımlanabilir: 3.15 bu importları tembel yapar, eski sürümler ise normal `import` yapar. Başlangıçta zamanın nereye gittiğini `python -X importtime -c "import pandas"` gösterir. En çok fayda, sık ve kısa süreli çalışan programlarda görülür; uzun süre çalışan bir sunucuda neredeyse hiçbir fark yaratmaz.

## Tipik hatalar

- `ModuleNotFoundError: No module named 'requests'` — kütüphane başka bir Python'a kurulmuş ya da ortam etkinleştirilmemiş. Aynı interpreter ile `python -m pip show requests` komutunu çalıştırın.
- Kendi dosyanız `json.py`, `random.py` ya da `csv.py` adını taşıyor — betik klasörü `sys.path` listesinde ilk sırada olduğundan standart modülün önüne geçer. Python 3.13+ hata mesajında "consider renaming" önerir. Dosyayı yeniden adlandırın ve `__pycache__` klasörünü silin.
- Döngüsel import: `a.py`, `b.py`'yi; `b.py` de `a.py`'yi import eder. Ortak kodu üçüncü bir modüle taşıyın ya da import'u fonksiyonun içine alın.
- pip, Python prompt'unun içinde çalıştırılmış (`>>> pip install`) — bu bir `SyntaxError` verir. pip komutları terminalde çalıştırılır.

## Özet

Modül bir dosya, paket bir modül klasörü, kütüphane ise bunların hazır bir setidir; `import` modülü önbellekte ve `sys.path` üzerinde arar ve bir kez çalıştırır. Üçüncü taraf kütüphaneleri yalnızca pip ya da uv ile venv sanal ortamına kurun: projeler birbirini bozmaz ve ortam kolayca yeniden oluşturulur. Kursta bu konu uygulamalı işlenir: harcama takipçisi bağımlılıkları olan bir pakete dönüşür ve tembel importlar sayesinde hızlı başlar.

## FAQ

**Her proje için ayrı venv oluşturmak zorunlu mu?**

Zorunlu değil, ama iyi bir alışkanlık: her projenin kütüphane sürümleri farklı olabilir; ayrı ortam çakışmaları önler ve sistem Python'unu kirletmez.

**pip ile uv arasındaki fark nedir?**

pip yalnızca paket kurar; uv ise ortam oluşturur, bağımlılıkları pyproject.toml dosyasına yazar ve kesin sürümleri kilit dosyasında tutar. Ayrıca belirgin biçimde daha hızlıdır.

**Kurulu Python kütüphanelerini nasıl listelerim?**

İlgili ortamda python -m pip list komutunu çalıştırın; pip freeze aynı listeyi requirements.txt biçiminde verir.

**Modüller nerede saklanır?**

Etkin ortamın site-packages klasöründe. Bir modülün yolunu __file__ özniteliği gösterir; örneğin import requests; print(requests.__file__).

**venv klasörünü başka bir bilgisayara taşıyabilir miyim?**

Hayır, ortam makinenin yollarına ve interpreter'ına bağlıdır. Bağımlılık listesini taşıyın ve ortamı yeniden oluşturun.


---
Source: Skillaria.Top (https://skillaria.top)