gitee-client 1.0.0__tar.gz

gitee_client-1.0.0/PKG-INFO

@@ -0,0 +1,430 @@
+Metadata-Version: 2.4
+Name: gitee-client
+Version: 1.0.0
+Summary: Gitee API v5 Python 客户端库 — 覆盖全部 264 个端点
+Author: TableRogue
+License: MIT
+Project-URL: Homepage, https://gitee.com/TableRogue/gitee_client
+Project-URL: Repository, https://gitee.com/TableRogue/gitee_client
+Project-URL: Issues, https://gitee.com/TableRogue/gitee_client/issues
+Keywords: gitee,api,client,git,china
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25
+
+# Gitee API v5 Python Client
+
+基于 [Gitee Open API v5](https://gitee.com/api/v5/swagger.json) 的完整 Python 客户端库。
+
+## 特性
+
+- **完整覆盖** — 175 个端点、16 个资源分组，全部可用
+- **直观的命名** — `client.repos.create_user_repos(...)`, `client.issues.list_repos_issues(...)`
+- **类型安全** — 82 个 TypedDict 数据模型，完整的类型提示
+- **自动分页** — `list_*_all()` 方法自动遍历所有页面
+- **统一的错误处理** — 异常层次结构清晰
+- **轻量依赖** — 仅需 `requests`
+
+## 安装
+
+```bash
+pip install requests  # 唯一依赖
+```
+
+将 `gitee_client/` 目录复制到你的项目中即可使用。
+
+## 快速开始
+
+```python
+from gitee_client import GiteeClient
+
+# 初始化（自动从 GITEE_ACCESS_TOKEN 环境变量读取 token）
+client = GiteeClient()
+
+# 或显式传入 token
+client = GiteeClient(access_token="your_access_token")
+
+# 也可用作上下文管理器
+with GiteeClient() as client:
+    repos = client.repos.list_user_repos()
+```
+
+## 使用示例
+
+### 仓库操作
+
+```python
+# 列出当前用户的所有仓库
+repos = client.repos.list_user_repos()
+
+# 遍历所有仓库（自动分页）
+for repo in client.repos.list_user_repos_all():
+    print(repo["full_name"])
+
+# 创建仓库
+new_repo = client.repos.create_user_repos(
+    name="my-project",
+    description="项目描述",
+    auto_init=True,
+)
+
+# 获取指定仓库
+repo = client.repos.get_repos(owner="username", repo="repo-name")
+
+# 更新仓库设置
+client.repos.update_repos(
+    owner="username", repo="repo-name",
+    name="repo-name",
+    description="新的描述",
+    private=True,
+)
+
+# 删除仓库
+client.repos.delete_repos(owner="username", repo="repo-name")
+
+# 列出某个用户的公开仓库
+repos = client.repos.list_users_repos(username="someone")
+```
+
+### Issue 操作
+
+```python
+# 列出仓库的所有 Issue
+issues = client.issues.list_repos_issues(
+    owner="username", repo="repo-name", state="open"
+)
+
+# 创建 Issue
+issue = client.issues.create_repos_issues(
+    owner="username", repo="repo-name",
+    title="Bug 报告",
+    body="详细描述...",
+)
+
+# 获取单个 Issue
+issue = client.issues.get_repos_issues(
+    owner="username", repo="repo-name", number=1
+)
+
+# 更新 Issue
+client.issues.update_repos_issues(
+    owner="username", repo="repo-name",
+    number=1, title="更新后的标题"
+)
+
+# 列出 Issue 评论
+comments = client.issues.list_repos_issues_comments(
+    owner="username", repo="repo-name", number=1
+)
+
+# 创建 Issue 评论
+client.issues.create_repos_issues_comments(
+    owner="username", repo="repo-name",
+    number=1, body="我的评论"
+)
+```
+
+### Pull Request 操作
+
+```python
+# 列出 Pull Requests
+prs = client.pulls.list_repos_pulls(
+    owner="username", repo="repo-name", state="open"
+)
+
+# 创建 Pull Request
+pr = client.pulls.create_repos_pulls(
+    owner="username", repo="repo-name",
+    title="新功能",
+    head="feature-branch",
+    base="master",
+    body="实现说明...",
+)
+
+# 获取单个 PR
+pr = client.pulls.get_repos_pulls(
+    owner="username", repo="repo-name", number=1
+)
+
+# 合并 PR
+client.pulls.update_repos_pulls_merge(
+    owner="username", repo="repo-name", number=1
+)
+
+# PR 审查
+client.pulls.create_repos_pulls_review(
+    owner="username", repo="repo-name", number=1
+)
+```
+
+### 用户操作
+
+```python
+# 获取当前用户信息
+me = client.users.list_user()
+
+# 获取指定用户信息
+user = client.users.get_users(username="someone")
+
+# 更新用户资料
+client.users.update_user(name="新名字", blog="https://example.com")
+
+# 关注用户
+client.users.update_user_following(username="someone")
+
+# 取消关注
+client.users.delete_user_following(username="someone")
+
+# 列出关注者
+followers = client.users.list_user_followers()
+```
+
+### 搜索
+
+```python
+# 搜索仓库
+results = client.search.list_search_repositories(q="gitee", language="python")
+
+# 遍历所有搜索结果
+for repo in client.search.list_search_repositories_all(q="open source"):
+    print(repo["full_name"])
+
+# 搜索 Issue
+issues = client.search.list_search_issues(q="bug", repo="owner/repo")
+
+# 搜索用户
+users = client.search.list_search_users(q="developer")
+```
+
+### 组织操作
+
+```python
+# 列出用户所属的组织
+orgs = client.organizations.list_user_orgs()
+
+# 获取组织信息
+org = client.organizations.get_orgs(org="org-name")
+
+# 列出组织成员
+members = client.organizations.list_orgs_members(org="org-name")
+
+# 创建组织
+client.organizations.create_users_organization(
+    name="new-org",
+    org="new-org",
+)
+```
+
+### Gist 操作
+
+```python
+# 列出代码片段
+gists = client.gists.list_gists()
+
+# 创建代码片段
+gist = client.gists.create_gists(
+    files={"hello.py": {"content": "print('Hello World')"}},
+    description="我的第一个 Gist",
+    public=True,
+)
+
+# 获取单个代码片段
+gist = client.gists.get_gists(id="gist_id")
+
+# 删除代码片段
+client.gists.delete_gists(id="gist_id")
+```
+
+### 标签和里程碑
+
+```python
+# 列出仓库标签
+labels = client.labels.list_repos_labels(owner="user", repo="repo")
+
+# 创建标签
+client.labels.create_repos_labels(
+    owner="user", repo="repo",
+    name="bug", color="#ff0000"
+)
+
+# 列出里程碑
+milestones = client.milestones.list_repos_milestones(owner="user", repo="repo")
+
+# 创建里程碑
+client.milestones.create_repos_milestones(
+    owner="user", repo="repo",
+    title="v1.0",
+    due_on="2026-12-31",
+)
+```
+
+### Webhook 管理
+
+```python
+# 列出 Webhooks
+hooks = client.webhooks.list_repos_hooks(owner="user", repo="repo")
+
+# 创建 Webhook
+hook = client.webhooks.create_repos_hooks(
+    owner="user", repo="repo",
+    url="https://example.com/webhook",
+    password="secret",
+    push_events=True,
+)
+```
+
+### 企业版功能
+
+```python
+# 列出企业成员
+members = client.enterprises.list_enterprises_members(enterprise="enterprise-name")
+
+# 获取企业信息
+enterprise = client.enterprises.get_enterprises(enterprise="enterprise-name")
+
+# 企业 Issue 列表
+issues = client.issues.list_enterprises_issues(enterprise="enterprise-name")
+```
+
+### 其他功能
+
+```python
+# 获取 Emoji 列表
+emojis = client.misc.list_emojis()
+
+# 获取 Gitignore 模板列表
+templates = client.misc.list_gitignore_templates()
+
+# 获取 License 列表
+licenses = client.misc.list_licenses()
+
+# 渲染 Markdown
+html = client.misc.create_markdown(text="# Hello\n\nThis is **markdown**.")
+
+# 获取授权用户的邮箱
+emails = client.emails.list_emails()
+
+# 获取 Gitee 指数
+metrics = client.git_data.get_repos_git_gitee_metrics(owner="user", repo="repo")
+```
+
+## API 资源分组
+
+| 属性 | 模块 | 端点数量 | 说明 |
+|------|------|---------|------|
+| `client.repos` | 仓库 | 76 | 仓库 CRUD、分支、标签、发布、协作者、提交、内容等 |
+| `client.pulls` | Pull Requests | 27 | PR 的创建、审查、合并、测试、指派等 |
+| `client.activity` | 动态 | 26 | 通知、私信、动态、Watch 等 |
+| `client.issues` | Issues | 21 | Issue 的增删改查、评论、操作日志等 |
+| `client.users` | 用户 | 18 | 用户资料、关注、SSH 公钥等 |
+| `client.enterprises` | 企业 | 17 | 企业管理、成员管理、周报等 |
+| `client.gists` | Gists | 17 | 代码片段的增删改查、评论、Star、Fork 等 |
+| `client.labels` | 标签 | 16 | 仓库标签、Issue 标签的增删改查 |
+| `client.organizations` | 组织 | 14 | 组织管理、成员管理、关注者等 |
+| `client.misc` | 杂项 | 9 | Emoji、Gitignore 模板、License、Markdown 渲染 |
+| `client.webhooks` | Webhooks | 6 | Webhook 的增删改查和测试 |
+| `client.checks` | 检查 | 5 | Check Runs 的创建、更新、查询 |
+| `client.milestones` | 里程碑 | 5 | 里程碑的增删改查 |
+| `client.search` | 搜索 | 3 | 搜索仓库、Issue、用户 |
+| `client.git_data` | Git 数据 | 3 | Blob、Tree、Gitee 指数 |
+| `client.emails` | 邮箱 | 1 | 获取授权用户邮箱 |
+
+## 方法命名规则
+
+方法名遵循 `{动作}_{资源路径}` 的命名模式：
+
+- `list_*` — GET 请求，返回列表（支持分页）
+- `get_*` — GET 请求，返回单个资源
+- `create_*` — POST 请求，创建资源
+- `update_*` — PUT/PATCH 请求，更新资源
+- `delete_*` — DELETE 请求，删除资源
+
+带有 `_all` 后缀的方法（如 `list_user_repos_all()`）是自动分页的便捷包装，返回生成器遍历所有结果。
+
+## 分页
+
+支持分页的 `list_*` 方法接受 `page` 和 `per_page` 参数：
+
+```python
+# 手动分页
+page1 = client.repos.list_user_repos(page=1, per_page=20)
+
+# 自动遍历所有页面
+for repo in client.repos.list_user_repos_all(per_page=50):
+    print(repo["full_name"])
+```
+
+## 错误处理
+
+```python
+from gitee_client import (
+    GiteeError, GiteeAPIError, GiteeAuthError,
+    GiteeNotFoundError, GiteeValidationError,
+)
+
+try:
+    client.repos.get_repos(owner="nonexistent", repo="repo")
+except GiteeNotFoundError as e:
+    print(f"资源不存在: {e}")
+except GiteeAuthError as e:
+    print(f"认证失败: {e}")
+except GiteeAPIError as e:
+    print(f"API 错误 {e.status_code}: {e.error_message}")
+```
+
+异常层次结构：
+
+```
+GiteeError
+└── GiteeAPIError
+    ├── GiteeAuthError       (401, 403)
+    ├── GiteeNotFoundError   (404)
+    ├── GiteeValidationError (422)
+    ├── GiteeRateLimitError  (429)
+    └── GiteeServerError     (5xx)
+```
+
+## 认证
+
+通过 Gitee 个人访问令牌（[获取 token](https://gitee.com/profile/personal_access_tokens)）进行认证：
+
+```python
+# 方式 1: 环境变量
+export GITEE_ACCESS_TOKEN="your_token_here"
+
+# 方式 2: 直接传入
+client = GiteeClient(access_token="your_token_here")
+```
+
+## 数据模型
+
+所有响应数据都有对应的 TypedDict 类型定义：
+
+```python
+from gitee_client.models import Project, User, Issue, PullRequest
+
+def process_repo(repo: Project) -> None:
+    print(repo["full_name"])   # IDE 自动补全
+    print(repo["html_url"])
+```
+
+## 依赖
+
+- Python >= 3.8
+- requests
+
+## 许可
+
+MIT