PyPI üzerinden Python paketlerini dağıtmak için kapsamlı bir rehber. Sürüm yönetimi en iyi uygulamaları, araçlar ve küresel geliştiriciler için iş akışlarını kapsar.
Python Paket Dağıtımı: PyPI'da Yayınlama ve Sürüm Yönetimi
Python'un zengin ekosistemi, Python Paket Dizini (PyPI) aracılığıyla kolayca erişilebilen geniş bir paket koleksiyonu tarafından desteklenmektedir. Bu kılavuz, kendi Python paketlerinizi PyPI üzerinden nasıl dağıtacağınıza dair kapsamlı bir genel bakış sunarak dünya çapındaki geliştiricilerin erişimine açık olmalarını sağlar. Yüksek kaliteli Python paketleri oluşturmak ve yayınlamak için gerekli araçları, sürüm yönetimi için en iyi uygulamaları ve iş akışlarını inceleyeceğiz.
Python Paketinizi Neden Dağıtmalısınız?
Python paketinizi dağıtmak sayısız fayda sunar:
- Çalışmanızı Paylaşmak: Diğer geliştiricilerin kodunuzu kolayca yeniden kullanmasına olanak tanır, işbirliğini ve yeniliği teşvik eder. Python ile oluşturulmuş özel veri analizi araçlarınızı küresel bir ekibin kullandığını hayal edin.
- Bağımlılık Yönetimi: Diğer projelerdeki bağımlılıkları yönetme sürecini basitleştirir. Paketiniz, tüm bağımlılıklarıyla birlikte tek bir komutla kurulabilir.
- Açık Kaynağa Katkı: Açık kaynak topluluğuna katkıda bulunmanızı ve çalışmanızla tanınmanızı sağlar. Birçok kritik yazılım bileşeni, dünya çapındaki geliştiriciler tarafından sürdürülen açık kaynaklı paketlerdir.
- Sürüm Kontrolü ve Güncellemeler: Sürümleri yönetmek, güncellemeleri yayınlamak ve hata düzeltmelerini ele almak için yapılandırılmış bir yol sağlar. Bu, kullanıcıların her zaman paketinizin en son ve en güvenilir sürümüne erişmesini sağlar.
- Kolay Kurulum: Kullanıcılar için `pip install paket-adiniz` komutuyla kurulumu basitleştirir.
Python Paket Dağıtımı için Gerekli Araçlar
Python paketleri oluşturmak ve dağıtmak için birkaç araç gereklidir:
- setuptools: Ad, sürüm, bağımlılıklar ve giriş noktaları dahil olmak üzere paket meta verilerini tanımlamak için yaygın olarak kullanılan bir kütüphanedir. Python projelerini paketlemek için fiili standarttır.
- wheel: Kaynak dağıtımlarına kıyasla daha verimli ve güvenilir bir kurulum süreci sağlayan bir dağıtım formatıdır. Wheel'ler, derleme gerektirmeden kurulabilen önceden oluşturulmuş dağıtımlardır.
- twine: Paketinizi PyPI'a güvenli bir şekilde yüklemek için kullanılan bir araçtır. Twine, iletim sırasında kimlik bilgilerinizi ve paket verilerinizi şifreleyerek gizli dinlemeye ve ortadaki adam saldırılarına karşı koruma sağlar.
- venv/virtualenv: Bunlar, yalıtılmış Python ortamları oluşturmak için kullanılan araçlardır. Sanal ortamlar kullanmak, bağımlılıkları yönetmek ve farklı projeler arasındaki çakışmaları önlemek için çok önemlidir.
Projenizi Kurma
Paketinizi dağıtmadan önce projenizi doğru şekilde yapılandırmanız gerekir.
Proje Yapısı Örneği
my_package/ ├── my_package/ │ ├── __init__.py │ ├── module1.py │ └── module2.py ├── tests/ │ ├── __init__.py │ ├── test_module1.py │ └── test_module2.py ├── README.md ├── LICENSE ├── setup.py └── .gitignore
Açıklama:
- my_package/: Paketinizin kaynak kodunu içeren ana dizin.
- my_package/__init__.py: `my_package` dizinini bir Python paketi yapar. Boş olabilir veya başlatma kodu içerebilir.
- my_package/module1.py, my_package/module2.py: Asıl kodu içeren Python modülleriniz.
- tests/: Birim testlerinizi içeren bir dizin. Paketinizin kalitesini ve güvenilirliğini sağlamak için testler yazmak çok önemlidir.
- README.md: Paketinizin tanımını, kullanım talimatlarını ve diğer ilgili bilgileri sağlayan bir Markdown dosyası. Bu genellikle kullanıcıların PyPI'da gördüğü ilk şeydir.
- LICENSE: Paketinizin dağıtıldığı lisansı içeren bir dosya (ör. MIT, Apache 2.0, GPL). Başkalarının kodunuzu nasıl kullanabileceğini belirtmek için uygun bir lisans seçmek esastır.
- setup.py: Paketinizin meta verilerini ve derleme talimatlarını tanımlayan ana yapılandırma dosyası.
- .gitignore: Git tarafından göz ardı edilmesi gereken dosyaları ve dizinleri belirtir (ör. geçici dosyalar, derleme çıktıları).
`setup.py` Dosyasını Oluşturma
`setup.py` dosyası, paket dağıtımınızın kalbidir. Paketiniz hakkında meta verileri ve onu derleme ve kurma talimatlarını içerir. İşte bir örnek:
import setuptools
with open("README.md", "r") as fh:
long_description = fh.read()
setuptools.setup(
name="my_package", # Paket adınızla değiştirin
version="0.1.0",
author="Adınız Soyadınız", # Adınızla değiştirin
author_email="eposta@adresiniz.com", # E-postanızla değiştirin
description="Küçük bir örnek paket",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/kullaniciadiniz/my_package", # Depo URL'nizle değiştirin
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.6',
install_requires=[
"requests", # Örnek bağımlılık
],
)
Açıklama:
- name: PyPI'da kullanılacak olan paketinizin adı. Benzersiz ve açıklayıcı bir ad seçin.
- version: Paketinizin sürüm numarası. Anlamsal sürümlemeyi (aşağıya bakın) takip edin.
- author, author_email: Adınız ve e-posta adresiniz.
- description: Paketinizin kısa bir açıklaması.
- long_description: Genellikle `README.md` dosyanızdan okunan daha uzun, daha ayrıntılı bir açıklama.
- long_description_content_type: Uzun açıklamanızın formatını belirtir (ör. "text/markdown").
- url: Paketinizin ana sayfasının URL'si (ör. GitHub deposu).
- packages: Dağıtımınıza dahil edilecek paketlerin bir listesi. `setuptools.find_packages()` projenizdeki tüm paketleri otomatik olarak keşfeder.
- classifiers: Kullanıcıların paketinizi PyPI'da bulmasına yardımcı olan meta veriler. Trove Sınıflandırıcıları listesinden uygun sınıflandırıcıları seçin. Desteklenen Python sürümleri, işletim sistemleri ve lisanslar için sınıflandırıcılar eklemeyi düşünün.
- python_requires: Paketinizi kullanmak için gereken minimum Python sürümünü belirtir.
- install_requires: Paketinizin gerektirdiği bağımlılıkların bir listesi. Bu bağımlılıklar, paketiniz kurulduğunda otomatik olarak kurulacaktır.
Sürüm Yönetimi: Anlamsal Sürümleme
Anlamsal Sürümleme (SemVer), paketinizdeki değişikliklerin doğasını iletmek için açık ve tutarlı bir yol sağlayan, yaygın olarak benimsenen bir sürümleme şemasıdır.
Bir SemVer sürüm numarası üç bölümden oluşur: MAJOR.MINOR.PATCH.
- MAJOR (ANA): Uyumsuz API değişiklikleri yaptığınızda artırılır. Bu, kullanıcıların kodlarını güncellemelerini gerektirebilecek önemli bir değişikliği belirtir.
- MINOR (ARA): Geriye dönük uyumlu bir şekilde işlevsellik eklediğinizde artırılır. Bu, mevcut kodu bozmayan yeni özellikleri veya iyileştirmeleri ifade eder.
- PATCH (YAMA): Geriye dönük uyumlu hata düzeltmeleri yaptığınızda artırılır. Bu, yeni özellikler eklemeyen veya mevcut işlevselliği bozmayan küçük düzeltmeler içindir.
Örnekler:
- 1.0.0: İlk sürüm.
- 1.1.0: Mevcut kodu bozmadan yeni bir özellik eklendi.
- 1.0.1: 1.0.0 sürümündeki bir hata düzeltildi.
- 2.0.0: Uyumsuz API değişiklikleri yapıldı.
SemVer kullanmak, kullanıcıların paketinizin yeni bir sürümüne yükseltmenin etkisini anlamalarına yardımcı olur.
Paketinizi Oluşturma
`setup.py` dosyanızı yapılandırdıktan sonra paketinizi oluşturabilirsiniz.
- Sanal bir ortam oluşturun: Paketinizin bağımlılıklarını yalıtmak için sanal bir ortam oluşturmanız şiddetle tavsiye edilir. `python3 -m venv .venv` (veya `virtualenv .venv`) komutunu kullanın ve ardından etkinleştirin (Linux/macOS'ta `source .venv/bin/activate`, Windows'ta `.venv\Scripts\activate`).
- Derleme bağımlılıklarını kurun: `pip install --upgrade setuptools wheel` komutunu çalıştırın.
- Paketi derleyin: `python setup.py sdist bdist_wheel` komutunu çalıştırın. Bu komut, `dist` dizininde iki dağıtım dosyası oluşturur: bir kaynak dağıtımı (sdist) ve bir wheel dağıtımı (bdist_wheel).
`sdist` kaynak kodunuzu ve `setup.py` dosyanızı içerir. `bdist_wheel` ise daha hızlı kurulabilen önceden oluşturulmuş bir dağıtımdır.
Paketinizi PyPI'da Yayınlama
Paketinizi yayınlamadan önce PyPI'da (https://pypi.org/) bir hesap oluşturmanız ve bir API token'ı (jetonu) oluşturmanız gerekir. Bu token, yüklemelerinizin kimliğini doğrulamak için kullanılacaktır.
- PyPI'a kaydolun: https://pypi.org/account/register/ adresine gidin ve bir hesap oluşturun.
- Bir API token'ı oluşturun: https://pypi.org/manage/account/ adresine gidin, "API tokens" bölümüne ilerleyin ve yeni bir token oluşturun. Paketinizi yüklemek için ihtiyacınız olacağından bu token'ı güvenli bir şekilde saklayın.
- Twine'ı kurun: `pip install twine` komutunu çalıştırın.
- Paketinizi yükleyin: `twine upload dist/*` komutunu çalıştırın. Sizden kullanıcı adınız (
__token__) ve şifreniz (oluşturduğunuz API token'ı) istenecektir.
Önemli Güvenlik Notu: API token'ınızı asla deponuza (repository) commit'lemeyin. Onu güvenli bir şekilde saklayın ve yükleme işlemi sırasında erişmek için ortam değişkenleri veya diğer güvenli yöntemleri kullanın.
Paket Kurulumunuzu Test Etme
Paketinizi yayınladıktan sonra doğru bir şekilde kurulabildiğini test etmek çok önemlidir.
- Yeni bir sanal ortam oluşturun: Bu, kurulumu temiz bir ortamda test ettiğinizden emin olmanızı sağlar.
- Paketinizi kurun: `pip install paket-adiniz` komutunu çalıştırın.
- Paketinizi içeri aktarın ve kullanın: Bir Python yorumlayıcısında, paketinizi içeri aktarın ve beklendiği gibi çalıştığını doğrulayın.
Sürekli Entegrasyon ve Sürekli Dağıtım (CI/CD)
Paketinizi oluşturma, test etme ve yayınlama sürecini otomatikleştirmek için GitHub Actions, GitLab CI veya Travis CI gibi CI/CD araçlarını kullanabilirsiniz.
İşte paketinizi oluşturup PyPI'da yayınlayan bir GitHub Actions iş akışı örneği:
name: Publish to PyPI
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python 3.x
uses: actions/setup-python@v2
with:
python-version: 3.x
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel twine
- name: Build package
run: python setup.py sdist bdist_wheel
- name: Publish package to PyPI
run: |
twine upload dist/* \
-u __token__ \
-p ${{ secrets.PYPI_API_TOKEN }}
Açıklama:
- Bu iş akışı, GitHub'da yeni bir sürüm yayınlandığında tetiklenir.
- Kodu alır, Python'u kurar, bağımlılıkları yükler, paketi oluşturur ve PyPI'a yükler.
secrets.PYPI_API_TOKEN, PyPI API token'ınızı saklayan bir GitHub secret'ıdır. Bu secret'ı GitHub depo ayarlarınızda yapılandırmanız gerekir.
Python Paket Dağıtımı için En İyi Uygulamalar
- Kapsamlı dokümantasyon yazın: Ayrıntılı bir `README.md` dosyası ve Sphinx gibi araçları kullanarak API dokümantasyonu ekleyin. Açık ve eksiksiz dokümantasyon, paketinizin kullanımını kolaylaştırmak için çok önemlidir.
- Birim testleri yazın: Kalitesini ve güvenilirliğini sağlamak için kodunuzu kapsamlı bir şekilde test edin. Pytest veya unittest gibi bir test çerçevesi kullanın.
- PEP 8 stil kılavuzlarını takip edin: Tutarlı ve okunabilir kod sağlamak için Python Geliştirme Önerisi 8 (PEP 8) stil kılavuzuna uyun.
- Bir lisans kullanın: Başkalarının kodunuzu nasıl kullanabileceğini belirtmek için uygun bir açık kaynak lisansı seçin.
- Bağımlılıklarınızı güncel tutun: Hata düzeltmelerinden, güvenlik yamalarından ve yeni özelliklerden yararlanmak için paketinizin bağımlılıklarını düzenli olarak güncelleyin.
- Sanal bir ortam kullanın: Bağımlılıkları yalıtmak için paketinizi her zaman bir sanal ortam içinde geliştirin ve test edin.
- Uluslararasılaştırma (i18n) ve yerelleştirmeyi (l10n) düşünün: Paketiniz kullanıcıya yönelik metin veya verilerle çalışıyorsa, onu farklı dillere ve bölgelere uyarlanabilir hale getirmeyi düşünün. Bu, potansiyel kullanıcı tabanınızı küresel olarak genişletir. Babel gibi araçlar bu konuda yardımcı olabilir.
- Farklı saat dilimleri ve para birimlerini yönetin: Paketiniz tarihler, saatler veya finansal işlemlerle ilgiliyse, dünyadaki farklı saat dilimlerini ve para birimlerini göz önünde bulundurun. Bu karmaşıklıkları doğru bir şekilde yönetmek için uygun kütüphaneleri ve API'leri kullanın.
- Açık hata mesajları sağlayın: Kullanıcıların neyin yanlış gittiğini ve nasıl düzelteceklerini anlamalarına yardımcı olan bilgilendirici hata mesajları yazın. Mümkünse bu hata mesajlarını farklı dillere çevirin.
- Erişilebilirlik hakkında düşünün: Paketinizin arayüzünü ve dokümantasyonunu tasarlarken engelli kullanıcıları göz önünde bulundurun. Paketinizin herkes tarafından kullanılabilir olmasını sağlamak için erişilebilirlik yönergelerini izleyin.
İleri Düzey Konular
- İsim alanı (Namespace) paketleri: Tek bir Python paketini birden çok dizine veya hatta birden çok dağıtıma bölmenize olanak tanır.
- Giriş noktaları (Entry points): Diğer paketlerden veya komut satırından çağrılabilecek fonksiyonlar veya sınıflar tanımlamanıza olanak tanır.
- Veri dosyaları: Dağıtımınıza Python olmayan dosyaları (ör. veri dosyaları, yapılandırma dosyaları) dahil etmenize olanak tanır.
- Koşullu bağımlılıklar: Yalnızca belirli koşullar altında (ör. belirli bir işletim sisteminde) gerekli olan bağımlılıkları belirtmenize olanak tanır.
Sonuç
Python paketinizi PyPI'da dağıtmak, çalışmanızı dünyayla paylaşmanın ve Python ekosistemine katkıda bulunmanın harika bir yoludur. Bu kılavuzda özetlenen adımları ve en iyi uygulamaları izleyerek, kurulumu, kullanımı ve bakımı kolay, yüksek kaliteli Python paketleri oluşturabilir ve yayınlayabilirsiniz. Paketinizin başarısını sağlamak için açık dokümantasyona, kapsamlı testlere ve tutarlı sürüm yönetimine öncelik vermeyi unutmayın.