Python öğrenirken ilk birkaç dosyayı çalıştırmak kolaydır; asıl güçlük, proje büyüdüğünde aynı kodun başka bir bilgisayarda da güvenilir biçimde çalışmasını sağlamaktır. Python sürümü, sanal ortam, paketler, klasör yapısı, ayarlar, testler ve çalışma komutları baştan düzenlenmezse küçük bir uygulama bile kısa sürede “yalnızca benim bilgisayarımda çalışıyor” sorununa dönüşebilir.
Bu rehber, Python projesine nasıl başlanır? sorusunu sadece kurulum adımlarıyla değil, sürdürülebilir bir geliştirme düzeniyle yanıtlar. Amaç; komut satırı aracı, otomasyon betiği, veri işleme uygulaması veya web projesi geliştirirken tekrar kullanılabilecek güvenli bir temel oluşturmaktır.
Sağlam bir başlangıç için desteklenen bir Python sürümü seçin, proje klasörü içinde izole bir sanal ortam oluşturun, bağımlılıkları proje dosyasında tanımlayın ve uygulama kodunu testlerden ayırın. Ayarları kaynak koda gömmeyin; README, sürüm kontrolü ve otomatik testleri ilk günden ekleyin.
En küçük uygulanabilir akış şöyledir:
“En yeni sürüm her zaman en doğru sürümdür” yaklaşımı üretim projelerinde yeterli değildir. Önce kullanacağınız framework, veritabanı sürücüsü ve kritik paketlerin destek matrisini kontrol edin. Yeni bir projede Python’ın aktif olarak desteklenen kararlı sürümlerinden birini seçmek, güvenlik güncellemeleri ve paket uyumluluğu açısından daha sağlıklıdır.
Python Geliştirici Rehberi, dalları feature, prerelease, bugfix ve security gibi durumlarla gösterir. Güncel tabloyu Python sürümlerinin resmî destek durumu sayfasından kontrol edebilirsiniz. Ekip içinde yalnız “Python 3” demek yerine, örneğin 3.14 serisi gibi açık bir hedef belirlemek sürprizleri azaltır.
README ve pyproject.toml içinde minimum Python sürümünü belirtin. Yerel geliştirme, CI ve üretimde aynı ana-minör sürümü kullanmaya çalışın. Birden fazla sürümü destekleyen bir kütüphane geliştiriyorsanız her desteklenen sürümü otomatik test matrisine ekleyin.
Sanal ortam, bir projeye kurulan paketleri işletim sisteminin veya başka projelerin paketlerinden ayırır. Python’ın venv belgesi, her ortamın bağımsız paket dizinine sahip olduğunu açıklar. Bu izolasyon, bir projenin ihtiyaç duyduğu paket sürümünün başka bir projeyi bozmasını önler.
Aktivasyon komutu işletim sistemine göre değişebilir; ancak otomasyonlarda doğrudan ortamın Python çalıştırıcısını çağırmak daha öngörülebilir olabilir. Sanal ortam klasörünü Git’e eklemeyin. Bunun yerine ortamın yeniden kurulmasını sağlayacak bağımlılık tanımlarını depoya alın.
Paket kurmadan önce python --version ve python -m pip --version çıktılarının beklenen sanal ortamı gösterdiğini kontrol edin. python -m pip kullanımı, yanlış pip çalıştırıcısına paket kurma riskini azaltır.
Tek bir evrensel klasör yapısı yoktur; fakat sorumlulukların ayrılması gerekir. Yeniden kullanılabilir paketlerde src düzeni, test sırasında yanlışlıkla depo kökündeki kodu içe aktarma ihtimalini azaltabilir. Basit bir başlangıç şu şekilde olabilir:
Python Paketleme Rehberi’nin proje paketleme öğreticisi, paket diziniyle test dizininin ayrıldığı güncel bir temel sunar. Küçük bir betikte bile giriş noktası, iş mantığı ve dış sistem erişimini ayırmak test edilebilirliği yükseltir.
Kendi dosyanıza json.py, logging.py, email.py veya requests.py gibi bir standart kütüphane ya da bağımlılık adı vermek, beklenmeyen import davranışlarına yol açabilir. Paket adını kısa, küçük harfli, anlaşılır ve mevcut modüllerle çakışmayacak şekilde seçin.
pyproject.toml, modern Python araçlarının ortak yapılandırma merkezidir. Proje adı, sürümü, açıklaması, desteklenen Python aralığı, çalışma bağımlılıkları ve build sistemi burada tanımlanabilir. Resmî pyproject.toml yazma rehberi, build-system ve project tablolarının görevlerini örneklerle açıklar.
Bu örnek yalnız yapıyı gösterir. Gerçek sürüm aralıklarını paketin değişiklik günlüğüne, güvenlik durumuna ve test sonuçlarına göre belirleyin. Kütüphane ile son kullanıcı uygulamasının bağımlılık stratejisinin aynı olmadığını unutmayın.
Bağımlılık eklerken “pip install çalıştı” sonucu yeterli değildir. Doğrudan kullandığınız paketleri belirleyin, geçişli bağımlılıkları araçların çözmesine izin verin ve üretim kurulumunun tekrar edilebilir olmasını sağlayın. Paket adını, kaynağını ve bakım durumunu kontrol etmeden kurmayın.
Gevşek sürüm aralığı kütüphane kullanıcılarına esneklik sağlayabilir; kilit dosyası ise bir uygulamanın aynı bağımlılık ağacıyla yeniden kurulmasına yardımcı olur. PyPA’nın pylock.toml belirtimi, tekrarlanabilir kurulum için standart bir kilit formatı tanımlar. Seçtiğiniz aracın kullandığı formatı ve güncelleme sürecini ekipçe belgeleyin.
Uygulamanın çalışması için gereken paketlerle test, lint ve dokümantasyon araçlarını ayrı gruplarda tutun. PyPA’nın Dependency Groups belirtimi, test ve lint gibi dahili geliştirme ihtiyaçlarının pyproject.toml içinde gruplanmasına imkân verir.
API anahtarı, veritabanı parolası ve erişim belirteci kaynak koda yazılmamalıdır. Ayarları ortam değişkenlerinden okuyun; yerel örnek için gerçek değer içermeyen .env.example benzeri bir şablon kullanın. Gerçek .env dosyasını .gitignore kapsamına alın.
Uygulama başlarken gerekli ayarların varlığını doğrulayın ve eksik değerlerde anlaşılır hata üretin. Geliştirme, test ve üretim ayarlarını birbirine karıştırmayın. Loglara sırların, oturum bilgilerinin veya kişisel verilerin yazılmasını engelleyin.
Bir modül içe aktarıldığında ağ isteği göndermek, veritabanına bağlanmak veya dosya silmek gibi yan etkiler oluşmamalıdır. Çalıştırma davranışını açık bir main fonksiyonunda toplayın.
Bu ayrım, iş mantığını test etmeyi ve aynı fonksiyonları başka bir arayüzden kullanmayı kolaylaştırır. Komut satırı paketi yayımlıyorsanız giriş noktasını pyproject.toml içinde tanımlayabilirsiniz.
Her istisnayı yakalayıp sessizce geçmek hatayı çözmez; yalnızca görünmez yapar. Yalnız ele alabileceğiniz istisnaları yakalayın, kullanıcıya eyleme dönük mesaj verin ve teknik ayrıntıyı uygun log seviyesine yazın. Geniş except Exception bloklarını sınırlı bir uygulama sınırında kullanın.
Log mesajlarında işlem adı, güvenli bağlam ve hata sınıfı bulunabilir. Buna karşılık parola, token, çerez ve tam kişisel veri loglanmamalıdır. Dış servis çağrılarında zaman aşımı belirleyin; retry işlemlerini sonsuz döngüye çevirmeyin ve aynı isteğin tekrarının yan etkisini değerlendirin.
Testler sonradan eklenen bir lüks değil, proje sözleşmesidir. Önce saf iş mantığını birim testlerle koruyun; dosya, ağ veya veritabanı sınırları için entegrasyon testleri ekleyin. pytest’in başlangıç rehberi, basit assert ifadeleriyle test yazmayı ve test keşfini gösterir.
Test adları davranışı anlatmalı, rastgele zamana veya gerçek dış servise gereksiz yere bağlı olmamalıdır. Hata düzeltirken önce sorunu yeniden üreten bir test eklemek aynı regresyonun dönmesini önler.
Yüksek satır kapsamı, doğru senaryoların test edildiğini garanti etmez. Normal akışın yanında boş veri, sınır değer, yetki hatası, zaman aşımı ve bozuk girdi senaryolarını düşünün. Kritik iş kuralları için anlaşılır ve kararlı testler, yalnızca yüzde hedefinden daha değerlidir.
Otomatik biçimlendirici kod tarzı tartışmalarını azaltır; lint aracı olası hataları ve gereksiz yapıları yakalar. Tür ipuçları ise editör desteğini ve büyük kod tabanlarında anlaşılabilirliği artırabilir. Ancak araçları rastgele üst üste eklemek yerine az sayıda kontrol seçin ve ayarlarını pyproject.toml içinde merkezileştirin.
Kontrolleri yerelde çalıştıran tek bir komut tanımlayın. Aynı komutu CI üzerinde de çalıştırmak, “bende geçti” farklarını azaltır. Araç sürümlerini ve kural değişikliklerini bağımlılık güncellemesi gibi gözden geçirin.
İlk çalışan koddan önce Git deposunu oluşturmak değişiklik geçmişini anlaşılır tutar. Commit’ler tek bir mantıksal değişikliği anlatmalı; üretilmiş dosyalar, sanal ortam, önbellek, sırlar ve IDE’ye özgü geçici veriler depoya girmemelidir.
README en az şu soruları yanıtlamalıdır:
Yeni bir geliştirici yalnız README ile temiz ortamda projeyi çalıştırabiliyorsa dokümantasyon temel amacına ulaşıyor demektir.
Sürekli entegrasyon, her değişiklikte aynı kalite kapılarını otomatik çalıştırmalıdır. Minimum akış; bağımlılık kurulumu, lint, test ve paket oluşturma kontrolünden oluşabilir. Desteklenen birden fazla Python sürümü varsa bir test matrisi kullanın.
CI günlüklerinde sırları maskeleyin, üçüncü taraf action veya eklentileri sabit ve incelenmiş sürümlerle kullanın. Üretilen paketi kurup basit bir çalıştırma testi yapmak, yalnız kaynak dizininden geçen fakat dağıtımda bozulan import hatalarını yakalayabilir.
Python’ın güvenlik politikası, güvenlik düzeltmelerinin desteklenen sürüm durumuyla ilişkisini açıklar. Bu nedenle çalışma zamanı yükseltmesini belirsiz geleceğe ertelemeyin.
İlk saat içinde proje amacı, Python sürümü, depo ve sanal ortamı hazırlayın. Ardından tek bir uçtan uca kullanıcı senaryosunu çalışan en küçük kodla tamamlayın. Aynı davranış için test ekleyin, ayarları dışarı alın ve kurulum komutlarını README’ye yazın.
İkinci aşamada klasör sınırlarını netleştirin, bağımlılıkları pyproject.toml içine taşıyın ve lint/test komutlarını CI’a bağlayın. Son olarak temiz bir klasörde depoyu yeniden klonlayıp yalnız belgelenmiş adımlarla çalıştırın. Bu temiz kurulum testi, eksik dosya ve gizli yerel bağımlılıkları erken ortaya çıkarır.
İzole ve yeniden kurulabilir geliştirme için çoğu projede evet. Konteyner kullanmak da proje bağımlılıklarını yönetme ihtiyacını ortadan kaldırmaz; konteyner ve sanal ortam farklı izolasyon katmanlarıdır.
Modern proje metadatası ve araç yapılandırması için pyproject.toml merkezî seçenektir. requirements.txt belirli kurulum listeleri için hâlâ kullanılabilir. Uygulama mı kütüphane mi geliştirdiğinize ve seçtiğiniz bağımlılık aracına göre ikisinin rolünü açıkça tanımlayın.
En yaygın nedenler farklı Python sürümü, eksik veya farklı paket sürümleri, belgelenmemiş ortam değişkenleri, işletim sistemine bağlı dosya yolları ve depoya alınmamış kaynaklardır. Sürüm sabitleme, temiz kurulum testi ve CI bu farkları erken yakalar.
İyi bir Python projesi, klasör sayısının çokluğu veya kullanılan aracın popülerliğiyle ölçülmez. Başka bir geliştiricinin projeyi güvenli biçimde kurabilmesi, test edebilmesi ve değiştirebilmesi önemlidir. Desteklenen sürüm + izole ortam + açık bağımlılık tanımı + ayrılmış kod yapısı + otomatik test + güvenli ayar yönetimi birleşimi, küçük betikten üretim uygulamasına kadar sağlam bir temel sağlar.
Python projenizde yaşadığınız ortam, import, paket veya klasör yapısı sorununu; Python sürümü ve aldığınız hata mesajıyla birlikte bu kategoride paylaşabilirsiniz. Sır, token ve kişisel verileri gönderinize eklemeyin.
Bu rehber, Python projesine nasıl başlanır? sorusunu sadece kurulum adımlarıyla değil, sürdürülebilir bir geliştirme düzeniyle yanıtlar. Amaç; komut satırı aracı, otomasyon betiği, veri işleme uygulaması veya web projesi geliştirirken tekrar kullanılabilecek güvenli bir temel oluşturmaktır.
Kısa cevap: Sağlam Python projesi nasıl kurulur?
Sağlam bir başlangıç için desteklenen bir Python sürümü seçin, proje klasörü içinde izole bir sanal ortam oluşturun, bağımlılıkları proje dosyasında tanımlayın ve uygulama kodunu testlerden ayırın. Ayarları kaynak koda gömmeyin; README, sürüm kontrolü ve otomatik testleri ilk günden ekleyin.
En küçük uygulanabilir akış şöyledir:
- Projenin amacını ve destekleyeceği Python sürümünü yazın.
- Git deposunu ve .gitignore dosyasını oluşturun.
- python -m venv .venv komutuyla sanal ortam açın.
- Paketleri yalnız bu ortama kurun.
- pyproject.toml ile proje metadatasını ve bağımlılıkları tanımlayın.
- Kod, test ve dokümantasyon klasörlerini ayırın.
- Tek bir çalıştırma komutu ve kısa bir README hazırlayın.
- Her değişiklikte test, biçim ve güvenlik kontrollerini çalıştırın.
Python sürümü nasıl seçilir?
“En yeni sürüm her zaman en doğru sürümdür” yaklaşımı üretim projelerinde yeterli değildir. Önce kullanacağınız framework, veritabanı sürücüsü ve kritik paketlerin destek matrisini kontrol edin. Yeni bir projede Python’ın aktif olarak desteklenen kararlı sürümlerinden birini seçmek, güvenlik güncellemeleri ve paket uyumluluğu açısından daha sağlıklıdır.
Python Geliştirici Rehberi, dalları feature, prerelease, bugfix ve security gibi durumlarla gösterir. Güncel tabloyu Python sürümlerinin resmî destek durumu sayfasından kontrol edebilirsiniz. Ekip içinde yalnız “Python 3” demek yerine, örneğin 3.14 serisi gibi açık bir hedef belirlemek sürprizleri azaltır.
Sürüm politikasını belgeleyin
README ve pyproject.toml içinde minimum Python sürümünü belirtin. Yerel geliştirme, CI ve üretimde aynı ana-minör sürümü kullanmaya çalışın. Birden fazla sürümü destekleyen bir kütüphane geliştiriyorsanız her desteklenen sürümü otomatik test matrisine ekleyin.
Sanal ortam neden zorunlu sayılmalıdır?
Sanal ortam, bir projeye kurulan paketleri işletim sisteminin veya başka projelerin paketlerinden ayırır. Python’ın venv belgesi, her ortamın bağımsız paket dizinine sahip olduğunu açıklar. Bu izolasyon, bir projenin ihtiyaç duyduğu paket sürümünün başka bir projeyi bozmasını önler.
python --version
python -m venv .venv
Aktivasyon komutu işletim sistemine göre değişebilir; ancak otomasyonlarda doğrudan ortamın Python çalıştırıcısını çağırmak daha öngörülebilir olabilir. Sanal ortam klasörünü Git’e eklemeyin. Bunun yerine ortamın yeniden kurulmasını sağlayacak bağımlılık tanımlarını depoya alın.
Doğru Python ve pip'i doğrulayın
Paket kurmadan önce python --version ve python -m pip --version çıktılarının beklenen sanal ortamı gösterdiğini kontrol edin. python -m pip kullanımı, yanlış pip çalıştırıcısına paket kurma riskini azaltır.
Proje klasör yapısı nasıl olmalı?
Tek bir evrensel klasör yapısı yoktur; fakat sorumlulukların ayrılması gerekir. Yeniden kullanılabilir paketlerde src düzeni, test sırasında yanlışlıkla depo kökündeki kodu içe aktarma ihtimalini azaltabilir. Basit bir başlangıç şu şekilde olabilir:
ornek-proje/
pyproject.toml
README.md
.gitignore
src/
ornek_proje/
__init__.py
cli.py
service.py
tests/
test_service.py
Python Paketleme Rehberi’nin proje paketleme öğreticisi, paket diziniyle test dizininin ayrıldığı güncel bir temel sunar. Küçük bir betikte bile giriş noktası, iş mantığı ve dış sistem erişimini ayırmak test edilebilirliği yükseltir.
Dosya adlarında çakışmadan kaçının
Kendi dosyanıza json.py, logging.py, email.py veya requests.py gibi bir standart kütüphane ya da bağımlılık adı vermek, beklenmeyen import davranışlarına yol açabilir. Paket adını kısa, küçük harfli, anlaşılır ve mevcut modüllerle çakışmayacak şekilde seçin.
pyproject.toml ne işe yarar?
pyproject.toml, modern Python araçlarının ortak yapılandırma merkezidir. Proje adı, sürümü, açıklaması, desteklenen Python aralığı, çalışma bağımlılıkları ve build sistemi burada tanımlanabilir. Resmî pyproject.toml yazma rehberi, build-system ve project tablolarının görevlerini örneklerle açıklar.
[project]
name = "ornek-proje"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
"httpx>=0.28,<1"
]
Bu örnek yalnız yapıyı gösterir. Gerçek sürüm aralıklarını paketin değişiklik günlüğüne, güvenlik durumuna ve test sonuçlarına göre belirleyin. Kütüphane ile son kullanıcı uygulamasının bağımlılık stratejisinin aynı olmadığını unutmayın.
Bağımlılıklar nasıl yönetilir?
Bağımlılık eklerken “pip install çalıştı” sonucu yeterli değildir. Doğrudan kullandığınız paketleri belirleyin, geçişli bağımlılıkları araçların çözmesine izin verin ve üretim kurulumunun tekrar edilebilir olmasını sağlayın. Paket adını, kaynağını ve bakım durumunu kontrol etmeden kurmayın.
Gevşek sürüm aralığı kütüphane kullanıcılarına esneklik sağlayabilir; kilit dosyası ise bir uygulamanın aynı bağımlılık ağacıyla yeniden kurulmasına yardımcı olur. PyPA’nın pylock.toml belirtimi, tekrarlanabilir kurulum için standart bir kilit formatı tanımlar. Seçtiğiniz aracın kullandığı formatı ve güncelleme sürecini ekipçe belgeleyin.
Üretim ve geliştirme bağımlılıklarını ayırın
Uygulamanın çalışması için gereken paketlerle test, lint ve dokümantasyon araçlarını ayrı gruplarda tutun. PyPA’nın Dependency Groups belirtimi, test ve lint gibi dahili geliştirme ihtiyaçlarının pyproject.toml içinde gruplanmasına imkân verir.
Sır yönetimi ve ayarlar nasıl yapılır?
API anahtarı, veritabanı parolası ve erişim belirteci kaynak koda yazılmamalıdır. Ayarları ortam değişkenlerinden okuyun; yerel örnek için gerçek değer içermeyen .env.example benzeri bir şablon kullanın. Gerçek .env dosyasını .gitignore kapsamına alın.
Uygulama başlarken gerekli ayarların varlığını doğrulayın ve eksik değerlerde anlaşılır hata üretin. Geliştirme, test ve üretim ayarlarını birbirine karıştırmayın. Loglara sırların, oturum bilgilerinin veya kişisel verilerin yazılmasını engelleyin.
Kodun giriş noktası nasıl tasarlanır?
Bir modül içe aktarıldığında ağ isteği göndermek, veritabanına bağlanmak veya dosya silmek gibi yan etkiler oluşmamalıdır. Çalıştırma davranışını açık bir main fonksiyonunda toplayın.
def main() -> int:
# ayarları yükle, servisleri kur ve işlemi başlat
return 0
if __name__ == "__main__":
raise SystemExit(main())
Bu ayrım, iş mantığını test etmeyi ve aynı fonksiyonları başka bir arayüzden kullanmayı kolaylaştırır. Komut satırı paketi yayımlıyorsanız giriş noktasını pyproject.toml içinde tanımlayabilirsiniz.
Hata yönetimi ve loglama nasıl kurulmalı?
Her istisnayı yakalayıp sessizce geçmek hatayı çözmez; yalnızca görünmez yapar. Yalnız ele alabileceğiniz istisnaları yakalayın, kullanıcıya eyleme dönük mesaj verin ve teknik ayrıntıyı uygun log seviyesine yazın. Geniş except Exception bloklarını sınırlı bir uygulama sınırında kullanın.
Log mesajlarında işlem adı, güvenli bağlam ve hata sınıfı bulunabilir. Buna karşılık parola, token, çerez ve tam kişisel veri loglanmamalıdır. Dış servis çağrılarında zaman aşımı belirleyin; retry işlemlerini sonsuz döngüye çevirmeyin ve aynı isteğin tekrarının yan etkisini değerlendirin.
Test düzeni ilk günden nasıl kurulur?
Testler sonradan eklenen bir lüks değil, proje sözleşmesidir. Önce saf iş mantığını birim testlerle koruyun; dosya, ağ veya veritabanı sınırları için entegrasyon testleri ekleyin. pytest’in başlangıç rehberi, basit assert ifadeleriyle test yazmayı ve test keşfini gösterir.
def toplam(fiyatlar):
return sum(fiyatlar)
def test_toplam():
assert toplam([10, 20, 5]) == 35
Test adları davranışı anlatmalı, rastgele zamana veya gerçek dış servise gereksiz yere bağlı olmamalıdır. Hata düzeltirken önce sorunu yeniden üreten bir test eklemek aynı regresyonun dönmesini önler.
Test kapsamı tek başına kalite değildir
Yüksek satır kapsamı, doğru senaryoların test edildiğini garanti etmez. Normal akışın yanında boş veri, sınır değer, yetki hatası, zaman aşımı ve bozuk girdi senaryolarını düşünün. Kritik iş kuralları için anlaşılır ve kararlı testler, yalnızca yüzde hedefinden daha değerlidir.
Biçim, lint ve tür kontrolleri nasıl kullanılmalı?
Otomatik biçimlendirici kod tarzı tartışmalarını azaltır; lint aracı olası hataları ve gereksiz yapıları yakalar. Tür ipuçları ise editör desteğini ve büyük kod tabanlarında anlaşılabilirliği artırabilir. Ancak araçları rastgele üst üste eklemek yerine az sayıda kontrol seçin ve ayarlarını pyproject.toml içinde merkezileştirin.
Kontrolleri yerelde çalıştıran tek bir komut tanımlayın. Aynı komutu CI üzerinde de çalıştırmak, “bende geçti” farklarını azaltır. Araç sürümlerini ve kural değişikliklerini bağımlılık güncellemesi gibi gözden geçirin.
Git ve README için minimum standart nedir?
İlk çalışan koddan önce Git deposunu oluşturmak değişiklik geçmişini anlaşılır tutar. Commit’ler tek bir mantıksal değişikliği anlatmalı; üretilmiş dosyalar, sanal ortam, önbellek, sırlar ve IDE’ye özgü geçici veriler depoya girmemelidir.
README en az şu soruları yanıtlamalıdır:
- Proje hangi problemi çözüyor?
- Hangi Python sürümü gerekiyor?
- Geliştirme ortamı nasıl kuruluyor?
- Uygulama ve testler hangi komutla çalışıyor?
- Gerekli ayarlar nelerdir?
- Katkı ve lisans koşulları nedir?
Yeni bir geliştirici yalnız README ile temiz ortamda projeyi çalıştırabiliyorsa dokümantasyon temel amacına ulaşıyor demektir.
CI süreci hangi kontrolleri çalıştırmalı?
Sürekli entegrasyon, her değişiklikte aynı kalite kapılarını otomatik çalıştırmalıdır. Minimum akış; bağımlılık kurulumu, lint, test ve paket oluşturma kontrolünden oluşabilir. Desteklenen birden fazla Python sürümü varsa bir test matrisi kullanın.
CI günlüklerinde sırları maskeleyin, üçüncü taraf action veya eklentileri sabit ve incelenmiş sürümlerle kullanın. Üretilen paketi kurup basit bir çalıştırma testi yapmak, yalnız kaynak dizininden geçen fakat dağıtımda bozulan import hatalarını yakalayabilir.
Python projesinde güvenlik kontrol listesi
- Destek süresi dolmamış Python sürümü kullanın.
- Paketleri resmî kaynaklardan ve doğru proje adından kurun.
- Bağımlılık değişikliklerini kod değişikliği gibi inceleyin.
- Kilit dosyasını ve bütünlük bilgisini seçilen araçla koruyun.
- Sırları depoya, test verisine veya loglara eklemeyin.
- Dış girdileri doğrulayın; shell komutlarını kullanıcı verisiyle birleştirmeyin.
- Dosya yollarında dizin geçişi ve yetki sınırlarını değerlendirin.
- HTTP çağrılarına zaman aşımı ve kontrollü hata yönetimi ekleyin.
- Güvenlik güncellemelerini düzenli bir bakım takviminde uygulayın.
Python’ın güvenlik politikası, güvenlik düzeltmelerinin desteklenen sürüm durumuyla ilişkisini açıklar. Bu nedenle çalışma zamanı yükseltmesini belirsiz geleceğe ertelemeyin.
İlk gün için uygulanabilir proje planı
İlk saat içinde proje amacı, Python sürümü, depo ve sanal ortamı hazırlayın. Ardından tek bir uçtan uca kullanıcı senaryosunu çalışan en küçük kodla tamamlayın. Aynı davranış için test ekleyin, ayarları dışarı alın ve kurulum komutlarını README’ye yazın.
İkinci aşamada klasör sınırlarını netleştirin, bağımlılıkları pyproject.toml içine taşıyın ve lint/test komutlarını CI’a bağlayın. Son olarak temiz bir klasörde depoyu yeniden klonlayıp yalnız belgelenmiş adımlarla çalıştırın. Bu temiz kurulum testi, eksik dosya ve gizli yerel bağımlılıkları erken ortaya çıkarır.
Sık sorulan sorular
Her Python projesinde venv gerekir mi?
İzole ve yeniden kurulabilir geliştirme için çoğu projede evet. Konteyner kullanmak da proje bağımlılıklarını yönetme ihtiyacını ortadan kaldırmaz; konteyner ve sanal ortam farklı izolasyon katmanlarıdır.
requirements.txt mi pyproject.toml mı?
Modern proje metadatası ve araç yapılandırması için pyproject.toml merkezî seçenektir. requirements.txt belirli kurulum listeleri için hâlâ kullanılabilir. Uygulama mı kütüphane mi geliştirdiğinize ve seçtiğiniz bağımlılık aracına göre ikisinin rolünü açıkça tanımlayın.
Python kodu neden başka bilgisayarda çalışmıyor?
En yaygın nedenler farklı Python sürümü, eksik veya farklı paket sürümleri, belgelenmemiş ortam değişkenleri, işletim sistemine bağlı dosya yolları ve depoya alınmamış kaynaklardır. Sürüm sabitleme, temiz kurulum testi ve CI bu farkları erken yakalar.
Sonuç: Araçtan önce tekrarlanabilirlik
İyi bir Python projesi, klasör sayısının çokluğu veya kullanılan aracın popülerliğiyle ölçülmez. Başka bir geliştiricinin projeyi güvenli biçimde kurabilmesi, test edebilmesi ve değiştirebilmesi önemlidir. Desteklenen sürüm + izole ortam + açık bağımlılık tanımı + ayrılmış kod yapısı + otomatik test + güvenli ayar yönetimi birleşimi, küçük betikten üretim uygulamasına kadar sağlam bir temel sağlar.
Python projenizde yaşadığınız ortam, import, paket veya klasör yapısı sorununu; Python sürümü ve aldığınız hata mesajıyla birlikte bu kategoride paylaşabilirsiniz. Sır, token ve kişisel verileri gönderinize eklemeyin.