kagglehub

Kaggle Hub 客户端库

安装

使用 pip 安装kagglehub包：

pip install kagglehub

用法

认证

仅当访问需要用户同意的公共资源或私有资源时才需要进行身份验证。

首先，您需要一个 Kaggle 帐户。您可以在这里注册。

登录后，您可以通过单击“API”部分下的“创建新令牌”按钮，在 https://www.kaggle.com/settings 下载您的 Kaggle API 凭证。

您有 3 种不同的身份验证选项。

选项1：调用kagglehub.login()

这将提示您输入用户名和令牌：

导入kagglehubkagglehub.login()

选项 2：从环境变量中读取凭据

您还可以选择将 Kaggle 用户名和令牌导出到环境中：

导出 KAGGLE_USERNAME=datadinosaurexport KAGGLE_KEY=xxxxxxxxxxxxxx

选项 3：从kaggle.json读取凭据

将您的kaggle.json凭证文件存储在~/.kaggle/kaggle.json 。

或者，您可以设置KAGGLE_CONFIG_DIR环境变量以将此位置更改为$KAGGLE_CONFIG_DIR/kaggle.json 。

Windows 用户注意：默认目录是%HOMEPATH%/kaggle.json 。

选项 4：从 Google Colab 机密中读取凭据

将您的用户名和密钥令牌存储为 Colab 秘密KAGGLE_USERNAME和KAGGLE_KEY 。

有关在 Colab 和 Colab Enterprise 中添加机密的说明，请参阅本文。

下载模型

以下示例下载此 Kaggle 模型的answer-equivalence-bem变体：https://www.kaggle.com/models/google/bert/tensorFlow2/answer-equivalence-bem

 import kagglehub# 下载最新版本.kagglehub.model_download('google/bert/tensorFlow2/answer-equivalence-bem')# 下载特定版本.kagglehub.model_download('google/bert/tensorFlow2/answer-equivalence-bem/1 ')# 下载单个文件.kagglehub.model_download('google/bert/tensorFlow2/answer-equivalence-bem', path='variables/variables.index')# 下载模型或文件，即使之前下载到了缓存。kagglehub.model_download('google/bert/tensorFlow2/answer-equivalence-bem', force_download=True)

上传模型

上传新变体（如果已存在，则上传新变体的版本）。

 import kagglehub# 例如，要将新变体上传到此模型：# - https://www.kaggle.com/models/google/bert/tensorFlow2/answer-equivalence-bem# # 您将使用以下句柄：` google/bert/tensorFlow2/answer-equivalence-bem`handle = '<KAGGLE_USERNAME>/<MODEL>/<FRAMEWORK>/<VARIATION>'local_model_dir = 'path/to/local/model/dir'kagglehub.model_upload(handle, local_model_dir)# 也可以指定一些版本说明（可选）kagglehub.model_upload(handle, local_model_dir, version_notes='improved precision')# 也可以指定许可证（可选）kagglehub.model_upload(handle, local_model_dir, license_name='Apache 2.0')# 可以还指定要忽略的文件/目录的模式列表。 # 这些模式与 `kagglehub.models.DEFAULT_IGNORE_PATTERNS` 组合 # 以确定要排除哪些文件和目录。 # 要忽略整个目录，请在模式中包含尾部斜杠 (/)。kagglehub.model_upload(handle, local_model_dir,ignore_patterns=["original/", "*.tmp"])

下载数据集

以下示例下载Spotify Recommendation Kaggle 数据集：https://www.kaggle.com/datasets/bricevergnou/spotify-recommendation

 import kagglehub# 下载最新版本 kagglehub.dataset_download('bricevergnou/spotify-recommendation')# 下载特定版本 kagglehub.dataset_download('bricevergnou/spotify-recommendation/versions/1')# 下载单个文件kagglehub.dataset_download( 'bricevergnou/spotify-推荐', path='data.csv')# 下载数据集或文件，即使之前下载到了cache.kagglehub.dataset_download('bricevergnou/spotify-recommendation', force_download=True)

上传数据集

上传新数据集（如果已存在，则上传新版本）。

 import kagglehub# 例如，要在以下位置上传新数据集（或版本）：# - https://www.kaggle.com/datasets/bricevergnou/spotify-recommendation# # 您将使用以下句柄：`bricevergnou/spotify-推荐`handle = '<KAGGLE_USERNAME>/<DATASET>local_dataset_dir = 'path/to/local/dataset/dir'# 创建一个新的数据集kagglehub.dataset_upload(handle, local_dataset_dir)# 然后您可以创建此现有数据集的新版本并包含版本说明（可选）。kagglehub.dataset_upload(handle, local_dataset_dir, version_notes='improved data')# 您还可以指定要忽略的文件/目录的模式列表。# 这些模式与`kagglehub.datasets.DEFAULT_IGNORE_PATTERNS` # 确定要排除哪些文件和目录。 # 要忽略整个目录，请在模式中包含尾部斜杠 (/)。kagglehub.dataset_upload(handle, local_dataset_dir,ignore_patterns=["original/", "*.tmp"])

下载竞赛

以下示例下载Digit Recognizer Kaggle 竞赛：https://www.kaggle.com/competitions/digit-recognizer

 import kagglehub# 下载最新版本.kagglehub.competition_download('digit-recognizer')# 下载单个文件kagglehub.competition_download('digit-recognizer', path='train.csv')# 下载比赛或文件，即使之前有下载到缓存。 kagglehub.competition_download（'数字识别器'，force_download = True）

发展

先决条件

我们使用孵化来管理这个项目。

请按照以下说明进行安装。

测试

# 运行当前 Python 版本的所有测试.hatch test# 运行所有 Python 版本的所有测试.hatch test --all# 运行特定 Python 版本的所有测试.hatch test -py 3.11# 运行单个测试文件hatch test tests/test_ <某些文件>.py

集成测试

要在本地计算机上运行集成测试，您需要设置 Kaggle API 凭据。您可以通过本文档前面部分中描述的两种方法之一来执行此操作。请参阅以下部分：

• 使用环境变量

• 使用凭证文件

通过任何这些方法设置凭据后，您可以运行集成测试，如下所示：

 # 运行所有testshatch测试integration_tests

从源代码运行kagglehub

 # 下载模型并打印路径 hatch run python -c "import kagglehub; print('path: ', kagglehub.model_download('google/bert/tensorFlow2/answer-equivalence-bem'))"

棉绒/格式

# Lint checkhatch 运行 lint:style
孵化运行 lint: 打字
hide run lint:all # 对于两者# Formathatch run lint:fmt

覆盖率报告

孵化测试--覆盖

建造

孵化建造

在 Docker 内运行hatch命令

这对于在一致的环境中运行并在 Python 版本之间轻松切换非常有用。

下面显示了如何运行hatch run lint:all但这也适用于任何其他孵化命令：

# Use default Python version
./docker-hatch run lint:all

# Use specific Python version (Must be a valid tag from: https://hub.docker.com/_/python)
./docker-hatch -v 3.9 run lint:all

# Run test in docker with specific Python version
./docker-hatch -v 3.9 test

VS 代码设置

先决条件

安装推荐的扩展。

指示

配置孵化以在项目文件夹中创建虚拟环境。

hatch config set dirs.env.virtual .env

之后，通过运行hatch -e all run tests来创建所需的所有 python 环境。

最后，配置 vscode 使用选定的环境之一： cmd + shift + p -> python: Select Interpreter -> 选择./.env中的文件夹之一

支持

kagglehub 库已配置自动日志记录，该日志记录存储在日志文件夹中。日志目标通过 os.path.expanduser 解析

下表包含可能的位置：

操作系统	日志路径
操作系统	/user/$USERNAME/.kaggle/logs/kagglehub.log
操作系统	〜/.kaggle/logs/kagglehub.log
视窗	C:Users%USERNAME%.kagglelogskagglehub.log

请包含日志以帮助解决问题。