pyproject.toml Nedir? Python Projesinde Nasıl Kullanılır?

pyproject.toml, bir Python projesinin paketleme bilgilerini ve geliştirme araçlarına ait yapılandırmaları daha ortak bir dosya etrafında düzenlemeye yardımcı olur. Böylece proje adı, Python sürümü, bağımlılıklar, derleme yöntemi ve araç ayarları dağınık yapılandırma dosyaları yerine daha anlaşılır bir yapı içinde tutulabilir.

Ancak pyproject.toml, her projede requirements.txt, setup.py veya setup.cfg dosyalarının birebir yerine geçen tek bir dosya olarak düşünülmemelidir. Hangi dosyanın kullanılacağı, projenin yalnızca çalıştırılacak bir uygulama mı yoksa dağıtılabilir bir paket mi olduğuna ve kullanılan araçların beklentilerine göre değişir.

pyproject.toml hangi problemi çözer?

Python projelerinde zaman içinde farklı ihtiyaçlar için farklı dosyalar kullanılabildi. Paket adı ve sürümü bir dosyada, bağımlılıklar başka bir dosyada, kod biçimlendirme veya test aracı ayarları ise ayrı yapılandırma dosyalarında bulunabiliyordu. Bu yaklaşım çalışabilir; fakat yeni bir projeye katılan kişinin hangi bilginin nerede tutulduğunu anlamasını zorlaştırabilir.

pyproject.toml bu dağınıklığı azaltmak için proje yapılandırmasına ortak bir giriş noktası sunar. Dosya, TOML söz dizimiyle yazılır ve paketleme araçlarının yanı sıra linter, biçimlendirici, tür denetleyici veya test aracı gibi yardımcı araçlar için de yapılandırma alanı barındırabilir. Python Packaging User Guide, dosyada [build-system], [project] ve [tool] tablolarını ayrı görevlerle tanımlar; bu yapı PEP 518 ve PEP 621 gibi standartlaştırma çalışmalarıyla şekillenmiştir. ([packaging.python.org](https://packaging.python.org/specifications/declaring-project-metadata/?utm_source=openai))

Buradaki temel fayda yalnızca “daha az dosya kullanmak” değildir. Asıl fayda, bir Python projesinin nasıl kurulacağını, projenin kendisine ait bilgileri ve yardımcı araçların ayarlarını birbirinden ayırarak okunabilir bir düzen oluşturmaktır. Örneğin bir geliştirici projeyi başka bir bilgisayara taşıdığında şu soruların cevaplarını daha kolay bulabilir:

• Bu projenin adı ve sürümü nedir?
• Hangi Python sürümleriyle çalışması bekleniyor?
• Kurulum sırasında hangi bağımlılıklar gerekir?
• Projeyi paketlemek için hangi derleme yöntemi kullanılacak?
• Kod biçimlendirme, test veya tür kontrolü araçları nasıl yapılandırılmış?

Bu dosya özellikle paketlenebilir Python projelerinde önem kazanır. Bir kütüphaneyi dağıtmak, kaynak koddan kurulabilir paket üretmek veya proje metadata bilgilerini standart bir biçimde tanımlamak istediğinizde pyproject.toml, paketleme araçlarının okuyabileceği ortak bir yapı sağlar. Buna karşılık yalnızca tek dosyalık bir Python betiği yazıyorsanız bu dosyanın tüm bölümlerine ihtiyaç duymayabilirsiniz.

Python proje yapılandırmasına yeni başlayanlar, kavramları uygulamalı biçimde öğrenmek için video Python eğitimi üzerinden dosya düzeni, bağımlılık yönetimi ve proje geliştirme temellerini adım adım çalışabilir.

Dosyayı okurken üç temel görevi baştan ayırmak işleri kolaylaştırır:

1. build-system: Projenin hangi paketleme yöntemiyle oluşturulacağını ve bu işlem için hangi derleme bağımlılıklarının gerektiğini ifade eder.
2. project: Projenin ne olduğunu; adını, sürümünü, açıklamasını, desteklediği Python sürümlerini ve çalışma bağımlılıklarını tanımlar.
3. tool: Kullanılan geliştirme araçlarının kendi ayarlarını, araç adına ayrılmış alt tablolarda tutar.

build-system, project ve tool bölümleri ne işe yarar?

Bu üç bölüm aynı dosyada bulunsa da aynı işi yapmaz. Başlangıç seviyesinde en sık yapılan hata, örneğin project.dependencies alanının test aracını çalıştıracağını veya tool bölümünün paketleme yöntemini otomatik olarak belirleyeceğini düşünmektir. Her bölümün sorumluluğu farklıdır.

[build-system]: Paketleme yöntemini tanımlar

[build-system] tablosu, projenin paketlenmesi sırasında kullanılacak backend’i ve bu backend’in çalışması için kurulması gereken bağımlılıkları belirtir. build-backend, paketleme işlemini hangi backend modülünün yürüteceğini söyler. requires ise bu işlemin başlaması için gerekli paketleri listeleyen bir dizidir.

Buradaki bilgiler, projenin çalışma zamanındaki bağımlılıklarıyla aynı şey değildir. Örneğin bir uygulamanın çalışması için ihtiyaç duyduğu kütüphaneler [project] altında yer alırken, dağıtılabilir paket üretmek için gereken backend bağımlılığı [build-system] altında tanımlanır. Hangi backend’in seçileceği projenin yapısına ve tercih edilen paketleme iş akışına bağlıdır; belirli bir araç her proje için tek doğru seçenek değildir.

[project]: Projenin kimliğini ve çalışma gereksinimlerini tanımlar

[project] tablosu, dağıtılacak projenin temel metadata bilgilerini içerir. Güncel spesifikasyonda name alanı projenin adını belirtir ve statik olarak tanımlanması gereken temel alandır. version alanı doğrudan yazılabilir veya backend tarafından üretilecek şekilde dinamik bırakılabilir. Diğer alanların zorunlu ya da isteğe bağlı durumu, kullanılan metadata spesifikasyonuna ve projenin ihtiyaçlarına göre değerlendirilmelidir. ([packaging.python.org](https://packaging.python.org/en/latest/specifications/pyproject-toml/?highlight=optional-dependencies&utm_source=openai))

• name: Paketin veya projenin dağıtım adını belirtir.
• version: Yayınlanan sürümü ifade eder.
• description: Projenin kısa açıklamasını taşır.
• requires-python: Projenin desteklediği Python sürümlerini belirtir.
• dependencies: Projenin kurulması veya çalışması için gereken bağımlılıkları listeler.

project bölümü bağımlılıkları tanımlayabilir; fakat tek başına test komutunun nasıl çalıştırılacağını, linter kurallarını veya kod biçimlendirme tercihlerini belirlemez. Bunlar araçların kendi yapılandırma alanlarında tanımlanır.

[tool]: Geliştirme araçlarının ayarlarını tutar

[tool] tablosu, projede kullanılan araçların yapılandırmalarını aynı dosya içinde toplamaya yarar. Araçlar kendi adlarına ayrılmış alt tablolar kullanır. Genel biçim şu şekildedir:

[tool.arac-adi]
ayar = "deger"

Örneğin bir formatter, linter veya test aracının ayarları [tool.<araç-adı>] altında bulunabilir. Ancak alt tablo adları ve desteklenen alanlar araca göre değişir; bu nedenle her aracın güncel dokümantasyonundaki TOML yapılandırması kontrol edilmelidir. tool bölümü, aracı projeye kurmaz ve hangi komutun çalıştırılacağını otomatik olarak seçmez; yalnızca ilgili aracın okuyacağı tercihleri sağlar. ([packaging.python.org](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/?highlight=2023&utm_source=openai))

Küçük bir Python projesi için çalışır pyproject.toml örneği

pyproject.toml dosyasını anlamanın en kolay yolu, onu küçük bir src-layout proje içinde görmektir. Aşağıdaki yapı; paket kodunu, testleri ve proje yapılandırmasını birbirinden ayırır:

ornek-proje/
├── pyproject.toml
├── src/
│   └── ornek_paket/
│       └── __init__.py
└── tests/
    └── test_basic.py

Bu yerleşimde içe aktarılabilir Python paketi src/ornek_paket/ altında bulunur. Kök dizindeki yapılandırma dosyaları ise paketin içine karışmaz. src-layout, kaynak kodunun proje kökünden yanlışlıkla doğrudan içe aktarılmasını önlemeye yardımcı olan bir düzen olarak kullanılır. ([packaging.python.org](https://packaging.python.org/en/latest/tutorials/packaging-projects/?highlight=https&utm_source=openai))

Aşağıdaki örnekte Hatchling bir build backend olarak seçilmiştir. Bu seçim tek doğru değildir; aynı standart metadata yapısı, uygun yapılandırmayla farklı backend seçenekleriyle de kullanılabilir. project alanları proje metadata bilgisini, tool alanları ise belirli araçların ayarlarını taşır. ([packaging.python.org](https://packaging.python.org/en/latest/tutorials/packaging-projects/?highlight=https&utm_source=openai))

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "ornek-paket"
version = "0.1.0"
description = "Küçük bir Python örnek paketi"
requires-python = ">=3.10"
dependencies = ["requests>=2"]

[tool.ruff]
line-length = 88

[tool.pytest.ini_options]
testpaths = ["tests"]

1. [build-system], paket oluşturulurken kullanılacak backend’in hangi build bağımlılıklarıyla çalışacağını belirtir. hatchling backend’i hatchling.build adıyla çağrılır.
2. [project], paketin adı, sürümü, açıklaması ve desteklediği Python sürümü gibi temel metadata alanlarını içerir.
3. dependencies dizisi, proje kurulduğunda gerekli olacak çalışma bağımlılıklarını bildirir. Buradaki requests>=2 ifadesi, uygun bir Requests sürümünün kurulmasını ister.
4. [tool.ruff], Ruff linter’ının satır uzunluğu ayarını tanımlar. Ruff, proje kökünde bulunan pyproject.toml içindeki bu tabloyu yapılandırma kaynağı olarak kullanabilir. ([docs.astral.sh](https://docs.astral.sh/ruff/configuration/?utm_source=openai))
5. [tool.pytest.ini_options], pytest için INI tarzı ayarların TOML içindeki karşılığıdır. testpaths değeri, testlerin tests klasöründe aranacağını belirtir. ([docs.pytest.org](https://docs.pytest.org/en/stable/reference/customize.html?utm_source=openai))

TOML’de tablo başlıkları köşeli parantezlerle yazılır; metin değerleri tırnak içine alınır ve listeler köşeli parantez içinde virgülle ayrılır. Aynı tabloyu ikinci kez tanımlamak geçerli değildir. Bu nedenle [project] veya [tool.ruff] başlığını yeniden açmak yerine ilgili anahtarları mevcut bloğa eklemek gerekir. ([toml.io](https://toml.io/en/v1.0.0?utm_source=openai))

Örneğin bu dosya doğru konumdaysa project bölümünden proje metadata bilgisi ve bağımlılık bildirimi, build-system bölümünden paketleme altyapısı, tool tablolarından da geliştirici araçlarının ayarları okunur. Böylece her bilginin görevi ayrışır. Python temellerinizi uygulamalı olarak kontrol etmek için ücretsiz Python bilgi testi üzerinden mevcut seviyenizi görebilirsiniz.

Kurulum, test ve paketleme komutları hangi bölümü okur?

Komutların aynı dosyaya bakması, hepsinin aynı işi yaptığı anlamına gelmez. Kurulum ve paketleme akışları genellikle build backend ile proje metadata’sını birlikte kullanırken, test ve linter komutları kendi araç tablolarına odaklanır. Aşağıdaki ayrım, kullanılan frontend, backend, test aracı ve sürüme göre değişebilecek genel bir çalışma modelidir. ([pip.pypa.io](https://pip.pypa.io/en/stable/reference/build-system/?utm_source=openai))

Editable kurulumda pip, backend’in PEP 660 desteğini kullanır; bu nedenle yalnızca -e seçeneğine bakarak her backend’in aynı davranacağını varsaymayın. Kaynak kodu değişiklikleri çoğu zaman yeniden kurulum gerektirmeden görülebilir; ancak metadata değişikliklerinde yeniden kurulum gerekebilir. ([pip.pypa.io](https://pip.pypa.io/en/stable/reference/build-system/?utm_source=openai))

• Önce [project] içindeki ad, sürüm, Python aralığı ve bağımlılıkları kontrol edin.
• Sonra [build-system] backend’inin doğru yazıldığını doğrulayın.
• Ardından [tool] altındaki test ve linter ayarlarını inceleyin.
• En son kurulum, test ve paketleme komutlarının çıktısını karşılaştırın.

Başlangıç hataları ve requirements.txt ile birlikte kullanım

pyproject.toml kullanırken yapılan hataların çoğu, bilginin yanlış bölüme yazılmasından veya TOML söz diziminin gözden kaçırılmasından kaynaklanır. Sorunu çözmek için önce hatanın dosyanın hangi bölümünde oluştuğunu, ardından kullanılan aracın hangi yapılandırmayı okuduğunu kontrol etmek gerekir.

1. Yanlış TOML söz dizimi

Belirti: Dosya okunamıyor, yapılandırma geçersiz bulunuyor veya satır ve sütun bilgisi veren bir ayrıştırma hatası görülüyor.

Olası neden: Eksik tırnak, kapanmayan köşeli parantez, hatalı virgül kullanımı ya da anahtar-değer satırında eşittir işaretinin unutulmasıdır. TOML, Python sözlüğü gibi yazılmaz; söz dizimi kurallarına ayrı olarak uymak gerekir.

Düzeltme: Hata mesajındaki satıra gidin ve özellikle tırnakları, virgülleri, tablo başlıklarını ve iç içe alanları kontrol edin. Değişiklikleri küçük adımlarla yaparak dosyayı her düzenlemeden sonra yeniden doğrulamak, hatalı satırı bulmayı kolaylaştırır.

2. Aynı tabloyu iki kez tanımlama

Belirti: Aynı bölümün tekrar tanımlandığını veya bir anahtarın birden fazla kez kullanıldığını belirten bir hata alınır.

Olası neden: Örneğin iki ayrı yerde [project] ya da aynı [tool] alt tablosu yazılmıştır. TOML içinde aynı tabloyu farklı bölümlerde tekrar açmak, alanları birleştirmek anlamına gelmez.

Düzeltme: Aynı tabloya ait alanları tek başlık altında toplayın. Farklı araçların ayarlarını ise [tool.arac_adi] gibi birbirinden ayrılan alt bölümlerde tutun.

3. project ve tool alanlarını karıştırma

Belirti: Proje kurulumu çalışırken bazı ayarlar yok sayılır veya bir araç, kendisine ait yapılandırmayı bulamaz.

Olası neden: Paket adı ve bağımlılıklar gibi proje metadata’sı [project] yerine [tool] altında yazılmış ya da test ve linter ayarları proje metadata’sına eklenmiştir.

Düzeltme: Bilginin amacını sorun: Paketin kimliği ve kurulumu ile ilgili alanlar [project] bölümüne; belirli bir aracın çalışma biçimiyle ilgili ayarlar [tool] altına yazılmalıdır.

4. Bağımlılıkları yanlış biçimde yazma

Belirti: Proje kurulurken bağımlılık bulunamaz, sürüm koşulu kabul edilmez veya beklenmeyen bir paket yüklenir.

Olası neden: [project].dependencies alanında paket adları TOML dizisi yerine farklı bir biçimde yazılmıştır. Paket adı ile sürüm koşulunun yazımı da kullandığınız paketleme akışının beklediği biçimle uyumlu olmayabilir.

Düzeltme: Bağımlılıkları ayrı dizeler hâlinde tanımlayın, paket adlarını doğru yazın ve sürüm aralıklarını yalnızca gerçekten ihtiyaç varsa ekleyin. Kurulumdan sonra temiz bir sanal ortamda deneme yapmak, eksik veya hatalı bağımlılıkları ortaya çıkarır.

5. İhtiyaç olmayan metadata alanlarını ekleme

Belirti: Dosya gereksiz yere büyür, bir alanın ne işe yaradığı belirsizleşir veya paketleme sırasında doğrulama sorunları oluşur.

Olası neden: Başka bir projenin şablonundaki tüm alanlar, kendi projenizin ihtiyacı olup olmadığı incelenmeden kopyalanmıştır.

Düzeltme: Küçük bir projede önce proje adı, sürüm bilgisi, açıklama, gerekli bağımlılıklar ve kullanılan paketleme akışı için gereken temel alanlarla başlayın. Bir alanı eklemeden önce şu soruyu sorun: Bu bilgi paket metadata’sı mı, araç ayarı mı, ortam kurulumu mu?

requirements.txt ile pyproject.toml birbirinin zorunlu alternatifi değildir. pyproject.toml proje metadata’sını, paketleme ayarlarını ve uygun araç yapılandırmalarını taşıyabilir. requirements.txt ise belirli bir çalışma ortamında kurulacak bağımlılıkların listesi veya ekipte kullanılan ayrı bir bağımlılık akışı için tercih edilebilir. Hangi dosyanın kullanılacağı; projenin paketlenip paketlenmediğine, dağıtım biçimine ve kullanılan araçlara göre değişir. Python temellerini daha planlı ve adım adım geliştirmek isteyenler, birebir Python dersleri kapsamında bu dosyaları kendi projeleri üzerinde çalışabilir.

Sık Sorulan Sorular

pyproject.toml ile requirements.txt aynı Python projesinde birlikte kullanılabilir mi?

Evet. pyproject.toml proje metadata’sı, paketleme bilgileri ve araç ayarları için; requirements.txt ise belirli bir ortamın kurulumu için kullanılabilir. Ancak aynı bağımlılıkların iki dosyada farklı sürüm koşullarıyla tekrar edilmesi tutarsızlık oluşturabileceğinden proje ekibi tek ve açık bir sorumluluk paylaşımı belirlemelidir.

build-system ile project bölümleri arasındaki temel fark nedir?

build-system, projenin nasıl paketleneceğini ve bu işlem için hangi derleme altyapısının gerektiğini belirtir. project ise paketin adı, sürümü, açıklaması ve bağımlılıkları gibi projenin kimliğini ve dağıtım metadata’sını tanımlar.

Linter ve test ayarları neden pyproject.toml içindeki tool bölümünde tutulur?

Bu ayarlar doğrudan paketin kimliğini değil, belirli bir geliştirme aracının nasıl çalışacağını açıklar. tool bölümü, farklı araçların ayarlarını aynı proje yapılandırması içinde düzenli biçimde ayırmaya yardımcı olur.

Küçük bir projede pyproject.toml dosyasına hangi alanları eklemek yeterlidir?

Genellikle kullanılan paketleme akışının gerektirdiği build-system bilgisi, project bölümündeki temel metadata ve gerçekten kullanılan araçların tool ayarları yeterlidir. İhtiyaç duyulmayan alanları eklemek yerine dosyayı projenin gerçek gereksinimleriyle sınırlı tutmak daha anlaşılır bir başlangıç sağlar.

İyi yapılandırılmış bir pyproject.toml dosyası, projenin kimliğini, kurulumu ve geliştirme araçlarını anlaşılır biçimde ayırır; requirements.txt ise ihtiyaç duyulan ortama göre bağımlılık kurulumunu destekler.