Kubernetes Python Client 下载统计指南：用 BigQuery 公共数据集洞察 PyPI 发行版下载量-育师

后端
云原生
容器编排

【免费下载链接】python

Official Python client library for kubernetes

项目地址：https://gitcode.com/gh_mirrors/python1/python

导读

Kubernetes 官方 Python 客户端（PyPI 包名kubernetes）以源码、wheel 包等形式发布到 PyPI 后，其下载行为会被 PyPI 完整记录下来。本文基于仓库内 devel/stats.md 的说明，介绍如何借助 PyPI 存储在 Google BigQuery 上的公共数据集the-psf:pypi，用 SQL 对kubernetes包各版本、各时间段的下载量进行统计与趋势分析。读完本文，你将掌握下载数据集的位置与结构、一份可立即运行的按版本下载量统计查询，以及围绕该查询的多种扩展思路，并理解它与本仓库版本号体系、发布流程之间的关联。

PyPI 下载数据与 BigQuery 公共数据集

PyPI（Python Package Index）会把每一次包下载的记录存储到 Google BigQuery 的公共数据集中，数据集 ID 为the-psf:pypi（公共数据集页面为the-psf:pypi，下辖downloads系列表）。由于这份数据对公众开放，任何人都可以直接用 BigQuery 查询，获得比 PyPI 网页统计更细粒度、可自由聚合的下载信息。

从 devel/stats.md 的示例查询可以看出，下载记录表具备两个关键维度：

日期维度：downloads表按日期切分（按日分表存储），查询时通过TABLE_DATE_RANGE指定起始日期与结束日期，即可跨日期聚合；
文件维度：每条下载记录对应一个具体的发布文件（file），可通过file.project区分项目名、通过file.version区分版本号。

对于本仓库而言，PyPI 上的项目名即 setup.py 中声明的PACKAGE_NAME = "kubernetes"（同时CLIENT_VERSION = "37.0.0+snapshot"），因此统计查询中的过滤条件就是file.project == "kubernetes"。

核心示例：按版本统计 kubernetes 包下载量

devel/stats.md 给出了一个可直接复用的查询，用于统计从 2016 年 11 月 20 日至今，kubernetes包各版本的累计下载量，并按下载量降序取前 20：

SELECT file.version, COUNT(*) as total_downloads, FROM TABLE_DATE_RANGE( [the-psf:pypi.downloads], TIMESTAMP("20161120"), CURRENT_TIMESTAMP() ) where file.project == "kubernetes" GROUP BY file.version ORDER BY total_downloads DESC LIMIT 20

逐句拆解如下：

片段	作用
`SELECT file.version, COUNT(*) as total_downloads`	以版本号为分组键，对命中的下载记录逐条计数，得到每个版本的下载总量
`TABLE_DATE_RANGE([the-psf:pypi.downloads], TIMESTAMP("20161120"), CURRENT_TIMESTAMP())`	遍历`downloads`从 2016-11-20 起到当前时刻的所有按日分表，这是旧版 BigQuery Legacy SQL 按日期范围跨表查询的写法
`where file.project == "kubernetes"`	只保留 PyPI 项目名为`kubernetes`的下载记录（注意 Legacy SQL 中比较运算使用`==`）
`GROUP BY file.version`	按版本聚合
`ORDER BY total_downloads DESC`	下载量从高到低排序，便于快速识别用户量最大的版本
`LIMIT 20`	只返回下载量最高的 20 个版本

如果你希望改用新版 BigQuery 标准 SQL，可以将上述 Legacy 查询等价改写为基于_TABLE_SUFFIX分区表达式的形式：

SELECT file.version, COUNT(*) AS total_downloads FROM `the-psf.pypi.downloads*` WHERE file.project = 'kubernetes' AND _TABLE_SUFFIX BETWEEN '20161120' AND FORMAT_DATE('%Y%m%d', CURRENT_DATE()) GROUP BY file.version ORDER BY total_downloads DESC LIMIT 20

两种写法查询的是同一份数据，标准 SQL 写法在字段引用（单引号字符串、=比较）上更贴近现代习惯。

结合版本号体系做精细统计

本仓库的版本号遵循 devel/release.md 中约定的x.y.zDn格式：D取a（alpha 预发布）或b（beta 预发布），正式版则省略Dn；此外还有持续随 master 分支更新的x.y.0+snapshot快照版本。当前版本常量可见于 scripts/constants.py（CLIENT_VERSION = "37.0.0+snapshot"）与 setup.py。因此在实际分析中，可以针对性地统计：

某个大版本系列的整体采用情况：对file.version使用前缀匹配（如file.version LIKE '37%'），观察37.0.0a1、37.0.0b1、37.0.0各阶段下载量的爬坡过程；
预发布与正式版的占比：通过file.version LIKE '%.0a%' OR file.version LIKE '%.0b%'过滤出 alpha/beta 版本下载量，评估社区对先行版的尝鲜意愿；
指定版本的精确下载量：将file.version == "36.0.3"等精确值代入查询，便于发版后复盘单个 release 的接受度。

需要说明的是，file.version的实际取值以 PyPI 上发布的历史版本为准；本仓库 README.md 中维护的"客户端版本 ↔ Kubernetes 版本"兼容矩阵（例如 client 36.y.z 对应 Kubernetes 1.36、client 37.y.z 对应 Kubernetes 1.37）也可以作为解读版本下载数据的辅助上下文。

下载统计与发布流程的闭环关系

要理解这份统计数据，最好把它放进本仓库的发布链路中看：

开发维护者按照 devel/release.md 的流程，用scripts/release.sh（配合 scripts/constants.py 中的KUBERNETES_BRANCH、CLIENT_VERSION、DEVELOPMENT_STATUS常量）生成快照或 alpha/beta/stable 版本；
在干净环境中通过python setup-release.py sdist、python setup-release.py bdist_wheel --universal构建发行包，再用twine upload dist/*上传到 PyPI；
包上传成功之后，用户的pip install kubernetes（见 README.md 的安装说明）才会产生下载记录，进而进入 BigQuery 公共数据集，成为本文所述 SQL 统计的数据来源。

也就是说，下载统计是发布动作的"结果观测"：setup.py中的CLIENT_VERSION决定了一个下载记录上的file.version取值，devel/release.md 的发布节奏（快照 → a1 → b1 → final，间隔约两周）则塑造了下载曲线上的阶段性爬升。从源码结构看，仓库目前没有内置下载统计工具，devel/stats.md 即为该项目面向维护者的官方统计入口。

注意事项

上述查询运行在 Google BigQuery 上，需要 BigQuery 账号与执行查询的权限；公共数据集本身免费可查，但超出免费配额的大规模扫描可能产生费用，建议在查询中始终用WHERE file.project == "kubernetes"和日期范围缩小扫描面；
示例采用旧版 Legacy SQL 语法（TABLE_DATE_RANGE、[dataset.table]、==），若控制台默认使用标准 SQL，请使用本文给出的标准 SQL 等价写法；
统计数据反映的是 PyPI 侧的下载行为，与仓库内部代码、CHANGELOG.md 中记录的 API 变更相互独立，解读下载量时应结合对应版本的 README.md 兼容矩阵与发布说明进行。