asyncrepo

asyncrepo 提供了一种从各种来源检索数据的统一异步接口。

安装

pip安装asyncrepo

使用

目前，请查看实时测试以获取一些示例

• AWS S3存储桶测试
• AWS S3对象测试
• Confluence页面测试
• 文件CSV行测试
• GitHub仓库测试
• Greenhouse职位测试
• Jira问题测试

动机

为统一和联邦搜索平台的开发者提供工具。

目前支持的仓库

• aws.s3_buckets.S3Buckets - 当前用户所属的AWS S3存储桶。
• aws.s3_objects.S3Objects - 属于存储桶的AWS S3对象。
• confluence.pages.Pages - 属于给定组织的Confluence页面
• file.csv_rows.CSVRows - 指定文件路径或URL的文件中的CSV行
• github.repos.Repos - 属于给定用户或组织的GitHub仓库。
• greenhouse.jobs.Jobs - 属于给定板的Greenhouse职位。
• jira.issues.Issues - 属于给定组织的JIRA问题。

支持的仓库操作

• .get(id: str)：通过其ID从仓库获取一个项目。
• .list()：获取仓库中所有项目的迭代器。
• .list_pages()：获取仓库中所有项目的分页迭代器。
• .search(query: str)：获取与查询匹配的仓库中所有项目的迭代器。
• .search_pages(query: str)：获取与查询匹配的仓库中所有项目的分页迭代器。

异常

• asyncrepo.exceptions.ItemNotFound：如果项目不存在于仓库中，.get(id: str)将引发。

按仓库支持

按仓库的注意事项

†: 在待解决的问题的路线上。

• aws.s3_buckets.S3Buckets
  • † 关于存储桶的可用信息仅限于基本元数据。
  • † 当前实现为 单页仓库。
• aws.s3_objects.S3Objects
  • † 无法获取对象的全部内容。
  • † 关于对象的可用信息仅限于基本元数据。
  • 搜索是通过前缀搜索API实现的。
• confluence.pages.Pages
  • † 无法将仓库范围限制为特定的空间。
  • 搜索API有时会对于应该有结果查询返回空结果集。这导致对仓库的实时测试变得脆弱。这可能在高并发下发生。
  • 与上述类似，API在高并发查询时偶尔会返回500错误。
  • † 已实施一个简单的重试系统来处理上述500错误，但它应该被抽象成一个更通用的重试系统，该系统可以应用于其他仓库。
• file.csv_rows.CSVRows
  • † 没有缓存文件的选项。如果使用URL，则意味着每次查询文件时，都需要下载（例如，每次获取、搜索或列出操作）。在未来，希望能够以某种TTL在内存或磁盘上缓存文件。
  • 因为CSV没有自然的分页，所以可以使用page_size选项来限制每页返回的行数。默认值为20。这允许你加载数据而无需将整个文件加载到内存中。
  • 因为CSV行没有自然的主键，id默认为行索引。你可以通过传递一个id给仓库来更改此设置，该仓库期望的是一个列名或列名的元组。
• github.repos.Repos
  • † 可能需要额外的工作来缓解速率限制问题。
  • † 使用PyGithub，它不是异步的。
  • † 修改PyGithub以支持异步（应考虑使用其他库如Gidgethub）。
  • † get操作可以检索用户/组织范围之外的仓库。
• greenhouse.jobs.Jobs
  • 这是一个 单页仓库。
• jira.issues.Issues
  • † 无法将仓库范围限制为特定项目。
  • .get方法接受键或ID，但项的.id始终是ID。这是因为ID不会改变，而键可能会因为将问题移动到不同的项目而改变。

仓库怪癖

因为这个库为非常不同的来源提供了一个统一的接口，所以所有仓库都会有一些怪癖。以下是一些怪癖。

天真搜索

并非所有来源都支持原生的搜索。作为解决方案，一些来源会回退到一种实现方式，该方式对仓库中每个项目的原始数据进行文本搜索。

天真获取

并非所有来源都支持原生的获取。作为解决方案，一些来源会回退到一种实现方式，该方式在整个仓库中进行扫描以找到具有给定ID的项目。

单页仓库

一些仓库基于项目列表的平面列表，而不是分页。此类仓库的所有项目都作为第一页和唯一页面返回。

项

所有项都由一个Item对象表示。此对象具有以下属性

• id：一个唯一标识项的字符串，可以传递给Repository.get以检索项。
• document：包含项数据的字典。
• repository：包含项的仓库。

愿望清单

以下是一个可能将要工作的清单。

一般改进

• 根据指示（†）解决注意事项。
• 使实时测试可在GitHub Actions中运行。
• 为各种支持的存储库编写模拟测试。
• 添加一个可以组合多个存储库的元存储库。
• 支持非默认排序。
• 停止从aiohttp中继承ClientSession，因为这会让开发者感到难过。
• 更多面向企业的实现。测试是在云托管服务上进行的，这些API通常与本地API不同。如果您想帮忙，请提交工单或拉取请求。
• 根据所需的存储库将依赖项拆分为单独的包。
• 规范化和详细记录存储库构造函数。目前，请查看测试或代码。
• 如描述的简单get实际上不是当get未实现时的默认回退。我应该添加一个默认实现，该实现通过使用实现的方法查找项目。
• 稳定的API。目前，API是不稳定的，可能会随时更改。

潜在操作

• Repository.create(item)
• Repository.update(item)
• Repository.delete(item)
• Item.save(upsert: bool=True)
• Item.delete()

潜在异常

• asyncrepo.exceptions.PermissionDenied - 当用户未授权执行操作时。
• asyncrepo.exceptions.OperationNotSupported - 当存储库不支持操作时。
• asyncrepo.exceptions.ItemAlreadyExists - 当项目已存在且upsert为False时。

潜在属性

这些属性可以添加到Item类中，以提供搜索结果和其他用例的有用输出。

• Item.title: Optional[str] - 页面标题、工单摘要、文件名等。
• Item.text: Optional[str] - 页面内容、工单描述、文件内容等。
• Item.url: Optional[str] - 页面、工单、文件等的URL。
• Item.image_url: Optional[str] - 工单状态图标、文件缩略图等。
• Item.facets: Dict[str, str] - 项目可能具有的广泛方面列表。文件类型、工单状态等。
• Item.created_at: Optional[datetime] - 项目创建的日期和时间。
• Item.updated_at: Optional[datetime] - 项目上次更新的日期和时间。
• Item.created_by: Optional[str] - 创建项目的用户。
• Item.updated_by: Optional[str] - 最后更新项目的用户。
• Item.created_by_url: Optional[str] - 创建项目的用户的URL。
• Item.updated_by_url: Optional[str] - 最后更新项目的用户的URL。
• Item.created_by_avatar_url: Optional[str] - 创建项目的用户的头像URL。
• Item.updated_by_avatar_url: Optional[str] - 最后更新项目的用户的头像URL。

潜在存储库

有那么多可能成为存储库的东西--这只是我为了灵感而保持的非常简短的列表。

• jira.projects.Projects
• confluence.spaces.Spaces
• confluence.blogs.Blogs
• jenkins.jobs.Jobs
• jenkins.builds.Builds
• elastic.indexes.Indexes
• elastic.documents.Documents
• slack.channels.Channels
• slack.users.Users
• slack.messages.Messages
• pypi.packages.Packages
• google.drive.Files
• google.mail.Mail
• google.calendar.Events
• github.code.Code

贡献指南

如果您有新功能的想法或发现了错误，请提交工单。如果您有解决问题的方案，也可以提交拉取请求！

而且，别担心贡献。如果您有兴趣通过提交拉取请求来帮助改进这个库，我非常乐意听到您的声音。

错误修复

• 创建一个由于识别到的错误而失败的测试
• 修复错误
• 确保测试通过
• 提交拉取请求

新功能

• 创建一个由于新功能未实现而失败的测试
• 实现新功能
• 确保测试通过
• 提交拉取请求

新存储库清单

• 将您的新的存储库添加到asyncrepo.repositories模块。
• 至少，您的存储库应该支持获取和列表。如果没有更好的方法，可以使用简单的搜索作为回退。
• 为您的仓库添加实时测试。如果需要凭证并且您必须针对私有服务器设置测试，请在 env.dist 文件中概述所需的凭证，并清楚地说明测试环境中预期存在哪些数据。
• 确保测试通过
• 在此文件中记录您的仓库。
• 提交拉取请求。