hug
2.6.0
最新のドキュメントを読む-Githubコードリポジトリを参照してください
ハグは、Python駆動型のAPIを可能な限りシンプルにすることを目指していますが、簡単ではありません。その結果、Python API開発を大幅に簡素化します。
ハグのデザインの目的：
書面による定義と同じくらい簡潔なPython駆動型APIを開発します。
フレームワークは、自己ドキュメントのコードを奨励する必要があります。
速いはずです。開発者は、パフォーマンス上の理由で他の場所を見る必要性を決して感じてはなりません。
抱擁のオントップと書かれたAPIのテストを書くことは、簡単で直感的でなければなりません。
APIフレームワークで行われた魔法は、APIフレームワークのユーザーに設定された問題をプッシュするよりも優れています。
次世代のPython APIの基礎となり、最新のテクノロジーを採用してください。
これらの目標の結果、ハグはPython 3+のみであり、Falconの高性能HTTPライブラリの上に構築されています
Tideliftサブスクリプションを使用して、プロがサポートされているハグを取得します
HUGの専門的なサポートは、Tideliftサブスクリプションの一部として利用できます。 Tideliftは、ソフトウェア開発チームに、ソフトウェアを購入して維持するための単一のソースを提供し、既存のツールとシームレスに統合しながら、それを最もよく知っている専門家からの専門的な成績を保証します。
ハグのインストールは、次のように簡単です。
PIP3インストールHUG-アップグレード
理想的には、仮想環境内。
ほんの数行で単純なエンドポイントを使用してAPIの例を作成します。
＃filename：happy_birthday.py "" "hug" "" Import [email protected]（ '/happy_birthday'）def happy_birthday（name、age：gag.types.number = 1）： "" "ユーザーにハッピーバースデーを言う" "" return "happy {age}誕生日{name}！"。フォーマット（** locals（））
コマンドラインタイプから実行するには：
hug -f happy_birthday.py
ブラウザの例にアクセスできます： localhost:8000/happy_birthday?name=hug&age=1 。次に、 localhost:8000/documentationでAPIのドキュメントをご覧ください
パラメーターはURLでエンコードすることもできます（例全体についてhappy_birthday.pyをチェックしてください）。
@hug.get（ '/greet/{event}'）def greet（event：str）： "" "" greets from from http://blog.ketchum.com/how-to-write-10-common-holiday -greeTings/） "" "greegings =" Happy "if event ==" Christmas "：greed =" merry "if event ==" kwanzaa "：greetings =" joyous "if event ==" wishes "：greed ="暖かい"return" {greetings} {event}！ "。format（** locals（））上記のようにサーバーを実行したら、次の方法で使用できます。
curl http://localhost:8000/greet/wishes "Warm wishes!"
＃filename：versioning_example.py "" "" hug api call with versioning "" "[email protected]（ '/echo'、versions = 1）def echo（text）：return [email protected] （ '/echo'、versions = 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またはlocalhost:8000のAPIのドキュメントにアクセスできます
注：HUGのバージョン化は、バージョンヘッダーとダイレクトURLベースの仕様の両方を自動的にサポートします。
HAGのhttpメソッドデコレーターは、元の機能を変更しません。これにより、ハグAPIのテストは、他のPython関数をテストするのと同じくらい簡単になります。さらに、これは、他のPythonコードのAPI関数との対話が、PythonのみのAPI関数を呼び出すのと同じくらい簡単であることを意味します。 HUGを使用して、 hug.testモジュールを使用して、APIの完全なPythonスタックを簡単にテストできます。
Hugimport happy_birthdayhug.test.get（happy_birthday、 'happy_birthday'、{'name'： 'timothy'、 'age'：25}）をインポートするこのResponseオブジェクトをテストアサーションに使用できます（ test_happy_birthday.pyをご覧ください）：
def tests_happy_birthday（）：respons = hug.test.get（happy_birthday、 'happy_birthday'、{'name'： 'timothy'、 'age'：25}）assert response.status == http_200assert応答。Hugは、すべてのAPIモジュールに__hug_wsgi__マジックメソッドを自動的に公開します。標準のWSGIサーバーでハグベースのAPIを実行することは、 module_name ： __hug_wsgi__を指すのと同じくらい簡単です。
例えば：
UWSGI -HTTP 0.0.0.0:8000 -WSGI-FILE例/hello_world.py - callable __hug_wsgi__
Hello World Hugの例APIを実行するには。
ハグフレームワークを使用してAPIを構築する場合、次の概念を使用してください。
メソッドデコレータは、 Pythonメソッドを変更せずにPython機能をAPIとして公開するHTTPメソッドデコレータget 、 post 、 updateなど
@hug.get（）＃< - hugメソッドdecoratordef hello_world（）：return "hello"
Hugは、飾る関数の構造を使用して、APIのユーザー向けのドキュメントを自動的に生成します。 HUGは、関数定義でパラメージが定義されている場合、常にリクエスト、応答、およびAPI_version変数を関数に渡します。
タイプアノテーション関数は、オプションでメソッド引数に添付されており、引数が検証され、Pythonタイプに変換される方法を指定します
@hug.get（）def math（number_1：int、number_2：int）：＃the：int両方の引数がタイプAnnotationReturn number_1 + number_2です
また、タイプの注釈は、 hugの自動ドキュメント生成にフィードして、APIのユーザーがどのデータを提供するかを知らせます。
api_functionの引数として要求されることに基づいて、要求 /応答データで実行されるディレクティブ関数。これらは入力パラメーターとしてのみ適用され、現在出力形式または変換として適用することはできません。
@hug.get（）def test_time（hug_timer）：return {'time_taken'：float（hug_timer）}}ディレクティブは、 hug_プレフィックスを使用した引数を介して、またはPython 3タイプのアノテーションを使用してアクセスできます。後者はより近代的なアプローチであり、推奨されます。モジュールで宣言されたディレクティブは、完全に適格な名前をタイプアノテーション（ex： module.directive_name ）として使用してアクセスできます。
明らかな入力変換のユースケースは別として、ディレクティブを使用して、リクエストクエリ文字列、ポストボディなどに存在しない場合でも、この方法でディレクティブを使用する方法の例として、データをAPI関数にパイプすることができます。例フォルダーの認証例を参照してください。
独自のディレクティブを追加するのは簡単です：
@hug.directive（）def square（value = 1、** kwargs）： '' 'パラメーターで渡された返品自体' '' return value *[email protected]（）@hug.local（）def tester（値：square = 10）：returnvaluetester（）== 100を返します
完全性については、魔法の名前アプローチを介して指令にアクセスする例を次に示します。
@hug.directive（）def Multiply（value = 1、** kwargs）： '' 'パラメーターで合格したパラメーターで渡されます' '' return value *[email protected]（）@hug.local（）def tester（）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'、hug.input_format.json（data）））
入力フォーマッタは、リクエストデータのcontent_typeに基づいてマッピングされ、基本的な解析のみを実行します。より詳細な解析は、 api_functionに存在するタイプの注釈によって行う必要があります
すべてのリクエストに対して呼び出されるミドルウェア関数ハグAPIプロセス
@hug.request_middleware（）def process_data（request、response）：request.env ['server_name'] = 'chander'@hug.response_middleware（）def process_data（request、response、resource）：respons.set_header（' myheader '、 '価値'）
：Falconスタイルのミドルウェアを使用して簡単に追加することもできます。
__hug __。http.add_middleware（middlewareobject（））
パラメーターマッピングを使用して、推定されたパラメーター名をオーバーライドできます。予約されたキーワードの場合：
marshmallow.fieldsをフィールドとしてインポート[email protected]（ '/foo'、map_params = {'from'： 'from_date'}） find_foo（from_date）を返します
入力フォーマッタは、リクエストデータのcontent_typeに基づいてマッピングされ、基本的な解析のみを実行します。より詳細な解析は、 api_functionに存在するタイプの注釈によって行う必要があります
HUGを使用すると、どんな方法でも大規模なプロジェクトを整理できます。ハグ装飾機能（リクエスト処理、ディレクティブ、タイプハンドラーなど）を含む任意のモジュールをインポートし、そのモジュールでベースAPIを拡張できます。
例えば：
something.py
[email protected]（ '/'）def say_hi（）をインポートする：「何かからhello 'を返す」
メインAPIファイルにインポートできます。
__init__.py
Hugfromをインポートします。 somethingsomeming（ '/'）def say_hi（）： "hir fromoot"@hug.extend_api（ '/something'）def monthy_api（）：return [something]を返します
または、このようなケースの場合 - URLルートに従って1つのモジュールのみが含まれている場合：
＃altionallyhug.api（__ name __）。拡張（何か、 '/何か'）
デフォルトでは、HAGは、ユーザーが定義されていないエンドポイントにアクセスしようとするときに自動生成API仕様を返します。この仕様を返したくない場合は、404ドキュメントをオフにすることができます。
コマンドラインアプリケーションから：
hug -nd -f {file} #nd flagは、404でドキュメントを生成しないように抱きしめますさらに、 hug.not_foundデコレーターを使用してカスタム404ハンドラーを簡単に作成できます。
@hug.not_found（）def not_found_handler（）：return "not not inged"
このデコレーターは、HAG HTTPメソッドデコレーターと同じ方法で機能し、バージョンでも認識されています。
@hug.not_found（バージョン= 1）def not_found_handler（）：return ""@hug.not_found（versions = 2）def not_found_handler（）：return "not not" not "
Coroutinesでget and cliメソッドデコレーターを使用する場合、HugはCoroutineの実行をスケジュールします。
Asyncio Coroutineデコレーターの使用
@hug.get（）@asyncio.coroutinedef hello_world（）：return "hello"
Python 3.5 Asyncキーワードを使用します。
@hug.get（）async def hello_world（）： "hello"を返します
注：ハグは、非同期サーバーではないトップファルコンで実行されています。 Asyncioを使用しても、リクエストは同期して処理されます。
Dockerで開発してシステムを清潔に保ちたい場合は、それを行うことができますが、最初にDocker Composeをインストールする必要があります。
それを完了したら、 dockerディレクトリにcdを使用して、 ./docker/gunicorn/Dockerfile /docker/gunicorn/dockerfileで指定されたWebサーバー（Gunicorn）を実行する必要があります。その後、ブラウザのAPIの出力をプレビューできます。ホストマシン。
$ cd ./docker#これは、Dockerコンテナのポート8000でGunicornを実行します。$ docker-compose up gunicorn＃ホストマシンから、ドッカーズIPアドレスを見つけます。 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ワークスペースバッシュ
Docker workspaceコンテナでは、ホストコンピューターの./docker/templatesディレクトリがDockerコンテナに/srcにマウントされます。これは、 ./docker/docker-compose.ymlのservices > appの下で指定されています。
BASH-4.3＃CD /SRC
bash-4.3＃tree.├──__init__.py
handlers
├├アクスバイ
hello.py
1つのディレクトリ、3つのファイルハグはセキュリティと品質を真剣に受け止めています。この焦点は、徹底的にテストされたコンポーネントのみに依存し、静的分析ツール（盗賊や安全など）を利用してコードベースのセキュリティを検証する理由です。潜在的なセキュリティの問題を見つけたり遭遇したりした場合は、すぐにお知らせください。
セキュリティの脆弱性を報告するには、Tideliftセキュリティの連絡先を使用してください。 Tideliftは、修正と開示を調整します。
ハグは、うまくいけば有用なガイドを表します。これは、開発者がよく書かれた直感的なAPIの作成を導くのに役立つプロジェクトの目標を表しています。
ありがとう、次のPython APIを開発するときにこの抱擁が役立つことを願っています！
〜ティモシー・クロスリー
