hug
2.6.0
Прочитайте последнюю документацию - просмотр репозитория кода GitHub
Hug стремится сделать разработку API, управляемых Python максимально простым, но не проще. В результате он резко упрощает разработку Python API.
Цели дизайна Hug:
Сделайте разработку API, управляемого на питоне таким кратким, как письменное определение.
Структура должна поощрять код этого самообслуживания.
Это должно быть быстро. Разработчик никогда не должен чувствовать необходимость смотреть куда -нибудь еще по соображениям производительности.
Написание тестов для API, написанных на вершине объятий, должно быть легким и интуитивно понятным.
Волшебство, сделанное один раз, в рамках API лучше, чем подтолкнуть проблему, установленную пользователю Framework API.
Будьте основой для API Python следующего поколения, используя новейшие технологии.
В результате этих целей Hug - это только Python 3+, и он построен на высокой HTTP Library Falcon.
Получите профессиональную поддержку объятия с подпиской Tidelift
Профессиональная поддержка Hug доступна как часть подписки Tidelift. Tidelift дает командам разработки программного обеспечения один источник для покупки и поддержания своего программного обеспечения, с профессиональными гарантиями от экспертов, которые знают его лучше всего, в то же время беспрепятственно интегрируются с существующими инструментами.
Установка объятий так же просто, как:
PIP3 установить объятие -обновлять
В идеале, в виртуальной среде.
Создайте пример API с простой конечной точкой всего за несколько строк.
# FileName: Happy_birthday.py "" "" Базовая (единственная функция) API, написанный с использованием hug "" "import [email protected] ('/happy_birthday') def happy_birthday (имя, возраст: hug.types.number = 1): "" "Снимательно с днем рождения пользователю" "return" Happy {Age} день рождения {name}! ". Format (** locals ())
Запустить, из типа командной строки:
Hug -f happy_birthday.py
Вы можете получить доступ к примеру в своем браузере по адресу: localhost:8000/happy_birthday?name=hug&age=1 . Затем ознакомьтесь с документацией для вашего API на localhost:8000/documentation
Параметры также могут быть закодированы в URL (проверьте happy_birthday.py для всего примера).
@hug.get ('/regret/{event}') def Greet (Event: str): "" "Приветствует соответствующим образом (с http://blog.ketchum.com/how-to-write-10-common-holiday -greetings/) "" "" Приветствуюсь = "счастливое" if event == "Рождество": приветствие = "Merry" if event == "kwanzaa": приветствия = "Jogyous", если событие == "желания": rewings = "Теплый "return" {приветствия} {event}! ". Format (** locals ())Который, как только вы запустите сервер, как указано выше, вы можете использовать таким образом:
curl http://localhost:8000/greet/wishes "Warm wishes!"
# FileName: versioning_example.py "" "" простой пример звонка API API с версией "" "Import [email protected] ('/echo', version = 1) def echo (text): return [email protected]. ('/echo', version = range (2, 5)) def echo (text): return "echo: {text}". format (** locals ())
Чтобы запустить пример:
Hug -f versioning_example.py
Затем вы можете получить доступ к примеру от localhost:8000/v1/echo?text=Hi / localhost:8000/v2/echo?text=Hi или доступ к документации для вашего API от localhost:8000
ПРИМЕЧАНИЕ. Разведение версии в HUG автоматически поддерживает как заголовок версии, так и спецификацию на основе прямых URL.
Декораторы http от HTTP's Decorators не изменяют ваши оригинальные функции. Это делает тестирование API так же простым, как тестирование любых других функций Python. Кроме того, это означает взаимодействие с вашими функциями API в другом коде Python так же просто, как и вызов только функции API Python. Hug позволяет легко проверить полный стек Python вашего API, используя модуль hug.test :
Импорт hugimport happy_birthdayhug.test.get (Happy_birthday, 'Happy_birthday', {'name': 'timothy', 'Age': 25}) # Возвращает объект ответа Вы можете использовать этот объект Response для утверждений тестирования (посмотрите на test_happy_birthday.py ):
def tests_happy_birthday (): response = gug.test.get (happy_birthday, 'happy_birthday', {'name': 'timothy', 'Age': 25}) assert response.status == http_200ssert response.data не это Hug автоматически разоблачает магический метод __hug_wsgi__ на каждом модуле API. Запуск вашего API на основе объятий на любом стандартном сервере WSGI должен быть таким же простым, как указать его на module_name : __hug_wsgi__ .
Например:
UWSGI--HTTP 0.0.0.0:8000-WSGI-FILE примеры/hello_world.py-Callable __hug_wsgi__
Чтобы запустить пример API Hello World Hug.
При построении API с помощью платформы объятия вы используете следующие концепции:
Декораторы метода get , post , update и т. Д.
@hug.get () # <- это метод объятия decoratordef hello_world (): вернуть "Привет"
Hug использует структуру функции, которую вы украшаете, для автоматического генерации документации для пользователей вашего API. Hug всегда передает переменную запроса, ответа и API_version в вашу функцию, если они определены параметры в определении вашей функции.
Тип Функции аннотаций , которые необязательно прикрепляются к вашим аргументам, чтобы указать, как аргумент подтвержден и преобразуется в тип Python
@hug.get () def Math (number_1: int, number_2: int): #the: int после обоих аргументов - это тип AnnotationTretur number_1 + number_2
Типовые аннотации также включаются в генерацию автоматической документации hug , чтобы пользователи вашего API знали, какие данные предоставляют.
Директивы функции, которые выполняются с помощью данных запроса / ответа на основе запроса в качестве аргумента в вашем API_FUNCTION. Они применяются только в качестве входных параметров и не могут применяться в настоящее время в качестве выходных форматов или преобразований.
@hug.get () def test_time (ug_timer): return {'time_taken': float (hug_timer)} Доступ к директивам можно получить с помощью аргумента с префиксом hug_ или с помощью аннотаций типа Python 3. Последний - более современный подход, и рекомендуется. Директивы, объявленные в модуле, можно получить, используя их полностью квалифицированное имя в качестве аннотации типа (например: module.directive_name ).
Помимо очевидного варианта использования преобразования ввода, директивы могут использоваться для передачи данных в ваши функции API, даже если они не присутствуют в строке запроса запроса, корпусе пост и т. Д. Для примера того, как использовать директивы таким образом, См. Пример аутентификации в папке примеров.
Добавление собственных директив прямо:
@hug.directive () def square (value = 1, ** kwargs): '' 'returns передается в параметре, умноженное само по себе' 'return value *[email protected] ()@hug.local () def tester ( Значение: square = 10): return valuetester () == 100
Для полноты, вот пример доступа к директиве с помощью подхода Magic Name:
@hug.directive () def intemply (value = 1, ** kwargs): '' 'returns Multipled Multipled Multiple' '' return *[email protected] ()@hug.local () def tester ( hug_multiply = 10): вернуть hug_multiplytester () == 100
Выходные форматеры Функция, которая принимает вывод вашей функции API и форматирует ее для транспортировки пользователю API.
@hug.default_output_format () def my_output_formatter (data): return "string: {0}". format (data)@hug.get (output = hug.output_format.json) def hello (): return {'hello': ' мир'}Как показано, вы можете легко изменить выходной формат как для всего API, так и для отдельного вызова API
Входные форматеры Функция, которая берет тело данных, приведенных пользователем вашего API, и форматирует ее для обработки.
@hug.default_input_format ("application/json") def my_input_formatter (data): return ('results', ug.input_format.json (data)) Форматиры ввода отображаются на основе content_type данных запроса и выполняют только базовый анализ. Более подробный анализ должен быть сделан с помощью типовых аннотаций, присутствующих на вашем api_function
Функции промежуточного программного обеспечения , которые вызываются для каждого запроса, процессы API объятия
@hug.request_middleware () def process_data (request, response): request.env ['server_name'] = 'medice'@hug.response_middleware () def process_data (запрос, ответ, resource): response.set_header (' myheader ', 'Ценить')Вы также можете легко добавить любое промежуточное программное обеспечение в стиле Falcon, используя:
__hug __. http.add_middleware (MiddlewareObject ())
Картирование параметров может использоваться для переопределения предполагаемых имен параметров, например. Для зарезервированных ключевых слов:
Import Marshmallow.fields As Fields [email protected] ('/foo', map_params = {'from': 'from_date'}) # api call использует 'from get_foo_by_date (from_date: fields.dateTime ()): вернуть find_foo (from_date)
Форматиры ввода отображаются на основе content_type данных запроса и выполняют только базовый анализ. Более подробный анализ должен быть сделан с помощью типовых аннотаций, присутствующих на вашем api_function
Hug позволяет вам организовать крупные проекты любым способом, который вы считаете нужным. Вы можете импортировать любой модуль, который содержит функции, украшенные объятиями (обработка запросов, директивы, обработчики типов и т. Д.) И расширить ваш базовый API с помощью этого модуля.
Например:
something.py
Импорт [email protected] ('/') def say_hi (): вернуть «Привет от чего -то»
Может быть импортирован в основной файл API:
__init__.py
Импорт обниматься. Импортировать что -то @hug.get ('/') def say_hi (): return "hi from root"@hug.extend_api ('/something') def comething_api (): return [что -то]Или альтернативно - для подобных случаев - где только один модуль включен по маршруту URL:
#Альтернативно hog.api (__ name __). Extend (что -то, '/что -то')
По умолчанию Hug возвращает автоматическую сгенерированную спецификацию API, когда пользователь пытается получить доступ к конечной точке, которая не определена. Если вы не хотите возвращать эту спецификацию, вы можете отключить 404 документацию:
Из приложения командной строки:
Hug -nd -f {file} #nd Flag сообщает Hug не генерировать документацию на 404 Кроме того, вы можете легко создать пользовательский обработчик 404, используя декоратор hug.not_found :
@hug.not_found () def not_found_handler (): вернуть "не найдено"
Этот декоратор работает так же, как и декораторы HTTP HTTP, и даже знает версию:
@hug.not_found (versions = 1) def not_found_handler (): return ""@hug.not_found (versions = 2) def not_found_handler (): return "не найдено"
При использовании декоратора метода get и cli на CORUTINES HUG планирует выполнение COROUTINE.
Использование декоратора Asyncio Coroutine
@hug.get ()@asyncio.coroutededef hello_world (): return "Привет"
Использование ключевого слова Python 3.5 Async.
@hug.get () async def hello_world (): вернуть "Привет"
Примечание: Hug работает на Top Falcon, который не является асинхронным сервером. Даже при использовании Asyncio запросы все еще будут обрабатываться синхронно.
Если вам нравится развиваться в Docker и сохранить свою систему в чистоте, вы можете сделать это, но вам нужно сначала установить Docker Compose.
После того, как вы это сделаете, вам понадобится cd в каталоге docker и запустите веб -сервер (стреляющий), указанный в ./docker/gunicorn/Dockerfile , после чего вы можете предварительно просмотреть вывод API в браузере на вашем хост -машина.
$ CD ./docker# Это будет работать над стрельцом на порту 8000 контейнера Docker. $ Docker-Compake Up Gunicorn# из хост-машины, найдите IP-адрес Dockers.# для Windows & Mac: $ Docker-Machine IP Default# для# Linux: $ ifconfig docker0 | grep 'inet' | Cut -d: -f2 | awk '{print $ 1}' | голова -n1 По умолчанию IP составляет 172.17.0.1. Предполагая, что это IP, который вы видите, вы затем отправитесь на http://172.17.0.1:8000/ в своем браузере, чтобы просмотреть ваш API.
Вы также можете войти в контейнер Docker, который вы можете рассмотреть свое рабочее пространство. В этом рабочем пространстве установлены Python и PIP, поэтому вы можете использовать эти инструменты в Docker. Например, если вам нужно проверить интерфейс CLI, вы бы использовали это.
$ Docker-Compose Run Workspace Bash
В вашем контейнере workspace Docker, каталог ./docker/templates на вашем хост -компьютере установлен в /src в контейнере Docker. Это указано в services > app ./docker/docker-compose.yml .
Bash-4.3# CD /SRC
bash-4.3# tree.├íмобил __init__.py
Handlers
├-- -дни рождения. Пусть
Hello.py.py
1 каталог, 3 файлаОбъятие относится к безопасности и качеству серьезно. Это направлено на то, почему мы зависим только от тщательно протестированных компонентов и используем инструменты статического анализа (например, бандит и безопасность) для проверки безопасности нашей кодовой базы. Если вы найдете или столкнетесь с какими -либо потенциальными проблемами безопасности, пожалуйста, сообщите нам об этом сразу же, чтобы мы могли их разрешить.
Чтобы сообщить об уязвимости безопасности, пожалуйста, используйте контакт с безопасностью TIDELIFT. Tidelift будет координировать исправление и раскрытие.
Объятие просто означает, надеюсь, полезное руководство. Это представляет цель проекта, чтобы помочь разработчикам создать хорошо написанные и интуитивные API.
Спасибо, и я надеюсь, что вы найдете это объятие полезным, когда вы разрабатываете свой следующий Python API!
~ Тимоти Кросли
