Створення python-пакетів (aka setup scripts)
Одна з справді корисних речей у python – це система скриптів установки. Будь-який розробник, що серйозно захоплюється python-програмуванням, рано чи пізно стикається з нею. Але через гнучкість інструментарію скриптів установки їх документація дуже роздута. На даний момент є набір утиліт (setuptools, distutils, distribute), що виконують однакові завдання.
У цій статті я на конкретних прикладах покажу як створити та налаштувати простий python-пакет.
Наш проект матиме таку функціональність:
- Метод, що повертає рядок: "Hello World!";
- Команда Helloworld друкує цей рядок у стандартний висновок.
Створюємо структуру проекту
Для початку створимо директорію для пакета. Її мінімальний набір файлів складається з: файлу дистриб'юції ( setup.py ), що описує метадані та python коду проекту (у нашому випадку модуля helloworld).
Також, гарним тоном вважається створення в корені директорії файлу з описом проекту: README.txt.
Отримуємо таку структуру:
Наша коренева директорія helloworld-project міститиме мета-дані пакета та допоміжні файли (тести, ліцензію, документацію тощо), а піддиректорія helloworld безпосередньо сам модуль helloworld.
Тепер відредагуємо файл: helloworld/core.py та додамо логіку нашої програми (отримання та виведення рядка "Hello World!"):
Редагуємо мета-інформацію (setup.py)
Заповнимо файл опису README.rst :
Тепер відредагуємо файл setup.py:
Переконайтеся, що у вашій системі доступні setuptools, інакше встановіть python-пакет distribute
Цих операцій достатньо, щоби зібрати пакет дистриб'юції. Виконайте команду збирання:
УУ разі успіху ви отримаєте файл: dist/helloworld-1.0.tar.gz . Це повноцінний, архівований python-пакет і ви можете розповсюджувати його серед інших розробників.
Віртуальне оточення
Virtualenv — пакет, який використовується для створення ізольованого python-оточення. Використовуємо її для тестування нашого проекту.
Створимо оточення env:
Команда створить директорію env всередині нашого проекту та встановить туди python, pip та distribute. Зробимо в нього встановлення нашого проекту.
І протестуємо його працездатність:
Все працює. Залишилося додати підтримку команди Helloworld в консолі.
Створення команд
Для створення команди helloworld змінимо файл setup.py:
У параметрі entry_points ми задаємо словник із "точками виклику" нашої програми. Ключ console_scripts задає список створюваних скриптів (у Windows це будуть exe-файли). В даному випадку ми вказали створення скрипта helloworld, що виконується, при викликі якого буде запускатися метод print_message з модуля helloworld.core.
Перевстановимо модуль у наше оточення і перевіримо роботу створеного скрипта (для цього доведеться активувати наше оточення):
Схоже, все працює.
Робота з версіями
Номер версії є важливою частиною будь-якого проекту. Від нього залежить оновлення пакетів та дозвіл залежностей. У прикладі вище ми вказали номер версії 1.0 у файлі setup.py. Більше правильне рішення перенести його у файл helloworld/__init__.py щоб зробити доступним у python-коді. За існуючими угодами для зберігання номера версії в модулі використовується змінна __version__.
Змінимо файл setup.py , щоб нам не доводилося редагувати номер версії у двох місцях:
Існує безліч систем найменування версій уPython зазвичай рекомендується використовувати PEP386. Можна припустити, що позначення версії складається з номера мажорного, мінорного релізів (номеру багфіксу за потреби), розділених крапками. В останній частині версії можна використовувати літери латинського алфавіту. Приклади з офіційної документації:
Управління залежностями
Додамо функціональності нашому проекту. Створимо команду serve, яка буде запускати вебсервер, що віддає сторінку з рядком "Hello world!" генерується нашим модулем. Для цього скористаємося пакетом Flask.
Додаємо файл helloworld/web.py :
І файл helloworld/templates/index.html:
І опишемо команду serve у файлі setup.py:
Тепер у нашому проекті з'явилася залежність від пакету Flask. Без його встановлення наша програма не буде правильно працювати. За опис залежностей файлу setup.py відповідає параметр install_requires:
Перевіримо встановлення залежностей оновивши наш пакет та роботу команди serve:
Керування файлами проекту (MANIFEST.in)
На даний момент при складанні нашого пакету distutils включає в нього тільки python-файли. Необхідно включити файл helloworld/templates/index.html без якого проект працювати не буде.
Щоб зробити це, ми повинні повідомити distutils які ще файли треба включати в наш проект. Одним із способів є створення файлу MANIFEST.in :
Ця команда вказує distutils на включення до проекту всіх html файлів у директорії helloworld/templates .
Також доведеться оновити setup.py:
Тепер шаблони будуть включені до нашого проекту.
Створення та запуск тестів
Хорошою практикою є створення тестів для вашого проекту. Додамо найпростішу реалізацію, файл tests.py :
І оновимо setup.py:
Тепер ми можемо провести попереднє тестування нашого проекту:
Зверніть увагу, що для запуску тестів навіть не потрібне створення віртуального оточення. Необхідні залежності будуть завантажені до директорії проекту у вигляді egg пакетів.