在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

sherlock-project/sherlock

菜单

开发指南

相关源文件

目的与范围

本指南旨在帮助希望为 Sherlock 项目做出贡献或扩展其功能的开发者。它涵盖了开发环境的设置、项目结构的理解、贡献方式以及测试您的更改。有关安装和使用信息，请参阅安装和使用，有关贡献政策，请参阅贡献。

设置开发环境

为 Sherlock 设置开发环境需要几个步骤，以确保您拥有所有必要的工具和依赖项。

先决条件

  • Python 3.9 或更高版本
  • Git
  • Poetry（用于依赖管理）

克隆并安装依赖项

  1. 克隆仓库

  2. 使用 Poetry 安装开发依赖项

  3. 激活虚拟环境

开发工具配置

Sherlock 使用 .editorconfig 来保持一致的编码风格。大多数现代编辑器都原生支持或通过插件支持此功能。

来源：pyproject.toml42-58 .editorconfig1-19

项目结构概览

了解项目结构对于高效开发至关重要。

来源：pyproject.toml23-24

关键文件及其用途

文件/目录目的
sherlock_project/sherlock.py处理用户名搜索的主引擎
data.json所有支持站点的配置文件
pyproject.toml项目元数据和依赖规范
tests/用于验证功能的测试套件
docs/项目文档

开发工作流

代码风格和标准

Sherlock 遵循 Python 的 PEP 8 准则，并在 .editorconfig 文件中定义了一些特定的偏好设置

  • Python 文件缩进 4 个空格
  • 字符串使用双引号
  • UTF-8 编码
  • LF 行末符

来源：.editorconfig1-19

使用 data.json

data.json 文件是 Sherlock 功能的核心。添加或修改站点条目时

  1. 确保格式与现有条目匹配
  2. 通过站点检查测试您的更改
  3. 验证错误检测方法是否正常工作

添加对新站点的支持

最常见的贡献之一是为 Sherlock 添加新站点的支持。

处理依赖项

Sherlock 使用 Poetry 进行依赖管理。主要依赖项包括

  • requests 和 requests-futures 用于 HTTP 请求
  • colorama 用于终端输出格式化
  • PySocks 和 stem 用于代理支持
  • pandas 和 openpyxl 用于报告生成

添加新依赖项

对于开发依赖项

来源：pyproject.toml42-58

代码组织与交互

下图显示了 Sherlock 的主要组件在开发过程中如何相互作用

来源：pyproject.toml61

测试框架

Sherlock 拥有一个全面的测试框架，以确保代码质量和功能。

运行测试

要运行测试套件：

测试类型

  1. 单元测试：测试单个组件
  2. 集成测试：测试组件如何协同工作
  3. 回归测试：确保新更改不会破坏现有功能
  4. 站点验证测试：验证站点配置是否正常工作

调试技巧

在开发或调试 Sherlock 时，请考虑以下方法

  1. 使用 --verbose 标志获取详细输出
  2. 使用 --site 选项隔离站点测试
  3. 添加临时调试打印语句
  4. 使用 Python 内置调试器（import pdb; pdb.set_trace()）进行单步执行

文档标准

Sherlock 的文档遵循以下标准

  • README.md 用于整体项目文档
  • 函数和类的 Docstrings
  • 复杂代码段的注释
  • 清晰的提交消息解释更改

发布流程

发布 Sherlock 新版本的过程包括

配置管理

Sherlock 使用多个配置文件

文件目的
pyproject.toml项目元数据、依赖项和构建设置
.editorconfig编辑器设置以保持一致的代码风格
tox.ini多环境测试配置

来源：pyproject.toml1-61 .editorconfig1-19

贡献最佳实践

  1. 从小处着手：从简单的问题或站点添加开始
  2. 遵循代码风格：遵守项目的代码风格
  3. 编写测试：为新功能编写测试
  4. 文档化更改：清晰地记录您的代码和更改
  5. 遵守行为准则：遵守项目的行为准则

来源：docs/CODE_OF_CONDUCT.md1-130

结论

本开发指南涵盖了为 Sherlock 项目做贡献的基本要点。遵循这些指南，您将能够有效地开发、测试并为项目做出贡献。有关特定主题的更多详细信息，请参阅相应的小节