Как сделать свою библиотеку python
Перейти к содержимому

Как сделать свою библиотеку python

  • автор:

How to create a Python library

Kia Eisinga

Ever wanted to create a Python library, albeit for your team at work or for some open source project online? In this blog you will learn how to!

The tutorial is easiest to follow when you are using the same tools, however it is also possible for you to use different ones.

The tools used in this tutorial are:
— Linux command prompt
— Visual Studio Code

Step 1: Create a directory in which you want to put your library
Open your command prompt and create a folder in which you will create your Python library.

Remember:
— With pwd you can see your present working directory.
— With ls you can list the folders and files in your directory.
— With cd <path> you can change the current present directory you are in.
— With mkdir <folder> you can create a new folder in your working directory.

In my case, the folder I will be working with is mypythonlibrary . Change the present working directory to be your folder.

Step 2: Create a virtual environment for your folder
When starting your project, it is always a good idea to create a virtual environment to encapsulate your project. A virtual environment consists of a certain Python version and some libraries.

Virtual environments prevent the issue of running into dependency issues later on. For example, in older projects you might have worked with older versions of the numpy library. Some old code, that once worked beautifully, might stop working once you update its version. Perhaps parts of numpy are no longer compatible with other parts of your program. Creating virtual environments prevents this. They are also useful in cases when you are collaborating with someone else, and you want to make sure that your application is working on their computer, and vice versa.

(Make sure you changed the present working directory to the folder you are going to create your Python library in ( cd <path/to/folder> ).)

Go ahead and create a virtual environment by typing:
> python3 -m venv venv

Once it is created, you must now activate the environment by using:
> source venv/bin/activate

Activating a virtual environment modifies the PATH and shell variables to point to the specific isolated Python set-up you created. PATH is an environmental variable in Linux and other Unix-like operating systems that tells the shell which directories to search for executable files (i.e., ready-to-run programs) in response to commands issued by a user. The command prompt will change to indicate which virtual environment you are currently in by prepending ( yourenvname ).

In your environment, make sure you have pip installed wheel , setuptools and twine . We will need them for later to build our Python library.
> pip install wheel
> pip install setuptools
> pip install twine

Step 3: Create a folder structure
In Visual Studio Code, open your folder mypythonlibrary (or any name you have given your folder). It should look something like this:

You now can start adding folders and files to your project. You can do this either through the command prompt or in Visual Studio Code itself.

  1. Create an empty file called setup.py . This is one of the most important files when creating a Python library!
  2. Create an empty file called README.md . This is the place where you can write markdown to describe the contents of your library for other users.
  3. Create a folder called mypythonlib , or whatever you want your Python library to be called when you pip install it. (The name should be unique on pip if you want to publish it later.)
  4. Create an empty file inside mypythonlib that is called __init__.py . Basically, any folder that has an __init__.py file in it, will be included in the library when we build it. Most of the time, you can leave the __init__.py files empty. Upon import, the code within __init__.py gets executed, so it should contain only the minimal amount of code that is needed to be able to run your project. For now, we will leave them as is.
  5. Also, in the same folder, create a file called myfunctions.py .
  6. And, finally, create a folder tests in your root folder. Inside, create an empty __init__.py file and an empty test_myfunctions.py .

Your set-up should now look something like this:

Step 4: Create content for your library
To put functions inside your library, you can place them in the myfunctions.py file. For example, copy the haversine function in your file:

This function will give us the distance in meters between two latitude and longitude points.

Whenever you write any code, it is highly encouraged to also write tests for this code. For testing with Python you can use the libraries pytest and pytest-runner . Install the library in your virtual environment:
> pip install pytest==4.4.1
> pip install pytest-runner==4.4

Let’s create a small test for the haversine function. Copy the following and place it inside the test_myfunctions.py file:

Finally, let’s create a setup.py file, that will help us to build the library. A limited version of setup.py will look something like this:

The name variable in setup holds whatever name you want your package wheel file to have. To make it easy, we will gave it the same name as the folder.

Set the packages you would like to create
While in principle you could use find_packages() without any arguments, this can potentially result in unwanted packages to be included. This can happen, for example, if you included an __init__.py in your tests/ directory (which we did). Alternatively, you can also use the exclude argument to explicitly prevent the inclusion of tests in the package, but this is slightly less robust. Let’s change it to the following:

Set the requirements your library needs
Note that pip does not use requirements.yml / requirements.txt when your project is installed as a dependency by others. Generally, for that, you will have to specify dependencies in the install_requires and tests_require arguments in your setup.py file.

Install_requires should be limited to the list of packages that are absolutely needed. This is because you do not want to make users install unnecessary packages. Also note that you do not need to list packages that are part of the standard Python library.

However, since we have only defined the haversine function so far and it only uses the math library (which is always available in Python), we can leave this argument empty.

Maybe you can remember us installing the pytest library before. Of course, you do not want to add pytest to your dependencies in install_requires : it isn’t required by the users of your package. In order to have it installed automatically only when you run tests you can add the following to your setup.py :

Running:
> python setup.py pytest
will execute all tests stored in the ‘tests’ folder.

Step 5: Build your library
Now that all the content is there, we want to build our library. Make sure your present working directory is /path/to/mypythonlibrary (so the root folder of your project). In your command prompt, run:
> python setup.py bdist_wheel

Your wheel file is stored in the “dist” folder that is now created. You can install your library by using:
> pip install /path/to/wheelfile.whl

Note that you could also publish your library to an internal file system on intranet at your workplace, or to the official PyPI repository and install it from there.

Once you have installed your Python library, you can import it using:
import mypythonlib
from mypythonlib import myfunctions

How to create Python library

Python programming language is extremely popular not only because it is easy to use but because it has lots of third-party libraries which really help in shortening development time. But how do you make one? I wondered the same thing and decided to create a simple Python library. The process of creating a library is not exactly straightforward so I decided to author this article which will hopefully help other people who are creating Python library for the first time or who are just trying to refresh memory on a certain step.

Introduction

Article will go over how to make simple Python library. More specifically, REST API client for FreeGeoIp’s API [1]. It will describe project structure, how to use setup.py , how to add unit tests to project and how to publish created library to PyPI using GitHub Actions as CI/CD solution.

Project structure

Project has straightforward and basic structure. There is one module — freegeoip_client , actual Python library we are trying to build here. tests folder which contains all unit tests and last, but not least, setup.py and setup.cfg files which are used to create Python package — more on them in Setuptools section.

Exit fullscreen mode

Python’s __init__.py file

__init__.py allows us to mark a directory as a Python package directory which enables importing Python code from one Python file into another. Also, it can be useful to define any variable at the package level. Doing so is often convenient if a package defines something that will be imported frequently, in an API-like fashion. If you are interested in learning more about this, there is an interesting Reddit thread covering appropriate uses of __init__.py file [2].

When creating Python library, __init__.py is used to import key functions and/or classes from various modules directly into the package namespace and thus enabling end-users to use Python module in an API-like fashion.

Exit fullscreen mode

Unit tests

In computer programming, unit testing is a software testing method by which individual units of source code—sets of one or more computer program modules together with associated control data, usage procedures, and operating procedures—are tested to determine whether they are fit for use.

Adding unit tests is always highly recommended since tests enable us to test edge cases which in return results in higher code quality and more robust code.

One of the more popular unit test frameworks for Python is pytest framework [3]. It makes it easy to write small, readable tests in a pythonic way. If you are not familiar with it, I would encourage you to check it out.

python-freegeoip-client project uses pytest framework for unit tests and requests-mock library for mocking API responses [4].

Exit fullscreen mode

Setuptools

Setuptools is a collection of enhancements to the Python distutils that allow developers to more easily build and distribute Python packages, especially ones that have dependencies on other packages.

Using setuptools you package Python code into, well, a package that can be imported in different scripts, either by installing it locally or by installing it using PyPI repository. Packaging Python code can be done using setup.py file, or, the preferred way, using pyproject.toml and setup.cfg files. I am, however, using setup.py file because there is pip bug where it is not possible to install packages locally when using pyproject.toml and setup.cfg files [5].

setup.py file for this Python project:

Exit fullscreen mode

If you are interested in setup.py file in more detail, there is an excellent article about it and how to use it [6].

The Python Package Index (PyPI) is a repository of software for the Python programming language.

By default, pip — package installer for Python — uses PyPI repository as the source for retrieving package dependencies. PyPI lets you find, install, and even publish your Python packages so that they are widely available to the public.

To publish packages to PyPI, you need to register an account [7] or login with the previously registered one [8]. Once logged in to PyPI, head over to Account settings and add new API token under API tokens section. API token will be required in the next step to publish package via GitHub Actions so make sure that you saved it.

Screenshot 2022-05-23 at 20.21.19.png

Click on Add API token button:

NOTE: For purposes of this blog, I’ve selected token scope as «Entire account (all projects)», but it is advised to have each API token on PyPI scoped only to a certain project.

GitHub Actions

Automate, customize, and execute your software development workflows right in your repository with GitHub Actions. You can discover, create, and share actions to perform any job you’d like, including CI/CD, and combine actions in a completely customized workflow.

GitHub Actions are free to use with each GitHub repository. You can set it up using the Actions tab in GitHub repository and clicking on New workflow button or you can directly add .github/workflow folder to your project code with .yml file in the folder that defines certain workflow.

Before creating CI/CD workflow, we need to add previously created API token to GitHub Secrets. Open your GitHub project and go to the Settings tab. Then select Secrets and finally Actions. Click on New repository secret button on top of the page. Name repository secret as PYPI_API_TOKEN and add API token’s value.

Screenshot 2022-05-23 at 20.42.04.png

Once done with this step, we can move on to defining workflow using .yml file that is saved within .github/workflow folder.

Setting up environment and dependencies

We need to define when CI/CD workflow will run and what environment will be used.

Exit fullscreen mode

Here we defined the name of the workflow, when workflow will run — on each push to main branch, and what environment will be used — latest version of Ubuntu Linux. We also defined the step which will install necessary Python dependencies.

Linting and running unit tests

Before publishing package to PyPI, we need to make sure that code is formatted correctly and that all unit tests are passing. This can be achieved by adding two additional steps to the workflow.

Exit fullscreen mode

Building and publishing to PyPI

The last step is to build the Python package — creating source distribution using sdist — and upload it to PyPI.

Exit fullscreen mode

Here we are using pypa/gh-action-pypi-publish@release/v1 GitHub Actions workflow from Marketplace to make publishing to PyPI easier [9]. Workflow will do all the heavy lifting to upload package to PyPI, we just need to provide our API token saved to repository secrets using $<< secrets.PYPI_API_TOKEN >> syntax.

And that’s it! We have GitHub actions workflow that will publish our Python library to the PyPI and make sure that code is formatted correctly, and all unit tests are passing successfully before publishing.

Conclusion

Thank you for reading and I hope this article was useful to you! In conclusion, this article went step-by-step over creating and publishing Python library to PyPI automatically using GitHub Actions CI/CD workflow.

If you like my content and find it useful, please consider following me. If you are feeling extra generous, please consider buying me a coffee.

Как создать свой первый open source проект на Python (17 шагов)

Каждый разработчик ПО должен знать как создать библиотеку с нуля. В процессе работы Вы можете многому научиться. Только не забудьте запастись временем и терпением.

Может показаться, что создать библиотеку с открытым исходным кодом сложно, но Вам не нужно быть потрепанным жизнью ветераном своего дела, чтобы разобраться в коде. Также как Вам не нужна мудреная идея продукта. Но точно понадобятся настойчивость и время. Надеюсь, что данное руководство поможет Вам создать первый проект с минимальной затратой и первого, и второго.

В этой статье мы пошагово разберем процесс создания базовой библиотеки на Python. Не забудьте заменить в приведенном ниже коде my_package, my_file и т.п. нужными вам именами.

Шаг 1: Составьте план

Мы планируем создать простую библиотеку для использования в Python. Данная библиотека позволит пользователю легко конвертировать блокнот Jupyter в HTML-файл или Python-скрипт.
Первая итерация нашей библиотеки позволит вызвать функцию, которая выведет определенное сообщение.

Теперь, когда мы уже знаем, что хотим делать, нужно придумать название для библиотеки.

Шаг 2: Дайте имя библиотеке

Придумывать имена сложно. Они должны быть короткими, уникальными и запоминающимися. Также они должны быть написаны строчными буквами, без прочерков и прочих знаков препинания. Подчеркивание не рекомендуется. В процессе создания библиотеки убедитесь, что придуманное Вами имя доступно на GitHub, Google и PyPi.

Если Вы надеетесь и верите, что однажды Ваша библиотека получит 10000 звезд GitHub, то стоит проверить, доступно ли данное имя в социальных сетях. В данном примере я назову свою библиотеку notebookc, потому что это имя доступное, короткое и более-менее описывает суть моей задумки.

Шаг 3. Настройте среду

Убедитесь, что у вас установлены и настроены Python 3.7, GitHub и Homebrew. Если вам нужно что-то из этого, вот подробности:

Python

Скачайте Python 3.7 здесь и установите его.

GitHub

Если у вас нет учетной записи GitHub, перейдите по этой ссылке и оформите бесплатную подписку. Посмотрите, как установить и настроить Git здесь. Вам потребуется утилита командной строки. Перейдите по ссылкам, скачайте и установите все, что Вам понадобится, придумайте юзернейм и укажите электронную почту.

Homebrew

Homebrew — менеджер библиотек для Mac. Инструкции по установке найдете здесь.

Начиная с Python 3.6 рекомендуется использовать venv для создания виртуальной среды для разработки библиотек. Существует множество способов управления виртуальными средами с помощью Python и все они со временем изменяются. Можете ознакомиться с обсуждением здесь, но, как говорится, доверяй, но проверяй.

Начиная с версии Python 3.3 venv входит в систему по умолчанию. Обратите внимание, что venv устанавливает pip и setuptools начиная с Python 3.4.

Создайте виртуальную среду Python 3.7 с помощью следующей команды:

python3.7 -m venv my_env

Замените my_env вашим именем. Активируйте среду таким образом:

Теперь вы должны наблюдать (my_env) (или имя, которое вы выбрали для вашей виртуальной среды) в крайнем левом углу терминала.

Когда закончите работу, деактивируйте виртуальную среду с помощью deactivate .

Теперь давайте настроим GitHub.

Шаг 4: Создайте организацию в GitHub

GitHub — лидер на рынке реестров контроля версий. Еще две популярные опции — GitLab и Bitbucket. В данном гиде мы будем использовать именно GitHub.

Вам придется часто обращаться к Git и GitHub, поэтому если Вы не знакомы с системой, то можете обратиться к моей статье.

Создайте новую организацию в GitHub. Следуйте инструкциям. Я назвал свою организацию notebooktoall. Вы можете создать репозиторий под своей личной учетной записью, но одна из целей работы — научиться создавать проект с открытым исходным кодом для более широкого сообщества.

image

Шаг 5: Настройте GitHub Repo

Создайте новый репозиторий. Я назвал свой notebookc.

image

Добавьте .gitignore из выпадающего списка. Выберите Python для своего репозитория. Содержимое Вашего файла .gitignore будет соответствовать папкам и типам файлов, исключенным из вашего хранилища. Вы можете позже изменить .gitignore, чтобы исключить другие ненужные или конфиденциальные файлы.

Рекомендую выбрать лицензию в списке Выбрать лицензию. Она определяет, что могут делать пользователи Вашего репозитория. Одни лицензии позволяют больше других. Если Вы ничего не выбираете, то автоматически начинают действовать стандартные законы об авторских правах. Узнайте больше о лицензиях здесь.

Для этого проекта я выбрал третью версию Открытого лицензионного соглашения GNU, потому что она популярная, проверенная и “гарантирует пользователям свободу использования, изучения, обмена и изменения программного обеспечения” — источник.

image

Шаг 6: Клонируйте и добавьте директории

Выберите, куда Вы хотите клонировать Ваш репозиторий или выполните следующую функцию:

git clone https://github.com/notebooktoall/notebookc.git

Подставьте свою организацию и репозиторий.

Перейдите в папку проекта с помощью десктопного графического интерфейса или редактора кода. Или используйте командную строку с cd my-project и после просмотрите файлы с ls —A .

Ваши исходные папки и файлы должны выглядеть так:

.git
.gitignore
LICENSE
README.rst

Создайте вложенную папку для основных файлов проекта. Я советую назвать ее так же, как и вашу библиотеку. Убедитесь, что в имени нет пробелов.

Создайте файл с именем __init__.py в основной вложенной папке. Этот файл пока останется пустым. Он необходим для импорта файлов.

Создайте еще один файл с таким же именем, как у основной вложенной папки, и добавьте .py. Мой файл называется notebookc.py. Вы можете назвать этот Python-файл как захотите. Пользователи библиотеки при импорте модуля будут ссылаться на имя этого файла.

Содержимое моей директории notebookc выглядит следующим образом:

.git
.gitignore
LICENSE
README.rst
notebookc/__init__.py
notebookc/notebookc.py

Шаг 7: Скачайте и установите requirements_dev.txt

На верхнем уровне директории проекта создайте файл requirements_dev.txt. Часто этот файл называют requirements.txt. Назвав его requirements_dev.txt, Вы показываете, что эти библиотеки могут устанавливаться только разработчиками проекта.

В файле укажите, что должны быть установлены pip и wheel.

Обратите внимание, что мы указываем точные версии библиотек с двойными знаками равенства и полными номерами версии.

Закрепите версии вашей библиотеку в requirements_dev.txt

Соавтор, который разветвляет репозиторий проекта и устанавливает закрепленные библиотеки require_dev.txt с помощью pip, будет иметь те же версии библиотеки, что и Вы. Вы знаете, что эта версия будет работать у них. Кроме того, Read The Docs будет использовать этот файл для установки библиотек при сборке документации.

В вашей активированной виртуальной среде установите библиотеку в файл needs_dev.txt с помощью следующей команды:

pip install -r requirements_dev.txt

Настоятельно рекомендую обновлять эти библиотеки по мере выхода новых версий. На данный момент установите любые последние версии, доступные на PyPi.

В следующей статье расскажу, как установить инструмент, облегчающий этот процесс. Подпишитесь, чтобы не пропустить.

Шаг 8: Поработайте с кодом

В целях демонстрации давайте создадим базовую функцию. Свою собственную крутую функцию сможете создать позже.

Вбейте следующее в Ваш основной файл (для меня это notebookc/notebookc/notebookc.py):

Вот наша функция во всей красе.

Строки документа начинаются и заканчиваются тремя последовательными двойными кавычками. Они будут использованы в следующей статье для автоматического создания документации.
Сохраните изменения. Если хотите освежить память о работе с Git, то можете заглянуть в эту статью.

Шаг 9: Создайте setup.py

Файл setup.py — это скрипт сборки для вашей библиотеки. Функция setup из Setuptools создаст библиотеку для загрузки в PyPI. Setuptools содержит информацию о вашей библиотеке, номере версии и о том, какие другие библиотеки требуются для пользователей.

Вот мой пример файла setup.py:

Обратите внимание, что long_description установлен на содержимое файла README.md. Список требований (requirements), указанный в setuptools.setup.install_requires, включает в себя все необходимые зависимости для работы вашей библиотеки.

В отличие от списка библиотек, требуемых для разработки в файле require_dev.txt, этот список должен быть максимально разрешающим. Узнайте почему здесь.

Ограничьте список install_requires только тем, что Вам надо — Вам не нужно, чтобы пользователи устанавливали лишние библиотеки. Обратите внимание, что необходимо только перечислить те библиотеки, которые не являются частью стандартной библиотеки Python. У Вашего пользователя и так будет установлен Python, если он будет использовать вашу библиотеку.
Наша библиотека не требует никаких внешних зависимостей, поэтому Вы можете исключить четыре библиотеки, перечисленных в примере выше.

Соавтор, который разветвляет репозиторий проекта и устанавливает закрепленные библиотеки с помощью pip, будет иметь те же версии, что и Вы. Это значит, что они должны работать.
Измените информацию setuptools так, чтобы она соответствовала информации вашей библиотеки. Существует множество других необязательных аргументов и классификаторов ключевых слов — см. перечень здесь. Более подробные руководства по setup.py можно найти здесь и здесь.

Сохраните свой код в локальном репозитории Git. Пора переходить к созданию библиотеки!

Шаг 10: Соберите первую версию

Twine — это набор утилит для безопасной публикации библиотек Python на PyPI. Добавьте библиотеку Twine в следующую пустую строку файла require_dev.txt таким образом:

Затем закрепите Twine в Вашей виртуальной среде, переустановив библиотеки needs_dev.txt.

Затем выполните следующую команду, чтобы создать файлы библиотеки:

Необходимо создать несколько скрытых папок: dist, build и — в моем случае — notebookc.egg-info. Давайте посмотрим на файлы в папке dist. Файл .whl — это файл Wheel — встроенный дистрибутив. Файл .tar.gz является исходным архивом.

На компьютере пользователя pip будет по мере возможности устанавливать библиотеки как wheels/колеса. Они устанавливаются быстрее. Когда pip не может этого сделать, он возвращается к исходному архиву.

Давайте подготовимся к загрузке нашего колеса и исходного архива.

Шаг 11: Создайте учётную запись TestPyPI

PyPI — каталог библиотек Python (Python Package Index). Это официальный менеджер библиотек Python. Если файлы не установлены локально, pip получает их оттуда.

TestPyPI — это работающая тестовая версия PyPI. Создайте здесь учетную запись TestPyPI и подтвердите адрес электронной почты. Обратите внимание, что у Вас должны быть отдельные пароли для загрузки на тестовый сайт и официальный сайт.

Шаг 12: Опубликуйте библиотеку в PyPI

Используйте Twine для безопасной публикации вашей библиотеки в TestPyPI. Введите следующую команду — никаких изменений не требуется.

Вам будет предложено ввести имя пользователя и пароль. Не забывайте, что TestPyPI и PyPI имеют разные пароли!

При необходимости исправьте все ошибки, создайте новый номер версии в файле setup.py и удалите старые артефакты сборки: папки build, dist и egg. Перестройте задачу с помощью python setup.py sdist bdist_wheel и повторно загрузите с помощью Twine. Наличие номеров версий в TestPyPI, которые ничего не значат, особой роли не играют — Вы единственный, кто будет использовать эти версии библиотек.

После того, как Вы успешно загрузили свою библиотеку, давайте удостоверимся, что Вы можете установить его и использовать.

Шаг 13: Проверьте и используйте установленную библиотеку

Создайте еще одну вкладку в командном интерпретаторе и запустите другую виртуальную среду.

Если Вы уже загрузили свою библиотеку на официальный сайт PyPI, то сможете выполнить команду pip install your-package . Мы можем извлечь библиотеку из TestPyPI и установить его с помощью измененной команды.

Вот официальные инструкции по установке вашей библиотеки из TestPyPI:

Вы можете заставить pip загружать библиотеки из TestPyPI вместо PyPI, указав это в index-url.

Если хотите, чтобы pip также извлекал и другие библиотеки из PyPI, Вы можете добавить — extra-index-url для указания на PyPI. Это полезно, когда тестируемая библиотека имеет зависимости:

Если у вашей библиотеки есть зависимости, используйте вторую команду и подставьте имя вашей библиотеки.

Вы должны увидеть последнюю версию библиотеки, установленного в Вашей виртуальной среде.

Чтобы убедиться, что Вы можете использовать свою библиотеку, запустите сеанс IPython в терминале следующим образом:

Импортируйте свою функцию и вызовите ее со строковым аргументом. Вот как выглядит мой код:

После я получаю следующий вывод:

(Когда-нибудь я конвертирую для тебя блокнот, Джефф)

Шаг 14: Залейте код на PyPI

Залейте Ваш код на настоящий сайт PyPI, чтобы люди могли скачать его с помощью pip install my_package .

Загрузить код можно так:

Обратите внимание, что Вам нужно обновить номер версии в setup.py, если Вы хотите залить новую версию в PyPI.

Отлично, теперь давайте загрузим нашу работу на GitHub.

Шаг 15: Залейте библиотеку на GitHub

Убедитесь, что Ваш код сохранен.

Моя папка проекта notebookc выглядит так:

Исключите любые виртуальные среды, которые Вы не хотите загружать. Файл Python .gitignore, который мы выбрали при создании репозитория, не должен допускать индексации артефактов сборки. Возможно, Вам придется удалить папки виртуальной среды.

Переместите вашу локальную ветку на GitHub с помощью git push origin my_branch .

Шаг 16: Создайте и объедините PR

В браузере перейдите к GitHub. У Вас должна появиться опция сделать pull-запрос. Нажимайте на зеленые кнопки, чтобы создать, объединить PR и чтобы убрать удаленную ветку.
Вернувшись в терминал, удалите локальную ветку с git branch -d my_feature_branch .

Шаг 17: Обновите рабочую версию на GitHub

Создайте новую версию библиотеки на GitHub, кликнув на релизы на главной странице репозитория. Введите необходимую информацию о релизе и сохраните.

На сегодня достаточно!

Мы научимся добавлять другие файлы и папки в будущих статьях.
А пока давайте повторим шаги, которые мы разобрали.

Итог: 17 шагов к рабочей библиотеке

  1. Составьте план.
  2. Дайте имя библиотеке.
  3. Настройте среду.
  4. Создайте организацию в GitHub.
  5. Настройте GitHub Repo.
  6. Клонируйте и добавьте директории.
  7. Скачайте и установите requirements_dev.txt.
  8. Поработайте с кодом.
  9. Создайте setup.py.
  10. Соберите первую версию.
  11. Создайте учётную запись TestPyPI.
  12. Опубликуйте библиотеку в PyPI.
  13. Проверьте и используйте установленную библиотеку.
  14. Залейте код на PyPI.
  15. Залейте библиотеку на GitHub.
  16. Создайте и объедините PR.
  17. Обновите рабочую версию на GitHub.

Узнайте подробности, как получить востребованную профессию с нуля или Level Up по навыкам и зарплате, пройдя платные онлайн-курсы SkillFactory:

Как написать, упаковать и распространять библиотеку на Python.

Python — отличный язык программирования, но упаковка — одна из его самых слабых точек. Это общеизвестный в сообществе факт. За последние годы установка, импорт, использование и создание пакетов значительно улучшилась, но она все еще не соответствует новым языкам, таким как Go и Rust, которые многому научились в борьбе с Python и другими зрелыми языками.

В этом уроке вы узнаете все, что вам нужно знать о написании, упаковке и распространении собственных пакетов.

Как написать библиотеку Python

Библиотека Python представляет собой согласованный набор модулей Python, который организован как пакет Python. В общем, это означает, что все модули живут под одним и тем же каталогом и этот каталог находится на пути поиска Python.

Давайте быстро напишем небольшой пакет Python 3 и проиллюстрируем все эти понятия.

Пакет Pathology

Python 3 имеет отличный объект Path, который является большим улучшением по сравнению с неудобным модулем Os.path Python 2. Но ему не хватает одной важной возможности — найти путь к текущему сценарию. Это очень важно, если вы хотите найти файлы доступа относительно текущего скрипта.

Во многих случаях сценарий может быть установлен в любом месте, поэтому вы не можете использовать абсолютные пути, а рабочий каталог может быть установлен на любое значение, поэтому вы не можете использовать относительный путь. Если вы хотите получить доступ к файлу в подкаталоге или родительском каталоге, вы должны иметь возможность определить текущий каталог сценариев.

Вот как вы это делаете в Python:

Чтобы получить доступ к файлу с именем «file.txt» в подкаталоге данных в каталоге текущего скрипта, вы можете использовать следующий код:print(open(str(script_dir/»data/file.txt»).read())

С пакетом pathology у вас есть встроенный метод script_dir, и вы используете его следующим образом:

Да, это глоток свежего воздуха. Пакет патологии очень прост. Он выводит свой собственный класс Path из Pathlib Path и добавляет статический script_dir(), который всегда возвращает путь вызывающего скрипта.

Из-за кросс-платформенной реализации pathlib.Path вы можете получить непосредственно от него и должны быть получены из определенного подкласса (PosixPath или WindowsPath). Разрешение dir-файла сценария использует модуль проверки, чтобы найти вызывающего, а затем его атрибут имени файла.

Тестирование пакета патологии

Всякий раз, когда вы пишете нечто более сложное, вы должны его протестировать. Модуль патологии не является исключением. Вот тесты с использованием стандартной модульной тестовой платформы:

Путь Python

Пакеты Python должны быть установлены где-то на пути поиска Python, который должен быть импортирован модулями Python. Путь поиска Python представляет собой список каталогов и всегда доступен в sys.path . Вот мой текущий sys.path:

Обратите внимание, что первая пустая строка вывода представляет текущий каталог, поэтому вы можете импортировать модули из текущего рабочего каталога, что бы это ни было. Вы можете напрямую добавлять или удалять каталоги в / из sys.path.

Вы также можете определить переменную среды PYTHONPATH, и есть несколько других способов ее контролировать. Стандартные site-packages включены по умолчанию, и именно там устанавливаются пакеты, которые вы устанавливаете с помощью pip.

Как упаковать библиотеку Python

Теперь, когда у нас есть наш код и тесты, давайте упакуем все это в нужную библиотеку. Python обеспечивает простой способ через модуль настройки. Вы создаете файл setup.py в корневом каталоге вашего пакета. Затем, чтобы создать исходный дистрибутив, вы запустите: python setup.py sdist

Чтобы создать двоичный дистрибутив, называемый колесом, вы запускаете: python setup.py bdist_wheel

Вот файл setup.py пакета патологии:

Он включает в себя множество метаданных в дополнение к элементу «packages», который использует функцию find_packages() , импортированную из s e tuptools, чтобы найти подпакеты.

Давайте построим дистрибутив источника:

Предупреждение связано с тем, что я использовал нестандартный файл README.md. Это безопасно поэтому игнорируем. Результатом является файл tar-gzipped в каталоге dist:

И вот двоичное распределение:

Пакет патологии содержит только чистые модули Python, поэтому можно создать универсальный пакет. Если ваш пакет включает расширения C, вам нужно будет создать отдельное колесо для каждой платформы:

Для более глубокого погружения в тему упаковки библиотек Python ознакомьтесь, как писать свои собственные пакеты Python .

Как раздавать пакет Python

Python имеет центральный репозиторий пакетов, называемый PyPI (индекс пакетов Python). Когда вы устанавливаете пакет Python с помощью pip, он загружает пакет из PyPI (если вы не укажете другой репозиторий). Чтобы распространять наш пакет патологии, нам нужно загрузить его в PyPI и предоставить некоторые дополнительные метаданные, которые требуется PyPI. Шаги:

  • Создайте учетную запись на PyPI (только один раз).
  • Зарегистрируйте свой пакет.
  • Загрузите свой пакет.

Создайте аккаунт

Вы можете создать учетную запись на веб-сайте PyPI . Затем создайте файл .pypirc в своем домашнем каталоге:

В целях тестирования вы можете добавить «pypitest» индексный сервер в ваш .pypirc файл:

Зарегистрируйте свой пакет

Если это первый выпуск вашего пакета, вам необходимо зарегистрировать его с помощью PyPI. Используйте команду register setup.py. Она попросит вас ввести пароль. Обратите внимание, что я указываю его на тестовый репозиторий:

Загрузите свой пакет

Теперь, когда пакет зарегистрирован, мы можем его загрузить. Я рекомендую использовать twine , который более безопасен. Установите его, как обычно, с помощью pip install twine . Затем загрузите свой пакет с помощью twine и укажите свой пароль (отредактированный ниже):

Для более глубокого погружения в тему распространения ваших пакетов ознакомьтесь с разделом «Пакеты Python» .

Заключение

В этом уроке мы прошли полноценный процесс написания библиотеки Python, ее упаковки и распространения через PyPI. На этом этапе у вас должны быть все инструменты для написания и обмена вашими библиотеками с остальным миром.

Кроме того, не стесняйтесь посмотреть, что у нас есть для продажи и для изучения на рынке , и, пожалуйста, задавайте любые вопросы и предоставляйте свою ценную обратную связь, используя приведенный ниже канал.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *