ADR-014: Python Environment And Dependency Lock

• Status: Accepted
• Date: 2026-08-18
• Roadmap task: F1-003
• Decision owners: data platform maintainers

Context

Munderecat’in corpus ve annotation pipeline’lari Python kullanacaktir. Contributor, CI ve release ortamlari ayni interpreter siniri ile ayni dependency cozumunu kullanmadiginda parser, normalization ve uretilmis veri sonuclari farklilasabilir. ADR-013 bu nedenle tek kok Python proje sozlesmesi ve tek lockfile ongorur.

Secim, yeni bir projenin bakim omru ile ilk veri/NLP dependency setinin uyumlulugunu dengelemelidir. Python 3.12 Mart 2026 itibariyla yalniz guvenlik duzeltmesi asamasindadir. Python 3.14 en yeni feature line’dir; ancak gercek pipeline dependency’leri henuz secilmeden onu alt sinir yapmak gereksiz uyumluluk riski getirir. Python 3.13 halen maintenance release almaktadir ve ilk release icin daha dengeli tabandir.

Resmi referanslar:

• Python 3.12.13 release status
• Python 3.13 maintenance release
• uv project layout and universal lockfile
• uv Python version requests
• uv required-version setting

Decision

Python Version

• Ilk release CPython 3.13 minor line’ini hedefler.
• .python-version degeri 3.13 olur; patch release repo contracti degil, yonetilen interpreter guncellemesidir.
• pyproject.toml, requires-python = ">=3.13,<3.14" ile dependency resolver ve calisma zamanini ayni minor line’a sinirlar.
• Birden fazla Python minor line icin CI ve lock matrisi ilk release’te tutulmaz.

Python 3.14’e gecis; zorunlu pipeline dependency’lerinin destegi, golden fixture sonuclari ve lock semantic diff’i gorulerek ayri bir toolchain degisikligi olarak yapilir.

Environment And Lock Tool

uv, repository Python environment ve dependency lock aracidir.

• Kok pyproject.toml canonical dependency declaration’idir.
• Kok uv.lock tek, platformlar arasi dependency lockfile’idir.
• .python-version uv ve uyumlu diger araclar icin varsayilan interpreter request’idir.
• Project-local environment .venv/ altinda olusabilir ve Git’e girmez.
• CI ve release, lock’i guncellememek icin uv ... --locked veya uv lock --check kullanir.
• Lock guncellemesi ayri ve gorunur diff olarak review edilir.

[tool.uv] required-version = ">=0.10.7,<0.11" uv lock ve project semantigini 0.10 serisine baglar. Patch guncellemeleri ayni lock’u yeniden uretiyorsa kabul edilebilir; 0.11 veya sonrasi explicit toolchain review gerektirir.

Initial Project State

Root proje ilk basta environment/lock container’idir:

• package = false,
• build backend yoktur,
• CLI entrypoint yoktur,
• runtime dependency yoktur,
• development dependency yoktur.

Gercek pipeline package yapisi ve dependency’leri sahip roadmap taskinda eklenir. Varsayimsal gelecekteki kutuphaneler bu kararda lock’a alinmaz.

Operating Contract

• Dependency degisikligi pyproject.toml ve uv.lock diff’ini birlikte tasir.
• Normal verification uv lock --check --offline ile lock drift’ini degisiklik yapmadan kontrol eder.
• Lock uretimi uv lock; environment uretimi uv sync --locked ile yapilir.
• Interpreter veya dependency download’u execution evidence icinde acikca belirtilir; repo icine interpreter, wheel cache veya .venv alinmaz.
• Python pipeline komutlari sistem pip veya aktif rastgele virtualenv’e guvenmez; root proje contracti uzerinden calisir.

Consequences

Benefits

• Contributor, CI ve release ayni dependency graphini kullanir.
• Tek Python minor line test ve fixture matrisini ilk release icin kucuk tutar.
• Universal lockfile platform markerlarini tek artifactte gorunur kilar.
• uv interpreter discovery, environment ve lock davranisini tek CLI’da birlestirir.
• Tool minor siniri lock semantiginin habersiz degismesini engeller.

Costs

• Python 3.12-only bir dependency kullanilamaz; once dependency alternatifi veya karar revizyonu gerekir.
• Python 3.14 ozellikleri ilk release tabaninda kullanilamaz.
• uv projeye katki icin ek bir bootstrap aracidir ve CI’da kontrollu surumle kurulmalidir.
• Tek minor line, kutuphane olarak genis Python compatibility iddiasi sunmaz; Munderecat pipeline’i bir uygulama/toolchain olarak ele alinir.

Alternatives Considered

Python 3.12

Daha eski paketlerle uyumlulugu yuksek olabilir, fakat yalniz guvenlik duzeltmesi asamasindaki bir minor line ile yeni ve uzun omurlu proje baslatmak reddedildi.

Python 3.14

En yeni dil ve runtime iyilestirmelerini sunar. Ilk dependency seti dogrulanmadan ekosistem uyumlulugu riskini arttirdigi icin simdilik ertelendi.

Poetry Or pip-tools

Her ikisi de dependency cozumleyebilir. Interpreter request, environment, cross-platform lock ve project commandlarini tek aracla yonetme hedefinde uv daha kucuk operasyon yuzeyi sundugu icin secilmedi.

Unlocked requirements Files

Yalniz range tabanli requirements.txt temiz clone ve release graphini tam kilitlemez. Deterministik veri uretimi hedefiyle uyumsuz oldugu icin reddedildi.

Revisit Conditions

• Zorunlu ve alternatifsiz bir pipeline dependency’si Python 3.13’u desteklemiyorsa.
• Python 3.13 maintenance durumundan ciktiginda.
• uv 0.10 serisinde cozumlenemeyen bir guvenlik veya lock dogruluk sorunu bulunursa.
• Multi-platform lock gercek CI platformlarinda farkli dependency graphi uretiyorsa.