Herkese merhabalar,

Projelerimizi tasarlarken mutlaka bir yerlerine sürekli kullanmayı planladığımız yapılarımızı koyuyoruz. Bu yapılar bizim için genel olarak kullanışlı olduğunda, her seferinde tekrar tekrar yazmak yerine bu yapıları bir paket yapmak istediğimizde, imdadımıza PyPI yetişiyor…

Öncelikle paketleyeceğimiz örnek bir yapımız olsun. Diyelim ki verilen metni list’e dönüştüren bir yapımız var. Biz de bu yapıyı paket haline getirmek istiyoruz. “text_to_list” isimli projemizi oluşturmaya başlıyoruz. PyPI için bir kütüphane oluştururken sahip olduğu standartları takip etmek gerekiyor;

textToListPackage/
├── LICENSE
├── pyproject.toml
├── setup.py
├── README.md
│── text_to_list/
│     ├── __init__.py
│     └── text_to_list.py
└── tests/

Sırayla isimlere göz atarsak;

LICENSE tahmin edebileceğiniz gibi, kütüphanenizin hangi lisans ile lisanslandığı detaylarını içeriyor. pyproject.toml kütüphanenizi indiren istemcilerin hangi paketleyici ile paketinizi yükleyeceğini, kimin tarafından yazıldığı, versiyon bağımlılıkları gibi detayları belirtir. README.md projenin PyPI içerisindeki görünür dökümantasyonudur. Paketimizin kendisi text_to_list altında kütüphane dosyaları bulunmalıdır. Test ise kütüphanenin testlerini barındırır.

Projeyi Paketlemeye Hazırlama

Projenin standart README dosyasında Markdown kullanarak kütüphanemizi nasıl yükleyebileceğimizi ve nasıl kullanılabileceğini yazıyoruz;

 # How to Install
```shell
pip install text_to_list
```
# How to Use It
```python
from text_to_list import text_to_list
text_to_list("Sample Sentence for Library")
```

LICENSE dosyası için kısa bir Google araması yapabilirsiniz, ben varsayılan olarak resmi dökümandaki LICENSE dosyasını kullanmayı tercih ettim;

Copyright (c) 2022 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Kütüphanemiz içerisindeki kullanılacak, class, function gibi yapıları text_to_list.py içerisinde tanımladıktan sonra, __init__.py içerisinde bu dosyaları çağırmayı unutmuyoruz, bu sayede paket yüklendikten sonra ulaşılabilir olacak.

text_to_list.py;

def text_to_list(text: str):
    """
    :param text: The text to be taken as a string and converted to a list.
    :return: Return parameter of function converted to list
    """
    listed_text = text.split(sep=" ")
    return listed_text

__init__.py;

from .text_to_list import text_to_list

setup.py dosyamız projenin özeti mahiyetinde bir dosya olduğundan versiyon bilgisini, sahipliğini ve bağımlılıklarını burada belirtiyoruz, projenizi paketlemek için birden fazla alternatif mevcut(setuptools, Hatcling, Flit vs.) ancak bunlardan en yaygını setuptools olduğu için ben de aynı yapıda anlatmak istedim;

import setuptools

with open('README.md', 'r', encoding='utf-8') as fh:
    long_description = fh.read()

setuptools.setup(
    name='text_to_list',
    author='Sezer BOZKIR',
    version="0.0.1",
    author_email='admin@sezerbozkir.com',
    description='Example PyPI (Python Package Index) Package',
    keywords='example, pypi, package',
    long_description=long_description,
    long_description_content_type='text/markdown',
    url='https://github.com/natgho/text_to_list',
    project_urls={
        'Documentation': 'https://github.com/natgho/text_to_list',
        'Bug Reports':
        'https://github.com/natgho/text_to_list/issues',
        'Source Code': 'https://github.com/natgho/text_to_list',
    },
    package_dir={'': 'text_to_list'},
    packages=setuptools.find_packages(where='text_to_list'),
    classifiers=[
        # see https://pypi.org/classifiers/
        'Development Status :: 5 - Production/Stable',

        'Intended Audience :: Developers',
        'Topic :: Software Development :: Build Tools',

        'Programming Language :: Python :: 3',
        'Programming Language :: Python :: 3.6',
        'Programming Language :: Python :: 3.7',
        'Programming Language :: Python :: 3.8',
        'Programming Language :: Python :: 3.9',
        'Programming Language :: Python :: 3 :: Only',
        'License :: OSI Approved :: MIT License',
        'Operating System :: OS Independent',
    ],
    python_requires='>=3.7',
    install_requires=['requests'],
)

Burada bağımlılıkları yüklemeye örnek olması açısından “requests” kütüphanesini de bağımlılık olarak ekledim. Paketimizi yüklediğimizde otomatik olarak requests kütüphanesi de bu sayede yüklenecek.

Eğer herşey yolundaysa artık paketimizi yükleyebilir ve test edebiliriz;

pip install .

Kütüphane ve bağımlılıklarımız yüklendiğinde interaktif konsolu açıp şu şekilde çalıştırabiliyor olmalıyız;

from text_to_list import text_to_list
print(text_to_list("This is very funny sample."))
# output: ['this', 'is', 'very', 'funny', 'sample.']

Artık paketimizi yükleyip, pypi üzerinden çekme adımına geçebiliriz.

Paketimizi Test PyPI Ortamında Denemek

Paketi gerçek ortamda yüklemeden önce, herşeyin yolunda gittiğinden emin olmak için PyPI’nin test ortamına kaydolup paketimizi oraya aktararak test ediyoruz. (link)

Paketimizi PyPI ortamına yüklemek için Twine kütüphanesini kurmamız gerekmekte. Bu kütüphane paketimizi yüklerken bize yardımcı olacak. (detaylar için);

pip install twine

paketimizi build alıyoruz;

python3 -m build

bu adım başarıyla tamamlandığında projemizin altında “dist” klasörünü görebiliyoruz olmalıyız. Dist klasörü paketimizin detaylarını içeren klasör. Projemizi test ortamına aktarmak için;

python -m twine upload --repository testpypi dist/* 

Bu komutun çıktısında sizden k.adı ve parola istemekte, bu adımda kaydolduğumuz bilgileri giriyoruz;

Uploading distributions to https://test.pypi.org/legacy/
Enter your username: natgho
Enter your password:
Uploading text_to_list-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.4/7.4 kB • 00:00 • ?
Uploading text_to_list-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.3/7.3 kB • 00:00 • ?

View at:
https://test.pypi.org/project/text-to-list/0.0.1/

URL adresine girdiğimizde README dosyamızın açıklama olarak eklendiğini, herşeyin yolunda olduğunu görüyoruz. Artık gerçek ortama paketimizi çıkarmamızın zamanı geldi;

twine upload dist/*

Aynı adımların benzerini bu sefer gerçek ortam için konsolda görüyoruz;

Uploading distributions to https://upload.pypi.org/legacy/
Enter your username: natgho
Enter your password:
Uploading text_to_list-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.4/7.4 kB • 00:00 • ?
Uploading text_to_list-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.3/7.3 kB • 00:00 • ?

View at:
https://pypi.org/project/text-to-list/0.0.1/

Herşey tamamlandığına göre, paketimizi kurmayı bu sefer pip üzerinden çağırarak deniyoruz;

sezer@optimist ~> pip install text-to-list
pip install text-to-list
Collecting text-to-list
  Using cached text_to_list-0.0.1-py3-none-any.whl (2.3 kB)
Collecting requests
  Using cached requests-2.28.1-py3-none-any.whl (62 kB)
Collecting certifi>=2017.4.17
  Using cached certifi-2022.9.24-py3-none-any.whl (161 kB)
Collecting idna<4,>=2.5
  Using cached idna-3.4-py3-none-any.whl (61 kB)
Collecting charset-normalizer<3,>=2
  Using cached charset_normalizer-2.1.1-py3-none-any.whl (39 kB)
Collecting urllib3<1.27,>=1.21.1
  Using cached urllib3-1.26.12-py2.py3-none-any.whl (140 kB)
Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests, text-to-list
Successfully installed certifi-2022.9.24 charset-normalizer-2.1.1 idna-3.4 requests-2.28.1 text-to-list-0.0.1 urllib3-1.26.12

https://github.com/Natgho/text-to-list

Bir başka yazımda görüşmek üzere, proje örneğine yukarıdaki Github linkinden ulaşabilirsiniz 🙂

Kaynaklar;

https://packaging.python.org/en/latest/tutorials/packaging-projects/
https://github.com/psf/requests
https://github.com/tomchen/example_pypi_package
https://towardsdatascience.com/create-your-own-python-package-and-publish-it-into-pypi-9306a29bc116