🐍

PyPIのProject linkセクションにカスタムURLを表示する方法

2022/03/14に公開

この記事は、スクラップでまとめながら調査した内容を記事に書き直した記事です。
(また、自分のブログにも英語で投稿しています。)

1. きっかけ

NumPyPandas の PyPI 上のページを見ていた時に、サイドバーの『Project links』のセクションに様々なリンクが表示されていることに気が付きました。一方で拙作の cpprb は(当時)『Homepage』しかリンクがありませんでした。


https://pypi.org/project/numpy/ のサイドバー

そこで、このリンクがどうすれば表示されるか、またリンクだけではなく、アイコンもありどのように指定しているのかを調査することにしました。

2. 調査

2.1 調査対象

今回調査をしている際に初めて知ったのですが、PyPIのホスティングサーバーは、warehouse というOSSでした。

https://github.com/pypa/warehouse

(PyPIのフッターにある『Contribute on GitHub』というリンクから見つけました。)

https://pypi.org/ のフッター(の一部)

2.2 リンク

urldownload_urlproject_urls に指定したリンクが表示されます。

url は『Homepage』、download_urlは『Download』と解釈され、project_urlsはラベル名とURLのセットで指定します。

https://github.com/pypa/warehouse/blob/cd9dd933343f855aa8a3a8235c9baf46b0421249/warehouse/templates/includes/packaging/project-data.html#L15-L30

https://github.com/pypa/warehouse/blob/cd9dd933343f855aa8a3a8235c9baf46b0421249/warehouse/packaging/models.py#L483-L499

2.3 アイコン

アイコンはユーザーによる指定ではなく、『ラベル名』や『URL』から自動的に選定される仕組みでした。
https://github.com/pypa/warehouse/blob/cd9dd933343f855aa8a3a8235c9baf46b0421249/warehouse/templates/packaging/detail.html#L20-L60

例えば、『ラベル名』を小文字にした時に『download』だとダウンロードアイコンが、『URL』に『github.com』や『github.io』が含まれている際にはGitHubアイコンが利用されます。

2.4 おまけ

urlproject_urls にGitHubのURLが含まれると、starやforkの数などを表示する『GitHub statistics』のセクションが表示されるようになります。

https://github.com/pypa/warehouse/blob/cd9dd933343f855aa8a3a8235c9baf46b0421249/warehouse/templates/includes/packaging/project-data.html#L34

https://github.com/pypa/warehouse/blob/cd9dd933343f855aa8a3a8235c9baf46b0421249/warehouse/packaging/models.py#L483-L508

3. 完成

ここまでの調査内容を元に、setup.py に次のように指定しました。

setup.py(抜粋)
setup(name="cpprb",
      # 省略
      url="https://ymd_h.gitlab.io/cpprb/",
      project_urls={
          "Source Code": "https://gitlab.com/ymd_h/cpprb",
          "Mirror": "https://github.com/ymd-h/cpprb",
          "Change Log": "https://ymd_h.gitlab.io/cpprb/changelog/",
          "Bug Report & QA": "https://github.com/ymd-h/cpprb/discussions"
      },
      # 省略
      )


https://pypi.org/project/cpprb/

追記: 2022/3/16

記事公開後に友人から、project_urlsの指定と、PyPI上での表示の順番が逆になっていて気持ち悪いと指摘を受けました。
確かにと思って、二人で調査をし、その友人が issue を見つけてくれました。

https://github.com/pypa/warehouse/issues/3097

どうやら一旦データを保存しているデータベースの返答順序に依存しており、2018年から逆順だと報告されているものも修正されないままになっているようです。

Discussion