PyPI 包下载分析

---

本文翻译自：Analyzing PyPI package downloads
https://packaging.python.org/en/latest/guides/analyzing-pypi-package-downloads/

---

本节介绍如何使用公共 PyPI下载统计数据集 来详细了解托管在PyPI上的一个（或多个）包的下载情况。
例如，您可以使用它来发现用于下载包的Python版本的分布。

---

一、背景

由于以下原因，PyPI不显示下载统计信息： 见[1]

• 使用内容分布网络（CDN）效率低下：下载统计信息不断变化。
  将它们包含在大量缓存的项目页面中，将需要更频繁地使缓存无效，并降低缓存的整体有效性。
• 高度不准确：有许多事情会阻止下载计数准确，其中一些包括：
  • pip的下载缓存（降低下载次数）
  • 内部或非官方镜像（都可以提高或降低下载次数）
  • 未托管在PyPI上的包（为了比较）
  • 下载计数膨胀的非官方脚本或尝试（提高下载计数）
  • 已知的历史数据质量问题（降低下载次数）
• 不是特别有用：仅仅因为一个项目被下载了很多并不意味着它是好的；
  同样，仅仅因为一个项目没有被下载很多并不意味着它是坏的！

简而言之，由于各种原因，它的价值很低，而且使它发挥作用所需的权衡很高，所以它没有有效利用有限的资源。

---

二、公共数据集

作为替代方案，Linehaul project 流将日志从PyPI下载到 Google BigQuery [2] ，它们所在的位置 存储为公共数据集。

---

1、设置

为了使用Google BigQuery 查询 公共PyPI下载统计数据集，您需要一个Google帐户并启用 BigQuery Google Cloud Platform项目上的API。
您每月最多可以运行1TB的查询, 使用BigQuery免费层，无需信用卡

• 导航到 BigQuery Web UI。
• 创建一个新项目。
• 启用 BigQuery API。

有关如何开始使用BigQuery的更详细说明，请查看 这是BigQuery快速入门指南。

---

2、数据 schema

在bigquery-public-data.pypi.file_downloads表中写入一个条目 下载。
该表包含有关下载了什么文件以及如何下载的信息 它被下载了。
一些有用的列在 表schema 包括：

列	描述	例子
时间戳	日期和时间	2020-03-09 00:33:03 UTC
file.project	项目名称	pipenv，nose
file.version	包版本	0.1.6, 1.4.2
details.installer.name	安装	皮普，班德抢夺
details.python	Python版本	2.7.12, 3.6.4

---

3、有用的查询

通过单击Compose query 按钮在BigQuery Web UI 中运行查询。

请注意，行存储在分区表中，这很有帮助 限制查询成本。这些示例查询分析来自 通过过滤timestamp列的最近历史记录。

---

计算包下载

以下查询计算项目“pytest”的总下载次数。

#standardSQL
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()

---

num_downloads
26190085

---

仅计算来自pip的下载，过滤details.installer.name 列.

#standardSQL
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  AND details.installer.name = 'pip'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()

---

num_downloads
24334215

---

随时间下载包

要按每月下载量分组，请使用TIMESTAMP_TRUNC函数。
按此列过滤 可降低相应的成本。

#standardSQL
SELECT
  COUNT(*) AS num_downloads,
  DATE_TRUNC(DATE(timestamp), MONTH) AS `month`
FROM `bigquery-public-data.pypi.file_downloads`
WHERE
  file.project = 'pytest'
  -- Only query the last 6 months of history
  AND DATE(timestamp)
    BETWEEN DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 6 MONTH), MONTH)
    AND CURRENT_DATE()
GROUP BY `month`
ORDER BY `month` DESC

---

num_downloads	月
1956741	2018-01-01
2344692	2017-12-01
1730398	2017-11-01
2047310	2017-10-01
1744443	2017-09-01
1916952	2017-08-01

---

Python 版本

从 details.python列 提取，Python版本。
查询处理超过500 GB的数据。

#standardSQL
SELECT
  REGEXP_EXTRACT(details.python, r"[0-9]+\.[0-9]+") AS python_version,
  COUNT(*) AS num_downloads,
FROM `bigquery-public-data.pypi.file_downloads`
WHERE
  -- Only query the last 6 months of history
  DATE(timestamp)
    BETWEEN DATE_TRUNC(DATE_SUB(CURRENT_DATE(), INTERVAL 6 MONTH), MONTH)
    AND CURRENT_DATE()
GROUP BY `python_version`
ORDER BY `num_downloads` DESC

---

python	num_downloads
3.7	18051328726
3.6	9635067203
3.8	7781904681
2.7	6381252241
零	2026630299
3.5	1894153540

---

获取到工件的绝对链接

它有时是 有帮助的，能够获得绝对的链接下载。
来自PyPI的工件基于它们的哈希值，例如如果一个特定的项目 或 发布 已从PyPI中删除。
元信息表包括path 列，其中包括散列和工件文件名。

注：此处生成的URL不能保证稳定，但目前与托管PyPI工件的URL保持一致。

SELECT
  CONCAT('https://files.pythonhosted.org/packages', path) as url
FROM
  `bigquery-public-data.pypi.distribution_metadata`
WHERE
  filename LIKE 'sampleproject%'

网址
https://files.pythonhosted.org/packages/eb/45/79be82bdeafcecb9dca474cad4003e32ef8e4a0dec6abbd4145ccb02abe1/sampleproject-1.2.0.tar.gz
https://files.pythonhosted.org/packages/56/0a/178e8bbb585ec5b13af42dae48b1d7425d6575b3ff9b02e5ec475e38e1d6/sampleproject_nomura-1.2.0-py2.py3-none-any.whl
https://files.pythonhosted.org/packages/63/88/3200eeaf22571f18d2c41e288862502e33365ccbdc12b892db23f51f8e70/sampleproject_nomura-1.2.0.tar.gz
https://files.pythonhosted.org/packages/21/e9/2743311822e71c0756394b6c5ab15cb64ca66c78c6c6a5cd872c9ed33154/sampleproject_doubleyoung18-1.3.0-py2.py3-none-any.whl
https://files.pythonhosted.org/packages/6f/5b/2f3fe94e1c02816fe23c7ceee5292fb186912929e1972eee7fb729fa27af/sampleproject-1.3.1.tar.gz

---

三、警告

除了上面背景中列出的警告之外，Lineard还遭受了bug，导致其在2018年7月26日之前大大低估了下载统计数据。
在此日期之前的下载量按比例准确（例如 Python2 vs Python3下载量的百分比），但总数比实际低一个数量级。

---

四、附加工具

除了使用BigQuery控制台，还有一些额外的工具在分析下载统计信息时可能很有用。

---

1、google-cloud-bigquery

您还可以访问公共PyPI下载统计数据集，通过BigQuery API和google-cloud-bigquery项目以编程方式， BigQuery的官方Python客户端库。

from google.cloud import bigquery

# Note: depending on where this code is being run, you may require
# additional authentication. See:
# https://cloud.google.com/bigquery/docs/authentication/
client = bigquery.Client()

query_job = client.query("""
SELECT COUNT(*) AS num_downloads
FROM `bigquery-public-data.pypi.file_downloads`
WHERE file.project = 'pytest'
  -- Only query the last 30 days of history
  AND DATE(timestamp)
    BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
    AND CURRENT_DATE()""")

results = query_job.result()  # Waits for job to complete.
for row in results:
    print("{} downloads".format(row.num_downloads))

---

2、pypinfo

pypinfo 是一个命令行工具，它提供对数据集和 可以生成几个有用的查询。
例如，您可以使用pypinfo package_name 命令 查询 包的下载总次数。

使用pip安装 pypinfo。

python3 -m pip install pypinfo

---

用法：

$ pypinfo requests
Served from cache: False
Data processed: 6.87 GiB
Data billed: 6.87 GiB
Estimated cost: $0.04

| download_count |
| -------------- |
|      9,316,415 |

---

3、pandas-gbq

该pandas-gbq 项目允许通过 Pandas 访问查询结果。

---

参考文献

[1] PyPI下载计数弃用电子邮件
[2] PyPI BigQuery数据集公告电子邮件

---

2024-06-06（四）