数据分析CLI数据可视化【免费下载链接】visidataA terminal spreadsheet multitool for discovering and arranging data项目地址https://gitcode.com/gh_mirrors/vi/visidata点击查看免费下载本文以 docs/gmail.md 为主体系统讲解如何在 Google Cloud Console 中创建 OAuth 2.0 应用、启用 Gmail API、生成客户端凭据并最终通过vd imap://...imap.gmail.com在 VisiData 中以表格形式浏览 Gmail 邮件的完整流程。读完本文你将掌握从 Google 侧凭据申请到 VisiData 侧 IMAP 加载的端到端配置方法并理解底层XOAUTH2认证、凭据缓存与刷新机制的工作原理。为什么需要 OAuth 2.0自 2022 年 5 月 30 日起Google 不再允许仅凭用户名 密码组合登录 IMAP Gmail 账户即传统的应用专用密码之外的密码直连方式被禁用。因此要在 VisiData 中打开 Gmail需要在 Google Cloud Console 创建一个 Google API 应用为应用附加必要的 scope授权范围这里为https://mail.google.com/生成 client ID 与 client secret让 VisiData 使用这份凭据存于一个 JSON 文件中完成 OAuth 2.0 授权。整个流程由 VisiData 的 IMAP 加载器visidata/loaders/imap.py和 Google 认证辅助模块visidata/loaders/google.py驱动。前置依赖VisiData 的 Google OAuth 支持依赖以下 Python 库由google_auth函数在运行时导入见 visidata/loaders/google.pygoogle-auth负责凭据对象、过期刷新creds.refresh(Request())google-auth-oauthlib提供InstalledAppFlow用于本地 OAuth 授权流程flow.run_local_server(port0)imaplib、email.parserPython 标准库用于 IMAP 连接与邮件解析见 visidata/loaders/imap.py。安装 VisiData 时请确保这些依赖可用缺少时在认证环节会抛出导入错误。第一步创建 Google Cloud 项目打开 Google Cloud Console点击CREATE PROJECT创建项目为项目命名后点击CREATE完成创建。第二步启用 Gmail API新开一个标签页访问 API Library搜索gmail点击搜索结果中的Gmail API点击ENABLE启用该 API第三步配置 OAuth consent screen回到第一个标签页在左侧菜单中选择OAuth consent screen选择External外部用户并点击CREATE创建应用为应用命名并输入你的 Gmail 地址点击ADD OR REMOVE SCOPES添加授权范围搜索gmail勾选 scope 值为https://mail.google.com/的行然后滚动到页面底部点击UPDATE此时应能看到已选中的 scope点击SAVE AND CONTINUE保存点击ADD USERS添加测试用户输入你的 Gmail 地址并点击ADD注意https://mail.google.com/属于敏感/受限 scope。在应用通过 Google 的验证审核之前只有你添加为测试用户的账户才能完成授权。把 Gmail 地址加入测试用户列表是为了保证 OAuth 流程能立即在你的账户上走通。第四步创建 OAuth 客户端并下载 JSON 凭据在左侧点击Credentials凭据在页面顶部点击CREATE CREDENTIALS然后选择OAuth client ID选择应用类型Desktop App桌面应用为 OAuth 2.0 客户端命名后点击CREATE点击DOWNLOAD JSON下载客户端凭据文件并将其移动到 VisiData 项目目录中第五步放置凭据文件原文档 docs/gmail.md 给出的指引是把下载的 JSON 文件放到路径vdplus/api/google/下并命名为google-creds.json。不过需要特别说明当前仓库源码 visidata/loaders/google.py 中的_google_creds_fn()实际查找的文件名是google_creds.json下划线并通过vd.pkg_resources_files(vdplus.api.google)解析包资源目录def _google_creds_fn(): filename google_creds.json google_creds_path vd.pkg_resources_files(vdplus.api.google) / filename import os if not os.path.exists(google_creds_path): vd.error(f{filename} file does not exist in {google_creds_path.parent}\n Create it by following this guide: https://github.com/saulpw/visidata/blob/develop/docs/gmail.md) else: return str(google_creds_path)因此实践中请以源码要求为准文件必须命名为google_creds.json下划线并放置到vdplus.api.google包资源对应的目录即 VisiData 加载器所在包目录当前仓库中为 visidata/loaders/ 对应的安装位置。若文件名或路径不匹配VisiData 会直接报错google_creds.json file does not exist in ...并提示参照本指南创建。文档中的google-creds.json连字符与源码中的google_creds.json下划线存在出入这是配置时最容易踩的坑请以源码的文件名为准。第六步用 vd 命令打开 Gmail凭据就绪后在命令行运行把邮箱地址换成你自己的vd imap://megmail.comimap.gmail.com此时 VisiData 会触发 OAuth 授权流程弹出浏览器窗口在浏览器中选择你配置时使用的那个 Google 账户点击Select all同意全部权限授权完成后回到 VisiData即可看到以表格形式加载的 Gmail 邮件列表注意Gmail 场景下不需要也不应在 URL 中指定密码。这一点在 docs/formats.md 的 imap 小节中同样有说明vd imap://someonegmail.comimap.gmail.com—— you dont specify a password for gmail here; instead, you will be prompted to follow some instructions此处不指定密码而是按提示完成 OAuth 授权。底层原理ImapSheet 与 XOAUTH2 认证链路1. URL 解析与加载器注册openurl_imap是 imap 加载器的入口visidata/loaders/imap.pyVisiData.api def openurl_imap(vd, url, **kwargs): url_parsed urlparse(str(url)) return ImapSheet(url_parsed.hostname, sourceurl_parsed, passwordurl_parsed.password)它把imap://user:passhost形式的 URL 解析为ImapSheetusername、password、hostname均来自 URL 的各组成部分。2. 按主机名分流Gmail 走 XOAUTH2其他走密码登录ImapSheet.iterload()的核心逻辑visidata/loaders/imap.pym imaplib.IMAP4_SSL(hostself.source.hostname) user self.source.username if self.source.hostname imap.gmail.com: credentials vd.google_auth(scopeshttps://mail.google.com/) header_template user%s\1authBearer %s\1\1 m.authenticate(XOAUTH2, lambda x: header_template % (user, credentials.token)) else: if self.password is None: vd.error(no password given in url) m.login(user, self.source.password)当主机是imap.gmail.com时调用vd.google_auth()获取凭据并以XOAUTH2认证机制登录构造user邮箱\1authBearer access_token\1\1作为认证头其他 IMAP 服务器如 Outlook/Hotmail仍走传统的用户名密码登录此时 URL 中必须带密码否则直接报错no password given in url。3. 邮件加载与展示认证成功后iterload()会通过m.list()枚举所有邮件文件夹逐个文件夹m.select(fname)后用m.search(None, ALL)取全部邮件编号用m.fetch(num, (RFC822))拉取原始邮件email.message_from_bytes解析为邮件对象并注入folder属性后 yield顶层columns定义了邮件表格的列message-id、folder、Date、From、To、Subject、defects、payload、content_typeaddRow对 multipart 邮件递归展开把父邮件头复制到每个子 payload 上再逐层入表保证多部分邮件如带附件的 HTML文本邮件也能按行查看。4. google_auth凭据缓存、刷新与本地授权google_auth函数visidata/loaders/google.py实现了完整的凭据生命周期GOOGLE_TOKEN_FILE Path(vd.options.visidata_dir)/fgoogle-{urllib.parse.quote_plus(str(scopes))}.pickle creds None if os.path.exists(GOOGLE_TOKEN_FILE): with open(GOOGLE_TOKEN_FILE, rb) as fp: creds pickle.load(fp) if not creds or not creds.valid: if creds and creds.expired and creds.refresh_token: from google.auth.transport.requests import Request creds.refresh(Request()) else: from google_auth_oauthlib.flow import InstalledAppFlow flow InstalledAppFlow.from_client_secrets_file(_google_creds_fn(), SCOPES) creds flow.run_local_server(port0) with open(GOOGLE_TOKEN_FILE, wb) as fp: pickle.dump(creds, fp)其流程可归纳为读取缓存授权令牌以 pickle 形式缓存在 VisiData 配置目录vd.options.visidata_dir下文件名按 scope 字符串 URL 编码生成如google-https%3A%2F%2Fmail.google.com%2F.pickle同一 scope 的令牌可复用有效性判断缓存存在且creds.valid为真则直接复用不再弹浏览器自动刷新令牌过期但持有refresh_token时通过google.auth.transport.requests.Request静默刷新无需用户干预首次授权无有效缓存时用InstalledAppFlow.from_client_secrets_file(_google_creds_fn(), SCOPES)读取你下载的凭据 JSONrun_local_server(port0)在本地随机端口起一个回环服务并打开浏览器完成授权回写缓存新获取或刷新后的凭据重新 pickle 到缓存文件后续打开直接命中。此外google_auth会对 scope 做归一化处理不以https://开头的 scope 会自动补全为https://www.googleapis.com/auth/前缀例如传入spreadsheets.readonly会被扩展为https://www.googleapis.com/auth/spreadsheets.readonly。5. 扩展同一套凭据也服务于 Google Sheets / Drive值得留意的是vd.google_auth()是通用 API并不只服务 Gmail。实验模块 visidata/experimental/gsheets.py 和 visidata/experimental/gdrive.py 分别通过vd.google_auth(spreadsheets.readonly)、vd.google_auth(drive.readonly)等 scope 复用同一份 OAuth 基础设施用vd.google_discovery.build(...)访问 Google Sheets 和 Drive。这意味着你在本文中配置的 client 凭据与授权流程稍作扩展即可用于其他 Google API 数据源。常见问题排查现象原因与对策报错google_creds.json file does not exist in ...凭据 JSON 未放置到vdplus.api.google包资源目录或文件名不是源码要求的google_creds.json下划线版本请核对第五步浏览器弹窗未出现检查是否已启用 Gmail API、OAuth consent screen 是否完成保存首次授权必须走浏览器授权后被拒绝 / 403邮箱未加入测试用户列表或 scope 未包含https://mail.google.com/敏感 scope 需在 consent screen 中ADD USERSURL 中带密码连接 Gmail 失败Gmail 已禁用密码直连必须走imap://userimap.gmail.com不带密码的 OAuth 流程令牌过期后再次弹窗正常情况下应自动刷新若 refresh_token 失效如撤销授权删除visidata_dir下的google-*.pickle缓存文件后重新授权即可延伸阅读IMAP 加载器的其他服务器用法含 Outlook/Hotmail 带密码示例与端口写法docs/formats.md 的imap小节例如vd imap://someonehotmail.com:pass123imap-mail.outlook.com:993文档目录总览与各指南入口docs/README.md其中明确列出 gmail.md: Gmail access via OAuth 2.0 setup认证实现源码visidata/loaders/google.py 与 visidata/loaders/imap.pyGoogle API 实验模块复用同一套 OAuth 基础visidata/experimental/gsheets.py、visidata/experimental/gdrive.py。赞分享数据分析CLI数据可视化【免费下载链接】visidataA terminal spreadsheet multitool for discovering and arranging data项目地址https://gitcode.com/gh_mirrors/vi/visidata点击查看免费下载相关推荐Tweepy 认证完全指南OAuth 1.0a 与 OAuth 2.0 的配置、代码流程与底层实现Tweepy 认证完全指南OAuth 1.0a 与 OAuth 2.0 的配置、代码流程与底层实现 Tweepy 是 Python 生态中最流行的 Twitt后端Wasp 邮箱认证Email Auth完整指南邮箱验证、密码重置与配置 API 详解v0.16Wasp 邮箱认证Email Auth完整指南邮箱验证、密码重置与配置 API 详解v0.16 本文面向使用 Wasp v0.16 构建全栈应用的开发Web框架后端前端CLI开发工具Nginx UI 集成 Casdoor 身份认证配置指南与 OAuth 2.0 实现原理Nginx UI 集成 Casdoor 身份认证配置指南与 OAuth 2.0 实现原理 本指南讲解如何在 Nginx UI 中将 Casdoor 配置为身份后端前端运维MCP 服务上一篇download库性能优化指南提升大文件下载速度的7个技巧下一篇Mermaid Live Editor终极指南5个简单步骤快速创建专业图表创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
