Пишемо обгортку над API, робимо з неї PIP-пакет, підключаємо тестування від Travis CI і дивимося на ліцензії відкритого



Вітаю, Хабрахабр! Дана стаття буде корисна бажаючим ознайомитися не тільки з оформленням власного пакету Python Package Index (PIP), але і з різними допоміжними інструментами, що допомагають супроводжувати розробку на всіх стадіях — на прикладі авторської роботи.

Необхідні інструменти:
  • середовище розробки — написання об'єктно-орієнтованого коду, тісно працює з інтерфейсом програми (у нашому випадку веб-сайту), іншими словами — написання та обробка запитів до API, і додаткових допоміжних файлів;
  • завантаження своїх напрацювань в загальний каталог пакетів — PyPI;
  • Github — створення репозиторію з метою контролю якості, поліпшення і перманентного оновлення бібліотеки, спільної взаємодії з областю відкритого вихідного коду;
  • одна з ліцензій вільного програмного забезпечення, в нашому випадку — MIT License;
  • Travis CI — безперервна зборка і тестування розроблюваного проекту у різних середовищах (наприклад, різні версії мови або інтерпретатора).
Даний список можна приймати за зміст статті у відповідному порядку.

Хочу додати, що переходити за запропонованими матеріалами, в яких зазначено багато важливої і цікавої інформації, не обов'язково — ви все одно отримаєте необхідні дані для завершення подібного проекту і вже тоді вирішите, чи варто вам використовувати додаткові посилання.

Введення
Я — постійний відвідувач різних інтернет-ресурсів, у тому числі одного відомого українського співтовариства програмістів, а за сумісництвом і постійно практикуючий програміст, — тому за браком ідей кинувся конструювати реалізацію статистики публікацій (на прикладі Хабрахабра) (див. малюнок нижче) для користувачів майданчики. Не важливо, в якому вигляді проект буде реалізований, але проміжної завданням є предмет обговорення статті — робота з API цього сайту, що в значній мірі полегшується написанням власної обгортки (PIP-пакета), включаючи безсумнівні додаткові плюси від розробки — наприклад, цікава нова область і набутий досвід.



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

Приклад остаточного варіанту — DouAPI (посилання на github, тримайте її відкритою паралельно зі статтею і звертайтеся для деталізації описуваного, не забудьте прочитати опис репозиторію). У ньому відсутні потрібні файли для тестування і якісь допоміжні рішення (наприклад, винести в окреме місце об'ємний код, який виконує форматування рядків або обробку додаткових запитів), але тільки із-за відсутності такої вимоги на даному етапі розробки.

Безпосередньо структура самого пакету повинна складатися з головного каталогу, підкаталогу з основними і допоміжними файлами і файлу дистрибуції «setup.py».



Для більшої ясності варто почати опис з реалізації модуля «api.py» посилання на github — імпортування модуля Requests, який дозволяє звертатися з HTTP-запитами на покращеному рівні.

import requests

Створення безпосередньо окремого класу для звернення за заданим до API сайту за заданим URL певним методом. Якщо ваша розробка буде обмежуватися якимись факторами і створення додаткового класу для запитів зайво — створюйте закритий метод вже в основному класі, але якщо ви не знаєте, як далеко зайде проект, які фічі ви захочете додати і яка складність вас чекає — зайвим не буде, щоб не витрачати час на переписування коду.

class DouAPI(object):

def method(self, method, values=None):

if values is not None: values['limit'] = 10000

response = requests.get('https://api.dou.ua/{0}/'.format(method), params=values)

if response.status_code == 200:
return response.json()['results']
else:
message = 'A request to the Dou API was unsuccessful. The server returned HTTP {0} {1}.'
return message.format(response.status_code, response.reason)

Виклик функції «method», приймає назву методу, яке відповідає необхідному URL і набору ключів-значень (HTTP Headers), повертає результат у вигляді формату JSON (такий же набір ключів-значень) в успішному випадку, і просто рядок з кодом помилки і причиною відповіді в іншому випадку (так намагайтеся не робити, краще створювати окремо свої власні винятки, як написано тут або здесь).
Клас, до якого далі звертається програміст через об'єкт (все інше, що виходить за рамки необхідних інструментів, загортайте в приватні змінні і методи, містить одну функцію «lenta», повертає об'єкт класу з методом запитів, передаючи назву методу «articles» та набір ключів-значень (наприклад, категорію і автора).

class Dou():
__slots__ = ('_dou')

def __init__(self):
self._dou = DouAPI()

def lenta(self, category=None, tag=None, author=None, date_from=None, date_to=None):

values = locals().copy()
values.pop('self')

values = {header:value for header, value in values.items() if value != None}

return self._dou.method('articles', values=values)

Так в підсумку виглядає приклад використання обгортки — імпортуємо необхідний клас, створюємо об'єкт, звертаємося до методу класу, вказуючи параметри, отримуємо дані у форматі JSON.

from dou import Dou

dou = Dou()

news = dou.lenta(category = 'news', date_from='2016-06-01')

print(news)

Якщо проілюструвати процес, взаємодія відбувається наступним чином:


Тепер розглянемо момент з файлом
«__init__.py», що дозволяє проініціалізувати клас реалізації на рівні звернення до каталогу, записуємо в нього наступне (посилання на github).

from .api import Dou

Фінальний етап — «setup.py» посилання на github) описує ряд даних, які необхідні для складання проекту з исходников (детальніше тут — зрозуміліше стане на практиці, коли повзаимодействуете з архівацією і розподілом пакета. Описувати що-небудь зайве, все повинно бути зрозуміло інтуїтивно.

try:
from setuptools import setup
except ImportError:
from distutils.core import setup

setup(
name='DouAPI',
version='1.0.0',
author='DmytryiStriletskyi',
author_email='dmytryi.striletskyi@gmail.com',
url='https://github.com/DmytryiStriletskyi/DouAPI',
description='Dou API wrapper',
download_url='https://github.com/DmytryiStriletskyi/DouAPI/archive/master.zip',
license='MIT',

packages=['dou'],
install_requires=['requests'],

classifiers=[
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 2.7',
'Programming Language :: Python :: 3.4',
'Programming Language :: Python :: 3.5',
]
)

Python Package Index (PIP)
У мережі існує безліч інструкцій по інсталяції пакетів в загальний каталог, тому в даній статті я буду описувати один-єдиний метод, який виявився найбільш зручним і продуктивним для мене:

  1. Реєструємо профіль PyPI;
  2. встановлюємо утиліту «Twine» для реєстрації та завантаження пакетів (детальніше тут) прямо в корінь проекту — «pip install twine»;
  3. комплектуємо дистрибутив — «python setup.py sdist»;
  4. наступний етап — «колеса», це сучасний формат розповсюдження (фактично архівні дані) пакетів — «python setup.py bdist_wheel» (детальніше тут і тут;
  5. реєстрація проекту — необхідно передати зазначені метадані («setup.py»), які розташовані у файлі PKG-INFO (знаходиться всередині архівованого проекту);
  6. фінальний етап — завантажити пакет — «twine upload dist/*».
Докладне керівництво розташоване за адресою, є варіант використання тестового сервера авторизації з каталогу тут, в мережі доступний матеріал російською мовою.

Інші взаємодії відбуваються через особистий аккаунт в PyPI: видалення, редагування, журнал історій, релізи, ролі і так далі.

Репозиторій пакета
Якщо виконана робота в перспективі може стати затребувана аудиторією, потрібно зробити наступний ряд заходів: створити власне сховище, оформити титульний аркуш проекту (README.md), підключити тестування і вибрати ліцензію. Якщо з першими двома файлами все зрозуміло, то наступні вимагають уточнень.

Ліцензія відкритого програмного забезпечення
Існує різноманітне безліч ліцензій, але лідируючі позиції займають MIT License, Apache License і GPL. Я використовую першу —
вона дозволяє використання і зміна коду будь-яким чином (за умови наявності копірайту), а також має маленький розмір. Існують і мінуси — відсутня патентне право, властиве іншим ліцензіями, але маленьким проектів дана ліцензія підходить добре.

Наприклад, ось так виглядає ліцензія в моєму репозиторії — MIT License, Github сам поставить наявність ліцензії у верхню панельку репозиторію.

Тестування проекту
Travis CI — якщо описати простими словами, то кожна зміна у вашому проекті тестується на вами зазначених середовищах. Дана майданчик досить легка у використанні — поміщаємо файл (посилання на github з назвою «.travis.yml» в кореневий каталог, у якому вказують: мова програмування, необхідні версії, інтерпретатори мови, які залежно встановити при інтеграції і розгортанні на сервері, плагін тестування і ще ряд параметрів.

Плюсів дуже багато, крім самого тестування — зручний інтерфейс з безліччю відображень статусу тестування, помилок, історії, швидке підключення, перевірка користувальницьких комітів в ваш проект до злиття. Також «Тревіс» повідомляє про результати поштою.


Першим ділом встановлюємо гак на репозиторій, слідом додаємо файл «.travis.yml», потім пушим зміни в проекті і спостерігаємо за результатами.


Буду радий, якщо дана стаття допоможе кому-небудь в освоєнні нового матеріалу або збудить інтерес до цієї області. Надсилайте свої запитання та поради, якщо вони у вас є, в особисті повідомлення.
Джерело: Хабрахабр

0 коментарів

Тільки зареєстровані та авторизовані користувачі можуть залишати коментарі.