個人のPythonプロジェクトをリリース可能なライブラリに変える

Question

私はプログラマーではなくアカデミックであり、自分の研究をサポートするためにPython自分用のプログラムを作成してきた長年の経験があります。私の最新のプロジェクトは他の多くの人に役立つ可能性があります私と同様、私はそれをオープンソースのPythonライブラリとしてリリースすることを考えています。

ただし、機能している個人プロジェクトから、他のユーザーが簡単にインストールして使用できるライブラリに移行するには、かなりのハードルがあるようです。この質問は、公開リリースに向けて作業を開始するために私が取るべき最初のステップについてです。

現在、ライブラリとライブラリ自体を使用するコードを含む単一のgitリポジトリがあり、何かが壊れた場合の緊急の取り消しボタンとしてgitを使用しています。これはすべて1人のユーザーには問題なく機能しますが、リリースしたい場合は明らかに適切ではありません。結局のところ、私のライブラリは別のリポジトリにあり、pipを使用して他のユーザーがインストールでき、安定したAPIを持っています。

公開したいと思った段階で、setuptoolsなどの使い方を学ぶのはそれほど難しいことではないでしょう-私の問題は、その時点に到達するためにどのように作業すべきかを知ることです。

だから私の質問は、Pythonライブラリプロジェクトを一般消費のために準備するために最初に取るべきステップは何ですか？ディレクトリ構造、gitリポジトリなどをどのように再編成する必要がありますか？ライブラリのリリースの公開に向けて作業を開始しますか？

より一般的には、これを初めて試すときに役立つことがわかっているリソースがあれば非常に役立ちます。ベストプラクティスや回避すべき間違いなどへのポインタも非常に役立ちます。

いくつかの明確化：現在の回答は、「どうすれば自分のPythonライブラリa他の人が使うのに良いものですか？」これは便利ですが、私が尋ねようとした質問とは異なります。

私は現在、プロジェクトのリリースに向けた長い旅のstartにいます。私の実装のコアは機能します（そして非常にうまく機能します）が、私は自分の前の作業量に圧倒されており、プロセスをナビゲートする方法に関するガイダンスを探しています。例えば：

私のライブラリコードは現在、それを使用する私のドメイン固有のコードに結合されています。サブフォルダーに存在し、同じgitリポジトリを共有します。最終的には、スタンドアロンライブラリにして独自のリポジトリに配置する必要がありますが、方法がわからないため、先延ばしにしています。（ライブラリを「開発モード」でインストールして編集できるようにする方法も、2つのgitリポジトリを同期させる方法もありません。）
最終的にはSphinxまたは他のツールを使用する必要があることを知っているので、私のdocstringは簡潔です。しかし、これらのツールは習得が簡単ではないようです。そのため、これは主要なサブプロジェクトになり、延期しています。
ある時点で、setuptoolsまたは他のツールを使用してパッケージ化し、依存関係を追跡することを学ぶ必要があります。これは非常に複雑です。これを今すぐ行う必要があるかどうかはわかりません。また、ドキュメントは新しいユーザーにとって絶対的な迷路であるため、後で行うことにします。
私は体系的なテストを行う必要がありませんでしたが、私はこのプロジェクトのために間違いなくそうするでしょう。（ii）選択した方法論に使用できるツールを学ぶ。（iii）選択したツールの使用方法を学ぶ。（iv）プロジェクトにテストスイートなどを実装します。これはそれ自体がプロジェクトです。
私がやらなければならないことが他にもあるかもしれません。たとえば、jonrsharpeは、git-flow、tox、TravisCI、virtualenv、およびCookieCutterについて言及する helpful link を投稿しました。（投稿は2013年のものなので、どれだけがまだ最新であるかを確認するために、いくつかの作業も行う必要があります。）

これをすべて組み合わせると、大変な作業になりますが、差し込み続ければ、すべて完了できると確信しており、急いでいません。私の問題は、それを1つずつ実行できる管理可能な手順に分割する方法を知ることです。

つまり、最終的にリリース可能な製品に到達するために、私が現在実行できる最も重要な具体的な手順はどれか、ということです。無料の週末がある場合、これらのうちどれに焦点を当てるべきですか？他に分離して実行できるものがある場合は、どれを実行すれば、すべてを実行する必要なく、少なくとも1つのステップを実行できますか？これらのことを学ぶ最も効率的な方法は何ですか？プロジェクト自体に集中する時間があるのですか？（これはすべて、本質的に趣味のプロジェクトであり、私の仕事ではないことを覚えておいてください。）私が実際に行う必要のないことはありますか。膨大な時間と労力？

すべての回答は大歓迎ですが、特にPython開発についての最新情報を参照しながら、これらのプロジェクト管理の側面に焦点を当てた回答を歓迎します。

Arseni Mourzenko · Answer

ライブラリを使用する場合、必要に応じてsetup.pyを追加することは最も重要なステップではありません。さらに重要なことは、ドキュメントを追加してライブラリを宣伝することです。 2番目のポイントはライブラリに強く依存するため、ドキュメントの側面に重点を置いて説明します。

あなたはあなたの図書館についてすべてを知っています。そして、これには問題があります。あなたはすでにインストール方法と使用方法を知っているので、多くのことが直感的または明白に見えるかもしれません。残念ながら、同じことはユーザーにとって明白でも直感的でもないかもしれません。自分のライブラリを何も知らないかのように見てみてください。さらに重要なこととして、他の人にライブラリを使用してもらい、彼らが抱えていたすべての困難を見つけるようにしてください。
図書館について、わかりやすい英語で説明します。あまりにも多くのライブラリーは、誰もがそれらについて知っていると想定しています。そうでない場合、ライブラリの目的が何であるかを理解するのは難しいかもしれません。
詳細な技術文書を書くだけでなく、ライブラリでいくつかのタスクを実行する方法を示す短いコードを忘れないでください。ほとんどの開発者は急いでおり、基本的なことを行う方法を理解するために何時間も費やす必要がある場合、他のライブラリに切り替える傾向があります。
連絡先情報を含めます。ライブラリが成功した場合（そして、私自身の経験によると、これはかなり未知のライブラリでも同様であることがわかりました）、人々はライブラリに問題を感じるでしょう：バグか、単にライブラリの一部を理解または使用することが困難です。多くの場合、フィードバックを受け取ってライブラリを改善すると便利です。問題を報告したすべての人にとって、問題が発生したときに別のライブラリに切り替えることを好む人が数百人いる可能性があります。

それに加えて：

ライブラリがPython 2または3または両方で動作するかどうかを明確にします。
ライブラリがWindowsで機能しない場合は、そのようにしてください。
必ず公式の規則を使用してください（確認するには、pep8を使用してください）。そうでない場合は、明確に説明するか修正してください。
Edgeケースの取り扱いに注意してください。ライブラリが間違ったタイプまたはサポートされていない値で呼び出された場合、それは、明白な英語で正確に何が間違っているかを示す必要があります。すべきではないことは、不可解な例外をスタックの10レベル下に上げ、ユーザーに何が問題かを理解させることです。

Jerry101 · Answer

これらは素晴らしい質問です。

リリース可能なライブラリに向けた重要な具体的な段階的ステップについて：

ライブラリとなるファイルをプロジェクトの他の部分から分離します。
- ライブラリは独自のgitリポジトリに移動する必要がありますが、現在のリポジトリ内の別の最上位ディレクトリにライブラリを配置するための中間ステップとして役立つ場合があります。別のリポジトリにする場合は、プロジェクトの残りの部分に隣接して保存し、pipのパッケージ化と開発モードの手順に進むまで../libraryを介して参照できるようにします。
- プロジェクトの残りの部分からこのライブラリへのすべてのアクセスは、そのパブリックAPIを経由する必要があります。あなたは離れてからかういくつかの相互依存関係を見つけるかもしれません。
ライブラリのAPIをドキュメント化するために、docstringを段階的に記述します。
- 最終的にdocstringはドキュメンテーションツールに送られますが、重要な作業は、APIを簡潔かつ十分に説明するテキストを他の人に書くことです。一度に少しずつ記入する方が簡単です。下書きを書いて、後でより良い説明や例が浮かんだら、後で書き直す方がはるかにうまくいきます。
- APIの一部を文書化するのが難しい場合は、APIのその部分に改善の余地があるかどうかを尋ねます。それはもっと簡単でしょうか？もっと規則的？あまりにも一般的ですか？専門的すぎる？より馴染みのある名前を使用できますか？
- Docstringは、ツールがチェックできる構造化コメントを使用して引数の型を文書化できます。まだ本当のドキュメントは見つかりませんが、PyCharm IDEはこれらのdocstringの構築に役立ち、メソッド呼び出しの編集中に引数の型をすぐにチェックします。
- そういえば、PyCharmは開発者の時間を節約し、コードの品質を向上させる素晴らしいツールです。「インスペクション」を実行して、コードを編集しながらコードをチェックします。可能な場合は型のチェック、欠落したインポートや未使用のインポートのチェック、メソッドの重複、PEP 8スタイルの間違いなど。
pytestを使用して単体テストの作成を開始します。リリースを作成するずっと前に、単体テストは、独自の開発でコーナーケースのバグを見つけ、コードの変更によって問題が解決されなかったという確信を提供することで報われます。繰り返しますが、これは時間をかけて構築することができます。始めるのはとても簡単です。
GitHub上の既存のオープンソースライブラリ（ほぼ同じサイズ）を調べて、ファイルとリリースがどのように構成されているかを確認します。彼らがどのようにバグ/問題の追跡とプルリクエストを行うかを見てください。経験がない場合は、これらの1人以上に貢献して、これらの複数人によるプロジェクト編成プロセスの経験を積んでください。 GitHubには、これらのプロセスに適したツールがあります。これは、最上位および任意のディレクトリにあるREADME.mdドキュメントファイルと、ライセンスファイルを使用して、適切な処理を行います。
ライブラリ、そのAPI、およびドキュメントに関するフィードバックを得るには、共同編集者の協力を検討してください。
- リリースするときは、休暇中にバグを修正するために1人以上の共同編集者に協力してもらい、ユーザーの質問に答えるのに役立ち、その間、コードレビューでプルリクエストを開始し、ライブラリを解放するタスクを分割することができます。また、プロジェクト管理とライブラリ設計に関する追加の経験をもたらします。
これまでは、線形のgitコミット履歴を作成してきました。最終的には、特定の修正や変更には「issueブランチ」、リリースへの制御された実行には「リリースブランチ」、マージの準備が整っていない進行中の複数人による作業には「開発ブランチ」を使用すると便利ですマスターブランチに。そのため、これらのGitスキルに依存する必要がある前に、1日か2日はこのことを学び、実践に取り掛かってください。 gitは非常に柔軟で便利ですが、ユーザーインターフェイス混乱する可能性があります。
- Gitブランチとその使用法について読む場所の1つは Pro Gitブックです。ブランチを使用する多くの方法のうち、「問題のブランチ」から始めます。
- GitHubデスクトップアプリは、ブランチを管理するための優れたツールです。また、すべての変更を確認しながらコミットメッセージを簡単に書き込むことができるため、コミットを行うのにも最適です。

esc_space · Answer

おそらく、あなたは自分の分野で成熟したOSSプロジェクトを見つけ、そのプロジェクトにコードを寄稿することができますか？次のようないくつかの利点があります。

あなたの貢献を最大化することができます。実際、多くの「趣味の」OSSプロジェクトは潜在的に価値がありますが、コミュニティではほとんど使用されていません（@ReaddyEddy回答を参照）。プロジェクトを最初からスクラッチにして、それを維持し、宣伝し、適切な例やドキュメントを提供するなど、それは多くの努力です。
あなたが言及した技術的な問題の多くは、成熟したプロジェクトですでに解決されています。
ライブラリがOSSプロジェクトに付加価値を与える場合、その貢献者がコードをプロジェクト標準に引き上げるのを助けることができます。したがって、労力を節約して経験を積むことができます。また、Sphinx、TravisCI、CookieCutterおよびその他の技術的側面に関する具体的な回答も得られます。

あなたが気に入って、おそらく使用する可能性のある関連するOSSプロジェクトがある場合は、問題やプルリクエストを開いたり、メンテナと連絡を取ったりしてみませんか？（開始する良い方法は、既存の問題を解決することかもしれません。）

laike9m · Answer

2019年です。最新のツールから始めることを強くお勧めします。 setup.pyは必要ありません。これはPythonコミュニティの人々が排除したいと考えているものであり、最終的にはそうすると思います。

詩を試してみてください、あなたはそれを後悔しません。

Bernhard · Answer

これはあなたが尋ねている複雑な質問であり、私は完全に同意します Arseniの答え。優れたドキュメントは非常に重要な側面です。いくつかの簡単な手順でライブラリを起動して実行できなかった場合は、そのままドロップします（実際に試してみたいと思わない限り）。

あなたが間違いなく検討するいくつかのこと

ライブラリをバージョン管理する方法について考えます。ある程度の下位互換性と、ルートに沿ったバグ修正も必要です。セマンティックバージョニングについて読む
Gitを比較的直線的に使用しています（元に戻すため）。 gitでの分岐に精通していますか。それは本当にそれほど難しくなく、人生を楽にします。枝をつかんだら。ブランチモデルをリポジトリに適合させます。この分岐モデルの、関連があると思われる部分を選択します。また、これを、使用しているリポジトリからのブランチと比較してください。
ライセンス：ライブラリのライセンスを提供する必要があります。私はこの問題の法的専門家ではないので、これへのリンクのみを共有できます一般的なライセンスの比較。この選択を軽くしないでください。
バグトラッカー。そのユーザーがバグレポートを提供できるようにしたい。これは、コードの品質を向上させるのに役立ちます。解決するバグごとに、テストフレームワークにテストを追加します。これにより、将来的に機能が停止しないことが保証されます（回帰テスト）。バグ追跡システムは、機能のリクエストに使用できます。
ユーザーの貢献。ユーザーの投稿を希望しますか？これがオープンソース製品で通常どのように機能するかはわかりませんが、ユーザーが機能ブランチを作成できるようにできると想像できます。 github経由であなたはこれをプルリクエストで制御できるようです

私はPythonに関連した経験がないので、その方向についてのヒントを与えることはできません。ただし、リモートリポジトリでの各コミットによってトリガーされるすべてのテストを自動化することは可能です（つまり、 Jenkins を使用）。ただし、これは延期することをお勧めします。これは、事前の経験なしに設定するのは多くの作業だからです。

ReaddyEddy · Answer

長年にわたって成熟したライブラリよりかなり少ない数のライブラリを使用してきたことで、導入ツールを選択した後の重要なアドバイスは次のとおりです。

ライブラリの依存関係を特定します。

整理コンテナーまたはVMのいずれかのクリーンな環境へのデプロイメントを試みます。問題を引き起こす個人的な環境には独特のものがしばしばあるため、このステップは非常に重要であると考えています。

誰が将来ライブラリを保守するかを検討します。誰かのペットプロジェクトであったライブラリを3〜4年間使用していて、最新の状態に保つために必要な更新を取得できないことほど不満はありません。

あなたまたはあなたのチームがライブラリのテストと文書化を継続することを約束するかどうかを検討してください（単体テストとCIパイプラインはここで方程式の一部になり始めます）。