Що робити, якщо потрібний Вам модуль підтримує тільки Python 2: покрокове керівництво


Дізнайтесь більше про нові кар'єрні можливості в EchoUA. Цікаві проекти, ринкова оплата, гарний колектив. Надсилайте резюме та приєднуйтеся до нас.

Розповідає Ентоні Шоу


Перед Вами невелика інструкція для розв’язання поширеної проблеми: при роботі над проектом виявляється, що один з необхідних Вам модулів не підтримує Python 3. Для прикладу взята клієнтська бібліотека для Qualys (засіб забезпечення безпеки). Ось що Вам слід зробити:

 

0. Упевнитися, що це питання ще не вирішене

До того як почати, перевірте, чи не стикався хтось раніше з такою ж проблемою, досліджуйте GitHub. Подивіться, можливо, на PyPi знайдеться відповідний пакет, у якому містяться оновлення для Python 3.

1. Зробити форк

Якщо пошуки все ж ні до чого не привели, приступайте до зміни вибраного модуля. Зазначимо, що зазвичай на PyPi вказуються підтримувані версії Python. У модулів, працюючих тільки з Python 2, ця інформація часто буває опущена. У даному прикладі ця частина опису модуля виглядає таким чином:

Отже, відкрийте основний проект на GitHub. До того як вносити будь-які зміни, обов’язково створіть його форк, потім скачайте або клонуйте репозиторій і створіть нову гілку. Назвою для неї буде, наприклад, “python3”.

Якщо Вам неясно, як виконати ці дії, читайте наше керівництво по Git для новачків.

2. Виправити оператори print

Треба розібратися до розв’язання проблем з імпортуванням з тим, чи це звичайнісінькі оператори виведення? Старі оператори print без дужок – одна з найпоширеніших перешкод, з якою можна зіткнутися в контексті переходу від Python 2 до Python 3. У третьому кроці ми використовуватимемо пакет Python – Modernize, що полегшує цей перехід, але його робота не торкнеться README, документації та деяких інших файлів. Щоб знайти абсолютно всі старі оператори print у межах модуля, скористайтеся рекурсивним пошуком по вкладених директоріях:

fgrep - r "print ".

Ви побачите, що деякі з виведених на екран відповідностей знаходяться в директорії git, ігноруйте їх. Усі інші знайдені оператори print замініть на функції print () у будь-якому текстовому редакторові, а після створіть з виправлень єдиний коміт командою:

git commit - a - m "print to python 3"

3. Провести тести

“Кращий” спосіб перевірити сумісність Python 2 і 3 – через повне тестування і CI сервіси типу Circle, Snap чи Travis. На жаль, для модернізованого Вами модуля жодних тестів немає. І у Вас залишається два варіанти:

  • написати тести самому;
  • провести статичний аналіз коду.

Якщо Ви сумніваєтеся, що другий варіант може Вам чимось допомогти, прочитайте нашу статтю про статичний аналізатор.

Статичний аналіз. Встановіть Python-Modernize:

pip install modernize

Спочатку запустіть його в режимі info:

python - modernize qualysapi

Це дозволить отримати загальне уявлення про те, які зміни будуть внесені. Все влаштовує? Тоді запускайте процес змін наступною командою:

python - modernize - wn qualysapi

Потім зробіть з них окремий коміт.

Додавання тестів. Перша перевірка: чи можна імпортувати модуль, пакет, підмодуль? Цей тест розкриває багато проблем у Python 3, пов’язаних з просторами імен. Використайте Tox для проведення тестування в різному оточенні.

Друга перевірка: чи є в проекті обробка рядків. На тему рядків у Python 3 інформація значно більше, ніж можна вмістити в цьому посту, але Ви можете звернутися до проекту six, у якому розглядається проблема визначення, чи є об’єкт рядком, а також використання юні-коду і методів байтової конвертації.

Третя перевірка передбачає наявність деякого досвіду в роботі з модулем. Ви не зможете відразу зайнятися юніт-тестуванням на основі наявної кодової бази, якщо не розумітимете, наскільки коректно вона працює на даний момент. Рухайтеся у зворотному напрямі – сфокусуйтеся на інтеграційному тестуванні, а від нього перейдіть до юніт-тестів. Спробуйте спершу написати простий скрипт, який використовує модуль за його прямим призначенням, а потім доповнюйте його іншими сценаріями використання. Якщо Ви вже налаштувалися пропустити цю перевірку, то прочитайте наш матеріал про користь юніт-тестування. 

4. Оновити setup.py

Відкрийте setup.py і подивіться, які зміни в нього треба внести, щоб упевнено заявляти, що модуль, який розглядається нами, тепер підтримує Python 3 :

setup (name=__pkgname__, version=__version__, author='Parag Baxi', author email='parag.baxi@gmail.com', description='QualysGuard (R) Qualys API Package', license ='BSD - new', keywords ='Qualys QualysGuard API helper network security', url='https://github.com/paragbaxi/qualysapi', package_dir={'': '.'}, packages=['qualysapi',], # package_data={'qualysapi':['LICENSE']}, # scripts=['src/scripts/qhostinfo.py', 'src/scripts/qscanhist.py', 'src/scripts/qreports.py'], long_description=read ('README.md'), classifiers=[ 'Development Status :: 5 - Production/Stable', 'Topic :: Utilities', 'License :: OSI Approved :: Apache Software License', 'Intended Audience :: Developers',], install_requires=[ 'requests',],
)

На що точно варто звернути увагу:

  1. У коді вище виявилася як вказівка ліцензії BSD, так і ліцензії Apache 2. При цьому в кодових файлах говориться Apache 2, а в директорії взагалі немає файлу LICENSE. Така ситуація могла виникнути через помилку, пов’язану з копіпастом, тому в даному випадку її логічно виправити в setup.py, а потім додати відповідний файл LICENSE.
  2. Розмітка в PyPi не відображається. Можна з цим змиритися, можна додати RST файл. Головне, пам’ятаєте про те, що це все ж не Ваший проект.
  3. Не написано, яку версію Python підтримує модуль. Додайте цю інформацію в setup.py.
  4. Використання Python-Modernize означає, що цей модуль залежний від пакета six. Позначте це в полі install_requires. Перевірте, чи всі вказані там пакети, від яких залежить змінюваний модуль, підтримують Python 3.

Подивимося, що вийшло:

setup (name=__pkgname__, version=__version__, author='Parag Baxi', author email='parag.baxi@gmail.com', description='QualysGuard (R) Qualys API Package', license="Apache License (2.0)", keywords ='Qualys QualysGuard API helper network security', url='https://github.com/paragbaxi/qualysapi', package_dir={'': '.'}, packages=['qualysapi',], # package_data={'qualysapi':['LICENSE']}, # scripts=['src/scripts/qhostinfo.py', 'src/scripts/qscanhist.py', 'src/scripts/qreports.py'],
long_description=read ('README.md'), classifiers=[ 'Development Status :: 5 - Production/Stable', 'Topic :: Utilities', 'License :: OSI Approved :: Apache Software License', 'Intended Audience :: Developers', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 3'], install_requires=[ 'requests', 'six'], )

5. Завантажити в основний проект

Повернемося до початку. При роботі над Вашим проектом Ви зіткнулися з тим, що один з модулів не підтримує Python 3. Ви позбавилися проблем сумісності, тепер треба вказати оновлену версію модуля у файлі requirements.txt. Переконайтеся в тому, що Ви спочатку запустили зміни на GitHub, скориставшись командою:

git push origin python3

Pip дозволяє Вам установлювати необхідне не лише з PyPi, але й прямо з репозиторія Git. Ви можете вказати конкретну гілку, використовуючи символ @. Параметр egg= використовується, щоб передати Pip ім’я пакету.

pip - e git+https://github.com/tonybaloney/[email protected]#egg=qualysapi

На цьому етапі можна продовжити запуск інтеграційних тестів для нової версії.

6. Відправити пул реквест

Тепер треба поділитися своєю роботою з автором і співтовариством Python на GitHub. Дотримуйтеся таких правил спілкування :

  1. Будьте ввічливими.
  2. Поясніть, що хотіли б використати цей модуль з Python 3.
  3. Подякуйте автору за його роботу зі створення модуля.
  4. Прокоментуйте, що зробили.

Ось такий пул реквест вийшов за підсумками розглянутого прикладу. Зачекайте, поки Ваші зміни заллють у проект, після чого чекайте, коли на PyPi з’явиться оновлення. (Точніше, сподівайтеся на те, що воно там з’явиться).

7. Нарешті, через три місяці

…автор пакета не залив Ваший код. Таке трапляється. Зазвичай це відбувається, коли людина підтримувала проект, поки використовувала його у рамках своєї робочої діяльності, а потім змінила місце роботи. Поверніться до setup.py і задайте модулю нове ім’я (не змінюючи поле packages), за типом “qualysapi-py3”. Зробіть пуш в PyPi, а потім оновіть повідомлення у Вашому пул реквесті, вказавши це нове ім’я. Тепер, коли хтось ще шукатиме допомогу з Python 3 для використання цього модуля, він побачить Ваший пост.

Переклад статті “Oh no! This package is Python 2 only”

Київ, Харків, Одеса, Дніпро, Запоріжжя, Кривий Ріг, Вінниця, Херсон, Черкаси, Житомир, Хмельницький, Чернівці, Рівне, Івано-Франківськ, Кременчук, Тернопіль, Луцьк, Ужгород, Кам'янець-Подільський, Стрий - за статистикою саме з цих міст програмісти найбільше переїжджають працювати до Львова. А Ви розглядаєте relocate?


Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *