ReDoc - Angular な静的 Webページを生成できる REST API ドキュメンテーションツール

REST API のドキュメンテーションツールにはいまだこれといった決定打がなく、定期的に「API document tool 2017」などのワードでぐぐってはブラウザを閉じ、ぐぐってはブラウザを閉じるという悶々とした日々を過ごしていました。そんなおり、以下の記事で「ReDoc」というツールを知りました。

簡単にさわってみたところ感じがよかったので紹介します。

なお、本稿で「API」と記載する場合 Web Application の RESTful API を指します。

ReDoc

ReDoc は、API ドキュメントのジェネレーターです。

github.com

手元で作成した成果物のスクリーンショットを掲載します。

f:id:iktakahiro:20170609022023p:plain

詳細は LiveDemo をご覧いただくのがよいでしょう。

ReDoc の特長

ReDoc の特長は以下のとおりです。

  • HTML に redoc.min.js と swagger.json を読み込ませるだけというお手軽設計
  • ドキュメントは Angular ベースの HTML + JS な静的ファイルとして出力される

利用方法

README のとおりですが、アプリケーションの JavaScript と API の定義ファイルを読み込むのみです。

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"></script>
  </body>
</html>

ローカルの swagger.json を読み込む場合は Web サーバー経由でアクセスします。

ReDoc のよさ

ReDoc のよさを語ります。

静的ファイルであることのよさ

現存する API ドキュメンテーションツールにはモック機能や実際のリクエストを発行できる機能が備わっている場合があります。Swagger UI がその代表例です。

リッチな機能を提供するためか、Swagger UI はサーバーサイドアプリケーションとして実装されていますが、 ごく個人的には、API の入出力情報を示す程度の目的を果たすために、アプリケーションサーバーを運用したくないと考えています。

ReDoc による API ドキュメントは静的ファイルとして構成されます。したがって GitHub Pages や AWS S3 などを利用して Static Web Site としてドキュメントを公開できます。

デフォルトスタイルのよさ

ReDoc はデフォルトのスタイルが美しく、そのままで公開クオリティ感があります。3ペインスタイルは、しばしば API Docs 界隈（？）でお手本とされる Stripe.com の API Reference や Auth0 の API Docs を参考にされているのではないかと推察されます。

構成もシンプルで、サービスロゴを入れたりカラムの色を調整するだけでもほどよいオリジナリティを出せる設計だと思います。

OpenAPI (Swagger) Specification を利用できることのよさ

ここ最近その動向がまったくオープンに感じられない Open API Initiative にはかなり色々思うところがありますが、さておき、OpenAPI (旧Swagger) Specification が API ドキュメントの定義ファイルとして一定の存在感を示していることは否定できません。

OpenAPI Specification のつらさもあってか、RAML のように別の “alt-YAML 的な何か” に走る動きや、そもそも JSON や YAML は無理なので、lord/slate のように Markdown で定義を書かせようという試みも見られます*1。

しかしながらひとめぐりしてみると、エコシステムは大きいほうがよいということと、フォーマットとして将来変換可能であったほうがよい *2 といった理由により、次善の策として OpenAPI Specification を採用しておくのは悪手ではないように思われます。

ReDoc は OpenAPI Specification をそのまま利用できるので、いままで Swagger を利用していた場合には資産を活かせます。将来 Swagger 方面に合流することになっても問題ありません。

おわりに

API ドキュメンテーションツールは多く存在します。その中で ReDoc は、OpenAPI Specification を利用しつつ品質のよい静的 Webページを生成する*3というバランスのよいポジションに属していると思います。

まずは現存する自社の API Document をリプレースしてみようと考えています。API ドキュメンテーションをめぐるツールやプラクティスについてどこかで意見交換できるとよいですね。

*1:Apiary… うっ…頭が…

*2:Markdown のような書式では仕様がファジーになりやすく JSON や YAML などに相互変換しにくいという問題があります。仕様によりますが

*3:HTML ファイルが generate されるわけではないので、変換といったほうが適切かも知れません

ケーススタディからはじめよ - 秀和システム『フリーライブラリで学ぶ 機械学習入門』レビュー

このたび縁あって『堅田洋資, 菊田遥平, 谷田和章, 森本哲也 (2017). フリーライブラリで学ぶ 機械学習入門』（以下、本書。著者名は書籍中掲載順）を恵贈賜りました。

著者並びに出版社の皆様にお礼と慰労をかねまして、僭越ながら本エントリにて一読後のレビューを掲載いたします。

フリーライブラリで学ぶ機械学習入門

フリーライブラリで学ぶ機械学習入門

なお読者の益となるようなるべく公正な目線でレビューします。掲載されているコードの正確性については本レビューの対象外とします。

総評

昨今「機械学習、深層学習、人工知能」というトピックを扱った書籍が多く出版されています。本書もその中の一冊と言えますが、以下の点が特長です。

  • Issue を起点としたビジネス領域のケーススタディが含まれていること

本書のうちいくつかの章は、「不動産の成約価格を予測したい」「ニュース記事をグループに分けたい」というような Issue、あるいはニーズを起点に始まります。物事を学ぶにあたり目的設定は理解を深めるための手助けとなり得ます。著者の経験を根拠とするであろうケーススタディは貴重なテキストです。

  • 講義形式であること

本書の内容は著者によって開催されたワークショップの内容がベースとなっています。そのため講義形式および口語体に近い文体で記述されている章があります。この点が冗長だと感じる人もいれば、読み手にやさしいと感じる人もいるでしょう。

本書に掲載されているケーススタディに関心を持たれた方や、ワークショップ形式（の雰囲気）で機械学習を学んでみたいと考えている方は手に取ってみるとよいのではないかと思います。

なお、「フリーライブラリ」と冠されていますが、実質的に活用されているのは Python であり、サンプルコードは Jupyter Notebook 形式で公開されています*1。

以下、各章をピックアップして簡単に紹介します。

第2章 予測モデルを作ってみよう

ビジネス要件が登場することが本書の1つの特長です。第2章は、「不動産仲介会社のデータサイエンティストであるあなたが、成約価格の予測システムを作らなくてはならなくなった」という状況設定のもと、予測モデル構築の流れについての解説がなされる章です。ビジネス要件を理解した上で、データを知り、特徴量を設計し、作成したモデルを評価していく… という流れです。

執筆者の堅田さんの経験に基づくものと推察され、参考になる点も多くあると思います。

第3章 クラスタリング入門

機械学習の解説書では頻出の K-means 法 *2を中心に、クラスタリングについて解説される章です。階層型クラスタリングにも言及があります（久しぶりに Dendrogram を見た気がしました）。

しばしば課題になるクラスター数の決定に関するアプローチや、K-means 法の適応に関する注意点などがあわせて解説され実践的な内容になっています。

第5章 レコメンデーション入門

古典的（？）な機械学習の適応例である、協調フィルタリングによるレコメンデーションについての解説が主です。スパースな行列を取り扱う方法としての次元削減 (Dimensionality Reduction) についても紙面が割かれています。

分類器を用いた手法によりレコメンデーションを行う方法が提案としてのみ掲載されていますが、ごく個人的には、ユーザーベース強調フィルタリングの解説は多いため、むしろこちらの詳細な解説を読みたかったりもしました。

第6章 評判分析入門

第6章は自然言語処理を活用して、映画レビュー内容のネガ/ポジ判定を行おうという章です。前提となる自然言語処理の基本、形態素解析や特徴量作成について丁寧に説明されています。

ちなみに、形態素解析の解説など一部内容が第4章の「トピックモデル入門」と重複しておりかつ第6章のほうが説明に紙面が割かれているので、自然言語処理について学びたい読者は先に6章を読んでから4章に遡ったほうが良いかも知れません。

第8章 ディープラーニング理論編 / 第9章ディープラーニング実践編

第8章、第9章は みんな大好きディープラーニングについての話題です。たびたび本書がケーススタディを軸にした解説書であると述べましたが、本章については理論ベースの解説です。

理論編では、Neural Network, Perceptron, 活性化関数などの理論から、CNN や RNN の実装についての解説があります。著者曰く「数式を1個も使わないという制約を己に課し*3」たそうで、講義形式であることも相まって読みやすい構成になっていると思います。

実践編は定番と化した Keras + TensorFlow のコンボを利用したディープラーニングの実践です。Keras を利用した画像およびテキストの分類問題への取り組みです。

Ex 補足資料

本書はある程度「Pythonが書けること」が前提となっていますが、巻末の Appendix にて、Anaconda 環境の導入や Jupyter Notebook の使い方、Python の文法（！）の解説があります。本書のサンプルコードを実行するにあたり実は Python がよく分かっていなかったことに気付いた方は、目をとおすとよいでしょう。

以上です。

関連するかもしれない書籍

  • とても売れているらしい。

ゼロから作るDeep Learning ―Pythonで学ぶディープラーニングの理論と実装

ゼロから作るDeep Learning ―Pythonで学ぶディープラーニングの理論と実装

  • 本格的に scikit-learn を活用したい方向け。

Python機械学習プログラミング 達人データサイエンティストによる理論と実践 (impress top gear)

Python機械学習プログラミング 達人データサイエンティストによる理論と実践 (impress top gear)

*1:https://github.com/yosukekatada/mlbook

*2:本書で実践されるのは scikit-learn に実装のある K-means++ です

*3:書籍版 251頁

いまこそ Python に "再"入門!! - 技術評論社『科学技術計算のための Python 入門』

積ん読消化週間ということで『中久喜 健司 (2016). 科学技術計算のための Python 入門 - 開発基礎、必須ライブラリ、高速化, 技術評論社』(以下、本書) を拝読しましたのでレビューを掲載します。

科学技術計算のためのPython入門 ――開発基礎、必須ライブラリ、高速化

科学技術計算のためのPython入門 ――開発基礎、必須ライブラリ、高速化

総評

本書の最大の特徴は、Python の文法や言語仕様の解説と、Python を分析ツールとしてみたときの用法がとてもバランスよく散りばめられている点です。

本書の内容は、大きく2つに別れます。Python の言語仕様や、開発するうえでの基礎知識を得られる前半と、いわゆる PyData パッケージ群について学べる後半です。前者については、動くコードを書くことを求めるあまり Python やプログラミング言語自体への理解がおざなりだったと考えている Python ユーザーに適した内容です。後者は、NumPy や SciPy などの有名な PyData 系パッケージを理解するための足がかりとなる内容で、これから本格的にデータ分析ツールとして Python を使い込んでいこうとするユーザーに役立つ内容です。

対象読者について

近年 Python の人気により、基礎から応用までの文法書は多く出版されています。データ分析に対する需要も引き続き高いようで、統計解析や機械学習関連本の刊行も活発です。後者にフォーカスを当てた書籍においても、副題に「Python 〜」と添えられていたり、サンプルコードが Python であるケースが目立ちます。

既存の書籍の傾向として、Python の文法にフォーカスを当てた書籍ではデータ分析の話題に触れられることは稀で、反対にデータ分析系の書籍においては、Python の文法に関しては概要に触れるだけにとどめられることが多いように思われます。これはもちろん、両者ともに奥深いものであるためいずれかにウェイトを置く必要があるからでしょう。

本書は「文法書」に近い構成です。分析手法や統計アルゴリズムはほぼ登場しません*1。本書後半のパッケージ紹介においても、著名な機械学習パッケージである scikit-learn の解説は省かれています。これが意図的なものであるのは、以下に本書 v頁より引用する想定読者からも明らかです。

本書の想定読者は、これから科学計算技術やエンジニアリングに Python を使い始めてみようと考えている方々で、たとえば以下のような方々です。

  • Python がどのような言語で何ができるのかを学びたい方

  • Python で科学技術計算を行ってみたい方

  • Python によるハイパフォーマンスプログラミングの基礎知識を学びたい方

  • Python の文法に加えて、実践的なプログラム構築法を学びたい方

今回のレビューとしても、上記がそのまま本書をおすすめできる読者層です。Python や科学技術計算といったワードから、例えばディープラーニングについて解説されているかのようなことを連想し期待するとミスマッチになります。

また、これは意見の分かれるところとは思いますが、プログラミング言語自体への入門としてはより平易な他の書籍を探すほうがよいでしょう。変数やデータ型などの基礎から解説されているため入門書とできないこともないのですが、全体的にフォーマルな解説で敷居高く感じられる読者がいるであろうことも否めません。

以下、各章について簡単にレビューします。

第1章 - Python の現状とその人気

導入部分で、技術的な内容よりも、「なぜ Python が使われるのか？」について紙面を割いている章です。「Python は最近人気である」「教育分野で利用が進んでいる」といった一般に聞くことがある内容を、論拠を示して解説しています。やはり一般に弱点とも言われる実行速度についてなどの言及もあり、「Python ってどうなの？」と聞かれた場合の回答としてはこの章を示せば充分なほどです。

第2章 〜 第3章 - 科学計算実装の流れ

「ロケットシミュレータ」を実装するという目的設定のもと、コーディングから静的コード解析、デバッグについて触れられているのが2章です*2。ユニットテストにも言及があるなど実践的でよいのですが、力学についての用語やそれなりの量のコードがいきなり登場するため、平易な内容を期待していた読者は多少面食らうかも知れません。実際、シミュレータ部分は読み飛ばしても全体の理解にはさほど影響がないので、次に進んでしまうのも一手です。

ユニットテストについては標準の unittest や docstring、サードパーティパッケージ nose についての解説があります。これら以外の選択肢としては pytest がよいでしょう。

3章は 定番ツールとも言える IPython や Jupyter Notebook、IDE として Spyder が登場します。

本書の内容を学ぶにあたっては Jupyter Notebook の利用が最適でしょう。IDE が必要な方には JetBrains 社の高機能 IDE PyCharm をおすすめします。

www.jetbrains.com

第4章 〜 第6章 - 一歩進んだ Python 文法解説

4章から、Python の文法や言語仕様の解説が始まります。変数や関数の定義、データ型や予約語など、通常プログラミング言語の解説に必要な内容が掲載されていると考えて問題ありません。加えて、リストの状態による shallow copy と deep copy の違い関する解説など、Python の Tips がいくつか取り上げられています。

本書中のコードですが、一部変数や関数への lowerCamelCase の採用*3や Single/Double Quote の揺れ*4など気になるものが若干ありました。命名については数学的慣例に基づいたことに依るものもあるように見えましたが、本書中で PEP 8 についての言及もあったことですし、一応この点に留意してコードを参考にするのが宜しいと思います。

また、文字列のフォーマットについて全体的に %演算子 を利用したコードが採用されています。この方法は古い方法であり非推奨とされているので、format() 関数を利用するほうがよいでしょう。

# %演算子
print("%d からカウントダウンします" % m)

# format 関数
"{0} からカウントダウンします".format(m)

余談ですがつい先日リリースされた Python 3.6 から新しい文字列フォーマットの方法*5が増えていますね*6。

# Python 3.6 からの新しい方法
f"{m} からカウントダウンします"

第7章 〜 第10章 - PyData 定番パッケージの紹介

第7章からは、いわゆる PyData パッケージの解説です。NumPy、SciPy、matplotlib, pandas の4つに1章ずつ割かれています。いずれも多機能なパッケージであるため、より深い知識を身につけるには専用の解説書や公式ドキュメントの参照が求められます。本書はこれらパッケージの導入として考えるとよいでしょう。

matplotlib の割り付けの指定はとても参考になる解説でした。

第11章 〜 第12章 - パフォーマンス向上のための Tips

11章および12章については、実行速度の高速化についてのトピックです。特に大きなデータを扱う場合に実行速度は重要な点ですから、関心を持たれる方も多いと想像します。本書では、高速化のためのアプローチを4つに大別しています。

  1. ボトルネックの解消 => コードの最適化
  2. 処理の並列化
  3. ライブラリの利用
  4. JIT コンパイラの利用

「1. ボトルネックの解消」として for 文を極力控えるなどの Python における代表的なパフォーマンスに関する注意事項のほか、メモリの利用に関する解説があります。

「2. 処理の並列化」は、multi thread/multi process についての内容が扱われています。一見並列処理による処理速度の実行が期待される multi thread への注意点がありつつ、I/O バウンドのときは multi thread を検討してもよいよというアドバイスは端的でよいと思いました。

「3 .ライブラリの利用」は、パフォーマンス向上の解法として Cython を利用することを紹介する内容です。C言語で実装したライブラリを Python から利用する方法も解説されています。

「4. JIT コンパイラの利用」では代表的な JIT コンパイラ Numba についての解説があります。

Numba は Pure な Python コードに多少手を入れるだけでパフォーマンスを大きく向上させられる可能性があるのでおすすめの方法です。

本書中に別解として Numexpr も登場します。

github.com

まとめ - 文法解説、パッケージ紹介、パフォーマンス Tips のバランスのよい構成

ここまで見てきたように、Python の言語仕様に踏み込みながら、PyData パッケージの導入も担うという点で希有なバランスを保つ本書です。多少でも Python の知識があると読み易いレベル感でもあるため、既に Python ユーザーである読者が 再入門 する際の手引きとして最適です。他のプログラミング言語ユーザーが Python を学ぶための一冊として利用するのもよいでしょう。

高度な分析ツールの普及により、便利なパッケージに手を伸ばしがちな昨今です。いまいちど、本書を片手にプログラミング言語としての Python の特性を確認してみるのもよいかも知れません。

関連するかも知れない書籍

  • NumPy と pandas について深掘りしたいなら

Pythonによるデータ分析入門 ―NumPy、pandasを使ったデータ処理

Pythonによるデータ分析入門 ―NumPy、pandasを使ったデータ処理

  • 機械学習について知りたいんだ！という人向け

Python機械学習プログラミング 達人データサイエンティストによる理論と実践 (impress top gear)

Python機械学習プログラミング 達人データサイエンティストによる理論と実践 (impress top gear)

*1:ロケットシミュレータのくだりや SciPy の章で若干登場します

*2:この設定は著者のバックグラウンドによるもと思われます

*3:157頁 myFunc など

*4:155頁 など

*5:PEP 498 -- Literal String Interpolation | Python.org

*6:そういえば ECMAScript 2015 の template literal っぽいですね

悩める Web スクレイパーのための一冊 - 技術評論社『Python クローリング & スクレイピング』

このたび、縁あって『加藤耕太 (2016). Python クローリング & スクレイピング データ収集・解析のための実践開発ガイド, 技術評論社』(以下、本書) を恵贈賜りました。

著者並びに出版社の皆様にお礼とご慰労をかねまして、僭越ながら本エントリにて一読後のレビューを掲載いたします。

Pythonクローリング&スクレイピング -データ収集・解析のための実践開発ガイド-

Pythonクローリング&スクレイピング -データ収集・解析のための実践開発ガイド-

なお読者の益となるようなるべく公正な目線でレビューします。掲載されているコードの厳密な正確性については本レビューの対象外とします。

総評

体系的に「スクレイピングとは」「クローラーとは」について学ぶにはとてもよい書籍です。本書の優れているところは、特に基礎編ともいえる前半部分で、ある事柄を説明するにあたり前提となる事柄をできるだけ丁寧に解説しているところです。

エラーハンドリングや取得先のデータ構造が変わってしまった場合の対応など、継続的に運用しないと見えてこない "悩み" とその対策がナレッジとして紹介されていることも「実践開発」という副題に則しています。

本書は、最初により原始的な方法 (e.g. UNIXコマンドによるデータ取得) を説明した上で、中盤以降で高度なライブラリ (e.g. Requests) を紹介する流れを取っています。これはおそらく、Python やそのライブラリの便利さを読者に実感させるという意図によるものだと思います。

通読することで、Python に限らない一般的な Webリソースの活用の手段を学べるとともに、実運用に耐えうるクローラーシステムを Python で開発するための前提知識を得られるでしょう。

こんな人に特におすすめ

以下の要望をお持ちの方には特におすすめできます。

  • Webスクレイピングやクローラーについて基礎から応用までしっかり学びたい。
  • 一度 〜 数回のデータ収集ではなく継続的にデータを収集するクローラーを開発、運用したい。

以下の方は、本書の内容が自分に合っているか確認してから購入するとよいかも知れません。

  • とにかく最短で Web ページのスクレイピングを行いたい。いますぐにだっ！
  • 特定のパッケージを使うことがすでに決まっていて (e.g. Beautiful Soup)、その範囲に限定した知識を得たい。
    • ただし Scrapy については相応に誌面が割かれているのでこの限りではありません。

ある程度予備知識がある状態で、クローリングとスクレイピングの要所を掴みたいという方にとっては冗長と感ぜられる章も存在するでしょう。この理由は、本書が対象としている技術を体系的に取り扱っているためであり、本書の欠点ではありません。

続いて各章毎に簡単にレビューしていきます。

第1章 クローリング・スクレイピングとは何か

1章では、そもそもクローリング・スクレイピングとはなにか、というトピックについて、Python すら用いず解説がはじまります。

  • wget コマンドによるデータの取得
  • cut や grep、sed コマンドによるデータの抽出や加工

各種コマンドの扱いに馴染みのない方は目を通してみるとよいでしょう。そうでない方は飛ばしてしまって差し支えない章です。

第2章 Python ではじめるクローリング・スクレイピング

2章の冒頭で Python のインストールや venv による環境構築、Python 自体のデータ構造や文法に関する最低限の解説があります。Python の標準ライブラリである urllib を使ったデータの取得と、re を使った正規表現によるスクレイピングの方法が紹介されています。

実際、この組み合わせは実用的ではないのですが、高度なパッケージの用法に移る前に前提となる知識を解説するという目的で取り扱われているのだと思います。

第3章 強力なライブラリの活用

3章は Python に明るいユーザーにとっては想像がつくであろう、Requests や Beautiful Soup、lxml といった定番の 3rd パーティパッケージが登場します。これらのパッケージを使って、あらためて HTML をスクレイピングするという構成です。

前章で正規表現による不都合を感じた読者は便利さを体験できる章であると思います。

また、本書からデータベースの扱いも始まり、MySQL および MongoDB の導入方法の解説があります。

データベースについては、本書では macOS ならびに Ubuntu に直接インストールする方法が取られているのですが、Docker の利用がより手軽かなと思いました。ただし本書の構成からすると、Docker を採用するには「Docker とは」という項目について紙面を割く必要が生じるため、見送ったのかなという気もします。Docker の知識がさほどなくても、Kitematic を利用すれば GUI で簡単に導入できますので利用を検討してみるとよいでしょう。

また、そもそもデータベースではなく CSV (TSV など含) ファイルとして保持しておけばよいという考え方もあります。僕の場合なんらかデータを収集する場合は概ね CSV ファイルにしておいて、データの抽出や並べ替え、集計などの操作を行いたい場合には pandas に読み込んで処理しています。もちろんこれはデータをどう管理したいかということに依ります。個人で気軽に扱いたいのであれば別途ツールの導入の必要ない CSV もよいと思います。

第4章 実用のためのメソッド

4章は実際運用するにあたって考慮すべきポイントがまとめられた章です。

特筆すべきは著作権について触れられている点でしょうか。(あくまで法律の専門家ではない者の見解であると前置きしつつ) 読者にこの点を喚起するのは適切であるように思います。

後半はエラーハンドリングや、クローリング先のデータ構造が変わってしまった場合の対処などが解説されています。

アドホックにデータを収集して終わり、というケースでは HTML構造の変化に遭遇することはないのですが、クローラーを一定期間運用していると、突然データが収集できなくなるとういことはありがちです。REST API などと違いフォーマルな仕様が提供されない Web スクレイピングにおいては、最初からある程度 robust な設計にしておくことが大切ですね。

第5章 クローリング・スクレイピングの実践とデータの活用

5章は、Wikipedia や Twitter のデータ、財務省が公開している国債金利データなどを扱う内容です。いわゆる「オープンデータ」についても言及があります。Python パッケージという観点では、あらたに pandas と matplotlib が登場します。

5章については、自分の用途と合致する例がある箇所を重点的に読むのに適した構成です。「実践」と称されているとおり、この章から情報量が一気に増えます。1つ1つの要素技術を詳しく解説するというよりも、さまざまな用途を想定しより多くのアプローチを紹介するという方針のように見えます。

JavaScript の解釈が必要な場合の手段として Selenium と PhantomJS の利用が主たるものとして紹介されています。

僕自身この領域はさほど馴染みがないので調べて見たところ、いわゆる Headless ブラウザやレンダリングエンジンの関連ライブラリ・パッケージがまとめられている GitHub のレポジトリがありましたので以下に掲載します。

github.com

本書の内容含め勉強になりました。

第6章 フレームワーク Scrapy

6章はおまちかね (?) の Scrapy を解説する章です。

github.com

Beautiful Soup でお手軽な クローラーシステムを作ったことはあるけれども Scrapy までは手が出せていない、というユーザーは一定数いるように感じます。 本章で、Scrapy の実装や設定についてひととおり解説がありますので、実は Scrapy を重点的に知りたい方にもこの書籍はおすすめできます。

ちなみに Scrapy が Python 3 に正式に対応したのは 2016年5月でしたが、執筆時期を考えるとぎりぎりのタイミングだったでしょうか*1。

本書中の Scrapy のサンプルコードは複雑ではない Class と Method を使った例ですので写経は容易です。データが欠損していそうなときを想定したハンドリングにも言及があります。こうした Tips が含まれているあたり実用的でいいですね。

6章の後半部分は Elasticsearch の活用や、OpenCV を使った画像解析に話題が及びます。ケースとしては非常に面白いのですが、Scrapy とは独立した話でもあるので、関心のある読者は目を通すとよいでしょう。

第7章 クローラーの継続的な運用・管理

最終章となる7章では、クローラーシステムの実行環境とその運用に関するトピックを扱っています。実行環境の1例として Amazon Web Service の EC2 が選択されています。サーバーへのデプロイ方法や、サーバー上での Python 環境の構築などについても解説に含まれます。

また、cron からメールを通知してみるという例の中で、Postfix (いわゆる SMTPサーバー) が登場します。

Postfix について、システム通知という限られた用途で Postfix のようなミドルウェアを運用・保守していくことは費用対効果がよくないと思いますので、メール通知が必要なのであれば Python スクリプト内から Amazon SES のような外部の SMTP サーバーを利用するのが無難だと考えています*2。あるいは、ジョブ実行を管理している何らかのツール (e.g. Rundeck) に委ねるか、ログ監視系のサービスやツールでエラーログを拾うなどするのも一案だと思います。

クローリング処理とスクレイピング処理を疎結合にするための手段として、Message Queue (以下、MQ) を介したジョブのコントロール方法が解説されています。具体的には Redis を MQ のデータストアとして採用しています。

システムに MQ を採用すること自体に少しハードルを感じる読者もいるのではないかと想像します。本書では図解付きで MQ の動作を解説しており分かりやすい内容になっています。別解として Amazon SQS の紹介もありますので手に馴染みそうなほうに挑戦してみてもよいでしょう。

AWS Lambda の登場以後、クローラーシステムの実行環境としていわゆる Serverless Architecture に分類されるクラウドサービスを活用するケースも見られるようになってきました*3。本書ではそうした環境については触れられていませんが、ここまでで得られた知識は他の環境においても充分活かせるものと思われます。

まとめ

本文中にも pandas や matplotlib など PyData*4 関連パッケージの利用例がありますが、クローラー開発が行えるばかりでなくその後のデータ分析のフェーズまで単一の言語で完遂できる Python の便利さを改めて感じる書籍でもありました。

Web サイトのスクレイピング、クローリング自体は古典的な試みです。近年はデータを分析したいという目的があって、必要なデータソースを収集するために当該技術が必要になるというケースが多くなってきているようです。関連技術の勉強会やハンズオンはとても盛況だと聞いています。注目の高まるクローラー開発技術ですが、システムとしては単純なバッチ処理よりも考慮事項が多く、実装者や運用者の悩みの種にもなりがちです。

本書は、クローリングとスクレイピング技術について順を追って学ぶことができ、実運用を見据えたいくつかの示唆を得られる構成になっています。クローラー運用に悩みを抱えている方にも、スクレイピング技術についてじっくり学びたい方にもおすすめの一冊です。

関連するかも知れない書籍

スクレイピングのまえに Python 勉強しなきゃ、という方向け。

Pythonスタートブック

Pythonスタートブック

拙著 (共著) で恐縮ですが、Python の豊かなライブラリたちはクローラーと組み合わせて活用できるはず。

Python ライブラリ厳選レシピ

Python ライブラリ厳選レシピ

  • 作者: 池内孝啓,鈴木たかのり,石本敦夫,小坂健二郎,真嘉比愛
  • 出版社/メーカー: 技術評論社
  • 発売日: 2015/10/17
  • メディア: 単行本（ソフトカバー）
  • この商品を含むブログ (1件) を見る

*1:謹んでお慶び申し上げます

*2:Amazon SES については 7章後半の節「クラウドを活用する」で言及があります

*3:AWS Lambdaで作るクローラー／スクレイピング

*4:データ分析やデータ活用に Python ならびに Python ライブラリを利用しようという人類の営みの総称

Redash の次にくるのは superset!! - Airbnb 謹製の BI ツールが OSS で

Redash (re:dash) 流行ってますね。

redash.io

最近 Github をにわかに賑わせている OSS が superset です。

github.com

superset とは

公式説明によると

data exploration platform

とのことですが、僕の感覚的にはこれはつまり、いわゆる Business Intelligence (以下 BI) Tool です。そう、Tableau のような。

  • OSS (Apache 2.0)
  • サーバーサイドは Python で書かれている
  • さまざまなデータソースに対応 (MySQL, Redshift、SparkSQL など)
  • グラフ描画の種類が豊富
  • Role や Permission についてある程度細かく設定可能
  • Airbnb Engineering チーム謹製

superset ざっと見

インストール方法は公式ドキュメントのとおりです。

あるいは Docker image を利用します。

f:id:iktakahiro:20161125193456p:plain:w600

初期設定をすませて、SQLite 上に展開されているサンプルデータセットを使ったダッシュボードにアクセスしてみると

f:id:iktakahiro:20161125193621p:plain:w700

ふぁっ!? (二度見

f:id:iktakahiro:20161125193719p:plain:w700

ふぁー (椅子からすべり落ちる

...

ごく簡単な利用方法としては、対象のデータソース (最も単純な場合、データーベースの中の1テーブル) を選択し、Filter や Group By 対象のカラムを選択し、描画したいグラフのパターンを選択してグラフを生成します。

例えば以下は、サンプルデータセットの誕生日データの円グラフです。

f:id:iktakahiro:20161125194031p:plain:w500

グラフの種類を選択できます。

f:id:iktakahiro:20161125194101p:plain:w300

棒グラフに変更。

f:id:iktakahiro:20161125194122p:plain:w500

謎の Words Cloud。

f:id:iktakahiro:20161125194145p:plain:w500

SQL 記述の支援ツールもついていて、クエリ結果はその場で確認できます。

f:id:iktakahiro:20161125194243p:plain:w500

Redash の違いと superset の可能性

superset をまだ使い込んでいるわけではないうえでの感想である点をご了承ください。

印象としては、Redash はなにはともあれ SQL が起点だったのに対して、superset は GUI でできることが非常に多いです。視覚表現も豊かで (実用度はさておき) 楽しくなるようなダッシュボードを組み立てられます。

重複する部分もあるとは思うのですが、

  • Redash: いちど SQL から組み立てた指標とグラフを定期的にモニタリングしていくのに便利
  • superset: Filter や Group By をいじりながら、インタラクティブにデータを探索してくのに便利

という使い分けになるのかなぁという気がしています。

サービスやプロダクトの改善のために社内でダッシュボードを構築する気運は高まるいっぽうです。BI 界隈の動きとしては、ここ数年勢いの止まらない Tableau の他にも、Google Data Studio や Amazon QuickSight など大型のツールも登場してきています。

superset は OSS ということもあり、社内ダッシュボード構築をまず始めてみるにはこれでいいのでは!? と思わせるようなインパクトがあります。

流行ると思います。

IPythonデータサイエンスクックブック ―対話型コンピューティングと可視化のためのレシピ集

IPythonデータサイエンスクックブック ―対話型コンピューティングと可視化のためのレシピ集

Tableau 10.0 Best Practices

Tableau 10.0 Best Practices

Swagger 定義ファイルから そこそこいい感じの静的 REST API ドキュメント作成する

tech

REST API のドキュメンテーションはサービス開発における課題として認知されており、解決に向け近年さまざまな試みが行われています。OPEN API および Swagger はその有力な動きの1つです。

長いものには巻かれろ (?) ということで、今回は Swagger 定義ファイルをベースとした REST API ドキュメントの生成方法をまとめます。

結論

swagger2markup-cli と asciidoctor を組み合わせて HTML ファイルを生成するのがよさそうです。

課題の共有

Swggger 定義ファイルからドキュメントを生成する手順はいくつか存在します。

  • swagger-ui を利用する
  • swagger-codegen で HTML を出力する

swagger-ui はリッチで美しいドキュメントを提供してくれます。しかしインタラクティブな API ドキュメントが必要ない場合、ドキュメント公開のためだけに Node アプリケーションの動作環境を維持しておくことはやや気が重く、できれば静的ファイルとして配置しておきたいところです。

そこで、swagger-codegen の利用が検討できます。

github.com

swagger-codegen は、Swagger 定義ファイルからサーバーサイド / クライアントのコードを出力するためのものですが、HTML 形式のドキュメントも出力できたりします。

swagger-codegen generate -i sample.yaml -l html -o output/

しかしながら、インターネットの歴史と伝統のかほりがほのかに醸し出される成果物となっており、このままでは公開しがたい感が否めません。

f:id:iktakahiro:20161122203315p:plain:w400

swagger-codegen で HTML を出力する場合、テンプレートを指定できます。選択肢としては、多少モダンな htmlDocs2 を指定するか、テーマを作成するかです。

今回は swagger-codegen による HTML出力以外のカジュアルな選択肢が必要な状況であるとして、話を進めます*1。

手順

そこそこいい感じの静的 API ドキュメント生成の手順は以下のとおりです。

  1. Swagger 定義ファイルから Asciidoc を生成する
  2. Asciidoc から HTML ファイルを生成する

カスタマイズなしで以下のような API ドキュメントが生成できます。

f:id:iktakahiro:20161122200815p:plain:w600

そこそこ良い感じだ。

Swagger to Asciidoc

まずは Swagger 定義ファイルを Asciidoc に変換します。

github.com

swagger2markup の 実行例は以下のとおりです。

$ java -jar swagger2markup-cli-1.1.0.jar convert -i sample.yaml -f api-doc

実行すると api-doc.adoc が出力されます。

= Simple API


[[_overview]]
== Overview
A simple API to learn how to write OpenAPI Specification


=== Version information
[%hardbreaks]
_Version_ : 1.0.0

Asciidoc to HTML

続いて Asciidoc を HTML に変換します。asciidoctor を利用します。

github.com

asciidoctor の実行例は以下のとおりです。

$ asciidoctor -a toc=left api-doc.adoc

実行すると api-doc.html が出力されます。

-a オプションに toc=left を指定することで サイドバーに Table of Contents が出力されたレイアウトを選択できます。

ここで紹介した一連のビルドプロセスを CI に反映して、Amazon S3 などに Deploy できるようにしておけばよいでしょう。

付録

その他の REST API ドキュメンテーションツール/サービス

Product Description
Apiary 国内で認知度が高いっぽい API ドキュメンテーション + Mock 生成できるクラウドサービス。噛めば噛むほど渋い思いをするらしい (?)。
RAML YAMLっぽいなにか からコードやドキュメントを生成するツール群。RESTful API Modeling Language で RAML とのこと。

一時期は群雄割拠感もあった API ドキュメンテーションツール界隈ですが、ここ2年くらいで淘汰が進んできた印象です。RAML は設計がモダンな感じなので普及して欲しいです*2。

Swagger 定義ファイルの学習

最近見つけたのですが Swagger 定義ファイルの構造を学ぶにあたり、次の記事が非常にわかりやすいです。

apihandyman.io

ごく単純でフラットな記述から、Swgger の機能を利用して重複部分を徐々に省いていくという構成になっていて、公式ドキュメントではまったく把握出来ない全体像を見事に解説しています。

Web API: The Good Parts

Web API: The Good Parts

*1:テーマ作成については別の機会で

*2:と言いつつ Swagger に巻かれる勢