orangain flavor

じっくりコトコト煮込んだみかん2。知らないことを知りたい。

書籍を書きながらOSSに貢献した話

book python

Pythonクローリング&スクレイピングでは、クローリング・スクレイピングやデータ解析のための様々なライブラリを紹介しています。 書籍でOSSのライブラリを紹介すると、そのライブラリに貢献する機会やインセンティブが生まれると考えています。

書籍で紹介すると貢献したくなる

書籍で解説するには、ドキュメントやソースコードを読んでライブラリの正確な挙動を知る必要があります。 ドキュメントが曖昧な場合、そうして得られた知識でドキュメント改善のための指摘や提案ができるようになります。

書籍で紹介するライブラリで変更の大きな新バージョンが公開される場合、Alpha版やBeta版、RC (Release Candidate) 版で検証して、書籍内のコードが正しく動くことを確認する必要があります。動かない場合は自分で直すなり、早めに直るよう報告するなりしたくなるでしょう。

ライブラリの挙動が不自然な場合、「〜については注意が必要です」のように注記するよりも、いっそ改善してしまったほうが解説がシンプルになることもあります。特に1つのライブラリだけが書籍で扱う実行環境から外れてしまうような場合は、そのライブラリに対応してもらえたら解説が楽になります*1。

Pythonクローリング&スクレイピングの場合、全編でPython 3を使っていますが、執筆を始めた時点ではPython 2.7のみに対応しているライブラリもありました。Python 3に対応してもらえるようPull Requestを送ったものもあります。

貢献したライブラリなど

せっかくなので、貢献したライブラリをまとめておきます。 並び順はPythonクローリング&スクレイピング（以降で書籍内と言った場合はこの本を指します。）での登場順です。

Beautiful Soup

Beautiful Soupはスクレイピングのための有名なライブラリです。 CSSセレクターで,の挙動がおかしかったのを修正しました。

WikiExtractor

WikiExtractorはWikipediaのダンプからテキストだけを抽出するコマンドです。 Python 2.xにしか対応してなかったので、Python 3にも対応させました。

python-amazon-simple-product-api

python-amazon-simple-product-apiはAmazonのProduct Advertising APIのラッパーです。 インストール時に依存ライブラリが正しくインストールされるようにしました。

PDFMiner.six

PDFMiner.sixはPDFからテキストやオブジェクトを抽出するライブラリです。 インストールが簡単になるようにしたり、コマンドの実行結果がおかしかった箇所を修正しました。

RoboBrowser

RoboBrowserはWebページの自動操作のためのライブラリです。 chardetというライブラリがインストールされていない環境でも文字化けが起きにくくする修正をマージしてほしかったですが、未反応のままです。

MechanicalSoup

MechanicalSoupもRoboBrowserと同様の自動操作のためのライブラリです。書籍内では名前が登場するのみです。 ドキュメントを修正しました。

BigQuery-Python

BigQuery-PythonはPythonからGoogle BigQueryを扱うクライアントです。 credentials.jsonというファイルを置いた場合に、コードが簡潔になるようにしました。

Scrapy

Scrapyはクローリング・スクレイピングのためのフレームワークです。 ドキュメントのわかりにくい箇所を修正したり、Python 3に対応したVer. 1.1 RC1が出た時に問題を報告・修正したりしました。 1個目のドキュメントの目次を見やすくしたPull Requestはお気に入りです。

OpenCV

OpenCVはコンピュータービジョンのためのライブラリです。 Debian上でPython 3からOpenCVを使えるようにするpython3-opencvパッケージを実現するパッチを投稿しましたが、特に進展なしでした。

このため、Ubuntu 14.04と16.04向けにpython3-opencvパッケージを含むPPA (Personal Package Archives) を作成しました。

rq

rqはRedisをバックエンドとした軽量なメッセージキューを実現するライブラリです。 ドキュメントが古い箇所やサンプルコードがPython 3で動かない箇所などを修正しました。

ウォッチしてたけど進まなかった問題

以下は特にできることがないのでウォッチしてましたが、残念ながら特に進展のなかった問題です。

MeCabのPython 3対応

MeCab公式のPythonバインディングでPython 3をサポートするPull Requestがあり、ウォッチしてましたがマージされていません。書籍内では代わりにmecab-python3を紹介しています。

Ubuntu 16.04のVagrant Box

Pythonとは直接関係ないですが、Ubuntu 16.04のVagrant Box (ubuntu/xenial64) がVagrant向けに設定されてなく、まともに使えないという問題があります。 このため、書籍内で使用する環境はUbuntu 14.04のままです*2。

まとめ

1つ1つは簡単なものばかりですが、少しでも世界を良くする手伝いができて良かったです。

Beta版やRC版を出しているにも関わらず正式版リリース後にバグ報告が来るという話をたまに聞きます。書籍を執筆することで、正式版リリース前に検証するインセンティブが働くのは非常に良いことだと思います。書籍を書く機会はあまりないので、もう少しカジュアルにこの効果を活用できないかと考えています（小さ目の電子書籍を書くとか？）。

また、個人で開発しているライブラリはドキュメントが不十分だったり、言語のツールチェインとの連携がスムーズでなかったり*3するので、貢献すると喜ばれるでしょう。

GitHubのおかげでOSSに貢献しやすい環境が整っているので、ぜひ気がついたことはどんどん報告・修正していきましょう。

おまけ：英語でのIssue/Pull Requestのコツ

英語のIssueやPull Requestでうまく伝わらないと感じることがあるかもしれません。 コツとしては、一定のフォーマットの小見出し*4に沿って書き、なるべく長い文章を書かないようにすることだと思います。

IssueであればEnvironmentとHow to Reproduceを示し、Expected BehaviorとActual Resultを、実際のコマンドの実行結果やスクリーンショットなどを示してわかりやすく対比させます。文章を読まなくてもわかるようにすると、英語の説明の拙さを補えます。

Pull Requestの場合はまず、変更を小さくして解決したい問題にフォーカスするのが重要です。 Issueと同様に、BeforeとAfterをわかりやすく対比させると良いでしょう。 変更の動機を説明するのが難しい場合は、まず問題を明確にするためのIssueを作成し、それをFixする形でPull Requestを作成するとシンプルに説明できるようになることもあります。

参考: 英語圏の開発者に初めてバグレポートを出す時の5つのポイント【連載：コピペで使えるIT英語tips】 - エンジニアtype

関連

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

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

*1:もちろんその実行環境が妥当な場合の話です。

*2:一部Ubuntu 16.04向けの補足もあります。

*3:Pythonであればpipでインストールできないとか。

*4:Issue TemplateやPull Request Templateがあればそれです。