From 7592af1c3a8b86e27152e0306af564b72ff09e093acc6c4b8c3e33fb181be8b6 Mon Sep 17 00:00:00 2001 From: Maoayo233 Date: Sun, 12 Apr 2026 23:24:13 +0800 Subject: [PATCH] initial commit --- .gitignore | 35 ++ README.md | 130 ++++++ ansible/.yamllint.yml | 13 + ansible/README.md | 206 ++++++++ ansible/ansible.cfg | 10 + ansible/inventory/group_vars/all.yml | 42 ++ ansible/inventory/hosts.yml | 7 + ansible/playbook.yml | 54 +++ ansible/requirements.yml | 4 + ansible/roles/common/tasks/main.yml | 61 +++ ansible/roles/gitea/handlers/main.yml | 9 + ansible/roles/gitea/tasks/configure.yml | 100 ++++ ansible/roles/gitea/tasks/install.yml | 50 ++ ansible/roles/gitea/tasks/main.yml | 8 + ansible/roles/gitea/templates/app.ini.j2 | 75 +++ .../roles/gitea/templates/gitea.service.j2 | 28 ++ ansible/roles/postgresql/handlers/main.yml | 5 + ansible/roles/postgresql/tasks/main.yml | 73 +++ .../roles/postgresql/templates/pg_hba.conf.j2 | 15 + issue-templates/README.md | 106 +++++ .../general/.gitea/ISSUE_TEMPLATE/config.yaml | 8 + .../ISSUE_TEMPLATE/course-question.yaml | 73 +++ .../.gitea/ISSUE_TEMPLATE/env-setup.yaml | 68 +++ .../.gitea/ISSUE_TEMPLATE/homework-help.yaml | 100 ++++ .../.gitea/ISSUE_TEMPLATE/config.yaml | 5 + .../.gitea/ISSUE_TEMPLATE/homework-help.yaml | 93 ++++ scripts/.gitignore | 16 + scripts/.secrets.toml.example | 13 + scripts/README.md | 304 ++++++++++++ scripts/example/members.csv | 6 + scripts/pyproject.toml | 45 ++ scripts/settings.toml | 56 +++ scripts/src/tjhlp/__init__.py | 3 + scripts/src/tjhlp/cli.py | 24 + scripts/src/tjhlp/client.py | 393 ++++++++++++++++ scripts/src/tjhlp/commands/__init__.py | 0 scripts/src/tjhlp/commands/labels.py | 67 +++ scripts/src/tjhlp/commands/notify.py | 117 +++++ scripts/src/tjhlp/commands/orgs.py | 116 +++++ scripts/src/tjhlp/commands/repos.py | 146 ++++++ scripts/src/tjhlp/commands/setup.py | 141 ++++++ scripts/src/tjhlp/commands/stats.py | 113 +++++ scripts/src/tjhlp/commands/users.py | 222 +++++++++ scripts/src/tjhlp/commands/webhooks.py | 97 ++++ scripts/src/tjhlp/config.py | 105 +++++ scripts/src/tjhlp/models.py | 107 +++++ scripts/src/tjhlp/utils.py | 142 ++++++ scripts/tests/conftest.py | 81 ++++ scripts/tests/test_client.py | 191 ++++++++ scripts/tests/test_commands.py | 250 ++++++++++ scripts/tests/test_config.py | 118 +++++ scripts/tests/test_models.py | 131 ++++++ scripts/tests/test_pure_functions.py | 123 +++++ scripts/tests/test_utils.py | 105 +++++ scripts/uv.lock | 441 ++++++++++++++++++ 55 files changed, 5051 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 ansible/.yamllint.yml create mode 100644 ansible/README.md create mode 100644 ansible/ansible.cfg create mode 100644 ansible/inventory/group_vars/all.yml create mode 100644 ansible/inventory/hosts.yml create mode 100644 ansible/playbook.yml create mode 100644 ansible/requirements.yml create mode 100644 ansible/roles/common/tasks/main.yml create mode 100644 ansible/roles/gitea/handlers/main.yml create mode 100644 ansible/roles/gitea/tasks/configure.yml create mode 100644 ansible/roles/gitea/tasks/install.yml create mode 100644 ansible/roles/gitea/tasks/main.yml create mode 100644 ansible/roles/gitea/templates/app.ini.j2 create mode 100644 ansible/roles/gitea/templates/gitea.service.j2 create mode 100644 ansible/roles/postgresql/handlers/main.yml create mode 100644 ansible/roles/postgresql/tasks/main.yml create mode 100644 ansible/roles/postgresql/templates/pg_hba.conf.j2 create mode 100644 issue-templates/README.md create mode 100644 issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml create mode 100644 issue-templates/general/.gitea/ISSUE_TEMPLATE/course-question.yaml create mode 100644 issue-templates/general/.gitea/ISSUE_TEMPLATE/env-setup.yaml create mode 100644 issue-templates/general/.gitea/ISSUE_TEMPLATE/homework-help.yaml create mode 100644 issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml create mode 100644 issue-templates/homework/.gitea/ISSUE_TEMPLATE/homework-help.yaml create mode 100644 scripts/.gitignore create mode 100644 scripts/.secrets.toml.example create mode 100644 scripts/README.md create mode 100644 scripts/example/members.csv create mode 100644 scripts/pyproject.toml create mode 100644 scripts/settings.toml create mode 100644 scripts/src/tjhlp/__init__.py create mode 100644 scripts/src/tjhlp/cli.py create mode 100644 scripts/src/tjhlp/client.py create mode 100644 scripts/src/tjhlp/commands/__init__.py create mode 100644 scripts/src/tjhlp/commands/labels.py create mode 100644 scripts/src/tjhlp/commands/notify.py create mode 100644 scripts/src/tjhlp/commands/orgs.py create mode 100644 scripts/src/tjhlp/commands/repos.py create mode 100644 scripts/src/tjhlp/commands/setup.py create mode 100644 scripts/src/tjhlp/commands/stats.py create mode 100644 scripts/src/tjhlp/commands/users.py create mode 100644 scripts/src/tjhlp/commands/webhooks.py create mode 100644 scripts/src/tjhlp/config.py create mode 100644 scripts/src/tjhlp/models.py create mode 100644 scripts/src/tjhlp/utils.py create mode 100644 scripts/tests/conftest.py create mode 100644 scripts/tests/test_client.py create mode 100644 scripts/tests/test_commands.py create mode 100644 scripts/tests/test_config.py create mode 100644 scripts/tests/test_models.py create mode 100644 scripts/tests/test_pure_functions.py create mode 100644 scripts/tests/test_utils.py create mode 100644 scripts/uv.lock diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..29e61d4 --- /dev/null +++ b/.gitignore @@ -0,0 +1,35 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.egg-info/ +dist/ +build/ +.venv/ +*.egg + +# Secrets & credentials +.secrets.toml +credentials_*.csv +*.pem +*.key + +# Ansible +*.retry + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Linter cache +.ruff_cache/ + +# OpenCode +.opencode/ diff --git a/README.md b/README.md new file mode 100644 index 0000000..23e0cc2 --- /dev/null +++ b/README.md @@ -0,0 +1,130 @@ +# TJHLP-Gitea + +同济大学高级语言程序设计课程(Tongji High-level Language Programming)基于 Gitea 的答疑平台。 + +## 项目背景 + +为课程搭建自托管的 Git 答疑平台, 提供以下能力: + +- 学生通过 Issue 提问, 结构化的 Issue Template 引导提问前思考、规范问题描述 +- 助教通过 Label 标记重复 / 低质问题, 管理答疑流程 +- Webhook 将 Issue 动态推送到 IM(如 QQ 机器人), 助教无需轮询平台即可收到通知 +- Python CLI 工具批量管理用户、仓库、标签等, 降低运维负担 + +选择 Gitea 自托管而非 GitHub Classroom / Piazza 等方案, 是因为国内网络环境限制, 且需要定制化功能。 + +## 项目结构 + +```text +tjhlp-gitea/ +├── ansible/ Ansible 自动化部署(Gitea + PostgreSQL) +├── issue-templates/ Issue 模板(按仓库类型区分) +└── scripts/ Python CLI 管理工具 +``` + +## 快速开始 + +### 1. 部署服务器 + +需要一台 Rocky Linux 8.10 服务器和本地安装的 Ansible。 + +```bash +cd ansible +# 编辑 inventory/hosts.yml 填入服务器地址 +# 编辑 inventory/group_vars/all.yml 修改域名、密码等 +ansible-playbook playbook.yml +``` + +部署完成后, Ansible 会自动创建管理员账号并输出访问地址。 + +### 2. 初始化平台 + +登录管理员账号, 在 **设置 -> 应用** 中创建 API Token, 然后: + +```bash +cd scripts +cp .secrets.toml.example .secrets.toml +# 编辑 .secrets.toml, 填入 gitea_token 和 SMTP 配置 + +uv sync +uv run tjhlp setup init --org tjhlp-2025f +``` + +这会创建课程组织、ta/students 团队、general 答疑仓库, 并推送 Issue Template 和预定义 Label。 + +### 3. 导入用户 + +准备 CSV 文件(格式见 `scripts/example/members.csv`): + +```csv +id,name,role +2659999,赵一伤,student +10001,李四催,ta +``` + +```bash +uv run tjhlp users create --file members.csv --org tjhlp-2025f +uv run tjhlp notify send-credentials --file credentials_*.csv +``` + +### 4. 创建作业仓库 + +```bash +uv run tjhlp repos create-homework --org tjhlp-2025f --number 1 +``` + +## 仓库设计 + +| 仓库 | 用途 | Issue Template | +| ------ | ------ | ---------------- | +| `{org}/general` | 一般性问题: 课程内容答疑、环境配置 | 课程答疑 / 作业问题 / 环境配置 | +| `{org}/hw01` ... | 各次作业的特定问题 | 仅作业问题模板 | + +## 开发与测试 + +### Python CLI 测试 + +```bash +cd scripts +uv sync --extra dev +uv run pytest tests/ -v # 运行全部测试 +uv run pytest tests/ --cov=tjhlp --cov-report=term-missing # 带覆盖率 +``` + +当前测试套件包含 99 个测试用例, 覆盖: + +- **数据模型**(models.py)— 100% 覆盖率 +- **配置校验**(config.py)— Pydantic 模型、Label 颜色验证、必填字段 +- **纯函数**— 密码生成、CSV 解析、邮件模板构建、HTML 转义防护 +- **API 客户端**(client.py)— 使用 [respx](https://lundberg.github.io/respx/) mock HTTP 层, 测试分页、错误处理、404 返回 None +- **命令集成**— 使用 Typer CliRunner + mock 测试 setup/users/repos 命令的完整流程 + +### Ansible 静态检查 + +```bash +cd ansible +ansible-playbook --syntax-check playbook.yml # 语法检查 +yamllint -c .yamllint.yml . # YAML 格式 +ansible-lint playbook.yml # 最佳实践 +``` + +### Issue Templates 验证 + +```bash +yamllint issue-templates/ # YAML 语法 +``` + +详见各子目录的 README。 + +## 技术栈 + +| 组件 | 技术选型 | +| ------ | ---------- | +| Git 平台 | Gitea(二进制 + systemd) | +| 数据库 | PostgreSQL 18 | +| 服务器 | Rocky Linux 8.10 | +| 部署工具 | Ansible | +| 管理工具 | Python 3.14 + Typer + httpx + Pydantic + Dynaconf | +| 包管理 | uv | +| 测试框架 | pytest + respx + pytest-cov | +| 代码检查 | ruff, yamllint, ansible-lint | diff --git a/ansible/.yamllint.yml b/ansible/.yamllint.yml new file mode 100644 index 0000000..a2d4853 --- /dev/null +++ b/ansible/.yamllint.yml @@ -0,0 +1,13 @@ +--- +extends: default + +rules: + line-length: + max: 160 + truthy: + allowed-values: ["true", "false", "yes", "no"] + comments: + min-spaces-from-content: 1 + indentation: + spaces: 2 + indent-sequences: consistent diff --git a/ansible/README.md b/ansible/README.md new file mode 100644 index 0000000..d4d9305 --- /dev/null +++ b/ansible/README.md @@ -0,0 +1,206 @@ +# Ansible 部署 + +使用 Ansible 在 Rocky Linux 8.10 服务器上自动部署 Gitea + PostgreSQL 18。 + +## 前置要求 + +- 控制机安装 Ansible >= 2.12 +- 目标服务器运行 Rocky Linux 8.10(或兼容的 RHEL 8 系发行版) +- 控制机可通过 SSH 连接目标服务器(建议配置密钥认证) +- 安装 Ansible 依赖(collection): + ```bash + ansible-galaxy collection install -r requirements.yml + ``` + +## 目录结构 + +``` +ansible/ +├── ansible.cfg Ansible 配置 +├── playbook.yml 主 Playbook +├── requirements.yml Ansible collection 依赖 +├── .yamllint.yml YAML lint 配置 +├── inventory/ +│ ├── hosts.yml 主机清单 +│ └── group_vars/ +│ └── all.yml 全局变量 +└── roles/ + ├── common/ 基础系统配置 + │ └── tasks/main.yml + ├── postgresql/ PostgreSQL 18 安装与配置 + │ ├── tasks/main.yml + │ ├── handlers/main.yml + │ └── templates/ + │ └── pg_hba.conf.j2 + └── gitea/ Gitea 安装与配置 + ├── tasks/ + │ ├── main.yml + │ ├── install.yml 下载二进制(在线获取最新版本) + │ └── configure.yml 生成配置、创建管理员 + ├── handlers/main.yml + └── templates/ + ├── app.ini.j2 Gitea 配置文件模板 + └── gitea.service.j2 systemd 服务文件 +``` + +## 配置 + +### 1. 主机清单 + +编辑 `inventory/hosts.yml`: + +```yaml +all: + hosts: + gitea-server: + ansible_host: 192.168.1.100 # 替换为实际 IP + ansible_user: root +``` + +### 2. 变量配置 + +编辑 `inventory/group_vars/all.yml`, **必须修改**的项: + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `gitea_domain` | Gitea 访问域名或 IP | `gitea.example.com` | +| `gitea_admin_password` | 管理员初始密码 | `ChangeMe!2025` | +| `gitea_db_password` | 数据库密码 | `change_this_db_password` | + +可选变量: + +| 变量 | 说明 | 默认值 | +|------|------|--------| +| `gitea_version` | 指定 Gitea 版本, 留空自动获取最新 | `""` | +| `gitea_http_port` | HTTP 端口 | `3000` | +| `gitea_admin_user` | 管理员用户名 | `admin` | +| `gitea_admin_email` | 管理员邮箱 | `admin@tongji.edu.cn` | +| `postgresql_version` | PostgreSQL 版本号 | `18` | +| `gitea_secret_key` | 安全密钥, 留空自动生成 | `""` | +| `gitea_internal_token` | 内部令牌, 留空自动生成 | `""` | + +**安全建议**: 生产部署时, `gitea_admin_password` 和 `gitea_db_password` 应使用 `ansible-vault` 加密, 而非明文写在 `all.yml` 中。 + +## 使用方法 + +### 完整部署 + +```bash +ansible-playbook playbook.yml +``` + +### 按 Role 单独运行 + +```bash +# 仅运行基础配置 +ansible-playbook playbook.yml --tags common + +# 仅运行 PostgreSQL +ansible-playbook playbook.yml --tags postgresql + +# 仅运行 Gitea(安装 + 配置) +ansible-playbook playbook.yml --tags gitea +``` + +### 更新系统软件包(默认不执行) + +```bash +ansible-playbook playbook.yml --tags update-system +``` + +## Role 说明 + +### common + +- 安装基础软件包(git, wget, curl 等) +- 创建 `git` 系统用户 +- 配置 firewalld 开放 Gitea 端口 +- 创建 Gitea 所需的目录结构并设置权限 + +### postgresql + +- 添加 PostgreSQL 官方 Yum 仓库 +- 禁用系统自带的 postgresql 模块 +- 安装 PostgreSQL(版本由 `postgresql_version` 变量控制, 默认 18)并初始化数据库集群 +- 配置 `pg_hba.conf` 认证方式为 md5 +- 创建 Gitea 所需的数据库和用户 + +### gitea + +- **安装**: 在线获取最新版本号(通过 `dl.gitea.com/gitea/version.json`), 下载对应的 linux-amd64 二进制到 `/usr/local/bin/gitea`。支持通过 `gitea_version` 变量锁定版本 +- **配置**: 通过 `gitea generate secret` 自动生成安全密钥, 渲染 `app.ini` 配置模板(禁用注册、禁用邮件、启用 Webhook), 部署 systemd 服务 +- **初始化**: 等待 Gitea 启动后, 通过 `gitea admin user create` 创建管理员账号 + +### app.ini 关键配置 + +| 配置项 | 值 | 说明 | +|--------|-----|------| +| `INSTALL_LOCK` | `true` | 跳过 Web 安装向导 | +| `DISABLE_REGISTRATION` | `true` | 禁止自助注册 | +| `ENABLE_NOTIFY_MAIL` | `false` | 不使用邮件通知 | +| `ALLOWED_HOST_LIST` | `*` | 允许 Webhook 访问任意主机 | +| `DEFAULT_REPO_UNITS` | `repo.code,repo.issues` | 新仓库默认只开启代码和 Issue | + +## 部署完成后 + +Playbook 执行完毕后会输出: + +``` +========================================== +Gitea 答疑平台部署完成! +========================================== +访问地址: http://gitea.example.com:3000 +管理员: admin +========================================== +后续步骤: +1. 登录管理员账号并修改初始密码 +2. 创建 API Token (设置 -> 应用 -> 生成令牌) +3. 配置 Python CLI 工具并执行 tjhlp setup init +========================================== +``` + +## 测试与验证 + +### 静态检查 + +无需连接服务器即可执行: + +```bash +# Playbook 语法检查 +ansible-playbook --syntax-check playbook.yml + +# YAML 格式检查(需要 pip install yamllint) +yamllint -c .yamllint.yml . + +# Ansible 最佳实践检查(需要 pip install ansible-lint) +ansible-lint playbook.yml +``` + +### Dry Run + +模拟执行, 不做实际变更(需要能 SSH 到目标服务器): + +```bash +ansible-playbook playbook.yml --check +``` + +### 集成测试(可选) + +如果需要在本地完整测试部署流程, 推荐使用 [Molecule](https://ansible.readthedocs.io/projects/molecule/) + Vagrant: + +```bash +pip install molecule molecule-vagrant pytest-testinfra +cd roles/gitea && molecule test +``` + +由于 Rocky 8 + systemd 在 Docker 中支持不完整, Vagrant(VirtualBox)是更可靠的测试环境。 + +### 部署后验证清单 + +部署完成后应检查: + +- [ ] Gitea Web 界面可访问(`http://{domain}:{port}`) +- [ ] 管理员账号可登录 +- [ ] PostgreSQL 服务运行中(`systemctl status postgresql-{version}`) +- [ ] Gitea 服务运行中(`systemctl status gitea`) +- [ ] 防火墙已开放对应端口(`firewall-cmd --list-ports`) diff --git a/ansible/ansible.cfg b/ansible/ansible.cfg new file mode 100644 index 0000000..3de4c64 --- /dev/null +++ b/ansible/ansible.cfg @@ -0,0 +1,10 @@ +[defaults] +inventory = inventory/hosts.yml +roles_path = roles +host_key_checking = False +retry_files_enabled = False + +[privilege_escalation] +become = True +become_method = sudo +become_user = root diff --git a/ansible/inventory/group_vars/all.yml b/ansible/inventory/group_vars/all.yml new file mode 100644 index 0000000..ccfd136 --- /dev/null +++ b/ansible/inventory/group_vars/all.yml @@ -0,0 +1,42 @@ +--- +# ============================================================================= +# Gitea 答疑平台部署变量 +# ============================================================================= + +# ----------------------------------------------------------------------------- +# Gitea 基础配置 +# ----------------------------------------------------------------------------- +# 留空则自动获取最新版本, 填写则使用指定版本(如 "1.25.1") +gitea_version: "" + +gitea_http_port: 3000 +gitea_domain: "gitea.example.com" # 替换为实际域名或 IP +gitea_app_name: "同济大学高级语言程序设计答疑平台" + +# ----------------------------------------------------------------------------- +# Gitea 管理员账号(首次部署自动创建, 部署后请修改密码) +# ----------------------------------------------------------------------------- +gitea_admin_user: "admin" +gitea_admin_password: "ChangeMe!2026" # 部署后务必修改 +gitea_admin_email: "shenjian@tongji.edu.cn" + +# ----------------------------------------------------------------------------- +# PostgreSQL 数据库配置 +# ----------------------------------------------------------------------------- +postgresql_version: 18 +gitea_db_name: "gitea" +gitea_db_user: "gitea" +gitea_db_password: "change_this_db_password" # 请修改为强密码 + +# ----------------------------------------------------------------------------- +# Webhook 配置 +# ----------------------------------------------------------------------------- +gitea_webhook_allowed_hosts: "*" +gitea_webhook_skip_tls: "false" + +# ----------------------------------------------------------------------------- +# 安全密钥(留空则自动生成, 生成后建议记录保存) +# ----------------------------------------------------------------------------- +gitea_secret_key: "" +gitea_internal_token: "" +gitea_lfs_jwt_secret: "" diff --git a/ansible/inventory/hosts.yml b/ansible/inventory/hosts.yml new file mode 100644 index 0000000..1569faf --- /dev/null +++ b/ansible/inventory/hosts.yml @@ -0,0 +1,7 @@ +--- +all: + hosts: + gitea-server: + ansible_host: 192.168.1.100 # 替换为实际服务器 IP + ansible_user: root # 替换为实际 SSH 用户 + # ansible_ssh_private_key_file: ~/.ssh/id_rsa diff --git a/ansible/playbook.yml b/ansible/playbook.yml new file mode 100644 index 0000000..200b7db --- /dev/null +++ b/ansible/playbook.yml @@ -0,0 +1,54 @@ +--- +# ============================================================================= +# Gitea 答疑平台部署 Playbook +# +# 使用方法: +# ansible-playbook playbook.yml +# +# 仅运行某个 role: +# ansible-playbook playbook.yml --tags postgresql +# ansible-playbook playbook.yml --tags gitea +# ============================================================================= + +- name: 部署 Gitea 答疑平台 + hosts: all + become: true + + pre_tasks: + - name: 检查操作系统 + assert: + that: + - ansible_os_family == "RedHat" + - ansible_distribution_major_version | int >= 8 + fail_msg: "此 Playbook 仅支持 RHEL/Rocky Linux 8+" + + - name: 更新系统软件包 + dnf: + name: "*" + state: latest + tags: [never, update-system] + + roles: + - role: common + tags: [common] + - role: postgresql + tags: [postgresql, database] + - role: gitea + tags: [gitea] + + post_tasks: + - name: 部署完成信息 + debug: + msg: | + ========================================== + Gitea 答疑平台部署完成! + ========================================== + 访问地址: http://{{ gitea_domain }}:{{ gitea_http_port }} + 管理员: {{ gitea_admin_user }} + Gitea 版本: {{ gitea_resolved_version }} + ========================================== + 后续步骤: + 1. 登录管理员账号并修改初始密码 + 2. 创建 API Token (设置 -> 应用 -> 生成令牌) + 3. 配置 Python CLI 工具并执行 tjhlp setup init + ========================================== diff --git a/ansible/requirements.yml b/ansible/requirements.yml new file mode 100644 index 0000000..55dc059 --- /dev/null +++ b/ansible/requirements.yml @@ -0,0 +1,4 @@ +--- +collections: + - name: community.postgresql + version: ">=3.0.0" diff --git a/ansible/roles/common/tasks/main.yml b/ansible/roles/common/tasks/main.yml new file mode 100644 index 0000000..e02a914 --- /dev/null +++ b/ansible/roles/common/tasks/main.yml @@ -0,0 +1,61 @@ +--- +# roles/common/tasks/main.yml +# 基础系统配置: 安装依赖包、创建 git 用户、配置防火墙、创建目录结构 + +- name: 安装基础依赖包 + dnf: + name: + - git + - wget + - curl + state: present + +- name: 创建 git 用户组 + group: + name: git + system: yes + state: present + +- name: 创建 git 系统用户 + user: + name: git + group: git + system: yes + shell: /bin/bash + home: /home/git + create_home: yes + comment: "Git Version Control" + +- name: 创建 Gitea 数据目录 + file: + path: "{{ item.path }}" + state: directory + owner: "{{ item.owner }}" + group: "{{ item.group }}" + mode: "{{ item.mode }}" + loop: + - { path: /var/lib/gitea, owner: git, group: git, mode: "0750" } + - { path: /var/lib/gitea/custom, owner: git, group: git, mode: "0750" } + - { path: /var/lib/gitea/data, owner: git, group: git, mode: "0750" } + - { path: /var/lib/gitea/log, owner: git, group: git, mode: "0750" } + +- name: 创建 Gitea 配置目录 + file: + path: /etc/gitea + state: directory + owner: root + group: git + mode: "0770" + +- name: 确保 firewalld 正在运行 + systemd: + name: firewalld + state: started + enabled: yes + +- name: 开放 Gitea HTTP 端口 + firewalld: + port: "{{ gitea_http_port }}/tcp" + permanent: yes + immediate: yes + state: enabled diff --git a/ansible/roles/gitea/handlers/main.yml b/ansible/roles/gitea/handlers/main.yml new file mode 100644 index 0000000..d56328c --- /dev/null +++ b/ansible/roles/gitea/handlers/main.yml @@ -0,0 +1,9 @@ +--- +- name: 重载 systemd + systemd: + daemon_reload: yes + +- name: 重启 Gitea + systemd: + name: gitea + state: restarted diff --git a/ansible/roles/gitea/tasks/configure.yml b/ansible/roles/gitea/tasks/configure.yml new file mode 100644 index 0000000..5810034 --- /dev/null +++ b/ansible/roles/gitea/tasks/configure.yml @@ -0,0 +1,100 @@ +--- +# roles/gitea/tasks/configure.yml +# 配置 Gitea: 生成密钥、app.ini、systemd 服务、创建管理员 + +- name: 生成 SECRET_KEY + command: /usr/local/bin/gitea generate secret SECRET_KEY + register: gitea_secret_key_result + changed_when: false + when: gitea_secret_key is not defined or gitea_secret_key == "" + +- name: 保存 SECRET_KEY + set_fact: + gitea_secret_key: "{{ gitea_secret_key_result.stdout }}" + when: gitea_secret_key is not defined or gitea_secret_key == "" + +- name: 生成 INTERNAL_TOKEN + command: /usr/local/bin/gitea generate secret INTERNAL_TOKEN + register: gitea_internal_token_result + changed_when: false + when: gitea_internal_token is not defined or gitea_internal_token == "" + +- name: 保存 INTERNAL_TOKEN + set_fact: + gitea_internal_token: "{{ gitea_internal_token_result.stdout }}" + when: gitea_internal_token is not defined or gitea_internal_token == "" + +- name: 生成 LFS_JWT_SECRET + command: /usr/local/bin/gitea generate secret LFS_JWT_SECRET + register: gitea_lfs_jwt_result + changed_when: false + when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == "" + +- name: 保存 LFS_JWT_SECRET + set_fact: + gitea_lfs_jwt_secret: "{{ gitea_lfs_jwt_result.stdout }}" + when: gitea_lfs_jwt_secret is not defined or gitea_lfs_jwt_secret == "" + +- name: 部署 Gitea 配置文件 + template: + src: app.ini.j2 + dest: /etc/gitea/app.ini + owner: root + group: git + mode: "0640" + notify: 重启 Gitea + +- name: 部署 systemd 服务文件 + template: + src: gitea.service.j2 + dest: /etc/systemd/system/gitea.service + owner: root + group: root + mode: "0644" + notify: + - 重载 systemd + - 重启 Gitea + +- name: 启用并启动 Gitea 服务 + systemd: + name: gitea + state: started + enabled: yes + +- name: 等待 Gitea 就绪 + uri: + url: "http://127.0.0.1:{{ gitea_http_port }}/api/v1/version" + method: GET + status_code: 200 + register: gitea_health + until: gitea_health.status == 200 + retries: 30 + delay: 2 + +- name: 显示 Gitea 版本 + debug: + msg: "Gitea {{ gitea_health.json.version }} 已启动" + +- name: 创建管理员账号 + command: > + /usr/local/bin/gitea admin user create + --username {{ gitea_admin_user }} + --password {{ gitea_admin_password }} + --email {{ gitea_admin_email }} + --admin + --config /etc/gitea/app.ini + become: true + become_user: git + environment: + GITEA_WORK_DIR: /var/lib/gitea + register: admin_create + changed_when: "'has been successfully created' in admin_create.stdout" + failed_when: > + admin_create.rc != 0 and + 'already exists' not in admin_create.stderr + no_log: true + +- name: 收紧配置目录权限 + file: + path: /etc/gitea + mode: "0750" diff --git a/ansible/roles/gitea/tasks/install.yml b/ansible/roles/gitea/tasks/install.yml new file mode 100644 index 0000000..639b0af --- /dev/null +++ b/ansible/roles/gitea/tasks/install.yml @@ -0,0 +1,50 @@ +--- +# roles/gitea/tasks/install.yml +# 下载并安装 Gitea 二进制文件 + +- name: 获取 Gitea 最新版本信息 + uri: + url: https://dl.gitea.com/gitea/version.json + return_content: yes + register: gitea_version_json + until: gitea_version_json.status == 200 + retries: 3 + delay: 2 + when: gitea_version == "" + +- name: 解析最新版本号 + set_fact: + gitea_resolved_version: "{{ (gitea_version_json.content | from_json).latest.version }}" + when: gitea_version == "" + +- name: 使用指定版本号 + set_fact: + gitea_resolved_version: "{{ gitea_version }}" + when: gitea_version != "" + +- name: 显示将要安装的 Gitea 版本 + debug: + msg: "将安装 Gitea {{ gitea_resolved_version }}" + +- name: 检查 Gitea 是否已安装 + stat: + path: /usr/local/bin/gitea + register: gitea_binary + +- name: 获取已安装的 Gitea 版本 + command: /usr/local/bin/gitea --version + register: gitea_installed_version + changed_when: false + failed_when: false + when: gitea_binary.stat.exists + +- name: 下载 Gitea 二进制文件 + get_url: + url: "https://dl.gitea.com/gitea/{{ gitea_resolved_version }}/gitea-{{ gitea_resolved_version }}-linux-amd64" + dest: /usr/local/bin/gitea + mode: "0755" + force: yes + when: > + not gitea_binary.stat.exists or + gitea_resolved_version not in (gitea_installed_version.stdout | default('')) + notify: 重启 Gitea diff --git a/ansible/roles/gitea/tasks/main.yml b/ansible/roles/gitea/tasks/main.yml new file mode 100644 index 0000000..231ca83 --- /dev/null +++ b/ansible/roles/gitea/tasks/main.yml @@ -0,0 +1,8 @@ +--- +# roles/gitea/tasks/main.yml + +- name: 安装 Gitea + import_tasks: install.yml + +- name: 配置 Gitea + import_tasks: configure.yml diff --git a/ansible/roles/gitea/templates/app.ini.j2 b/ansible/roles/gitea/templates/app.ini.j2 new file mode 100644 index 0000000..5adb61b --- /dev/null +++ b/ansible/roles/gitea/templates/app.ini.j2 @@ -0,0 +1,75 @@ +; Gitea Configuration +; Managed by Ansible - DO NOT EDIT MANUALLY + +APP_NAME = {{ gitea_app_name | default('同济大学高级语言程序设计答疑平台') }} +RUN_USER = git +RUN_MODE = prod +WORK_PATH = /var/lib/gitea + +[database] +DB_TYPE = postgres +HOST = 127.0.0.1:5432 +NAME = {{ gitea_db_name }} +USER = {{ gitea_db_user }} +PASSWD = {{ gitea_db_password }} +SSL_MODE = disable +LOG_SQL = false + +[server] +PROTOCOL = http +DOMAIN = {{ gitea_domain }} +HTTP_ADDR = {{ gitea_http_addr | default('0.0.0.0') }} +HTTP_PORT = {{ gitea_http_port }} +ROOT_URL = http://{{ gitea_domain }}:{{ gitea_http_port }}/ +APP_DATA_PATH = /var/lib/gitea/data +LFS_START_SERVER = true +LFS_JWT_SECRET = {{ gitea_lfs_jwt_secret }} + +[repository] +ROOT = /var/lib/gitea/data/gitea-repositories +DEFAULT_BRANCH = main +DEFAULT_REPO_UNITS = repo.code,repo.issues +DISABLE_STARS = true + +[security] +INSTALL_LOCK = true +SECRET_KEY = {{ gitea_secret_key }} +INTERNAL_TOKEN = {{ gitea_internal_token }} +MIN_PASSWORD_LENGTH = 8 + +[service] +DISABLE_REGISTRATION = true +REQUIRE_SIGNIN_VIEW = false +ENABLE_NOTIFY_MAIL = false +DEFAULT_KEEP_EMAIL_PRIVATE = true +NO_REPLY_ADDRESS = noreply.{{ gitea_domain }} + +[mailer] +ENABLED = false + +[session] +PROVIDER = file +PROVIDER_CONFIG = /var/lib/gitea/data/sessions + +[log] +ROOT_PATH = /var/lib/gitea/log +MODE = file +LEVEL = info + +[webhook] +ALLOWED_HOST_LIST = {{ gitea_webhook_allowed_hosts | default('*') }} +SKIP_TLS_VERIFY = {{ gitea_webhook_skip_tls | default('false') }} + +[api] +ENABLE_SWAGGER = true +MAX_RESPONSE_ITEMS = 100 + +[indexer] +ISSUE_INDEXER_PATH = /var/lib/gitea/data/indexers/issues.bleve + +[picture] +DISABLE_GRAVATAR = true + +[openid] +ENABLE_OPENID_SIGNIN = false +ENABLE_OPENID_SIGNUP = false diff --git a/ansible/roles/gitea/templates/gitea.service.j2 b/ansible/roles/gitea/templates/gitea.service.j2 new file mode 100644 index 0000000..af5ff18 --- /dev/null +++ b/ansible/roles/gitea/templates/gitea.service.j2 @@ -0,0 +1,28 @@ +[Unit] +Description=Gitea (Git with a cup of tea) +After=syslog.target +After=network.target +After=postgresql-{{ postgresql_version }}.service + +[Service] +Type=simple +User=git +Group=git +WorkingDirectory=/var/lib/gitea +ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini +Restart=always +RestartSec=5s +Environment=USER=git HOME=/home/git GITEA_WORK_DIR=/var/lib/gitea + +# Resource limits +LimitMEMLOCK=infinity +LimitNOFILE=65535 + +# Sandboxing +ProtectSystem=full +PrivateDevices=yes +PrivateTmp=yes +NoNewPrivileges=true + +[Install] +WantedBy=multi-user.target diff --git a/ansible/roles/postgresql/handlers/main.yml b/ansible/roles/postgresql/handlers/main.yml new file mode 100644 index 0000000..ff841f4 --- /dev/null +++ b/ansible/roles/postgresql/handlers/main.yml @@ -0,0 +1,5 @@ +--- +- name: 重启 PostgreSQL + systemd: + name: "postgresql-{{ postgresql_version }}" + state: restarted diff --git a/ansible/roles/postgresql/tasks/main.yml b/ansible/roles/postgresql/tasks/main.yml new file mode 100644 index 0000000..cfba9e4 --- /dev/null +++ b/ansible/roles/postgresql/tasks/main.yml @@ -0,0 +1,73 @@ +--- +# roles/postgresql/tasks/main.yml +# PostgreSQL 安装与配置 + +- name: 禁用系统自带的 postgresql 模块 + command: dnf module disable postgresql -y + register: pg_module_disable + changed_when: "'Nothing to do' not in pg_module_disable.stdout" + failed_when: false + +- name: 安装 PostgreSQL 官方仓库 RPM + dnf: + name: "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm" + state: present + disable_gpg_check: yes + +- name: 安装 PostgreSQL {{ postgresql_version }} + dnf: + name: + - postgresql{{ postgresql_version }}-server + - postgresql{{ postgresql_version }} + - python3-psycopg2 + state: present + +- name: 检查 PostgreSQL 数据目录是否已初始化 + stat: + path: "/var/lib/pgsql/{{ postgresql_version }}/data/PG_VERSION" + register: pg_data_dir + +- name: 初始化 PostgreSQL 数据库集群 + command: "/usr/pgsql-{{ postgresql_version }}/bin/postgresql-{{ postgresql_version }}-setup initdb" + when: not pg_data_dir.stat.exists + +- name: 部署 pg_hba.conf + template: + src: pg_hba.conf.j2 + dest: "/var/lib/pgsql/{{ postgresql_version }}/data/pg_hba.conf" + owner: postgres + group: postgres + mode: "0600" + notify: 重启 PostgreSQL + +- name: 启用并启动 PostgreSQL 服务 + systemd: + name: "postgresql-{{ postgresql_version }}" + state: started + enabled: yes + +- name: 等待 PostgreSQL 就绪 + wait_for: + port: 5432 + delay: 2 + timeout: 30 + +- name: 创建 Gitea 数据库用户 + become: true + become_user: postgres + community.postgresql.postgresql_user: + name: "{{ gitea_db_user }}" + password: "{{ gitea_db_password }}" + state: present + no_log: true + +- name: 创建 Gitea 数据库 + become: true + become_user: postgres + community.postgresql.postgresql_db: + name: "{{ gitea_db_name }}" + owner: "{{ gitea_db_user }}" + encoding: UTF-8 + lc_collate: en_US.UTF-8 + lc_ctype: en_US.UTF-8 + state: present diff --git a/ansible/roles/postgresql/templates/pg_hba.conf.j2 b/ansible/roles/postgresql/templates/pg_hba.conf.j2 new file mode 100644 index 0000000..de4e506 --- /dev/null +++ b/ansible/roles/postgresql/templates/pg_hba.conf.j2 @@ -0,0 +1,15 @@ +# PostgreSQL Client Authentication Configuration File +# =================================================== +# Managed by Ansible - DO NOT EDIT MANUALLY + +# TYPE DATABASE USER ADDRESS METHOD + +# "local" is for Unix domain socket connections only +local all postgres peer +local all all md5 + +# IPv4 local connections: +host all all 127.0.0.1/32 md5 + +# IPv6 local connections: +host all all ::1/128 md5 diff --git a/issue-templates/README.md b/issue-templates/README.md new file mode 100644 index 0000000..740a079 --- /dev/null +++ b/issue-templates/README.md @@ -0,0 +1,106 @@ +# Issue Templates + +结构化的 Issue 模板, 引导学生在提问前思考、规范问题描述, 减少低质量和重复提问。 + +## 设计理念 + +每个模板都包含以下引导机制: + +1. **强制先思考再提问** - 每个模板都有"你目前的理解"或"已尝试的方法"必填字段, 促使学生先尝试自己解决 +2. **减少重复提问** - 提交确认中要求"已搜索过已有 Issue" +3. **结构化信息收集** - 使用 YAML 表单格式(dropdown、textarea with render 等), 比自由文本更规范 +4. **禁止空白 Issue** - `config.yaml` 设置 `blank_issues_enabled: false`, 强制使用模板 + +## 目录结构 + +``` +issue-templates/ +├── general/ general 仓库使用 +│ └── .gitea/ISSUE_TEMPLATE/ +│ ├── config.yaml 禁止空白 Issue + 外部链接 +│ ├── course-question.yaml 课程内容 / 知识点答疑 +│ ├── homework-help.yaml 编程作业问题 +│ └── env-setup.yaml 环境配置问题 +└── homework/ hwXX 作业仓库使用 + └── .gitea/ISSUE_TEMPLATE/ + ├── config.yaml 禁止空白 Issue + 引导到 general + └── homework-help.yaml 编程作业问题(无作业编号字段) +``` + +## 模板说明 + +### general 仓库(3 个模板) + +#### 课程内容 / 知识点答疑 (`course-question.yaml`) + +适用于 C/C++ 语法、数据结构、算法等课程内容的概念性疑问。 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| 问题分类 | dropdown | Y | 语法 / 数据类型 / 指针与内存 / 函数 / 结构体 / 文件操作 / 预处理 / 其他 | +| 问题描述 | textarea | Y | 清晰描述问题 | +| 你目前的理解 | textarea | Y | 描述当前理解和困惑点 | +| 参考资料 | textarea | N | 已查阅的教材/网络资源 | +| 提交确认 | checkboxes | Y | 已搜索重复 + 已查阅教材 | + +#### 编程作业问题 (`homework-help.yaml`) + +适用于作业中遇到的编译错误、运行时错误、逻辑问题。 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| 作业编号 | input | Y | 如 "hw03 第2题" | +| 问题类型 | dropdown | Y | 编译错误 / 运行时错误 / 逻辑错误 / 思路不清晰 / 其他 | +| 问题描述 | textarea | Y | | +| 相关代码 | textarea (render: c) | Y | 代码片段, 自动语法高亮 | +| 错误信息 / 实际输出 | textarea (render: shell) | N | | +| 期望行为 | textarea | Y | | +| 已尝试的调试方法 | textarea | Y | 核心引导字段 | +| 提交确认 | checkboxes | Y | 已搜索重复 + 仅贴相关代码 | + +#### 环境配置问题 (`env-setup.yaml`) + +适用于 IDE 安装、编译器配置、开发环境搭建问题。课程统一使用 Windows。 + +| 字段 | 类型 | 必填 | 说明 | +|------|------|:----:|------| +| IDE / 编辑器 | dropdown | Y | Visual Studio / VS Code / CLion / Dev-C++ / Code::Blocks / 其他 | +| 编译器 | dropdown | Y | MSVC / GCC (MinGW) / Clang / 不确定 / 其他 | +| 问题描述 | textarea | Y | | +| 已尝试的解决方法 | textarea | Y | 核心引导字段 | +| 错误截图 / 日志 | textarea | N | 支持拖拽上传图片 | +| 提交确认 | checkboxes | Y | 已搜索重复 + 已查阅配置指南 | + +### homework 仓库(1 个模板) + +作业仓库仅包含 `homework-help.yaml`, 与 general 版本的区别: + +- **无"作业编号"字段** - 仓库名(hw01, hw02...)本身即标识作业 +- **新增"题目理解"问题类型** - dropdown 中增加此选项 +- **config.yaml 中引导非作业问题到 general 仓库** + +## 部署方式 + +模板通过 Python CLI 工具推送到仓库: + +```bash +# 初始化时自动推送到 general 仓库 +uv run tjhlp setup init --org tjhlp-2025f + +# 创建作业仓库时自动推送作业模板 +uv run tjhlp repos create-homework --org tjhlp-2025f --number 1 + +# 手动推送到指定仓库 +uv run tjhlp repos init-templates tjhlp-2025f/general --type general +uv run tjhlp repos init-templates tjhlp-2025f/hw01 --type homework +``` + +## 自定义 + +如需调整模板内容(如添加新的问题分类、修改引导文案), 直接编辑对应的 YAML 文件, 然后重新推送: + +```bash +uv run tjhlp repos init-templates tjhlp-2025f/general --type general +``` + +YAML 模板语法参考 [Gitea 文档](https://docs.gitea.com/usage/issue-pull-request-templates#syntax-for-yaml-template)。 diff --git a/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml b/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml new file mode 100644 index 0000000..d27d095 --- /dev/null +++ b/issue-templates/general/.gitea/ISSUE_TEMPLATE/config.yaml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: 课程主页 + url: https://example.com + about: 访问课程主页获取有关资源 + - name: 常见问题汇总 + url: https://example.com/faq + about: 提问前请先查阅常见问题汇总 diff --git a/issue-templates/general/.gitea/ISSUE_TEMPLATE/course-question.yaml b/issue-templates/general/.gitea/ISSUE_TEMPLATE/course-question.yaml new file mode 100644 index 0000000..e91df9f --- /dev/null +++ b/issue-templates/general/.gitea/ISSUE_TEMPLATE/course-question.yaml @@ -0,0 +1,73 @@ +name: 课程内容 / 知识点答疑 +about: 关于 C/C++ 语法、算法、数据结构等课程内容的疑问 +title: "[课程答疑] " +labels: + - 课程内容 +body: + - type: markdown + attributes: + value: | + ## 提问前请确认 + + - 请先在 Issue 列表中搜索是否已有相同或类似的问题 + - 请先查阅课件中的相关章节 + - 清晰地描述你的问题, 并说明你目前的理解——这有助于助教更准确地帮助你 + + - type: dropdown + id: category + attributes: + label: 问题分类 + description: 选择最接近你问题的分类 + options: + - 语法问题 + - 数据类型与运算 + - 指针与内存管理 + - 函数 + - 数组与字符串 + - 结构体与联合体 + - 文件操作 + - 预处理与编译 + - 其他 + validations: + required: true + + - type: textarea + id: description + attributes: + label: 问题描述 + description: 清晰、具体地描述你的问题 + placeholder: | + 例如: 我在学习指针数组和数组指针时, 不理解 int *p[3] 和 int (*p)[3] 的区别…… + validations: + required: true + + - type: textarea + id: current-understanding + attributes: + label: 你目前的理解 + description: 描述你对这个问题目前的理解, 以及具体哪里感到困惑。这一步很重要——尝试用自己的话表述, 有助于理清思路。 + placeholder: | + 例如: 我目前理解 int *p[3] 是一个包含 3 个 int 指针的数组, 但不确定 int (*p)[3] 为什么要加括号…… + validations: + required: true + + - type: textarea + id: references + attributes: + label: 参考资料 + description: 你已经查阅了哪些教材章节、课件页码或网络资源?(选填) + placeholder: | + 例如: 教材第 8 章 8.3 节;课件第 12 讲第 15 页;CSDN 上搜索了"指针数组 vs 数组指针"…… + validations: + required: false + + - type: checkboxes + id: confirmations + attributes: + label: 提交确认 + description: 请确认以下事项 + options: + - label: 我已在 Issue 列表中搜索过, 确认没有重复的问题 + required: true + - label: 我已查阅教材或课件中的相关内容 + required: true diff --git a/issue-templates/general/.gitea/ISSUE_TEMPLATE/env-setup.yaml b/issue-templates/general/.gitea/ISSUE_TEMPLATE/env-setup.yaml new file mode 100644 index 0000000..92c497a --- /dev/null +++ b/issue-templates/general/.gitea/ISSUE_TEMPLATE/env-setup.yaml @@ -0,0 +1,68 @@ +name: 环境配置问题 +about: IDE 安装、编译器配置、开发环境搭建等问题 +title: "[环境配置] " +labels: + - 环境配置 +body: + - type: markdown + attributes: + value: | + ## 提问前请确认 + + - 请先查阅课程提供的环境配置指南 + - 在 Issue 列表中搜索是否已有相同的环境问题及解决方案 + - 尽量提供完整的错误截图或日志信息 + + - type: dropdown + id: compiler + attributes: + label: 编译器 + description: 你使用的开发工具 + options: + - Visual Studio(MSVC) + - 小熊猫 C++(gcc) + - 其他(请说明) + validations: + required: true + + - type: textarea + id: description + attributes: + label: 问题描述 + description: 描述你遇到的环境配置问题 + placeholder: | + 例如: VS 的“解决方案资源管理器”关闭后不知道在哪里打开 + validations: + required: true + + - type: textarea + id: attempts + attributes: + label: 已尝试的解决方法 + description: 你已经尝试了哪些方法来解决这个问题? + placeholder: | + 例如: + - 按照课程指南重新安装了 MinGW + - 检查了环境变量 PATH, 发现没有添加 MinGW 的 bin 目录 + - 在网上搜索了 "VS Code gcc not found" 但给出的方法没有解决…… + validations: + required: true + + - type: textarea + id: error-logs + attributes: + label: 错误截图 / 日志 + description: 请粘贴错误截图或完整的日志信息(选填, 可直接拖拽图片到此处) + validations: + required: false + + - type: checkboxes + id: confirmations + attributes: + label: 提交确认 + description: 请确认以下事项 + options: + - label: 我已在 Issue 列表中搜索过, 确认没有重复的问题 + required: true + - label: 我已查阅课程提供的环境配置指南 + required: true diff --git a/issue-templates/general/.gitea/ISSUE_TEMPLATE/homework-help.yaml b/issue-templates/general/.gitea/ISSUE_TEMPLATE/homework-help.yaml new file mode 100644 index 0000000..68e90fe --- /dev/null +++ b/issue-templates/general/.gitea/ISSUE_TEMPLATE/homework-help.yaml @@ -0,0 +1,100 @@ +name: 编程作业问题 +about: 作业中遇到的编译错误、运行时错误、逻辑问题等 +title: "[作业] " +labels: + - 编程作业 +body: + - type: markdown + attributes: + value: | + ## 提问须知 + + - **请描述你的思路和卡点**, 而不是直接贴完整代码要求别人帮你写 + - 只贴出**与问题相关的代码片段**, 不要贴整个文件 + - 如果有编译错误或运行时错误, 请附上完整的错误信息 + - 先尝试自己调试(加 `cout` 输出中间变量、使用 VS 调试工具等), 并说明你尝试了什么 + + - type: input + id: homework-id + attributes: + label: 作业编号 + description: 作业编号及题目(如适用) + placeholder: "例如: 3-b3-1" + validations: + required: true + + - type: dropdown + id: problem-type + attributes: + label: 问题类型 + description: 选择最接近的问题类型 + options: + - 编译错误 + - 运行时错误(崩溃/段错误) + - 逻辑错误(输出不符合预期) + - 思路不清晰(不知道怎么下手) + - 其他 + validations: + required: true + + - type: textarea + id: description + attributes: + label: 问题描述 + description: 简要描述你遇到的问题 + placeholder: | + 例如: 我的排序函数在处理包含重复元素的数组时输出结果不正确…… + validations: + required: true + + - type: textarea + id: code + attributes: + label: 相关代码 + description: 贴出与问题相关的代码片段(不要贴完整作业代码) + render: cpp + validations: + required: true + + - type: textarea + id: error-output + attributes: + label: 错误信息 / 实际输出 + description: 编译器报错信息、程序崩溃信息或实际输出结果(选填) + render: shell + validations: + required: false + + - type: textarea + id: expected + attributes: + label: 期望行为 + description: 描述你期望程序的正确行为或输出 + placeholder: | + 例如: 输入 [3, 1, 2, 1], 期望输出 [1, 1, 2, 3], 但实际输出 [1, 2, 3, 1]…… + validations: + required: true + + - type: textarea + id: debugging-attempts + attributes: + label: 已尝试的调试方法 + description: 你已经尝试了哪些方法来定位问题?这一步很重要——调试能力是编程的核心技能之一。 + placeholder: | + 例如: + - 在循环中加了 cout 输出每轮交换后的数组内容 + - 检查了数组下标, 发现第 3 轮循环时 i 的值超出了范围 + - 用 VS 的断点调试逐步执行, 发现…… + validations: + required: true + + - type: checkboxes + id: confirmations + attributes: + label: 提交确认 + description: 请确认以下事项 + options: + - label: 我已在 Issue 列表中搜索过, 确认没有重复的问题 + required: true + - label: 我贴出的是与问题相关的代码片段, 而非完整作业代码 + required: true diff --git a/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml new file mode 100644 index 0000000..5d2c238 --- /dev/null +++ b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/config.yaml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: 一般性问题请到 general 仓库提问 + url: https://example.com + about: 课程内容答疑、环境配置等非作业特定问题请到 general 仓库 diff --git a/issue-templates/homework/.gitea/ISSUE_TEMPLATE/homework-help.yaml b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/homework-help.yaml new file mode 100644 index 0000000..9562134 --- /dev/null +++ b/issue-templates/homework/.gitea/ISSUE_TEMPLATE/homework-help.yaml @@ -0,0 +1,93 @@ +name: 编程作业问题 +about: 本次作业中遇到的编译错误、运行时错误、逻辑问题等 +title: "[求助] " +labels: + - 编程作业 +body: + - type: markdown + attributes: + value: | + ## 提问须知 + + - **请描述你的思路和卡点**, 而不是直接贴完整代码要求别人帮你写 + - 只贴出**与问题相关的代码片段**, 不要贴整个文件 + - 如果有编译错误或运行时错误, 请附上完整的错误信息 + - 先尝试自己调试(加 `printf` 输出中间变量、使用断点调试等), 并说明你尝试了什么 + - 课程内容答疑、环境配置等**非本次作业特定的问题**请到 **general** 仓库提问 + + - type: dropdown + id: problem-type + attributes: + label: 问题类型 + description: 选择最接近的问题类型 + options: + - 编译错误 + - 运行时错误(崩溃/段错误) + - 逻辑错误(输出不符合预期) + - 思路不清晰(不知道怎么下手) + - 题目理解 + - 其他 + validations: + required: true + + - type: textarea + id: description + attributes: + label: 问题描述 + description: 简要描述你遇到的问题(如涉及多道题目请注明题号) + placeholder: | + 例如: 第 2 题, 我的排序函数在处理包含重复元素的数组时输出结果不正确…… + validations: + required: true + + - type: textarea + id: code + attributes: + label: 相关代码 + description: 贴出与问题相关的代码片段(不要贴完整作业代码) + render: c + validations: + required: true + + - type: textarea + id: error-output + attributes: + label: 错误信息 / 实际输出 + description: 编译器报错信息、程序崩溃信息或实际输出结果(选填) + render: shell + validations: + required: false + + - type: textarea + id: expected + attributes: + label: 期望行为 + description: 描述你期望程序的正确行为或输出 + placeholder: | + 例如: 输入 [3, 1, 2, 1], 期望输出 [1, 1, 2, 3], 但实际输出 [1, 2, 3, 1]…… + validations: + required: true + + - type: textarea + id: debugging-attempts + attributes: + label: 已尝试的调试方法 + description: 你已经尝试了哪些方法来定位问题?这一步很重要——调试能力是编程的核心技能之一。 + placeholder: | + 例如: + - 在循环中加了 printf 输出每轮交换后的数组内容 + - 检查了数组下标, 发现第 3 轮循环时 i 的值超出了范围 + - 用 VS Code 的断点调试逐步执行, 发现…… + validations: + required: true + + - type: checkboxes + id: confirmations + attributes: + label: 提交确认 + description: 请确认以下事项 + options: + - label: 我已在 Issue 列表中搜索过, 确认没有重复的问题 + required: true + - label: 我贴出的是与问题相关的代码片段, 而非完整作业代码 + required: true diff --git a/scripts/.gitignore b/scripts/.gitignore new file mode 100644 index 0000000..054077c --- /dev/null +++ b/scripts/.gitignore @@ -0,0 +1,16 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.egg-info/ +dist/ +build/ +.venv/ +*.egg + +# Pytest +.coverage + +# Secrets & credentials +.secrets.toml +credentials_*.csv diff --git a/scripts/.secrets.toml.example b/scripts/.secrets.toml.example new file mode 100644 index 0000000..8e35cf9 --- /dev/null +++ b/scripts/.secrets.toml.example @@ -0,0 +1,13 @@ +# 将此文件复制为 .secrets.toml 并填入实际值 +# .secrets.toml 已被 .gitignore 排除, 不会提交到仓库 + +[default.gitea] +token = "your-gitea-api-token" + +[default.smtp] +host = "smtp.example.com" +port = 465 +user = "noreply@example.com" +password = "your-smtp-password" +from_addr = "同济大学高级语言程序设计课程 " + diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..2e589aa --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,304 @@ +# Python CLI 管理工具 + +`tjhlp` 是课程答疑平台的命令行管理工具, 通过 Gitea REST API 批量管理用户、组织、仓库、Webhook、Label, 并提供 Issue 统计和邮件通知功能。 + +## 前置要求 + +- Python >= 3.14 +- [uv](https://docs.astral.sh/uv/) + +## 安装 + +```bash +cd scripts +uv sync +``` + +安装后即可使用 `uv run tjhlp` 调用。 + +## 配置 + +### 基础配置 (`settings.toml`) + +已随项目提供, 包含默认值和预定义 Label 集合。一般无需修改。 + +### 敏感配置 (`.secrets.toml`) + +```bash +cp .secrets.toml.example .secrets.toml +``` + +编辑 `.secrets.toml`, 填入实际值: + +```toml +[default.gitea] +token = "your-gitea-api-token" # 必填 + +[default.smtp] +host = "smtp.example.com" # 发送邮件时必填 +port = 465 +user = "noreply@example.com" +password = "your-smtp-password" +from_addr = "同济大学高级语言程序设计课程 " +``` + +API Token 获取方式: 登录 Gitea -> 设置 -> 应用 -> 生成令牌(勾选所有权限)。 + +`.secrets.toml` 已在 `.gitignore` 中排除, 不会被提交。 + +### 环境变量覆盖 + +所有配置项均可通过 `TJHLP_` 前缀的环境变量覆盖: + +```bash +export TJHLP_GITEA_URL=http://192.168.1.100:3000 +export TJHLP_GITEA_TOKEN=your-token +``` + +## 命令一览 + +``` +tjhlp +├── setup +│ ├── init 一键初始化: 创建组织/团队/仓库/Labels/Webhook +│ └── status 检查 Gitea 连接状态 +├── users +│ ├── create 从 CSV 批量创建账号(随机密码) +│ ├── list 列出所有用户 +│ └── delete 批量删除用户 +├── orgs +│ ├── create 创建组织 +│ ├── create-team 创建团队 +│ ├── add-members 批量添加成员到团队 +│ └── list-teams 列出组织下的团队 +├── repos +│ ├── create 创建仓库 +│ ├── create-homework 创建作业仓库(自动推送模板/Labels/Webhook) +│ ├── init-templates 推送 Issue Templates 到仓库 +│ └── configure 配置仓库设置 +├── webhooks +│ ├── create 创建 Webhook +│ ├── list 列出 Webhook +│ ├── test 测试 Webhook +│ └── delete 删除 Webhook +├── labels +│ ├── sync 同步预定义 Label 到仓库 +│ └── list 列出仓库 Label +├── stats +│ ├── summary Issue 统计摘要 +│ └── export 导出 Issue 数据到 CSV +└── notify + └── send-credentials 通过 SMTP 发送账号密码邮件 +``` + +## 典型工作流 + +### 学期初始化 + +```bash +# 1. 检查连接 +uv run tjhlp setup status + +# 2. 一键初始化(创建组织 + 团队 + general 仓库 + Labels + Webhook) +uv run tjhlp setup init \ + --org tjhlp-2025f \ + --webhook-url http://notify-server:8080/webhook \ + --webhook-secret mysecret + +# 3. 批量创建用户并分配到团队 +uv run tjhlp users create --file members.csv --org tjhlp-2025f + +# 4. 发送账号密码邮件 +uv run tjhlp notify send-credentials --file credentials_20250901_120000.csv + +# 5. (可选)先预览邮件, 不实际发送 +uv run tjhlp notify send-credentials --file credentials_*.csv --dry-run +``` + +### 每次布置作业 + +```bash +uv run tjhlp repos create-homework \ + --org tjhlp-2025f \ + --number 3 \ + --desc "作业3: 链表操作" \ + --webhook-url http://notify-server:8080/webhook +``` + +这会自动完成: 创建 `hw03` 仓库 -> 推送作业 Issue Template -> 同步 Labels -> 配置 Webhook -> 添加到 ta/students 团队。 + +### 日常管理 + +```bash +# 查看 Issue 统计 +uv run tjhlp stats summary tjhlp-2025f/general + +# 导出 Issue 数据 +uv run tjhlp stats export tjhlp-2025f/hw03 --output hw03_issues.csv + +# 同步 Label 到新仓库 +uv run tjhlp labels sync tjhlp-2025f/hw03 + +# 查看 Webhook 状态 +uv run tjhlp webhooks list tjhlp-2025f/general +``` + +### 学期结束清理 + +```bash +uv run tjhlp users delete --file members.csv --yes +``` + +## CSV 格式 + +### 输入: `members.csv` + +```csv +id,name,role +2659999,赵一伤,student +2659876,钱二败,student +10001,李四催,ta +``` + +- `id` - 学号或工号, 同时作为 Gitea 用户名 +- `name` - 姓名, 作为 Gitea 的 full_name +- `role` - `student` 或 `ta`, 决定分配到哪个团队 +- 邮箱自动生成为 `{id}@tongji.edu.cn` + +示例文件见 `example/members.csv`。 + +### 输出: `credentials_*.csv` + +`users create` 执行后自动生成: + +```csv +id,name,role,username,password,email +2659999,赵一伤,student,2659999,xK9#mP2$vL4w,2659999@tongji.edu.cn +``` + +此文件包含随机生成的初始密码, 用于 `notify send-credentials` 发送邮件。**请妥善保管并在使用后删除。** + +## 预定义 Label + +通过 `settings.toml` 配置, `setup init` 和 `labels sync` 时自动创建: + +| Label | 颜色 | 用途 | +|-------|------|------| +| `duplicate` | 灰色 | 助教标记重复问题 | +| `invalid` | 黄色 | 不符合提问规范 | +| `resolved` | 绿色 | 已解决 | +| `wontfix` | 白色 | 不予处理 | +| `good-question` | 紫色 | 优质问题 | +| `FAQ` | 蓝色 | 常见问题 | +| `课程内容` | 粉紫 | 课程知识点相关 | +| `编程作业` | 浅红 | 编程作业相关 | +| `环境配置` | 浅青 | 环境配置相关 | +| `紧急` | 红色 | 需要尽快回复 | + +## 测试 + +### 安装开发依赖 + +```bash +uv sync --extra dev +``` + +### 运行测试 + +```bash +uv run pytest tests/ -v # 全部测试 +uv run pytest tests/test_models.py # 只运行模型测试 +uv run pytest tests/ -k "password" # 按名称过滤 +``` + +### 覆盖率报告 + +```bash +uv run pytest tests/ --cov=tjhlp --cov-report=term-missing +``` + +### 代码检查 + +```bash +uv run ruff check src/ +uv run ruff format --check src/ +``` + +### 测试套件结构 + +``` +tests/ +├── conftest.py 公共 fixtures(mock config、client、样本数据) +├── test_models.py 数据模型(MemberRecord、Gitea API 模型、枚举) +├── test_config.py 配置校验(LabelDef 颜色、GiteaConfig/SmtpConfig 必填字段) +├── test_utils.py 工具函数(parse_repo、compute_issue_stats) +├── test_pure_functions.py 纯函数(密码生成、CSV 解析、邮件模板) +├── test_client.py API 客户端(respx mock HTTP, 分页、错误处理、CRUD) +└── test_commands.py 命令集成(CliRunner + mock, setup/users/repos 流程) +``` + +### 测试分层 + +| 层级 | 测试对象 | 方法 | 速度 | +| ------ | ---------- | ------ | ------ | +| 单元测试 | models, config, 纯函数 | 直接调用, 无 mock | 极快 | +| API 客户端测试 | client.py | [respx](https://lundberg.github.io/respx/) mock HTTP 层 | 快 | +| 命令集成测试 | commands/*.py | Typer CliRunner + mock GiteaClient | 快 | +| 端到端测试 | 完整流程 | 需要运行中的 Gitea 实例 | 慢(手动) | + +当前 93 个测试用例, 核心模块覆盖率: + +| 模块 | 覆盖率 | 说明 | +| ------ | -------- | ------ | +| `models.py` | 100% | 全部模型和 computed fields | +| `config.py` | 87% | Pydantic 校验逻辑(未覆盖 Dynaconf 加载函数) | +| `users.py` | 79% | 创建/跳过/删除流程 | +| `client.py` | 67% | 核心 HTTP 方法和分页(未覆盖所有 API endpoint) | +| `notify.py` | 38% | 邮件文本构建(未覆盖 SMTP 发送) | + +## 项目结构 + +``` +scripts/ +├── pyproject.toml 项目配置(Python >=3.14, 依赖声明) +├── settings.toml 默认配置 + 预定义 Label +├── .secrets.toml.example 敏感配置示例 +├── example/ +│ └── members.csv 示例成员名单 +├── tests/ 测试套件 +│ ├── conftest.py 公共 fixtures +│ ├── test_models.py 数据模型测试 +│ ├── test_config.py 配置校验测试 +│ ├── test_utils.py 工具函数测试 +│ ├── test_pure_functions.py 纯函数测试 +│ ├── test_client.py API 客户端测试 +│ └── test_commands.py 命令集成测试 +└── src/tjhlp/ + ├── cli.py Typer 主入口 + ├── config.py Dynaconf 加载 + Pydantic 校验 + ├── client.py Gitea REST API 客户端(自动分页/错误处理) + ├── models.py 数据模型 + ├── utils.py 共享工具函数(parse_repo, push_templates 等) + └── commands/ + ├── setup.py 初始化命令 + ├── users.py 用户管理 + ├── orgs.py 组织/团队管理 + ├── repos.py 仓库管理 + ├── webhooks.py Webhook 管理 + ├── labels.py Label 管理 + ├── stats.py Issue 统计 + └── notify.py 邮件通知 +``` + +## 技术选型 + +| 库 | 用途 | +| ---- | ------ | +| [Typer](https://typer.tiangolo.com/) | CLI 框架 | +| [httpx](https://www.python-httpx.org/) | HTTP 客户端(调用 Gitea API) | +| [Rich](https://rich.readthedocs.io/) | 终端美化(表格、颜色、进度) | +| [Pydantic](https://docs.pydantic.dev/) | 数据校验、配置模型 | +| [Dynaconf](https://www.dynaconf.com/) | 配置管理(TOML + 环境变量 + secrets 分离) | +| [pytest](https://docs.pytest.org/) | 测试框架 | +| [respx](https://lundberg.github.io/respx/) | httpx mock 库(API 客户端测试) | +| [ruff](https://docs.astral.sh/ruff/) | 代码检查与格式化 | diff --git a/scripts/example/members.csv b/scripts/example/members.csv new file mode 100644 index 0000000..03251f4 --- /dev/null +++ b/scripts/example/members.csv @@ -0,0 +1,6 @@ +id,name,role +2659999,赵一伤,student +2659876,钱二败,student +2650001,孙三毁,student +10001,李四催,ta +10002,周五输,ta diff --git a/scripts/pyproject.toml b/scripts/pyproject.toml new file mode 100644 index 0000000..59f9e0e --- /dev/null +++ b/scripts/pyproject.toml @@ -0,0 +1,45 @@ +[project] +name = "tjhlp" +version = "0.1.0" +description = "同济大学高级语言程序设计课程 Gitea 答疑平台管理工具" +readme = "README.md" +requires-python = ">=3.14" +dependencies = [ + "typer>=0.15", + "httpx>=0.28", + "rich>=14", + "pydantic>=2.10", + "dynaconf>=3.2", +] + +[project.optional-dependencies] +dev = [ + "pytest>=8", + "pytest-cov", + "pytest-mock", + "respx>=0.22", + "ruff", +] + +[project.scripts] +tjhlp = "tjhlp.cli:app" + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["src/tjhlp"] + +[tool.ruff] +target-version = "py314" +line-length = 100 +src = ["src"] + +[tool.ruff.lint] +select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "RUF"] +ignore = ["B008"] + +[tool.pytest.ini_options] +testpaths = ["tests"] +addopts = "-v --tb=short" diff --git a/scripts/settings.toml b/scripts/settings.toml new file mode 100644 index 0000000..a562426 --- /dev/null +++ b/scripts/settings.toml @@ -0,0 +1,56 @@ +[default.gitea] +url = "http://10.80.42.185:3000" +email_domain = "tongji.edu.cn" +default_org = "" +password_length = 12 + +# 预定义 Label 集合 +[[default.gitea.labels]] +name = "duplicate" +color = "#cfd3d7" +description = "重复问题" + +[[default.gitea.labels]] +name = "invalid" +color = "#e4e669" +description = "不符合提问规范" + +[[default.gitea.labels]] +name = "resolved" +color = "#0e8a16" +description = "已解决" + +[[default.gitea.labels]] +name = "wontfix" +color = "#ffffff" +description = "不予处理" + +[[default.gitea.labels]] +name = "good-question" +color = "#7057ff" +description = "优质问题" + +[[default.gitea.labels]] +name = "FAQ" +color = "#0075ca" +description = "常见问题" + +[[default.gitea.labels]] +name = "课程内容" +color = "#d876e3" +description = "课程知识点相关" + +[[default.gitea.labels]] +name = "编程作业" +color = "#f9d0c4" +description = "编程作业相关" + +[[default.gitea.labels]] +name = "环境配置" +color = "#bfdadc" +description = "环境配置相关" + +[[default.gitea.labels]] +name = "紧急" +color = "#b60205" +description = "需要尽快回复" diff --git a/scripts/src/tjhlp/__init__.py b/scripts/src/tjhlp/__init__.py new file mode 100644 index 0000000..2509ae9 --- /dev/null +++ b/scripts/src/tjhlp/__init__.py @@ -0,0 +1,3 @@ +"""同济大学高级语言程序设计课程 Gitea 答疑平台管理工具""" + +__version__ = "0.1.0" diff --git a/scripts/src/tjhlp/cli.py b/scripts/src/tjhlp/cli.py new file mode 100644 index 0000000..b7b3716 --- /dev/null +++ b/scripts/src/tjhlp/cli.py @@ -0,0 +1,24 @@ +"""CLI 主入口: 注册所有子命令""" + +import typer + +from tjhlp.commands import labels, notify, orgs, repos, setup, stats, users, webhooks + +app = typer.Typer( + name="tjhlp", + help="同济大学高级语言程序设计课程 Gitea 答疑平台管理工具", + no_args_is_help=True, +) + +app.add_typer(setup.app, name="setup", help="初始化与环境配置") +app.add_typer(users.app, name="users", help="用户管理") +app.add_typer(orgs.app, name="orgs", help="组织与团队管理") +app.add_typer(repos.app, name="repos", help="仓库管理") +app.add_typer(webhooks.app, name="webhooks", help="Webhook 管理") +app.add_typer(labels.app, name="labels", help="Label 管理") +app.add_typer(stats.app, name="stats", help="Issue 统计") +app.add_typer(notify.app, name="notify", help="邮件通知") + + +if __name__ == "__main__": + app() diff --git a/scripts/src/tjhlp/client.py b/scripts/src/tjhlp/client.py new file mode 100644 index 0000000..767ab49 --- /dev/null +++ b/scripts/src/tjhlp/client.py @@ -0,0 +1,393 @@ +"""Gitea REST API 客户端封装""" + +from __future__ import annotations + +from typing import Any + +import httpx +from rich.console import Console + +from tjhlp.config import GiteaConfig +from tjhlp.models import ( + GiteaLabel, + GiteaOrg, + GiteaRepo, + GiteaTeam, + GiteaUser, + GiteaWebhook, +) + +console = Console() + + +class GiteaClientError(Exception): + """Gitea API 调用异常""" + + def __init__(self, status_code: int, message: str, url: str = ""): + self.status_code = status_code + self.message = message + self.url = url + super().__init__(f"[{status_code}] {url}: {message}") + + +class GiteaClient: + """Gitea REST API 客户端 + + 自动处理认证、分页和错误。 + """ + + def __init__(self, config: GiteaConfig) -> None: + self.base_url = str(config.url).rstrip("/") + "/api/v1" + self._client = httpx.Client( + base_url=self.base_url, + headers={ + "Authorization": f"token {config.token.get_secret_value()}", + "Content-Type": "application/json", + "Accept": "application/json", + }, + timeout=30.0, + ) + + def close(self) -> None: + self._client.close() + + def __enter__(self) -> GiteaClient: + return self + + def __exit__(self, *args: object) -> None: + self.close() + + # ------------------------------------------------------------------ + # 底层请求 + # ------------------------------------------------------------------ + + def _request( + self, + method: str, + path: str, + *, + json: dict[str, Any] | None = None, + params: dict[str, Any] | None = None, + ) -> httpx.Response: + resp = self._client.request(method, path, json=json, params=params) + if resp.status_code >= 400: + try: + detail = resp.json().get("message", resp.text) + except Exception: + detail = resp.text + raise GiteaClientError(resp.status_code, detail, path) + return resp + + def _get(self, path: str, **params: Any) -> Any: + return self._request("GET", path, params=params or None).json() + + def _post(self, path: str, json: dict[str, Any] | None = None) -> Any: + resp = self._request("POST", path, json=json) + if resp.status_code == 204: + return None + return resp.json() + + def _delete(self, path: str) -> None: + self._request("DELETE", path) + + def _patch(self, path: str, json: dict[str, Any] | None = None) -> Any: + resp = self._request("PATCH", path, json=json) + if resp.status_code == 204: + return None + return resp.json() + + def _put(self, path: str, json: dict[str, Any] | None = None) -> None: + self._request("PUT", path, json=json) + + def _get_paginated(self, path: str, limit: int = 50, **params: Any) -> list[Any]: + """自动分页获取所有结果""" + results: list[Any] = [] + page = 1 + while True: + p = {**params, "page": page, "limit": limit} + data = self._get(path, **p) + if not data: + break + results.extend(data) + if len(data) < limit: + break + page += 1 + return results + + # ------------------------------------------------------------------ + # 版本 + # ------------------------------------------------------------------ + + def get_version(self) -> str: + return self._get("/version")["version"] + + # ------------------------------------------------------------------ + # 用户管理 + # ------------------------------------------------------------------ + + def create_user( + self, + username: str, + password: str, + email: str, + full_name: str = "", + *, + must_change_password: bool = True, + ) -> GiteaUser: + data = self._post( + "/admin/users", + json={ + "username": username, + "password": password, + "email": email, + "full_name": full_name, + "must_change_password": must_change_password, + "visibility": "limited", + }, + ) + return GiteaUser(**data) + + def list_users(self) -> list[GiteaUser]: + data = self._get_paginated("/admin/users") + return [GiteaUser(**u) for u in data] + + def get_user(self, username: str) -> GiteaUser | None: + try: + data = self._get(f"/users/{username}") + return GiteaUser(**data) + except GiteaClientError as e: + if e.status_code == 404: + return None + raise + + def delete_user(self, username: str) -> None: + self._delete(f"/admin/users/{username}") + + # ------------------------------------------------------------------ + # 组织管理 + # ------------------------------------------------------------------ + + def create_org( + self, + name: str, + full_name: str = "", + description: str = "", + *, + visibility: str = "public", + ) -> GiteaOrg: + data = self._post( + "/orgs", + json={ + "username": name, + "full_name": full_name, + "description": description, + "visibility": visibility, + }, + ) + return GiteaOrg(**data) + + def get_org(self, name: str) -> GiteaOrg | None: + try: + data = self._get(f"/orgs/{name}") + return GiteaOrg(**data) + except GiteaClientError as e: + if e.status_code == 404: + return None + raise + + # ------------------------------------------------------------------ + # 团队管理 + # ------------------------------------------------------------------ + + def create_team( + self, + org: str, + name: str, + *, + permission: str = "read", + units: list[str] | None = None, + can_create_org_repo: bool = False, + ) -> GiteaTeam: + if units is None: + units = ["repo.code", "repo.issues"] + data = self._post( + f"/orgs/{org}/teams", + json={ + "name": name, + "permission": permission, + "units": units, + "can_create_org_repo": can_create_org_repo, + }, + ) + return GiteaTeam(**data) + + def list_teams(self, org: str) -> list[GiteaTeam]: + data = self._get_paginated(f"/orgs/{org}/teams") + return [GiteaTeam(**t) for t in data] + + def get_team_by_name(self, org: str, team_name: str) -> GiteaTeam | None: + teams = self.list_teams(org) + for t in teams: + if t.name == team_name: + return t + return None + + def add_team_member(self, team_id: int, username: str) -> None: + self._put(f"/teams/{team_id}/members/{username}") + + def add_team_repo(self, team_id: int, org: str, repo: str) -> None: + self._put(f"/teams/{team_id}/repos/{org}/{repo}") + + # ------------------------------------------------------------------ + # 仓库管理 + # ------------------------------------------------------------------ + + def create_org_repo( + self, + org: str, + name: str, + *, + description: str = "", + private: bool = False, + auto_init: bool = True, + default_branch: str = "main", + ) -> GiteaRepo: + data = self._post( + f"/orgs/{org}/repos", + json={ + "name": name, + "description": description, + "private": private, + "auto_init": auto_init, + "default_branch": default_branch, + }, + ) + return GiteaRepo(**data) + + def get_repo(self, owner: str, repo: str) -> GiteaRepo | None: + try: + data = self._get(f"/repos/{owner}/{repo}") + return GiteaRepo(**data) + except GiteaClientError as e: + if e.status_code == 404: + return None + raise + + def update_repo(self, owner: str, repo: str, **kwargs: Any) -> GiteaRepo: + data = self._patch(f"/repos/{owner}/{repo}", json=kwargs) + return GiteaRepo(**data) + + # ------------------------------------------------------------------ + # 仓库文件操作(用于推送 Issue Templates) + # ------------------------------------------------------------------ + + def create_or_update_file( + self, + owner: str, + repo: str, + filepath: str, + content_b64: str, + message: str, + *, + sha: str | None = None, + branch: str = "main", + ) -> dict[str, Any]: + """创建或更新仓库中的文件""" + json_body: dict[str, Any] = { + "content": content_b64, + "message": message, + "branch": branch, + } + if sha: + json_body["sha"] = sha + return self._request( + "PUT" if sha else "POST", + f"/repos/{owner}/{repo}/contents/{filepath}", + json=json_body, + ).json() + + def get_file_contents( + self, owner: str, repo: str, filepath: str, *, ref: str = "main" + ) -> dict[str, Any] | None: + """获取文件内容(含 sha)""" + try: + return self._get(f"/repos/{owner}/{repo}/contents/{filepath}", ref=ref) + except GiteaClientError as e: + if e.status_code == 404: + return None + raise + + # ------------------------------------------------------------------ + # Label 管理 + # ------------------------------------------------------------------ + + def create_label( + self, owner: str, repo: str, name: str, color: str, description: str = "" + ) -> GiteaLabel: + data = self._post( + f"/repos/{owner}/{repo}/labels", + json={"name": name, "color": color, "description": description}, + ) + return GiteaLabel(**data) + + def list_labels(self, owner: str, repo: str) -> list[GiteaLabel]: + data = self._get_paginated(f"/repos/{owner}/{repo}/labels") + return [GiteaLabel(**lbl) for lbl in data] + + def delete_label(self, owner: str, repo: str, label_id: int) -> None: + self._delete(f"/repos/{owner}/{repo}/labels/{label_id}") + + # ------------------------------------------------------------------ + # Webhook 管理 + # ------------------------------------------------------------------ + + def create_webhook( + self, + owner: str, + repo: str, + target_url: str, + *, + secret: str = "", + events: list[str] | None = None, + content_type: str = "json", + active: bool = True, + ) -> GiteaWebhook: + if events is None: + events = ["issues", "issue_comment"] + data = self._post( + f"/repos/{owner}/{repo}/hooks", + json={ + "type": "gitea", + "active": active, + "config": { + "url": target_url, + "content_type": content_type, + "secret": secret, + }, + "events": events, + }, + ) + return GiteaWebhook(**data) + + def list_webhooks(self, owner: str, repo: str) -> list[GiteaWebhook]: + data = self._get_paginated(f"/repos/{owner}/{repo}/hooks") + return [GiteaWebhook(**w) for w in data] + + def delete_webhook(self, owner: str, repo: str, hook_id: int) -> None: + self._delete(f"/repos/{owner}/{repo}/hooks/{hook_id}") + + def test_webhook(self, owner: str, repo: str, hook_id: int) -> None: + self._post(f"/repos/{owner}/{repo}/hooks/{hook_id}/tests") + + # ------------------------------------------------------------------ + # Issue 管理(用于统计) + # ------------------------------------------------------------------ + + def list_issues( + self, + owner: str, + repo: str, + *, + state: str = "all", + ) -> list[dict[str, Any]]: + return self._get_paginated(f"/repos/{owner}/{repo}/issues", state=state, type="issues") diff --git a/scripts/src/tjhlp/commands/__init__.py b/scripts/src/tjhlp/commands/__init__.py new file mode 100644 index 0000000..473a0f4 diff --git a/scripts/src/tjhlp/commands/labels.py b/scripts/src/tjhlp/commands/labels.py new file mode 100644 index 0000000..7b53dd3 --- /dev/null +++ b/scripts/src/tjhlp/commands/labels.py @@ -0,0 +1,67 @@ +"""labels 命令: Label 管理""" + +from __future__ import annotations + +import typer +from rich.console import Console +from rich.table import Table + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import get_gitea_config +from tjhlp.utils import parse_repo +from tjhlp.utils import sync_labels as _sync_labels + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +@app.command("sync") +def sync_labels( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + remove_extra: bool = typer.Option(False, "--remove-extra", help="删除不在预定义集合中的 Label"), +) -> None: + """将预定义 Label 同步到指定仓库""" + org_name, repo_name = parse_repo(repo) + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + created = _sync_labels(client, org_name, repo_name, cfg) + console.print(f" 新增 {created} 个 Label") + + if remove_extra: + existing_labels = client.list_labels(org_name, repo_name) + predefined_names = {lbl.name for lbl in cfg.labels} + removed = 0 + for lbl in existing_labels: + if lbl.name not in predefined_names: + try: + client.delete_label(org_name, repo_name, lbl.id) + console.print(f" [red]删除[/red] {lbl.name}") + removed += 1 + except GiteaClientError as e: + console.print(f" [red]删除失败[/red] {lbl.name}: {e.message}") + console.print(f" 删除 {removed} 个多余 Label") + + +@app.command("list") +def list_labels( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), +) -> None: + """列出仓库的所有 Label""" + org_name, repo_name = parse_repo(repo) + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + labels = client.list_labels(org_name, repo_name) + if not labels: + console.print("没有 Label") + return + + table = Table(title=f"{repo} 的 Labels") + table.add_column("ID", style="dim") + table.add_column("名称") + table.add_column("颜色") + table.add_column("描述") + for lbl in labels: + table.add_row(str(lbl.id), lbl.name, lbl.color, lbl.description) + console.print(table) diff --git a/scripts/src/tjhlp/commands/notify.py b/scripts/src/tjhlp/commands/notify.py new file mode 100644 index 0000000..b92a0e1 --- /dev/null +++ b/scripts/src/tjhlp/commands/notify.py @@ -0,0 +1,117 @@ +"""notify 命令: 通过 SMTP 发送账号凭据邮件""" + +from __future__ import annotations + +import csv +import smtplib +import ssl +import time +from email.mime.text import MIMEText +from pathlib import Path + +import typer +from rich.console import Console +from rich.panel import Panel + +from tjhlp.config import get_gitea_config, get_smtp_config +from tjhlp.models import CredentialRecord + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +def _build_email_text(cred: CredentialRecord, gitea_url: str) -> str: + """构建纯文本邮件正文""" + return f"""\ +同济大学高级语言程序设计 - 答疑平台账号 +{"=" * 40} + +{cred.name}同学/老师, 你好! + +你的课程答疑平台账号已创建, 请使用以下信息登录: + + 平台地址: {gitea_url} + 用户名: {cred.username} + 初始密码: {cred.password} + +首次登录后请立即修改密码。 +如有问题, 请联系助教。 +""" + + +def _read_credentials_csv(filepath: Path) -> list[CredentialRecord]: + """读取凭据 CSV 文件""" + records: list[CredentialRecord] = [] + with open(filepath, encoding="utf-8-sig") as f: + reader = csv.DictReader(f) + for row in reader: + records.append(CredentialRecord.model_validate(row)) + return records + + +@app.command("send-credentials") +def send_credentials( + file: Path = typer.Option(..., "--file", "-f", help="凭据 CSV 文件路径(由 users create 生成)"), + dry_run: bool = typer.Option(False, "--dry-run", help="仅预览邮件内容, 不实际发送"), + batch_size: int = typer.Option( + 10, "--batch-size", help="每批发送数量, 批次间暂停 2 秒(避免触发 SMTP 限制)" + ), +) -> None: + """通过 SMTP 向同济邮箱发送账号密码邮件""" + if not file.exists(): + console.print(f"[red]文件不存在: {file}[/red]") + raise typer.Exit(code=1) + + gitea_cfg = get_gitea_config() + credentials = _read_credentials_csv(file) + console.print(f"读取到 {len(credentials)} 条凭据记录") + + if dry_run: + # 预览第一封邮件 + if credentials: + cred = credentials[0] + text = _build_email_text(cred, str(gitea_cfg.url)) + console.print(Panel(text, title=f"邮件预览 -> {cred.email}", border_style="blue")) + console.print(f"\n[yellow]dry-run 模式, 共 {len(credentials)} 封邮件待发送[/yellow]") + return + + smtp_cfg = get_smtp_config() + from_addr = smtp_cfg.from_addr or smtp_cfg.user + + stats = {"sent": 0, "failed": 0} + + context = ssl.create_default_context() + + try: + with smtplib.SMTP_SSL(smtp_cfg.host, smtp_cfg.port, context=context) as server: + server.login(smtp_cfg.user, smtp_cfg.password.get_secret_value()) + console.print(f"[green]已连接 SMTP 服务器 {smtp_cfg.host}[/green]") + + for i, cred in enumerate(credentials, 1): + msg = MIMEText(_build_email_text(cred, str(gitea_cfg.url)), "plain", "utf-8") + msg["Subject"] = "同济大学高级语言程序设计 - 答疑平台账号信息" + msg["From"] = from_addr + msg["To"] = cred.email + + try: + server.send_message(msg) + console.print( + f" [{i}/{len(credentials)}] [green]已发送[/green] -> {cred.email}" + ) + stats["sent"] += 1 + except Exception as e: + console.print( + f" [{i}/{len(credentials)}] [red]失败[/red] -> {cred.email}: {e}" + ) + stats["failed"] += 1 + + # 按 batch_size 暂停, 避免触发 SMTP 速率限制 + if i % batch_size == 0 and i < len(credentials): + console.print(f" [dim]已发送 {i} 封, 暂停 2 秒...[/dim]") + time.sleep(2) + + except Exception as e: + console.print(f"[red]SMTP 连接失败: {e}[/red]") + raise typer.Exit(code=1) from e + + console.print(f"\n完成: 发送 {stats['sent']}, 失败 {stats['failed']}") diff --git a/scripts/src/tjhlp/commands/orgs.py b/scripts/src/tjhlp/commands/orgs.py new file mode 100644 index 0000000..82916ae --- /dev/null +++ b/scripts/src/tjhlp/commands/orgs.py @@ -0,0 +1,116 @@ +"""orgs 命令: 组织与团队管理""" + +from __future__ import annotations + +import csv +from pathlib import Path + +import typer +from rich.console import Console +from rich.table import Table + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import get_gitea_config +from tjhlp.models import MemberRecord + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +@app.command("create") +def create_org( + name: str = typer.Argument(help="组织名称(如 tjhlp-2025f)"), + full_name: str = typer.Option("", "--full-name", help="组织全名"), + description: str = typer.Option("课程答疑平台", "--desc", "-d", help="组织描述"), + visibility: str = typer.Option("public", "--visibility", help="可见性: public/limited/private"), +) -> None: + """创建课程组织""" + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + existing = client.get_org(name) + if existing: + console.print(f"[yellow]组织 {name} 已存在[/yellow]") + return + + org = client.create_org( + name, + full_name=full_name, + description=description, + visibility=visibility, + ) + console.print(f"[green]组织 {org.name} 已创建[/green]") + + +@app.command("create-team") +def create_team( + org: str = typer.Argument(help="组织名称"), + team_name: str = typer.Argument(help="团队名称"), + permission: str = typer.Option("read", "--permission", "-p", help="权限: read/write/admin"), +) -> None: + """在组织下创建团队""" + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + existing = client.get_team_by_name(org, team_name) + if existing: + console.print(f"[yellow]团队 {team_name} 已存在[/yellow]") + return + + team = client.create_team(org, team_name, permission=permission) + console.print(f"[green]团队 {team.name} 已创建(权限: {permission})[/green]") + + +@app.command("add-members") +def add_members( + org: str = typer.Option(..., "--org", help="组织名称"), + file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), +) -> None: + """根据 CSV 批量添加成员到组织对应团队(student -> students, ta -> ta)""" + if not file.exists(): + console.print(f"[red]文件不存在: {file}[/red]") + raise typer.Exit(code=1) + + cfg = get_gitea_config() + records: list[MemberRecord] = [] + with open(file, encoding="utf-8-sig") as f: + reader = csv.DictReader(f) + for row in reader: + records.append(MemberRecord.model_validate(row)) + + with GiteaClient(cfg) as client: + ta_team = client.get_team_by_name(org, "ta") + students_team = client.get_team_by_name(org, "students") + + if not ta_team or not students_team: + console.print("[red]未找到 ta 或 students 团队, 请先执行 setup init[/red]") + raise typer.Exit(code=1) + + stats = {"added": 0, "failed": 0} + for member in records: + team = ta_team if member.role == "ta" else students_team + try: + client.add_team_member(team.id, member.username) + console.print(f" [green]添加[/green] {member.username} -> {team.name}") + stats["added"] += 1 + except GiteaClientError as e: + console.print(f" [red]失败[/red] {member.username}: {e.message}") + stats["failed"] += 1 + + console.print(f"\n完成: 添加 {stats['added']}, 失败 {stats['failed']}") + + +@app.command("list-teams") +def list_teams( + org: str = typer.Argument(help="组织名称"), +) -> None: + """列出组织下的所有团队""" + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + teams = client.list_teams(org) + table = Table(title=f"组织 {org} 的团队") + table.add_column("ID", style="dim") + table.add_column("名称") + table.add_column("权限") + table.add_column("单元") + for t in teams: + table.add_row(str(t.id), t.name, t.permission, ", ".join(t.units)) + console.print(table) diff --git a/scripts/src/tjhlp/commands/repos.py b/scripts/src/tjhlp/commands/repos.py new file mode 100644 index 0000000..dc39dd4 --- /dev/null +++ b/scripts/src/tjhlp/commands/repos.py @@ -0,0 +1,146 @@ +"""repos 命令: 仓库管理""" + +from __future__ import annotations + +from pathlib import Path + +import typer +from rich.console import Console + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import get_gitea_config +from tjhlp.utils import parse_repo, push_templates, sync_labels + +app = typer.Typer(no_args_is_help=True) +console = Console() + +_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent.parent +_TEMPLATES_DIR = _PROJECT_ROOT / "issue-templates" + + +@app.command("create") +def create_repo( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + description: str = typer.Option("", "--desc", "-d", help="仓库描述"), + private: bool = typer.Option(False, "--private", help="是否设为私有"), +) -> None: + """在组织下创建仓库""" + org_name, repo_name = parse_repo(repo) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + existing = client.get_repo(org_name, repo_name) + if existing: + console.print(f"[yellow]仓库 {repo} 已存在[/yellow]") + return + + result = client.create_org_repo( + org_name, + repo_name, + description=description, + private=private, + auto_init=True, + ) + console.print(f"[green]仓库已创建: {result.html_url}[/green]") + + +@app.command("create-homework") +def create_homework( + org: str = typer.Option(..., "--org", help="组织名称"), + number: int = typer.Option(..., "--number", "-n", help="作业编号(如 3 对应 hw03)"), + description: str = typer.Option("", "--desc", "-d", help="作业描述"), + webhook_url: str = typer.Option("", "--webhook-url", help="Webhook 通知地址"), + webhook_secret: str = typer.Option("", "--webhook-secret", help="Webhook 密钥"), +) -> None: + """创建作业仓库(自动命名 hwXX, 推送作业模板, 同步 Labels, 配置 Webhook)""" + repo_name = f"hw{number:02d}" + desc = description or f"作业 {number:02d}" + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + # 创建仓库 + existing = client.get_repo(org, repo_name) + if existing: + console.print(f"[yellow]仓库 {org}/{repo_name} 已存在[/yellow]") + else: + client.create_org_repo(org, repo_name, description=desc, auto_init=True) + console.print(f"[green]仓库 {org}/{repo_name} 已创建[/green]") + + # 推送作业 Issue Templates + console.print("\n推送 Issue Templates...") + hw_tpl_dir = _TEMPLATES_DIR / "homework" + n = push_templates(client, org, repo_name, hw_tpl_dir) + console.print(f" 共推送 {n} 个模板文件") + + # 同步 Labels + console.print("\n同步 Labels...") + created = sync_labels(client, org, repo_name, cfg) + console.print(f" 新增 {created} 个 Label") + + # 配置 Webhook + if webhook_url: + console.print("\n配置 Webhook...") + client.create_webhook( + org, + repo_name, + webhook_url, + secret=webhook_secret, + events=["issues", "issue_comment"], + ) + console.print(f" [green]Webhook -> {webhook_url}[/green]") + + # 添加到团队 + console.print("\n添加到团队...") + for team_name in ("ta", "students"): + team = client.get_team_by_name(org, team_name) + if team: + try: + client.add_team_repo(team.id, org, repo_name) + console.print(f" [green]{team_name} -> {repo_name}[/green]") + except GiteaClientError as e: + console.print(f" [yellow]{team_name}: {e.message}[/yellow]") + + console.print(f"\n[bold green]作业仓库 {org}/{repo_name} 配置完成[/bold green]") + + +@app.command("init-templates") +def init_templates( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + template_type: str = typer.Option( + "general", "--type", "-t", help="模板类型: general 或 homework" + ), +) -> None: + """将 Issue Templates 推送到指定仓库""" + org_name, repo_name = parse_repo(repo) + + tpl_dir = _TEMPLATES_DIR / template_type + if not tpl_dir.exists(): + console.print(f"[red]模板类型 {template_type} 不存在(路径: {tpl_dir})[/red]") + raise typer.Exit(code=1) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + n = push_templates(client, org_name, repo_name, tpl_dir) + console.print(f"\n共推送 {n} 个模板文件到 {repo}") + + +@app.command("configure") +def configure_repo( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + disable_wiki: bool = typer.Option(True, help="禁用 Wiki"), + disable_projects: bool = typer.Option(True, help="禁用 Projects"), + disable_packages: bool = typer.Option(True, help="禁用 Packages"), +) -> None: + """配置仓库设置(禁用不需要的功能)""" + org_name, repo_name = parse_repo(repo) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + client.update_repo( + org_name, + repo_name, + has_wiki=not disable_wiki, + has_projects=not disable_projects, + has_packages=not disable_packages, + ) + console.print(f"[green]仓库 {repo} 配置已更新[/green]") diff --git a/scripts/src/tjhlp/commands/setup.py b/scripts/src/tjhlp/commands/setup.py new file mode 100644 index 0000000..8026f39 --- /dev/null +++ b/scripts/src/tjhlp/commands/setup.py @@ -0,0 +1,141 @@ +"""setup 命令: 一键初始化课程答疑平台""" + +from __future__ import annotations + +from pathlib import Path + +import typer +from rich.console import Console + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import get_gitea_config +from tjhlp.utils import push_templates, sync_labels + +app = typer.Typer(no_args_is_help=True) +console = Console() + +# Issue Templates 目录(相对于项目根) +_PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent.parent +_TEMPLATES_DIR = _PROJECT_ROOT / "issue-templates" + + +@app.command() +def init( + org: str = typer.Option(..., "--org", help="组织名称(如 tjhlp-2025f)"), + semester: str = typer.Option("", "--semester", help="学期标识(如 2025f), 默认从组织名推断"), + webhook_url: str = typer.Option("", "--webhook-url", help="Webhook 通知地址"), + webhook_secret: str = typer.Option("", "--webhook-secret", help="Webhook 密钥"), +) -> None: + """一键初始化课程答疑平台: 创建组织、团队、general 仓库、Labels、Webhook""" + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + # 1. 检查连接 + version = client.get_version() + console.print(f"[green]已连接 Gitea {version}[/green]") + + # 2. 创建组织 + console.print(f"\n[bold]1. 创建组织 {org}[/bold]") + existing_org = client.get_org(org) + if existing_org: + console.print(" [yellow]组织已存在, 跳过[/yellow]") + else: + sem = semester or org + client.create_org( + org, + full_name=f"同济大学高级语言程序设计 ({sem})", + description="课程答疑平台", + visibility="public", + ) + console.print(" [green]已创建[/green]") + + # 3. 创建团队 + console.print("\n[bold]2. 创建团队[/bold]") + for team_name, permission, units in [ + ("ta", "write", ["repo.code", "repo.issues"]), + ("students", "read", ["repo.code", "repo.issues"]), + ]: + existing_team = client.get_team_by_name(org, team_name) + if existing_team: + console.print(f" [yellow]{team_name} 团队已存在, 跳过[/yellow]") + else: + client.create_team( + org, + team_name, + permission=permission, + units=units, + ) + console.print(f" [green]{team_name} 团队已创建 (权限: {permission})[/green]") + + # 4. 创建 general 仓库 + console.print("\n[bold]3. 创建 general 仓库[/bold]") + existing_repo = client.get_repo(org, "general") + if existing_repo: + console.print(" [yellow]general 仓库已存在, 跳过创建[/yellow]") + else: + client.create_org_repo( + org, + "general", + description="课程答疑 - 一般性问题(课程内容、环境配置等)", + private=False, + auto_init=True, + ) + console.print(" [green]已创建[/green]") + + # 5. 推送 Issue Templates + console.print("\n[bold]4. 推送 Issue Templates 到 general 仓库[/bold]") + general_tpl_dir = _TEMPLATES_DIR / "general" + if general_tpl_dir.exists(): + n = push_templates(client, org, "general", general_tpl_dir) + console.print(f" 共推送 {n} 个模板文件") + else: + console.print(f" [red]模板目录不存在: {general_tpl_dir}[/red]") + + # 6. 同步 Labels + console.print("\n[bold]5. 同步预定义 Labels[/bold]") + created = sync_labels(client, org, "general", cfg) + existing_count = len(client.list_labels(org, "general")) + console.print(f" 新增 {created} 个 Label, 当前共 {existing_count} 个") + + # 7. 配置 Webhook + if webhook_url: + console.print("\n[bold]6. 配置 Webhook[/bold]") + client.create_webhook( + org, + "general", + webhook_url, + secret=webhook_secret, + events=["issues", "issue_comment"], + ) + console.print(f" [green]Webhook 已配置 -> {webhook_url}[/green]") + else: + console.print("\n[bold]6. 跳过 Webhook 配置[/bold](未提供 --webhook-url)") + + # 8. 将仓库添加到团队 + console.print("\n[bold]7. 将 general 仓库添加到团队[/bold]") + for team_name in ("ta", "students"): + team = client.get_team_by_name(org, team_name) + if team: + try: + client.add_team_repo(team.id, org, "general") + console.print(f" [green]{team_name} -> general[/green]") + except GiteaClientError as e: + console.print(f" [yellow]{team_name}: {e.message}[/yellow]") + + console.print("\n[bold green]初始化完成![/bold green]") + console.print(f"访问 {str(cfg.url).rstrip('/')}/{org}/general 查看仓库") + + +@app.command() +def status() -> None: + """检查 Gitea 实例连接状态""" + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + try: + version = client.get_version() + console.print(f"[green]Gitea {version} 运行正常[/green]") + console.print(f"URL: {cfg.url}") + except Exception as e: + console.print(f"[red]连接失败: {e}[/red]") + raise typer.Exit(code=1) from e diff --git a/scripts/src/tjhlp/commands/stats.py b/scripts/src/tjhlp/commands/stats.py new file mode 100644 index 0000000..5602b9e --- /dev/null +++ b/scripts/src/tjhlp/commands/stats.py @@ -0,0 +1,113 @@ +"""stats 命令: Issue 统计""" + +from __future__ import annotations + +import csv +from pathlib import Path + +import typer +from rich.console import Console +from rich.table import Table + +from tjhlp.client import GiteaClient +from tjhlp.config import get_gitea_config +from tjhlp.utils import compute_issue_stats, parse_repo + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +@app.command("summary") +def summary( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), +) -> None: + """显示 Issue 统计摘要""" + org_name, repo_name = parse_repo(repo) + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + issues = client.list_issues(org_name, repo_name, state="all") + + if not issues: + console.print("暂无 Issue") + return + + stats = compute_issue_stats(issues) + + console.print(f"\n[bold]Issue 统计 - {repo}[/bold]\n") + + overview = Table(show_header=False) + overview.add_column("指标", style="bold") + overview.add_column("数量") + overview.add_row("总计", str(stats["total"])) + overview.add_row("开启中", f"[green]{stats['open']}[/green]") + overview.add_row("已关闭", f"[dim]{stats['closed']}[/dim]") + overview.add_row("有回复", str(stats["with_comments"])) + overview.add_row("待回复(开启且无回复)", f"[red]{stats['no_reply']}[/red]") + console.print(overview) + + if stats["label_counts"]: + console.print("\n[bold]按 Label 分布[/bold]") + label_table = Table() + label_table.add_column("Label") + label_table.add_column("数量", justify="right") + for name, count in stats["label_counts"].most_common(): + label_table.add_row(name, str(count)) + console.print(label_table) + + if stats["user_counts"]: + console.print("\n[bold]提问排行 (Top 10)[/bold]") + user_table = Table() + user_table.add_column("用户") + user_table.add_column("提问数", justify="right") + for name, count in stats["user_counts"].most_common(10): + user_table.add_row(name, str(count)) + console.print(user_table) + + +@app.command("export") +def export_stats( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + output: Path = typer.Option("issues_export.csv", "--output", "-o", help="导出文件路径"), +) -> None: + """导出 Issue 数据到 CSV""" + org_name, repo_name = parse_repo(repo) + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + issues = client.list_issues(org_name, repo_name, state="all") + + if not issues: + console.print("暂无 Issue") + return + + with open(output, "w", newline="", encoding="utf-8") as f: + writer = csv.DictWriter( + f, + fieldnames=[ + "number", + "title", + "state", + "user", + "labels", + "comments", + "created_at", + "updated_at", + ], + ) + writer.writeheader() + for issue in issues: + writer.writerow( + { + "number": issue.get("number", ""), + "title": issue.get("title", ""), + "state": issue.get("state", ""), + "user": issue.get("user", {}).get("login", ""), + "labels": "; ".join(lbl.get("name", "") for lbl in issue.get("labels", [])), + "comments": issue.get("comments", 0), + "created_at": issue.get("created_at", ""), + "updated_at": issue.get("updated_at", ""), + } + ) + + console.print(f"[green]已导出 {len(issues)} 条 Issue 到 {output}[/green]") diff --git a/scripts/src/tjhlp/commands/users.py b/scripts/src/tjhlp/commands/users.py new file mode 100644 index 0000000..0f13838 --- /dev/null +++ b/scripts/src/tjhlp/commands/users.py @@ -0,0 +1,222 @@ +"""users 命令: 用户管理(批量创建/列出/删除)""" + +import csv +import secrets +import string +from datetime import UTC, datetime +from pathlib import Path + +import typer +from rich.console import Console +from rich.table import Table + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import get_gitea_config +from tjhlp.models import CredentialRecord, MemberRecord, MemberRole + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +def _generate_password(length: int = 12) -> str: + """生成随机密码: 至少包含大小写字母、数字和特殊字符""" + if length < 8: + length = 8 + alphabet = string.ascii_letters + string.digits + "!@#$%&*" + while True: + password = "".join(secrets.choice(alphabet) for _ in range(length)) + if ( + any(c.islower() for c in password) + and any(c.isupper() for c in password) + and any(c.isdigit() for c in password) + and any(c in "!@#$%&*" for c in password) + ): + return password + + +def _read_members_csv(filepath: Path) -> list[MemberRecord]: + """读取 members CSV 文件""" + records: list[MemberRecord] = [] + with open(filepath, encoding="utf-8-sig") as f: + reader = csv.DictReader(f) + for row in reader: + records.append(MemberRecord.model_validate(row)) + return records + + +@app.command("create") +def create_users( + file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), + org: str = typer.Option("", "--org", help="自动添加到指定组织的对应团队"), + output: Path = typer.Option(None, "--output", "-o", help="凭据输出文件路径(默认自动生成)"), + dry_run: bool = typer.Option(False, "--dry-run", help="仅预览, 不实际创建"), +) -> None: + """从 CSV 批量创建用户账号, 生成随机密码并输出到凭据文件""" + if not file.exists(): + console.print(f"[red]文件不存在: {file}[/red]") + raise typer.Exit(code=1) + + cfg = get_gitea_config() + members = _read_members_csv(file) + console.print( + f"读取到 {len(members)} 条记录 " + f"(学生: {sum(1 for m in members if m.role == MemberRole.STUDENT)}, " + f"助教: {sum(1 for m in members if m.role == MemberRole.TA)})" + ) + + if dry_run: + table = Table(title="预览(dry-run)") + table.add_column("ID") + table.add_column("姓名") + table.add_column("角色") + table.add_column("邮箱") + for m in members: + table.add_row(m.id, m.name, m.role, m.email) + console.print(table) + return + + credentials: list[CredentialRecord] = [] + stats = {"created": 0, "skipped": 0, "failed": 0} + + with GiteaClient(cfg) as client: + # 获取团队 ID(如果指定了组织) + ta_team = None + students_team = None + if org: + ta_team = client.get_team_by_name(org, "ta") + students_team = client.get_team_by_name(org, "students") + + for member in members: + # 检查用户是否已存在 + existing = client.get_user(member.username) + if existing: + console.print(f" [yellow]跳过[/yellow] {member.username}({member.name})- 已存在") + stats["skipped"] += 1 + continue + + password = _generate_password(cfg.password_length) + + try: + client.create_user( + username=member.username, + password=password, + email=member.email, + full_name=member.name, + must_change_password=True, + ) + console.print(f" [green]创建[/green] {member.username}({member.name})") + stats["created"] += 1 + + credentials.append( + CredentialRecord( + id=member.id, + name=member.name, + role=member.role.value, + username=member.username, + password=password, + email=member.email, + ) + ) + + # 添加到团队 + if org: + team = ta_team if member.role == MemberRole.TA else students_team + if team: + try: + client.add_team_member(team.id, member.username) + except GiteaClientError as e: + console.print(f" [yellow]添加到团队失败: {e.message}[/yellow]") + + except GiteaClientError as e: + console.print(f" [red]失败[/red] {member.username}({member.name}): {e.message}") + stats["failed"] += 1 + + # 写出凭据文件 + if credentials: + if output is None: + ts = datetime.now(tz=UTC).strftime("%Y%m%d_%H%M%S") + output = Path(f"credentials_{ts}.csv") + with open(output, "w", newline="", encoding="utf-8") as f: + writer = csv.DictWriter( + f, + fieldnames=["id", "name", "role", "username", "password", "email"], + ) + writer.writeheader() + for cred in credentials: + writer.writerow(cred.model_dump()) + console.print(f"\n凭据已保存到 [bold]{output}[/bold]") + + console.print( + f"\n完成: 创建 {stats['created']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" + ) + + +@app.command("list") +def list_users() -> None: + """列出 Gitea 上的所有用户""" + cfg = get_gitea_config() + + with GiteaClient(cfg) as client: + users = client.list_users() + table = Table(title=f"用户列表(共 {len(users)} 个)") + table.add_column("ID", style="dim") + table.add_column("用户名") + table.add_column("姓名") + table.add_column("邮箱") + table.add_column("管理员") + table.add_column("活跃") + for u in users: + table.add_row( + str(u.id), + u.login, + u.full_name, + u.email, + "[green]是[/green]" if u.is_admin else "", + "[green]是[/green]" if u.active else "[red]否[/red]", + ) + console.print(table) + + +@app.command("delete") +def delete_users( + file: Path = typer.Option(..., "--file", "-f", help="成员名单 CSV 文件路径"), + confirm: bool = typer.Option(False, "--yes", "-y", help="跳过确认提示"), +) -> None: + """根据 CSV 名单批量删除用户(危险操作)""" + if not file.exists(): + console.print(f"[red]文件不存在: {file}[/red]") + raise typer.Exit(code=1) + + members = _read_members_csv(file) + console.print(f"[red bold]即将删除 {len(members)} 个用户![/red bold]") + + if not confirm: + typer.confirm("确认删除?此操作不可恢复", abort=True) + + cfg = get_gitea_config() + stats = {"deleted": 0, "skipped": 0, "failed": 0} + + with GiteaClient(cfg) as client: + for member in members: + existing = client.get_user(member.username) + if not existing: + console.print(f" [yellow]跳过[/yellow] {member.username} - 不存在") + stats["skipped"] += 1 + continue + + if existing.is_admin: + console.print(f" [yellow]跳过[/yellow] {member.username} - 管理员账号") + stats["skipped"] += 1 + continue + + try: + client.delete_user(member.username) + console.print(f" [red]已删除[/red] {member.username}({member.name})") + stats["deleted"] += 1 + except GiteaClientError as e: + console.print(f" [red]失败[/red] {member.username}: {e.message}") + stats["failed"] += 1 + + console.print( + f"\n完成: 删除 {stats['deleted']}, 跳过 {stats['skipped']}, 失败 {stats['failed']}" + ) diff --git a/scripts/src/tjhlp/commands/webhooks.py b/scripts/src/tjhlp/commands/webhooks.py new file mode 100644 index 0000000..c03bdfa --- /dev/null +++ b/scripts/src/tjhlp/commands/webhooks.py @@ -0,0 +1,97 @@ +"""webhooks 命令: Webhook 管理""" + +from __future__ import annotations + +import typer +from rich.console import Console +from rich.table import Table + +from tjhlp.client import GiteaClient +from tjhlp.config import get_gitea_config +from tjhlp.utils import parse_repo + +app = typer.Typer(no_args_is_help=True) +console = Console() + + +@app.command("create") +def create_webhook( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + url: str = typer.Option(..., "--url", help="Webhook 目标 URL"), + secret: str = typer.Option("", "--secret", help="Webhook 密钥"), + events: str = typer.Option("issues,issue_comment", "--events", help="触发事件, 逗号分隔"), +) -> None: + """为仓库创建 Webhook""" + org_name, repo_name = parse_repo(repo) + event_list = [e.strip() for e in events.split(",")] + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + hook = client.create_webhook( + org_name, + repo_name, + url, + secret=secret, + events=event_list, + ) + console.print(f"[green]Webhook #{hook.id} 已创建 -> {url}[/green]") + console.print(f" 事件: {', '.join(event_list)}") + + +@app.command("list") +def list_webhooks( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), +) -> None: + """列出仓库的所有 Webhook""" + org_name, repo_name = parse_repo(repo) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + hooks = client.list_webhooks(org_name, repo_name) + if not hooks: + console.print("没有 Webhook") + return + + table = Table(title=f"{repo} 的 Webhook") + table.add_column("ID", style="dim") + table.add_column("类型") + table.add_column("URL") + table.add_column("事件") + table.add_column("状态") + for h in hooks: + table.add_row( + str(h.id), + h.type, + h.config.get("url", ""), + ", ".join(h.events), + "[green]活跃[/green]" if h.active else "[red]禁用[/red]", + ) + console.print(table) + + +@app.command("test") +def test_webhook( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + hook_id: int = typer.Argument(help="Webhook ID"), +) -> None: + """测试指定 Webhook""" + org_name, repo_name = parse_repo(repo) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + client.test_webhook(org_name, repo_name, hook_id) + console.print(f"[green]已向 Webhook #{hook_id} 发送测试请求[/green]") + + +@app.command("delete") +def delete_webhook( + repo: str = typer.Argument(help="仓库名称, 格式为 org/repo"), + hook_id: int = typer.Argument(help="Webhook ID"), +) -> None: + """删除指定 Webhook""" + org_name, repo_name = parse_repo(repo) + + cfg = get_gitea_config() + with GiteaClient(cfg) as client: + client.delete_webhook(org_name, repo_name, hook_id) + console.print(f"[red]Webhook #{hook_id} 已删除[/red]") diff --git a/scripts/src/tjhlp/config.py b/scripts/src/tjhlp/config.py new file mode 100644 index 0000000..53d7a13 --- /dev/null +++ b/scripts/src/tjhlp/config.py @@ -0,0 +1,105 @@ +"""配置管理: Dynaconf 加载 + Pydantic 校验""" + +from __future__ import annotations + +from pathlib import Path + +from dynaconf import Dynaconf +from pydantic import AliasGenerator, BaseModel, ConfigDict, HttpUrl, SecretStr, field_validator + +# --------------------------------------------------------------------------- +# Dynaconf 实例(在 scripts/ 目录下查找配置文件) +# --------------------------------------------------------------------------- +_SCRIPTS_DIR = Path(__file__).resolve().parent.parent.parent + +settings = Dynaconf( + envvar_prefix="TJHLP", + settings_files=[ + str(_SCRIPTS_DIR / "settings.toml"), + str(_SCRIPTS_DIR / ".secrets.toml"), + ], + environments=True, + load_dotenv=True, +) + + +# --------------------------------------------------------------------------- +# Pydantic 强类型配置模型 +# --------------------------------------------------------------------------- +class LabelDef(BaseModel): + """预定义 Label""" + + name: str + color: str + description: str = "" + + @field_validator("color") + @classmethod + def color_must_be_hex(cls, v: str) -> str: + v = v.lstrip("#") + if len(v) not in (3, 6) or not all(c in "0123456789abcdefABCDEF" for c in v): + raise ValueError(f"无效的颜色值: #{v}") + return f"#{v}" + + +class GiteaConfig(BaseModel): + """Gitea 连接配置""" + + model_config = ConfigDict( + alias_generator=AliasGenerator(validation_alias=str.upper), + populate_by_name=True, + ) + + url: HttpUrl + token: SecretStr + email_domain: str = "tongji.edu.cn" + default_org: str = "" + password_length: int = 16 + labels: list[LabelDef] = [] + + +class SmtpConfig(BaseModel): + """SMTP 邮件配置""" + + model_config = ConfigDict( + alias_generator=AliasGenerator(validation_alias=str.upper), + populate_by_name=True, + ) + + host: str + port: int = 465 + user: str + password: SecretStr + from_addr: str = "" + + +class Config(BaseModel): + """总配置模型""" + + model_config = ConfigDict( + alias_generator=AliasGenerator( + validation_alias=str.upper, + ), + populate_by_name=True, + ) + + gitea: GiteaConfig + smtp: SmtpConfig | None = None + + +def get_config() -> Config: + """获取完整配置""" + return Config.model_validate(settings.to_dict()) + + +def get_gitea_config() -> GiteaConfig: + """从 Dynaconf 加载并校验 Gitea 配置""" + return get_config().gitea + + +def get_smtp_config() -> SmtpConfig: + """从 Dynaconf 加载并校验 SMTP 配置""" + cfg = get_config() + if cfg.smtp is None: + raise ValueError("SMTP 配置缺失, 请在 .secrets.toml 中配置") + return cfg.smtp diff --git a/scripts/src/tjhlp/models.py b/scripts/src/tjhlp/models.py new file mode 100644 index 0000000..dc47b9c --- /dev/null +++ b/scripts/src/tjhlp/models.py @@ -0,0 +1,107 @@ +"""Pydantic 数据模型: 用于 CSV 解析、API 请求/响应""" + +from enum import StrEnum + +from pydantic import BaseModel, computed_field + + +# --------------------------------------------------------------------------- +# 枚举 +# --------------------------------------------------------------------------- +class MemberRole(StrEnum): + STUDENT = "student" + TA = "ta" + + +# --------------------------------------------------------------------------- +# CSV 输入模型 +# --------------------------------------------------------------------------- +class MemberRecord(BaseModel): + """members.csv 中的一行记录""" + + id: str + name: str + role: MemberRole + + @computed_field + @property + def email(self) -> str: + return f"{self.id}@tongji.edu.cn" + + @computed_field + @property + def username(self) -> str: + return self.id + + +class CredentialRecord(BaseModel): + """生成的凭据记录(输出到 credentials CSV)""" + + id: str + name: str + role: str + username: str + password: str + email: str + + +# --------------------------------------------------------------------------- +# Gitea API 响应模型(部分字段) +# --------------------------------------------------------------------------- +class GiteaUser(BaseModel): + id: int + login: str + full_name: str = "" + email: str = "" + is_admin: bool = False + active: bool = True + + +class GiteaOrg(BaseModel): + id: int + name: str + full_name: str = "" + description: str = "" + + +class GiteaTeam(BaseModel): + id: int + name: str + permission: str = "" + units: list[str] = [] + + +class GiteaRepo(BaseModel): + id: int + name: str + full_name: str = "" + description: str = "" + private: bool = False + html_url: str = "" + + +class GiteaLabel(BaseModel): + id: int + name: str + color: str + description: str = "" + + +class GiteaWebhook(BaseModel): + id: int + type: str + active: bool = True + config: dict = {} + events: list[str] = [] + + +class GiteaIssue(BaseModel): + id: int + number: int + title: str + state: str = "" + labels: list[GiteaLabel] = [] + comments: int = 0 + created_at: str = "" + updated_at: str = "" + user: GiteaUser | None = None diff --git a/scripts/src/tjhlp/utils.py b/scripts/src/tjhlp/utils.py new file mode 100644 index 0000000..aef5422 --- /dev/null +++ b/scripts/src/tjhlp/utils.py @@ -0,0 +1,142 @@ +"""共享工具函数: 仓库名解析、Issue Template 推送、Label 同步、统计计算""" + +from __future__ import annotations + +import base64 +from collections import Counter +from pathlib import Path +from typing import Any + +import typer +from rich.console import Console + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import GiteaConfig + +console = Console() + + +# --------------------------------------------------------------------------- +# 仓库名解析 +# --------------------------------------------------------------------------- +def parse_repo(repo: str) -> tuple[str, str]: + """将 'org/repo' 格式的字符串解析为 (org, repo) 元组。 + + 格式不正确时打印错误并退出。 + """ + parts = repo.split("/") + if len(parts) != 2 or not parts[0] or not parts[1]: + console.print("[red]仓库名称格式应为 org/repo[/red]") + raise typer.Exit(code=1) + return parts[0], parts[1] + + +# --------------------------------------------------------------------------- +# Issue Template 推送 +# --------------------------------------------------------------------------- +def push_templates( + client: GiteaClient, + org: str, + repo: str, + template_dir: Path, +) -> int: + """将本地 issue template 目录推送到远端仓库, 返回推送的文件数。""" + count = 0 + gitea_dir = template_dir / ".gitea" / "ISSUE_TEMPLATE" + if not gitea_dir.exists(): + console.print(f"[yellow]模板目录不存在: {gitea_dir}[/yellow]") + return 0 + + for filepath in sorted(gitea_dir.iterdir()): + if not filepath.is_file(): + continue + remote_path = f".gitea/ISSUE_TEMPLATE/{filepath.name}" + content_b64 = base64.b64encode(filepath.read_bytes()).decode() + + existing = client.get_file_contents(org, repo, remote_path) + if existing: + sha = existing.get("sha", "") + client.create_or_update_file( + org, + repo, + remote_path, + content_b64, + f"更新 Issue Template: {filepath.name}", + sha=sha, + ) + console.print(f" [blue]更新[/blue] {remote_path}") + else: + client.create_or_update_file( + org, + repo, + remote_path, + content_b64, + f"添加 Issue Template: {filepath.name}", + ) + console.print(f" [green]创建[/green] {remote_path}") + count += 1 + + return count + + +# --------------------------------------------------------------------------- +# Label 同步 +# --------------------------------------------------------------------------- +def sync_labels(client: GiteaClient, org: str, repo: str, cfg: GiteaConfig) -> int: + """将预定义 Label 同步到仓库, 返回新增数量。""" + existing = {lbl.name for lbl in client.list_labels(org, repo)} + created = 0 + for lbl_def in cfg.labels: + if lbl_def.name in existing: + continue + try: + client.create_label(org, repo, lbl_def.name, lbl_def.color, lbl_def.description) + created += 1 + except GiteaClientError as e: + console.print(f" [red]创建 Label {lbl_def.name} 失败: {e.message}[/red]") + return created + + +# --------------------------------------------------------------------------- +# Issue 统计计算(纯函数, 无外部依赖) +# --------------------------------------------------------------------------- +def compute_issue_stats(issues: list[dict[str, Any]]) -> dict[str, Any]: + """从 Issue 列表中计算统计数据。 + + 返回值结构: + { + "total": int, + "open": int, + "closed": int, + "with_comments": int, + "no_reply": int, + "label_counts": Counter, + "user_counts": Counter, + } + """ + total = len(issues) + open_count = sum(1 for i in issues if i.get("state") == "open") + closed_count = sum(1 for i in issues if i.get("state") == "closed") + with_comments = sum(1 for i in issues if i.get("comments", 0) > 0) + no_reply = sum(1 for i in issues if i.get("state") == "open" and i.get("comments", 0) == 0) + + label_counter: Counter[str] = Counter() + for issue in issues: + for label in issue.get("labels", []): + label_counter[label.get("name", "unknown")] += 1 + + user_counter: Counter[str] = Counter() + for issue in issues: + user = issue.get("user") + if user: + user_counter[user.get("login", "unknown")] += 1 + + return { + "total": total, + "open": open_count, + "closed": closed_count, + "with_comments": with_comments, + "no_reply": no_reply, + "label_counts": label_counter, + "user_counts": user_counter, + } diff --git a/scripts/tests/conftest.py b/scripts/tests/conftest.py new file mode 100644 index 0000000..21bfe3b --- /dev/null +++ b/scripts/tests/conftest.py @@ -0,0 +1,81 @@ +"""测试公共 fixtures""" + +from unittest.mock import MagicMock + +import pytest +from pydantic import HttpUrl, SecretStr + +from tjhlp.config import GiteaConfig, LabelDef, SmtpConfig +from tjhlp.models import CredentialRecord, MemberRecord, MemberRole + + +@pytest.fixture() +def sample_labels() -> list[LabelDef]: + return [ + LabelDef(name="duplicate", color="#cfd3d7", description="重复问题"), + LabelDef(name="resolved", color="#0e8a16", description="已解决"), + ] + + +@pytest.fixture() +def gitea_config(sample_labels: list[LabelDef]) -> GiteaConfig: + return GiteaConfig( + url=HttpUrl("http://localhost:3000"), + token=SecretStr("test-token-12345"), + email_domain="tongji.edu.cn", + default_org="tjhlp-test", + password_length=12, + labels=sample_labels, + ) + + +@pytest.fixture() +def smtp_config() -> SmtpConfig: + return SmtpConfig( + host="smtp.test.com", + port=465, + user="test@test.com", + password=SecretStr("smtp-pass"), + from_addr="Test ", + ) + + +@pytest.fixture() +def sample_members() -> list[MemberRecord]: + return [ + MemberRecord(id="2659999", name="赵一伤", role=MemberRole.STUDENT), + MemberRecord(id="2659876", name="钱二败", role=MemberRole.STUDENT), + MemberRecord(id="10001", name="李四催", role=MemberRole.TA), + ] + + +@pytest.fixture() +def sample_credentials() -> list[CredentialRecord]: + return [ + CredentialRecord( + id="2659999", + name="赵一伤", + role=MemberRole.STUDENT, + username="2659999", + password="xK9#mP2$vL4w", + email="2659999@tongji.edu.cn", + ), + CredentialRecord( + id="10001", + name="李四催", + role=MemberRole.TA, + username="10001", + password="aB3$cD5&eF7h", + email="10001@tongji.edu.cn", + ), + ] + + +@pytest.fixture() +def mock_gitea_client() -> MagicMock: + """创建一个 mock GiteaClient, 可在各命令测试中复用""" + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_version.return_value = "1.25.5" + return client diff --git a/scripts/tests/test_client.py b/scripts/tests/test_client.py new file mode 100644 index 0000000..fa0362b --- /dev/null +++ b/scripts/tests/test_client.py @@ -0,0 +1,191 @@ +"""client.py 单元测试: 使用 respx mock HTTP 层""" + +from __future__ import annotations + +from collections.abc import Generator + +import httpx +import pytest +import respx +from pydantic import HttpUrl, SecretStr + +from tjhlp.client import GiteaClient, GiteaClientError +from tjhlp.config import GiteaConfig + + +@pytest.fixture() +def config() -> GiteaConfig: + return GiteaConfig( + url=HttpUrl("http://gitea.test"), + token=SecretStr("test-token"), + ) + + +@pytest.fixture() +def client(config: GiteaConfig) -> Generator[GiteaClient]: + c = GiteaClient(config) + yield c + c.close() + + +class TestClientInit: + def test_base_url(self, config: GiteaConfig): + c = GiteaClient(config) + assert c.base_url == "http://gitea.test/api/v1" + c.close() + + def test_base_url_strips_trailing_slash(self): + cfg = GiteaConfig(url=HttpUrl("http://gitea.test/"), token=SecretStr("tok")) + c = GiteaClient(cfg) + assert c.base_url == "http://gitea.test/api/v1" + c.close() + + def test_context_manager(self, config: GiteaConfig): + with GiteaClient(config) as c: + assert c.base_url == "http://gitea.test/api/v1" + + +class TestVersion: + @respx.mock + def test_get_version(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/version").respond(json={"version": "1.25.5"}) + assert client.get_version() == "1.25.5" + + +class TestErrorHandling: + @respx.mock + def test_404_raises(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/users/nonexistent").respond( + status_code=404, json={"message": "not found"} + ) + with pytest.raises(GiteaClientError) as exc_info: + client._get("/users/nonexistent") + assert exc_info.value.status_code == 404 + + @respx.mock + def test_500_raises(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/version").respond( + status_code=500, json={"message": "internal error"} + ) + with pytest.raises(GiteaClientError) as exc_info: + client.get_version() + assert exc_info.value.status_code == 500 + + +class TestGetUser: + @respx.mock + def test_existing_user(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/users/student1").respond( + json={"id": 1, "login": "student1", "full_name": "Student One"} + ) + user = client.get_user("student1") + assert user is not None + assert user.login == "student1" + + @respx.mock + def test_nonexistent_user(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/users/nobody").respond( + status_code=404, json={"message": "not found"} + ) + user = client.get_user("nobody") + assert user is None + + +class TestGetOrg: + @respx.mock + def test_existing_org(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/orgs/tjhlp").respond(json={"id": 1, "name": "tjhlp"}) + org = client.get_org("tjhlp") + assert org is not None + assert org.name == "tjhlp" + + @respx.mock + def test_nonexistent_org(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/orgs/nope").respond( + status_code=404, json={"message": "not found"} + ) + assert client.get_org("nope") is None + + +class TestPagination: + @respx.mock + def test_single_page(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/admin/users").respond( + json=[{"id": 1, "login": "a"}, {"id": 2, "login": "b"}] + ) + users = client.list_users() + assert len(users) == 2 + + @respx.mock + def test_multi_page(self, client: GiteaClient): + # First page returns exactly `limit` items -> triggers page 2 + page1 = [{"id": i, "login": f"u{i}"} for i in range(50)] + page2 = [{"id": 50, "login": "u50"}] + + route = respx.get("http://gitea.test/api/v1/admin/users") + route.side_effect = [ + httpx.Response(200, json=page1), + httpx.Response(200, json=page2), + ] + users = client.list_users() + assert len(users) == 51 + + @respx.mock + def test_empty_result(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/admin/users").respond(json=[]) + users = client.list_users() + assert len(users) == 0 + + +class TestCreateUser: + @respx.mock + def test_create_user(self, client: GiteaClient): + respx.post("http://gitea.test/api/v1/admin/users").respond( + json={ + "id": 1, + "login": "2659999", + "full_name": "赵一伤", + "email": "2659999@tongji.edu.cn", + } + ) + user = client.create_user("2659999", "password", "2659999@tongji.edu.cn", "赵一伤") + assert user.login == "2659999" + assert user.full_name == "赵一伤" + + +class TestLabels: + @respx.mock + def test_create_label(self, client: GiteaClient): + respx.post("http://gitea.test/api/v1/repos/org/repo/labels").respond( + json={"id": 1, "name": "bug", "color": "#ff0000", "description": "Bug report"} + ) + label = client.create_label("org", "repo", "bug", "#ff0000", "Bug report") + assert label.name == "bug" + + @respx.mock + def test_list_labels_empty(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/repos/org/repo/labels").respond(json=[]) + labels = client.list_labels("org", "repo") + assert labels == [] + + +class TestGetTeamByName: + @respx.mock + def test_found(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/orgs/org/teams").respond( + json=[ + {"id": 1, "name": "ta", "permission": "write", "units": []}, + {"id": 2, "name": "students", "permission": "read", "units": []}, + ] + ) + team = client.get_team_by_name("org", "ta") + assert team is not None + assert team.id == 1 + + @respx.mock + def test_not_found(self, client: GiteaClient): + respx.get("http://gitea.test/api/v1/orgs/org/teams").respond( + json=[{"id": 1, "name": "ta", "permission": "write", "units": []}] + ) + team = client.get_team_by_name("org", "nonexistent") + assert team is None diff --git a/scripts/tests/test_commands.py b/scripts/tests/test_commands.py new file mode 100644 index 0000000..e9113ad --- /dev/null +++ b/scripts/tests/test_commands.py @@ -0,0 +1,250 @@ +"""命令集成测试: 使用 mock GiteaClient 测试 CLI 命令逻辑""" + +from __future__ import annotations + +import csv +from pathlib import Path +from unittest.mock import MagicMock, patch + +import pytest +from pydantic import HttpUrl, SecretStr +from typer.testing import CliRunner + +from tjhlp.cli import app +from tjhlp.config import GiteaConfig, LabelDef +from tjhlp.models import GiteaRepo, GiteaTeam, GiteaUser + +runner = CliRunner() + + +@pytest.fixture() +def mock_config() -> GiteaConfig: + return GiteaConfig( + url=HttpUrl("http://gitea.test"), + token=SecretStr("test-token"), + labels=[ + LabelDef(name="duplicate", color="#cfd3d7", description="重复"), + LabelDef(name="resolved", color="#0e8a16", description="已解决"), + ], + ) + + +# --------------------------------------------------------------------------- +# setup status +# --------------------------------------------------------------------------- +class TestSetupStatus: + @patch("tjhlp.commands.setup.GiteaClient") + @patch("tjhlp.commands.setup.get_gitea_config") + def test_status_ok(self, mock_get_cfg, mock_client_cls, mock_config): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_version.return_value = "1.25.5" + mock_client_cls.return_value = client + + result = runner.invoke(app, ["setup", "status"]) + assert result.exit_code == 0 + assert "1.25.5" in result.output + + +# --------------------------------------------------------------------------- +# users list +# --------------------------------------------------------------------------- +class TestUsersList: + @patch("tjhlp.commands.users.GiteaClient") + @patch("tjhlp.commands.users.get_gitea_config") + def test_list_users(self, mock_get_cfg, mock_client_cls, mock_config): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.list_users.return_value = [ + GiteaUser(id=1, login="admin", full_name="Admin", is_admin=True), + GiteaUser(id=2, login="2659999", full_name="赵一伤"), + ] + mock_client_cls.return_value = client + + result = runner.invoke(app, ["users", "list"]) + assert result.exit_code == 0 + assert "admin" in result.output + assert "2659999" in result.output + + +# --------------------------------------------------------------------------- +# users create (dry-run) +# --------------------------------------------------------------------------- +class TestUsersCreateDryRun: + def test_dry_run(self, tmp_path: Path, mock_config): + csv_file = tmp_path / "members.csv" + csv_file.write_text( + "id,name,role\n2659999,赵一伤,student\n10001,李四催,ta\n", + encoding="utf-8", + ) + + with patch("tjhlp.commands.users.get_gitea_config", return_value=mock_config): + result = runner.invoke( + app, + [ + "users", + "create", + "--file", + str(csv_file), + "--dry-run", + ], + ) + assert result.exit_code == 0 + assert "2659999" in result.output + assert "赵一伤" in result.output + + +# --------------------------------------------------------------------------- +# users create (actual) +# --------------------------------------------------------------------------- +class TestUsersCreate: + @patch("tjhlp.commands.users.GiteaClient") + @patch("tjhlp.commands.users.get_gitea_config") + def test_creates_users_and_outputs_credentials( + self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path + ): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_user.return_value = None # user doesn't exist + client.create_user.return_value = GiteaUser(id=1, login="2659999") + client.get_team_by_name.return_value = None # no org specified + mock_client_cls.return_value = client + + csv_file = tmp_path / "members.csv" + csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") + out_file = tmp_path / "creds.csv" + + result = runner.invoke( + app, + [ + "users", + "create", + "--file", + str(csv_file), + "--output", + str(out_file), + ], + ) + assert result.exit_code == 0 + assert "创建" in result.output + assert out_file.exists() + + # Verify credentials CSV + with open(out_file, encoding="utf-8") as f: + rows = list(csv.DictReader(f)) + assert len(rows) == 1 + assert rows[0]["id"] == "2659999" + assert len(rows[0]["password"]) >= 8 + + @patch("tjhlp.commands.users.GiteaClient") + @patch("tjhlp.commands.users.get_gitea_config") + def test_skips_existing_user(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_user.return_value = GiteaUser(id=1, login="2659999") # already exists + mock_client_cls.return_value = client + + csv_file = tmp_path / "members.csv" + csv_file.write_text("id,name,role\n2659999,赵一伤,student\n", encoding="utf-8") + + result = runner.invoke(app, ["users", "create", "--file", str(csv_file)]) + assert result.exit_code == 0 + assert "跳过" in result.output + client.create_user.assert_not_called() + + +# --------------------------------------------------------------------------- +# users delete +# --------------------------------------------------------------------------- +class TestUsersDelete: + @patch("tjhlp.commands.users.GiteaClient") + @patch("tjhlp.commands.users.get_gitea_config") + def test_skips_admin(self, mock_get_cfg, mock_client_cls, mock_config, tmp_path: Path): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_user.return_value = GiteaUser(id=1, login="admin", is_admin=True) + mock_client_cls.return_value = client + + csv_file = tmp_path / "members.csv" + csv_file.write_text("id,name,role\nadmin,Admin,ta\n", encoding="utf-8") + + result = runner.invoke( + app, + [ + "users", + "delete", + "--file", + str(csv_file), + "--yes", + ], + ) + assert result.exit_code == 0 + assert "管理员" in result.output + client.delete_user.assert_not_called() + + +# --------------------------------------------------------------------------- +# repos create-homework +# --------------------------------------------------------------------------- +class TestReposCreateHomework: + @patch("tjhlp.commands.repos.push_templates", return_value=2) + @patch("tjhlp.commands.repos.sync_labels", return_value=3) + @patch("tjhlp.commands.repos.GiteaClient") + @patch("tjhlp.commands.repos.get_gitea_config") + def test_creates_hw_repo( + self, mock_get_cfg, mock_client_cls, mock_sync, mock_push, mock_config + ): + mock_get_cfg.return_value = mock_config + client = MagicMock() + client.__enter__ = MagicMock(return_value=client) + client.__exit__ = MagicMock(return_value=False) + client.get_repo.return_value = None # doesn't exist + client.create_org_repo.return_value = GiteaRepo(id=1, name="hw03") + client.get_team_by_name.return_value = GiteaTeam(id=1, name="ta", permission="write") + mock_client_cls.return_value = client + + result = runner.invoke( + app, + [ + "repos", + "create-homework", + "--org", + "tjhlp-2025f", + "--number", + "3", + ], + ) + assert result.exit_code == 0 + assert "hw03" in result.output + client.create_org_repo.assert_called_once() + # Verify the repo name is hw03 + call_args = client.create_org_repo.call_args + assert call_args[0][1] == "hw03" + + +# --------------------------------------------------------------------------- +# CLI help +# --------------------------------------------------------------------------- +class TestCLIHelp: + def test_root_help(self): + result = runner.invoke(app, ["--help"]) + assert result.exit_code == 0 + assert "同济大学" in result.output + + def test_setup_help(self): + result = runner.invoke(app, ["setup", "--help"]) + assert result.exit_code == 0 + + def test_users_help(self): + result = runner.invoke(app, ["users", "--help"]) + assert result.exit_code == 0 diff --git a/scripts/tests/test_config.py b/scripts/tests/test_config.py new file mode 100644 index 0000000..fb76b5b --- /dev/null +++ b/scripts/tests/test_config.py @@ -0,0 +1,118 @@ +"""config.py 单元测试: Pydantic 模型校验""" + +from __future__ import annotations + +from typing import Any + +import pytest +from pydantic import HttpUrl, SecretStr, ValidationError + +from tjhlp.config import GiteaConfig, LabelDef, SmtpConfig + + +class TestLabelDef: + def test_valid_6_digit_hex(self): + lbl = LabelDef(name="test", color="#aabbcc") + assert lbl.color == "#aabbcc" + + def test_valid_3_digit_hex(self): + lbl = LabelDef(name="test", color="#abc") + assert lbl.color == "#abc" + + def test_strips_and_normalizes_hash(self): + lbl = LabelDef(name="test", color="aabbcc") + assert lbl.color == "#aabbcc" + + def test_uppercase_hex(self): + lbl = LabelDef(name="test", color="#AABBCC") + assert lbl.color == "#AABBCC" + + def test_invalid_hex_chars(self): + with pytest.raises(ValidationError): + LabelDef(name="test", color="#xyz123") + + def test_invalid_length_4(self): + with pytest.raises(ValidationError): + LabelDef(name="test", color="#abcd") + + def test_invalid_length_1(self): + with pytest.raises(ValidationError): + LabelDef(name="test", color="#a") + + def test_empty_color(self): + with pytest.raises(ValidationError): + LabelDef(name="test", color="") + + def test_hash_only(self): + with pytest.raises(ValidationError): + LabelDef(name="test", color="#") + + def test_default_description(self): + lbl = LabelDef(name="test", color="#abc") + assert lbl.description == "" + + def test_with_description(self): + lbl = LabelDef(name="test", color="#abc", description="A label") + assert lbl.description == "A label" + + +class TestGiteaConfig: + def test_valid(self): + cfg = GiteaConfig( + url=HttpUrl("http://localhost:3000"), + token=SecretStr("token123"), + ) + assert cfg.email_domain == "tongji.edu.cn" + assert cfg.password_length == 16 + assert cfg.labels == [] + + def test_missing_url_raises(self): + with pytest.raises(ValidationError): + kwargs: dict[str, Any] = {"token": SecretStr("token123")} + GiteaConfig(**kwargs) + + def test_missing_token_raises(self): + with pytest.raises(ValidationError): + kwargs: dict[str, Any] = {"url": HttpUrl("http://localhost:3000")} + GiteaConfig(**kwargs) + + def test_token_is_secret(self): + cfg = GiteaConfig( + url=HttpUrl("http://localhost:3000"), + token=SecretStr("secret-token"), + ) + # SecretStr hides value in repr + assert "secret-token" not in repr(cfg.token) + assert cfg.token.get_secret_value() == "secret-token" + + def test_with_labels(self): + cfg = GiteaConfig( + url=HttpUrl("http://localhost:3000"), + token=SecretStr("token"), + labels=[LabelDef(name="bug", color="#ff0000")], + ) + assert len(cfg.labels) == 1 + + +class TestSmtpConfig: + def test_valid(self): + cfg = SmtpConfig( + host="smtp.test.com", + user="user@test.com", + password=SecretStr("pass123"), + ) + assert cfg.port == 465 + assert cfg.from_addr == "" + + def test_missing_host_raises(self): + with pytest.raises(ValidationError): + kwargs: dict[str, Any] = {"user": "user", "password": SecretStr("pass")} + SmtpConfig(**kwargs) + + def test_password_is_secret(self): + cfg = SmtpConfig( + host="smtp.test.com", + user="user@test.com", + password=SecretStr("my-secret"), + ) + assert cfg.password.get_secret_value() == "my-secret" diff --git a/scripts/tests/test_models.py b/scripts/tests/test_models.py new file mode 100644 index 0000000..e360a79 --- /dev/null +++ b/scripts/tests/test_models.py @@ -0,0 +1,131 @@ +"""models.py 单元测试""" + +from __future__ import annotations + +import pytest +from pydantic import ValidationError + +from tjhlp.models import ( + CredentialRecord, + GiteaIssue, + GiteaLabel, + GiteaRepo, + GiteaUser, + MemberRecord, + MemberRole, +) + + +class TestMemberRole: + def test_valid_roles(self): + assert MemberRole("student") == MemberRole.STUDENT + assert MemberRole("ta") == MemberRole.TA + + def test_invalid_role(self): + with pytest.raises(ValueError): + MemberRole("professor") + + +class TestMemberRecord: + def test_basic_student(self): + m = MemberRecord(id="2659999", name="赵一伤", role=MemberRole.STUDENT) + assert m.id == "2659999" + assert m.name == "赵一伤" + assert m.role == MemberRole.STUDENT + + def test_computed_email(self): + m = MemberRecord(id="2659999", name="赵一伤", role=MemberRole.STUDENT) + assert m.email == "2659999@tongji.edu.cn" + + def test_computed_username(self): + m = MemberRecord(id="2659999", name="赵一伤", role=MemberRole.STUDENT) + assert m.username == "2659999" + + def test_ta_role(self): + m = MemberRecord(id="10001", name="李四催", role=MemberRole.TA) + assert m.role == MemberRole.TA + assert m.email == "10001@tongji.edu.cn" + + def test_empty_id_email(self): + """空 ID 会生成 @tongji.edu.cn 的邮箱""" + m = MemberRecord(id="", name="测试", role=MemberRole.STUDENT) + assert m.email == "@tongji.edu.cn" + + def test_invalid_role_raises(self): + with pytest.raises(ValidationError): + MemberRecord(id="123", name="测试", role="admin") # type: ignore + + def test_missing_field_raises(self): + with pytest.raises(ValidationError): + MemberRecord(id="123", name="测试") # type: ignore + + +class TestCredentialRecord: + def test_basic(self): + c = CredentialRecord( + id="2659999", + name="赵一伤", + role=MemberRole.STUDENT, + username="2659999", + password="abc123", + email="2659999@tongji.edu.cn", + ) + assert c.username == "2659999" + assert c.password == "abc123" + + def test_model_dump(self): + c = CredentialRecord( + id="2659999", + name="赵一伤", + role=MemberRole.STUDENT, + username="2659999", + password="abc123", + email="2659999@tongji.edu.cn", + ) + d = c.model_dump() + assert d["id"] == "2659999" + assert d["password"] == "abc123" + assert len(d) == 6 + + +class TestGiteaModels: + def test_gitea_user(self): + u = GiteaUser(id=1, login="admin", full_name="Admin", is_admin=True) + assert u.is_admin is True + assert u.active is True # default + + def test_gitea_user_defaults(self): + u = GiteaUser(id=1, login="student1") + assert u.full_name == "" + assert u.email == "" + assert u.is_admin is False + + def test_gitea_repo(self): + r = GiteaRepo( + id=1, name="general", full_name="tjhlp/general", html_url="http://x/tjhlp/general" + ) + assert r.private is False + + def test_gitea_label(self): + lbl = GiteaLabel(id=1, name="bug", color="#ff0000") + assert lbl.description == "" + + def test_gitea_issue_with_none_user(self): + i = GiteaIssue(id=1, number=1, title="test", user=None) + assert i.user is None + + def test_gitea_issue_with_user(self): + i = GiteaIssue( + id=1, + number=1, + title="test", + user=GiteaUser(id=1, login="student1"), + ) + assert i.user is not None + assert i.user.login == "student1" + + def test_gitea_issue_defaults(self): + i = GiteaIssue(id=1, number=1, title="test") + assert i.state == "" + assert i.labels == [] + assert i.comments == 0 diff --git a/scripts/tests/test_pure_functions.py b/scripts/tests/test_pure_functions.py new file mode 100644 index 0000000..2f17e53 --- /dev/null +++ b/scripts/tests/test_pure_functions.py @@ -0,0 +1,123 @@ +"""纯函数单元测试: 密码生成、邮件模板构建""" + +from __future__ import annotations + +from pathlib import Path + +from tjhlp.commands.notify import _build_email_text, _read_credentials_csv +from tjhlp.commands.users import _generate_password, _read_members_csv +from tjhlp.models import CredentialRecord, MemberRole + + +class TestGeneratePassword: + def test_default_length(self): + pw = _generate_password() + assert len(pw) == 12 + + def test_custom_length(self): + pw = _generate_password(16) + assert len(pw) == 16 + + def test_min_length_enforced(self): + """length < 8 should be corrected to 8""" + pw = _generate_password(4) + assert len(pw) == 8 + + def test_contains_lowercase(self): + for _ in range(20): + pw = _generate_password() + assert any(c.islower() for c in pw), f"No lowercase in: {pw}" + + def test_contains_uppercase(self): + for _ in range(20): + pw = _generate_password() + assert any(c.isupper() for c in pw), f"No uppercase in: {pw}" + + def test_contains_digit(self): + for _ in range(20): + pw = _generate_password() + assert any(c.isdigit() for c in pw), f"No digit in: {pw}" + + def test_contains_special(self): + special = set("!@#$%&*") + for _ in range(20): + pw = _generate_password() + assert any(c in special for c in pw), f"No special char in: {pw}" + + def test_randomness(self): + """多次生成不应产生相同的密码""" + passwords = {_generate_password() for _ in range(50)} + assert len(passwords) > 45 # 极低概率碰撞 + + +class TestReadMembersCsv: + def test_basic(self, tmp_path: Path): + csv_file = tmp_path / "members.csv" + csv_file.write_text( + "id,name,role\n2659999,赵一伤,student\n10001,李四催,ta\n", encoding="utf-8" + ) + + records = _read_members_csv(csv_file) + assert len(records) == 2 + assert records[0].id == "2659999" + assert records[0].role == "student" + assert records[1].role == "ta" + + def test_bom_encoding(self, tmp_path: Path): + csv_file = tmp_path / "members.csv" + csv_file.write_bytes( + b"\xef\xbb\xbfid,name,role\n2659999,\xe5\xbc\xa0\xe4\xb8\x89,student\n" + ) + + records = _read_members_csv(csv_file) + assert len(records) == 1 + assert records[0].id == "2659999" + + def test_empty_file(self, tmp_path: Path): + csv_file = tmp_path / "members.csv" + csv_file.write_text("id,name,role\n", encoding="utf-8") + + records = _read_members_csv(csv_file) + assert len(records) == 0 + + +class TestBuildEmailText: + def test_contains_fields(self): + cred = CredentialRecord( + id="2659999", + name="赵一伤", + role=MemberRole.STUDENT, + username="2659999", + password="testpass", + email="2659999@tongji.edu.cn", + ) + text = _build_email_text(cred, "http://gitea.test") + assert "赵一伤" in text + assert "2659999" in text + assert "testpass" in text + assert "http://gitea.test" in text + + def test_is_plain_text(self): + cred = CredentialRecord( + id="1", + name="test", + role=MemberRole.STUDENT, + username="1", + password="pw", + email="1@tongji.edu.cn", + ) + text = _build_email_text(cred, "http://x") + assert "" not in text + + +class TestReadCredentialsCsv: + def test_basic(self, tmp_path: Path): + csv_file = tmp_path / "creds.csv" + csv_file.write_text( + "id,name,role,username,password,email\n" + "2659999,赵一伤,student,2659999,abc123,2659999@tongji.edu.cn\n", + encoding="utf-8", + ) + records = _read_credentials_csv(csv_file) + assert len(records) == 1 + assert records[0].password == "abc123" diff --git a/scripts/tests/test_utils.py b/scripts/tests/test_utils.py new file mode 100644 index 0000000..96e3414 --- /dev/null +++ b/scripts/tests/test_utils.py @@ -0,0 +1,105 @@ +"""utils.py 单元测试: parse_repo, compute_issue_stats""" + +from __future__ import annotations + +import pytest + +from tjhlp.utils import compute_issue_stats, parse_repo + +# typer.Exit 在非 CLI 上下文中抛出 click.exceptions.Exit +_EXIT_EXCEPTIONS = (SystemExit, Exception) + + +class TestParseRepo: + def test_valid(self): + assert parse_repo("org/repo") == ("org", "repo") + + def test_valid_with_hyphens(self): + assert parse_repo("tjhlp-2025f/hw01") == ("tjhlp-2025f", "hw01") + + def test_no_slash(self): + with pytest.raises(_EXIT_EXCEPTIONS): + parse_repo("noslash") + + def test_multiple_slashes(self): + with pytest.raises(_EXIT_EXCEPTIONS): + parse_repo("a/b/c") + + def test_empty_org(self): + with pytest.raises(_EXIT_EXCEPTIONS): + parse_repo("/repo") + + def test_empty_repo(self): + with pytest.raises(_EXIT_EXCEPTIONS): + parse_repo("org/") + + def test_empty_string(self): + with pytest.raises(_EXIT_EXCEPTIONS): + parse_repo("") + + +class TestComputeIssueStats: + def test_empty_list(self): + stats = compute_issue_stats([]) + assert stats["total"] == 0 + assert stats["open"] == 0 + assert stats["closed"] == 0 + assert stats["no_reply"] == 0 + + def test_basic_counts(self): + issues = [ + {"state": "open", "comments": 0}, + {"state": "open", "comments": 2}, + {"state": "closed", "comments": 1}, + ] + stats = compute_issue_stats(issues) + assert stats["total"] == 3 + assert stats["open"] == 2 + assert stats["closed"] == 1 + assert stats["with_comments"] == 2 + assert stats["no_reply"] == 1 + + def test_label_counts(self): + issues = [ + {"state": "open", "comments": 0, "labels": [{"name": "bug"}, {"name": "紧急"}]}, + {"state": "open", "comments": 0, "labels": [{"name": "bug"}]}, + {"state": "closed", "comments": 1, "labels": []}, + ] + stats = compute_issue_stats(issues) + assert stats["label_counts"]["bug"] == 2 + assert stats["label_counts"]["紧急"] == 1 + + def test_user_counts(self): + issues = [ + {"state": "open", "comments": 0, "user": {"login": "student1"}}, + {"state": "open", "comments": 0, "user": {"login": "student1"}}, + {"state": "open", "comments": 0, "user": {"login": "student2"}}, + ] + stats = compute_issue_stats(issues) + assert stats["user_counts"]["student1"] == 2 + assert stats["user_counts"]["student2"] == 1 + + def test_missing_user(self): + issues = [ + {"state": "open", "comments": 0, "user": None}, + {"state": "open", "comments": 0}, # no user key at all + ] + stats = compute_issue_stats(issues) + assert stats["total"] == 2 + assert len(stats["user_counts"]) == 0 + + def test_missing_labels(self): + issues = [ + {"state": "open", "comments": 0}, # no labels key + ] + stats = compute_issue_stats(issues) + assert len(stats["label_counts"]) == 0 + + def test_no_reply_only_counts_open(self): + """closed issues with 0 comments should NOT count as no_reply""" + issues = [ + {"state": "closed", "comments": 0}, + {"state": "open", "comments": 0}, + ] + stats = compute_issue_stats(issues) + assert stats["no_reply"] == 1 diff --git a/scripts/uv.lock b/scripts/uv.lock new file mode 100644 index 0000000..d66e231 --- /dev/null +++ b/scripts/uv.lock @@ -0,0 +1,441 @@ +version = 1 +revision = 3 +requires-python = ">=3.14" + +[[package]] +name = "annotated-doc" +version = "0.0.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" }, +] + +[[package]] +name = "annotated-types" +version = "0.7.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ee/67/531ea369ba64dcff5ec9c3402f9f51bf748cec26dde048a2f973a4eea7f5/annotated_types-0.7.0.tar.gz", hash = "sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89", size = 16081, upload-time = "2024-05-20T21:33:25.928Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" }, +] + +[[package]] +name = "anyio" +version = "4.13.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "idna" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" }, +] + +[[package]] +name = "certifi" +version = "2026.2.25" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/af/2d/7bf41579a8986e348fa033a31cdd0e4121114f6bce2457e8876010b092dd/certifi-2026.2.25.tar.gz", hash = "sha256:e887ab5cee78ea814d3472169153c2d12cd43b14bd03329a39a9c6e2e80bfba7", size = 155029, upload-time = "2026-02-25T02:54:17.342Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9a/3c/c17fb3ca2d9c3acff52e30b309f538586f9f5b9c9cf454f3845fc9af4881/certifi-2026.2.25-py3-none-any.whl", hash = "sha256:027692e4402ad994f1c42e52a4997a9763c646b73e4096e4d5d6db8af1d6f0fa", size = 153684, upload-time = "2026-02-25T02:54:15.766Z" }, +] + +[[package]] +name = "click" +version = "8.3.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/57/75/31212c6bf2503fdf920d87fee5d7a86a2e3bcf444984126f13d8e4016804/click-8.3.2.tar.gz", hash = "sha256:14162b8b3b3550a7d479eafa77dfd3c38d9dc8951f6f69c78913a8f9a7540fd5", size = 302856, upload-time = "2026-04-03T19:14:45.118Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e4/20/71885d8b97d4f3dde17b1fdb92dbd4908b00541c5a3379787137285f602e/click-8.3.2-py3-none-any.whl", hash = "sha256:1924d2c27c5653561cd2cae4548d1406039cb79b858b747cfea24924bbc1616d", size = 108379, upload-time = "2026-04-03T19:14:43.505Z" }, +] + +[[package]] +name = "colorama" +version = "0.4.6" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" }, +] + +[[package]] +name = "coverage" +version = "7.13.5" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/9d/e0/70553e3000e345daff267cec284ce4cbf3fc141b6da229ac52775b5428f1/coverage-7.13.5.tar.gz", hash = "sha256:c81f6515c4c40141f83f502b07bbfa5c240ba25bbe73da7b33f1e5b6120ff179", size = 915967, upload-time = "2026-03-17T10:33:18.341Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8e/77/39703f0d1d4b478bfd30191d3c14f53caf596fac00efb3f8f6ee23646439/coverage-7.13.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:fbabfaceaeb587e16f7008f7795cd80d20ec548dc7f94fbb0d4ec2e038ce563f", size = 219621, upload-time = "2026-03-17T10:32:08.589Z" }, + { url = "https://files.pythonhosted.org/packages/e2/3e/51dff36d99ae14639a133d9b164d63e628532e2974d8b1edb99dd1ebc733/coverage-7.13.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:9bb2a28101a443669a423b665939381084412b81c3f8c0fcfbac57f4e30b5b8e", size = 219953, upload-time = "2026-03-17T10:32:10.507Z" }, + { url = "https://files.pythonhosted.org/packages/6a/6c/1f1917b01eb647c2f2adc9962bd66c79eb978951cab61bdc1acab3290c07/coverage-7.13.5-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:bd3a2fbc1c6cccb3c5106140d87cc6a8715110373ef42b63cf5aea29df8c217a", size = 250992, upload-time = "2026-03-17T10:32:12.41Z" }, + { url = "https://files.pythonhosted.org/packages/22/e5/06b1f88f42a5a99df42ce61208bdec3bddb3d261412874280a19796fc09c/coverage-7.13.5-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6c36ddb64ed9d7e496028d1d00dfec3e428e0aabf4006583bb1839958d280510", size = 253503, upload-time = "2026-03-17T10:32:14.449Z" }, + { url = "https://files.pythonhosted.org/packages/80/28/2a148a51e5907e504fa7b85490277734e6771d8844ebcc48764a15e28155/coverage-7.13.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:380e8e9084d8eb38db3a9176a1a4f3c0082c3806fa0dc882d1d87abc3c789247", size = 254852, upload-time = "2026-03-17T10:32:16.56Z" }, + { url = "https://files.pythonhosted.org/packages/61/77/50e8d3d85cc0b7ebe09f30f151d670e302c7ff4a1bf6243f71dd8b0981fa/coverage-7.13.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e808af52a0513762df4d945ea164a24b37f2f518cbe97e03deaa0ee66139b4d6", size = 257161, upload-time = "2026-03-17T10:32:19.004Z" }, + { url = "https://files.pythonhosted.org/packages/3b/c4/b5fd1d4b7bf8d0e75d997afd3925c59ba629fc8616f1b3aae7605132e256/coverage-7.13.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e301d30dd7e95ae068671d746ba8c34e945a82682e62918e41b2679acd2051a0", size = 251021, upload-time = "2026-03-17T10:32:21.344Z" }, + { url = "https://files.pythonhosted.org/packages/f8/66/6ea21f910e92d69ef0b1c3346ea5922a51bad4446c9126db2ae96ee24c4c/coverage-7.13.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:800bc829053c80d240a687ceeb927a94fd108bbdc68dfbe505d0d75ab578a882", size = 252858, upload-time = "2026-03-17T10:32:23.506Z" }, + { url = "https://files.pythonhosted.org/packages/9e/ea/879c83cb5d61aa2a35fb80e72715e92672daef8191b84911a643f533840c/coverage-7.13.5-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0b67af5492adb31940ee418a5a655c28e48165da5afab8c7fa6fd72a142f8740", size = 250823, upload-time = "2026-03-17T10:32:25.516Z" }, + { url = "https://files.pythonhosted.org/packages/8a/fb/616d95d3adb88b9803b275580bdeee8bd1b69a886d057652521f83d7322f/coverage-7.13.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:c9136ff29c3a91e25b1d1552b5308e53a1e0653a23e53b6366d7c2dcbbaf8a16", size = 255099, upload-time = "2026-03-17T10:32:27.944Z" }, + { url = "https://files.pythonhosted.org/packages/1c/93/25e6917c90ec1c9a56b0b26f6cad6408e5f13bb6b35d484a0d75c9cf000d/coverage-7.13.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:cff784eef7f0b8f6cb28804fbddcfa99f89efe4cc35fb5627e3ac58f91ed3ac0", size = 250638, upload-time = "2026-03-17T10:32:29.914Z" }, + { url = "https://files.pythonhosted.org/packages/fc/7b/dc1776b0464145a929deed214aef9fb1493f159b59ff3c7eeeedf91eddd0/coverage-7.13.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:68a4953be99b17ac3c23b6efbc8a38330d99680c9458927491d18700ef23ded0", size = 252295, upload-time = "2026-03-17T10:32:31.981Z" }, + { url = "https://files.pythonhosted.org/packages/ea/fb/99cbbc56a26e07762a2740713f3c8f9f3f3106e3a3dd8cc4474954bccd34/coverage-7.13.5-cp314-cp314-win32.whl", hash = "sha256:35a31f2b1578185fbe6aa2e74cea1b1d0bbf4c552774247d9160d29b80ed56cc", size = 222360, upload-time = "2026-03-17T10:32:34.233Z" }, + { url = "https://files.pythonhosted.org/packages/8d/b7/4758d4f73fb536347cc5e4ad63662f9d60ba9118cb6785e9616b2ce5d7fa/coverage-7.13.5-cp314-cp314-win_amd64.whl", hash = "sha256:2aa055ae1857258f9e0045be26a6d62bdb47a72448b62d7b55f4820f361a2633", size = 223174, upload-time = "2026-03-17T10:32:36.369Z" }, + { url = "https://files.pythonhosted.org/packages/2c/f2/24d84e1dfe70f8ac9fdf30d338239860d0d1d5da0bda528959d0ebc9da28/coverage-7.13.5-cp314-cp314-win_arm64.whl", hash = "sha256:1b11eef33edeae9d142f9b4358edb76273b3bfd30bc3df9a4f95d0e49caf94e8", size = 221739, upload-time = "2026-03-17T10:32:38.736Z" }, + { url = "https://files.pythonhosted.org/packages/60/5b/4a168591057b3668c2428bff25dd3ebc21b629d666d90bcdfa0217940e84/coverage-7.13.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:10a0c37f0b646eaff7cce1874c31d1f1ccb297688d4c747291f4f4c70741cc8b", size = 220351, upload-time = "2026-03-17T10:32:41.196Z" }, + { url = "https://files.pythonhosted.org/packages/f5/21/1fd5c4dbfe4a58b6b99649125635df46decdfd4a784c3cd6d410d303e370/coverage-7.13.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b5db73ba3c41c7008037fa731ad5459fc3944cb7452fc0aa9f822ad3533c583c", size = 220612, upload-time = "2026-03-17T10:32:43.204Z" }, + { url = "https://files.pythonhosted.org/packages/d6/fe/2a924b3055a5e7e4512655a9d4609781b0d62334fa0140c3e742926834e2/coverage-7.13.5-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:750db93a81e3e5a9831b534be7b1229df848b2e125a604fe6651e48aa070e5f9", size = 261985, upload-time = "2026-03-17T10:32:45.514Z" }, + { url = "https://files.pythonhosted.org/packages/d7/0d/c8928f2bd518c45990fe1a2ab8db42e914ef9b726c975facc4282578c3eb/coverage-7.13.5-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:9ddb4f4a5479f2539644be484da179b653273bca1a323947d48ab107b3ed1f29", size = 264107, upload-time = "2026-03-17T10:32:47.971Z" }, + { url = "https://files.pythonhosted.org/packages/ef/ae/4ae35bbd9a0af9d820362751f0766582833c211224b38665c0f8de3d487f/coverage-7.13.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d8a7a2049c14f413163e2bdabd37e41179b1d1ccb10ffc6ccc4b7a718429c607", size = 266513, upload-time = "2026-03-17T10:32:50.1Z" }, + { url = "https://files.pythonhosted.org/packages/9c/20/d326174c55af36f74eac6ae781612d9492f060ce8244b570bb9d50d9d609/coverage-7.13.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1c85e0b6c05c592ea6d8768a66a254bfb3874b53774b12d4c89c481eb78cb90", size = 267650, upload-time = "2026-03-17T10:32:52.391Z" }, + { url = "https://files.pythonhosted.org/packages/7a/5e/31484d62cbd0eabd3412e30d74386ece4a0837d4f6c3040a653878bfc019/coverage-7.13.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:777c4d1eff1b67876139d24288aaf1817f6c03d6bae9c5cc8d27b83bcfe38fe3", size = 261089, upload-time = "2026-03-17T10:32:54.544Z" }, + { url = "https://files.pythonhosted.org/packages/e9/d8/49a72d6de146eebb0b7e48cc0f4bc2c0dd858e3d4790ab2b39a2872b62bd/coverage-7.13.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6697e29b93707167687543480a40f0db8f356e86d9f67ddf2e37e2dfd91a9dab", size = 263982, upload-time = "2026-03-17T10:32:56.803Z" }, + { url = "https://files.pythonhosted.org/packages/06/3b/0351f1bd566e6e4dd39e978efe7958bde1d32f879e85589de147654f57bb/coverage-7.13.5-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:8fdf453a942c3e4d99bd80088141c4c6960bb232c409d9c3558e2dbaa3998562", size = 261579, upload-time = "2026-03-17T10:32:59.466Z" }, + { url = "https://files.pythonhosted.org/packages/5d/ce/796a2a2f4017f554d7810f5c573449b35b1e46788424a548d4d19201b222/coverage-7.13.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:32ca0c0114c9834a43f045a87dcebd69d108d8ffb666957ea65aa132f50332e2", size = 265316, upload-time = "2026-03-17T10:33:01.847Z" }, + { url = "https://files.pythonhosted.org/packages/3d/16/d5ae91455541d1a78bc90abf495be600588aff8f6db5c8b0dae739fa39c9/coverage-7.13.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8769751c10f339021e2638cd354e13adeac54004d1941119b2c96fe5276d45ea", size = 260427, upload-time = "2026-03-17T10:33:03.945Z" }, + { url = "https://files.pythonhosted.org/packages/48/11/07f413dba62db21fb3fad5d0de013a50e073cc4e2dc4306e770360f6dfc8/coverage-7.13.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:cec2d83125531bd153175354055cdb7a09987af08a9430bd173c937c6d0fba2a", size = 262745, upload-time = "2026-03-17T10:33:06.285Z" }, + { url = "https://files.pythonhosted.org/packages/91/15/d792371332eb4663115becf4bad47e047d16234b1aff687b1b18c58d60ae/coverage-7.13.5-cp314-cp314t-win32.whl", hash = "sha256:0cd9ed7a8b181775459296e402ca4fb27db1279740a24e93b3b41942ebe4b215", size = 223146, upload-time = "2026-03-17T10:33:08.756Z" }, + { url = "https://files.pythonhosted.org/packages/db/51/37221f59a111dca5e85be7dbf09696323b5b9f13ff65e0641d535ed06ea8/coverage-7.13.5-cp314-cp314t-win_amd64.whl", hash = "sha256:301e3b7dfefecaca37c9f1aa6f0049b7d4ab8dd933742b607765d757aca77d43", size = 224254, upload-time = "2026-03-17T10:33:11.174Z" }, + { url = "https://files.pythonhosted.org/packages/54/83/6acacc889de8987441aa7d5adfbdbf33d288dad28704a67e574f1df9bcbb/coverage-7.13.5-cp314-cp314t-win_arm64.whl", hash = "sha256:9dacc2ad679b292709e0f5fc1ac74a6d4d5562e424058962c7bb0c658ad25e45", size = 222276, upload-time = "2026-03-17T10:33:13.466Z" }, + { url = "https://files.pythonhosted.org/packages/9e/ee/a4cf96b8ce1e566ed238f0659ac2d3f007ed1d14b181bcb684e19561a69a/coverage-7.13.5-py3-none-any.whl", hash = "sha256:34b02417cf070e173989b3db962f7ed56d2f644307b2cf9d5a0f258e13084a61", size = 211346, upload-time = "2026-03-17T10:33:15.691Z" }, +] + +[[package]] +name = "dynaconf" +version = "3.2.13" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/57/0e/05927cf459e73f8bf9a9277cbea6f2d5b7db8a5cc9dc1e20e7a5fbac1b90/dynaconf-3.2.13.tar.gz", hash = "sha256:d79e0189d97b3f226b8ebb1717e2ce05d1a05cdf6ea05de66d24625fdb5a0cbd", size = 283507, upload-time = "2026-03-17T19:38:47.632Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/97/43/11d6e5d2c00bf000b5329717c74563bf76a9193f4a41cb0c4ef277dde4fa/dynaconf-3.2.13-py2.py3-none-any.whl", hash = "sha256:4305527aef4834bdba3e39479b23c005186e83fb85f65bcaa4bcea58fa26759b", size = 238041, upload-time = "2026-03-17T19:38:45.337Z" }, +] + +[[package]] +name = "h11" +version = "0.16.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" }, +] + +[[package]] +name = "httpcore" +version = "1.0.9" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "certifi" }, + { name = "h11" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" }, +] + +[[package]] +name = "httpx" +version = "0.28.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "certifi" }, + { name = "httpcore" }, + { name = "idna" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" }, +] + +[[package]] +name = "idna" +version = "3.11" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" }, +] + +[[package]] +name = "iniconfig" +version = "2.3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/72/34/14ca021ce8e5dfedc35312d08ba8bf51fdd999c576889fc2c24cb97f4f10/iniconfig-2.3.0.tar.gz", hash = "sha256:c76315c77db068650d49c5b56314774a7804df16fee4402c1f19d6d15d8c4730", size = 20503, upload-time = "2025-10-18T21:55:43.219Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/cb/b1/3846dd7f199d53cb17f49cba7e651e9ce294d8497c8c150530ed11865bb8/iniconfig-2.3.0-py3-none-any.whl", hash = "sha256:f631c04d2c48c52b84d0d0549c99ff3859c98df65b3101406327ecc7d53fbf12", size = 7484, upload-time = "2025-10-18T21:55:41.639Z" }, +] + +[[package]] +name = "markdown-it-py" +version = "4.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mdurl" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5b/f5/4ec618ed16cc4f8fb3b701563655a69816155e79e24a17b651541804721d/markdown_it_py-4.0.0.tar.gz", hash = "sha256:cb0a2b4aa34f932c007117b194e945bd74e0ec24133ceb5bac59009cda1cb9f3", size = 73070, upload-time = "2025-08-11T12:57:52.854Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/94/54/e7d793b573f298e1c9013b8c4dade17d481164aa517d1d7148619c2cedbf/markdown_it_py-4.0.0-py3-none-any.whl", hash = "sha256:87327c59b172c5011896038353a81343b6754500a08cd7a4973bb48c6d578147", size = 87321, upload-time = "2025-08-11T12:57:51.923Z" }, +] + +[[package]] +name = "mdurl" +version = "0.1.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, +] + +[[package]] +name = "packaging" +version = "26.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/65/ee/299d360cdc32edc7d2cf530f3accf79c4fca01e96ffc950d8a52213bd8e4/packaging-26.0.tar.gz", hash = "sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4", size = 143416, upload-time = "2026-01-21T20:50:39.064Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/b9/c538f279a4e237a006a2c98387d081e9eb060d203d8ed34467cc0f0b9b53/packaging-26.0-py3-none-any.whl", hash = "sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529", size = 74366, upload-time = "2026-01-21T20:50:37.788Z" }, +] + +[[package]] +name = "pluggy" +version = "1.6.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/f9/e2/3e91f31a7d2b083fe6ef3fa267035b518369d9511ffab804f839851d2779/pluggy-1.6.0.tar.gz", hash = "sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3", size = 69412, upload-time = "2025-05-15T12:30:07.975Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" }, +] + +[[package]] +name = "pydantic" +version = "2.12.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "annotated-types" }, + { name = "pydantic-core" }, + { name = "typing-extensions" }, + { name = "typing-inspection" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/69/44/36f1a6e523abc58ae5f928898e4aca2e0ea509b5aa6f6f392a5d882be928/pydantic-2.12.5.tar.gz", hash = "sha256:4d351024c75c0f085a9febbb665ce8c0c6ec5d30e903bdb6394b7ede26aebb49", size = 821591, upload-time = "2025-11-26T15:11:46.471Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5a/87/b70ad306ebb6f9b585f114d0ac2137d792b48be34d732d60e597c2f8465a/pydantic-2.12.5-py3-none-any.whl", hash = "sha256:e561593fccf61e8a20fc46dfc2dfe075b8be7d0188df33f221ad1f0139180f9d", size = 463580, upload-time = "2025-11-26T15:11:44.605Z" }, +] + +[[package]] +name = "pydantic-core" +version = "2.41.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/71/70/23b021c950c2addd24ec408e9ab05d59b035b39d97cdc1130e1bce647bb6/pydantic_core-2.41.5.tar.gz", hash = "sha256:08daa51ea16ad373ffd5e7606252cc32f07bc72b28284b6bc9c6df804816476e", size = 460952, upload-time = "2025-11-04T13:43:49.098Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ea/28/46b7c5c9635ae96ea0fbb779e271a38129df2550f763937659ee6c5dbc65/pydantic_core-2.41.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:3f37a19d7ebcdd20b96485056ba9e8b304e27d9904d233d7b1015db320e51f0a", size = 2119622, upload-time = "2025-11-04T13:40:56.68Z" }, + { url = "https://files.pythonhosted.org/packages/74/1a/145646e5687e8d9a1e8d09acb278c8535ebe9e972e1f162ed338a622f193/pydantic_core-2.41.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d1d9764366c73f996edd17abb6d9d7649a7eb690006ab6adbda117717099b14", size = 1891725, upload-time = "2025-11-04T13:40:58.807Z" }, + { url = "https://files.pythonhosted.org/packages/23/04/e89c29e267b8060b40dca97bfc64a19b2a3cf99018167ea1677d96368273/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e1c2af0fce638d5f1988b686f3b3ea8cd7de5f244ca147c777769e798a9cd1", size = 1915040, upload-time = "2025-11-04T13:41:00.853Z" }, + { url = "https://files.pythonhosted.org/packages/84/a3/15a82ac7bd97992a82257f777b3583d3e84bdb06ba6858f745daa2ec8a85/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:506d766a8727beef16b7adaeb8ee6217c64fc813646b424d0804d67c16eddb66", size = 2063691, upload-time = "2025-11-04T13:41:03.504Z" }, + { url = "https://files.pythonhosted.org/packages/74/9b/0046701313c6ef08c0c1cf0e028c67c770a4e1275ca73131563c5f2a310a/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4819fa52133c9aa3c387b3328f25c1facc356491e6135b459f1de698ff64d869", size = 2213897, upload-time = "2025-11-04T13:41:05.804Z" }, + { url = "https://files.pythonhosted.org/packages/8a/cd/6bac76ecd1b27e75a95ca3a9a559c643b3afcd2dd62086d4b7a32a18b169/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2b761d210c9ea91feda40d25b4efe82a1707da2ef62901466a42492c028553a2", size = 2333302, upload-time = "2025-11-04T13:41:07.809Z" }, + { url = "https://files.pythonhosted.org/packages/4c/d2/ef2074dc020dd6e109611a8be4449b98cd25e1b9b8a303c2f0fca2f2bcf7/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:22f0fb8c1c583a3b6f24df2470833b40207e907b90c928cc8d3594b76f874375", size = 2064877, upload-time = "2025-11-04T13:41:09.827Z" }, + { url = "https://files.pythonhosted.org/packages/18/66/e9db17a9a763d72f03de903883c057b2592c09509ccfe468187f2a2eef29/pydantic_core-2.41.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c870e99878c634505236d81e5443092fba820f0373997ff75f90f68cd553", size = 2180680, upload-time = "2025-11-04T13:41:12.379Z" }, + { url = "https://files.pythonhosted.org/packages/d3/9e/3ce66cebb929f3ced22be85d4c2399b8e85b622db77dad36b73c5387f8f8/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0177272f88ab8312479336e1d777f6b124537d47f2123f89cb37e0accea97f90", size = 2138960, upload-time = "2025-11-04T13:41:14.627Z" }, + { url = "https://files.pythonhosted.org/packages/a6/62/205a998f4327d2079326b01abee48e502ea739d174f0a89295c481a2272e/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:63510af5e38f8955b8ee5687740d6ebf7c2a0886d15a6d65c32814613681bc07", size = 2339102, upload-time = "2025-11-04T13:41:16.868Z" }, + { url = "https://files.pythonhosted.org/packages/3c/0d/f05e79471e889d74d3d88f5bd20d0ed189ad94c2423d81ff8d0000aab4ff/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:e56ba91f47764cc14f1daacd723e3e82d1a89d783f0f5afe9c364b8bb491ccdb", size = 2326039, upload-time = "2025-11-04T13:41:18.934Z" }, + { url = "https://files.pythonhosted.org/packages/ec/e1/e08a6208bb100da7e0c4b288eed624a703f4d129bde2da475721a80cab32/pydantic_core-2.41.5-cp314-cp314-win32.whl", hash = "sha256:aec5cf2fd867b4ff45b9959f8b20ea3993fc93e63c7363fe6851424c8a7e7c23", size = 1995126, upload-time = "2025-11-04T13:41:21.418Z" }, + { url = "https://files.pythonhosted.org/packages/48/5d/56ba7b24e9557f99c9237e29f5c09913c81eeb2f3217e40e922353668092/pydantic_core-2.41.5-cp314-cp314-win_amd64.whl", hash = "sha256:8e7c86f27c585ef37c35e56a96363ab8de4e549a95512445b85c96d3e2f7c1bf", size = 2015489, upload-time = "2025-11-04T13:41:24.076Z" }, + { url = "https://files.pythonhosted.org/packages/4e/bb/f7a190991ec9e3e0ba22e4993d8755bbc4a32925c0b5b42775c03e8148f9/pydantic_core-2.41.5-cp314-cp314-win_arm64.whl", hash = "sha256:e672ba74fbc2dc8eea59fb6d4aed6845e6905fc2a8afe93175d94a83ba2a01a0", size = 1977288, upload-time = "2025-11-04T13:41:26.33Z" }, + { url = "https://files.pythonhosted.org/packages/92/ed/77542d0c51538e32e15afe7899d79efce4b81eee631d99850edc2f5e9349/pydantic_core-2.41.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8566def80554c3faa0e65ac30ab0932b9e3a5cd7f8323764303d468e5c37595a", size = 2120255, upload-time = "2025-11-04T13:41:28.569Z" }, + { url = "https://files.pythonhosted.org/packages/bb/3d/6913dde84d5be21e284439676168b28d8bbba5600d838b9dca99de0fad71/pydantic_core-2.41.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b80aa5095cd3109962a298ce14110ae16b8c1aece8b72f9dafe81cf597ad80b3", size = 1863760, upload-time = "2025-11-04T13:41:31.055Z" }, + { url = "https://files.pythonhosted.org/packages/5a/f0/e5e6b99d4191da102f2b0eb9687aaa7f5bea5d9964071a84effc3e40f997/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3006c3dd9ba34b0c094c544c6006cc79e87d8612999f1a5d43b769b89181f23c", size = 1878092, upload-time = "2025-11-04T13:41:33.21Z" }, + { url = "https://files.pythonhosted.org/packages/71/48/36fb760642d568925953bcc8116455513d6e34c4beaa37544118c36aba6d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72f6c8b11857a856bcfa48c86f5368439f74453563f951e473514579d44aa612", size = 2053385, upload-time = "2025-11-04T13:41:35.508Z" }, + { url = "https://files.pythonhosted.org/packages/20/25/92dc684dd8eb75a234bc1c764b4210cf2646479d54b47bf46061657292a8/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5cb1b2f9742240e4bb26b652a5aeb840aa4b417c7748b6f8387927bc6e45e40d", size = 2218832, upload-time = "2025-11-04T13:41:37.732Z" }, + { url = "https://files.pythonhosted.org/packages/e2/09/f53e0b05023d3e30357d82eb35835d0f6340ca344720a4599cd663dca599/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3d54f38609ff308209bd43acea66061494157703364ae40c951f83ba99a1a9", size = 2327585, upload-time = "2025-11-04T13:41:40Z" }, + { url = "https://files.pythonhosted.org/packages/aa/4e/2ae1aa85d6af35a39b236b1b1641de73f5a6ac4d5a7509f77b814885760c/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2ff4321e56e879ee8d2a879501c8e469414d948f4aba74a2d4593184eb326660", size = 2041078, upload-time = "2025-11-04T13:41:42.323Z" }, + { url = "https://files.pythonhosted.org/packages/cd/13/2e215f17f0ef326fc72afe94776edb77525142c693767fc347ed6288728d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d0d2568a8c11bf8225044aa94409e21da0cb09dcdafe9ecd10250b2baad531a9", size = 2173914, upload-time = "2025-11-04T13:41:45.221Z" }, + { url = "https://files.pythonhosted.org/packages/02/7a/f999a6dcbcd0e5660bc348a3991c8915ce6599f4f2c6ac22f01d7a10816c/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:a39455728aabd58ceabb03c90e12f71fd30fa69615760a075b9fec596456ccc3", size = 2129560, upload-time = "2025-11-04T13:41:47.474Z" }, + { url = "https://files.pythonhosted.org/packages/3a/b1/6c990ac65e3b4c079a4fb9f5b05f5b013afa0f4ed6780a3dd236d2cbdc64/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:239edca560d05757817c13dc17c50766136d21f7cd0fac50295499ae24f90fdf", size = 2329244, upload-time = "2025-11-04T13:41:49.992Z" }, + { url = "https://files.pythonhosted.org/packages/d9/02/3c562f3a51afd4d88fff8dffb1771b30cfdfd79befd9883ee094f5b6c0d8/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:2a5e06546e19f24c6a96a129142a75cee553cc018ffee48a460059b1185f4470", size = 2331955, upload-time = "2025-11-04T13:41:54.079Z" }, + { url = "https://files.pythonhosted.org/packages/5c/96/5fb7d8c3c17bc8c62fdb031c47d77a1af698f1d7a406b0f79aaa1338f9ad/pydantic_core-2.41.5-cp314-cp314t-win32.whl", hash = "sha256:b4ececa40ac28afa90871c2cc2b9ffd2ff0bf749380fbdf57d165fd23da353aa", size = 1988906, upload-time = "2025-11-04T13:41:56.606Z" }, + { url = "https://files.pythonhosted.org/packages/22/ed/182129d83032702912c2e2d8bbe33c036f342cc735737064668585dac28f/pydantic_core-2.41.5-cp314-cp314t-win_amd64.whl", hash = "sha256:80aa89cad80b32a912a65332f64a4450ed00966111b6615ca6816153d3585a8c", size = 1981607, upload-time = "2025-11-04T13:41:58.889Z" }, + { url = "https://files.pythonhosted.org/packages/9f/ed/068e41660b832bb0b1aa5b58011dea2a3fe0ba7861ff38c4d4904c1c1a99/pydantic_core-2.41.5-cp314-cp314t-win_arm64.whl", hash = "sha256:35b44f37a3199f771c3eaa53051bc8a70cd7b54f333531c59e29fd4db5d15008", size = 1974769, upload-time = "2025-11-04T13:42:01.186Z" }, +] + +[[package]] +name = "pygments" +version = "2.20.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" }, +] + +[[package]] +name = "pytest" +version = "9.0.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "iniconfig" }, + { name = "packaging" }, + { name = "pluggy" }, + { name = "pygments" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/7d/0d/549bd94f1a0a402dc8cf64563a117c0f3765662e2e668477624baeec44d5/pytest-9.0.3.tar.gz", hash = "sha256:b86ada508af81d19edeb213c681b1d48246c1a91d304c6c81a427674c17eb91c", size = 1572165, upload-time = "2026-04-07T17:16:18.027Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d4/24/a372aaf5c9b7208e7112038812994107bc65a84cd00e0354a88c2c77a617/pytest-9.0.3-py3-none-any.whl", hash = "sha256:2c5efc453d45394fdd706ade797c0a81091eccd1d6e4bccfcd476e2b8e0ab5d9", size = 375249, upload-time = "2026-04-07T17:16:16.13Z" }, +] + +[[package]] +name = "pytest-cov" +version = "7.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "coverage" }, + { name = "pluggy" }, + { name = "pytest" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b1/51/a849f96e117386044471c8ec2bd6cfebacda285da9525c9106aeb28da671/pytest_cov-7.1.0.tar.gz", hash = "sha256:30674f2b5f6351aa09702a9c8c364f6a01c27aae0c1366ae8016160d1efc56b2", size = 55592, upload-time = "2026-03-21T20:11:16.284Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" }, +] + +[[package]] +name = "pytest-mock" +version = "3.15.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pytest" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/68/14/eb014d26be205d38ad5ad20d9a80f7d201472e08167f0bb4361e251084a9/pytest_mock-3.15.1.tar.gz", hash = "sha256:1849a238f6f396da19762269de72cb1814ab44416fa73a8686deac10b0d87a0f", size = 34036, upload-time = "2025-09-16T16:37:27.081Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5a/cc/06253936f4a7fa2e0f48dfe6d851d9c56df896a9ab09ac019d70b760619c/pytest_mock-3.15.1-py3-none-any.whl", hash = "sha256:0a25e2eb88fe5168d535041d09a4529a188176ae608a6d249ee65abc0949630d", size = 10095, upload-time = "2025-09-16T16:37:25.734Z" }, +] + +[[package]] +name = "respx" +version = "0.23.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "httpx" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/43/98/4e55c9c486404ec12373708d015ebce157966965a5ebe7f28ff2c784d41b/respx-0.23.1.tar.gz", hash = "sha256:242dcc6ce6b5b9bf621f5870c82a63997e8e82bc7c947f9ffe272b8f3dd5a780", size = 29243, upload-time = "2026-04-08T14:37:16.008Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1d/4a/221da6ca167db45693d8d26c7dc79ccfc978a440251bf6721c9aaf251ac0/respx-0.23.1-py2.py3-none-any.whl", hash = "sha256:b18004b029935384bccfa6d7d9d74b4ec9af73a081cc28600fffc0447f4b8c1a", size = 25557, upload-time = "2026-04-08T14:37:14.613Z" }, +] + +[[package]] +name = "rich" +version = "14.3.4" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown-it-py" }, + { name = "pygments" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/e9/67/cae617f1351490c25a4b8ac3b8b63a4dda609295d8222bad12242dfdc629/rich-14.3.4.tar.gz", hash = "sha256:817e02727f2b25b40ef56f5aa2217f400c8489f79ca8f46ea2b70dd5e14558a9", size = 230524, upload-time = "2026-04-11T02:57:45.419Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b3/76/6d163cfac87b632216f71879e6b2cf17163f773ff59c00b5ff4900a80fa3/rich-14.3.4-py3-none-any.whl", hash = "sha256:07e7adb4690f68864777b1450859253bed81a99a31ac321ac1817b2313558952", size = 310480, upload-time = "2026-04-11T02:57:47.484Z" }, +] + +[[package]] +name = "ruff" +version = "0.15.10" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e7/d9/aa3f7d59a10ef6b14fe3431706f854dbf03c5976be614a9796d36326810c/ruff-0.15.10.tar.gz", hash = "sha256:d1f86e67ebfdef88e00faefa1552b5e510e1d35f3be7d423dc7e84e63788c94e", size = 4631728, upload-time = "2026-04-09T14:06:09.884Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/eb/00/a1c2fdc9939b2c03691edbda290afcd297f1f389196172826b03d6b6a595/ruff-0.15.10-py3-none-linux_armv6l.whl", hash = "sha256:0744e31482f8f7d0d10a11fcbf897af272fefdfcb10f5af907b18c2813ff4d5f", size = 10563362, upload-time = "2026-04-09T14:06:21.189Z" }, + { url = "https://files.pythonhosted.org/packages/5c/15/006990029aea0bebe9d33c73c3e28c80c391ebdba408d1b08496f00d422d/ruff-0.15.10-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:b1e7c16ea0ff5a53b7c2df52d947e685973049be1cdfe2b59a9c43601897b22e", size = 10951122, upload-time = "2026-04-09T14:06:02.236Z" }, + { url = "https://files.pythonhosted.org/packages/f2/c0/4ac978fe874d0618c7da647862afe697b281c2806f13ce904ad652fa87e4/ruff-0.15.10-py3-none-macosx_11_0_arm64.whl", hash = "sha256:93cc06a19e5155b4441dd72808fdf84290d84ad8a39ca3b0f994363ade4cebb1", size = 10314005, upload-time = "2026-04-09T14:06:00.026Z" }, + { url = "https://files.pythonhosted.org/packages/da/73/c209138a5c98c0d321266372fc4e33ad43d506d7e5dd817dd89b60a8548f/ruff-0.15.10-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:83e1dd04312997c99ea6965df66a14fb4f03ba978564574ffc68b0d61fd3989e", size = 10643450, upload-time = "2026-04-09T14:05:42.137Z" }, + { url = "https://files.pythonhosted.org/packages/ec/76/0deec355d8ec10709653635b1f90856735302cb8e149acfdf6f82a5feb70/ruff-0.15.10-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8154d43684e4333360fedd11aaa40b1b08a4e37d8ffa9d95fee6fa5b37b6fab1", size = 10379597, upload-time = "2026-04-09T14:05:49.984Z" }, + { url = "https://files.pythonhosted.org/packages/dc/be/86bba8fc8798c081e28a4b3bb6d143ccad3fd5f6f024f02002b8f08a9fa3/ruff-0.15.10-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:8ab88715f3a6deb6bde6c227f3a123410bec7b855c3ae331b4c006189e895cef", size = 11146645, upload-time = "2026-04-09T14:06:12.246Z" }, + { url = "https://files.pythonhosted.org/packages/a8/89/140025e65911b281c57be1d385ba1d932c2366ca88ae6663685aed8d4881/ruff-0.15.10-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a768ff5969b4f44c349d48edf4ab4f91eddb27fd9d77799598e130fb628aa158", size = 12030289, upload-time = "2026-04-09T14:06:04.776Z" }, + { url = "https://files.pythonhosted.org/packages/88/de/ddacca9545a5e01332567db01d44bd8cf725f2db3b3d61a80550b48308ea/ruff-0.15.10-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0ee3ef42dab7078bda5ff6a1bcba8539e9857deb447132ad5566a038674540d0", size = 11496266, upload-time = "2026-04-09T14:05:55.485Z" }, + { url = "https://files.pythonhosted.org/packages/bc/bb/7ddb00a83760ff4a83c4e2fc231fd63937cc7317c10c82f583302e0f6586/ruff-0.15.10-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51cb8cc943e891ba99989dd92d61e29b1d231e14811db9be6440ecf25d5c1609", size = 11256418, upload-time = "2026-04-09T14:05:57.69Z" }, + { url = "https://files.pythonhosted.org/packages/dc/8d/55de0d35aacf6cd50b6ee91ee0f291672080021896543776f4170fc5c454/ruff-0.15.10-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:e59c9bdc056a320fb9ea1700a8d591718b8faf78af065484e801258d3a76bc3f", size = 11288416, upload-time = "2026-04-09T14:05:44.695Z" }, + { url = "https://files.pythonhosted.org/packages/68/cf/9438b1a27426ec46a80e0a718093c7f958ef72f43eb3111862949ead3cc1/ruff-0.15.10-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:136c00ca2f47b0018b073f28cb5c1506642a830ea941a60354b0e8bc8076b151", size = 10621053, upload-time = "2026-04-09T14:05:52.782Z" }, + { url = "https://files.pythonhosted.org/packages/4c/50/e29be6e2c135e9cd4cb15fbade49d6a2717e009dff3766dd080fcb82e251/ruff-0.15.10-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8b80a2f3c9c8a950d6237f2ca12b206bccff626139be9fa005f14feb881a1ae8", size = 10378302, upload-time = "2026-04-09T14:06:14.361Z" }, + { url = "https://files.pythonhosted.org/packages/18/2f/e0b36a6f99c51bb89f3a30239bc7bf97e87a37ae80aa2d6542d6e5150364/ruff-0.15.10-py3-none-musllinux_1_2_i686.whl", hash = "sha256:e3e53c588164dc025b671c9df2462429d60357ea91af7e92e9d56c565a9f1b07", size = 10850074, upload-time = "2026-04-09T14:06:16.581Z" }, + { url = "https://files.pythonhosted.org/packages/11/08/874da392558ce087a0f9b709dc6ec0d60cbc694c1c772dab8d5f31efe8cb/ruff-0.15.10-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b0c52744cf9f143a393e284125d2576140b68264a93c6716464e129a3e9adb48", size = 11358051, upload-time = "2026-04-09T14:06:18.948Z" }, + { url = "https://files.pythonhosted.org/packages/e4/46/602938f030adfa043e67112b73821024dc79f3ab4df5474c25fa4c1d2d14/ruff-0.15.10-py3-none-win32.whl", hash = "sha256:d4272e87e801e9a27a2e8df7b21011c909d9ddd82f4f3281d269b6ba19789ca5", size = 10588964, upload-time = "2026-04-09T14:06:07.14Z" }, + { url = "https://files.pythonhosted.org/packages/25/b6/261225b875d7a13b33a6d02508c39c28450b2041bb01d0f7f1a83d569512/ruff-0.15.10-py3-none-win_amd64.whl", hash = "sha256:28cb32d53203242d403d819fd6983152489b12e4a3ae44993543d6fe62ab42ed", size = 11745044, upload-time = "2026-04-09T14:05:39.473Z" }, + { url = "https://files.pythonhosted.org/packages/58/ed/dea90a65b7d9e69888890fb14c90d7f51bf0c1e82ad800aeb0160e4bacfd/ruff-0.15.10-py3-none-win_arm64.whl", hash = "sha256:601d1610a9e1f1c2165a4f561eeaa2e2ea1e97f3287c5aa258d3dab8b57c6188", size = 11035607, upload-time = "2026-04-09T14:05:47.593Z" }, +] + +[[package]] +name = "shellingham" +version = "1.5.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" }, +] + +[[package]] +name = "tjhlp" +version = "0.1.0" +source = { editable = "." } +dependencies = [ + { name = "dynaconf" }, + { name = "httpx" }, + { name = "pydantic" }, + { name = "rich" }, + { name = "typer" }, +] + +[package.optional-dependencies] +dev = [ + { name = "pytest" }, + { name = "pytest-cov" }, + { name = "pytest-mock" }, + { name = "respx" }, + { name = "ruff" }, +] + +[package.metadata] +requires-dist = [ + { name = "dynaconf", specifier = ">=3.2" }, + { name = "httpx", specifier = ">=0.28" }, + { name = "pydantic", specifier = ">=2.10" }, + { name = "pytest", marker = "extra == 'dev'", specifier = ">=8" }, + { name = "pytest-cov", marker = "extra == 'dev'" }, + { name = "pytest-mock", marker = "extra == 'dev'" }, + { name = "respx", marker = "extra == 'dev'", specifier = ">=0.22" }, + { name = "rich", specifier = ">=14" }, + { name = "ruff", marker = "extra == 'dev'" }, + { name = "typer", specifier = ">=0.15" }, +] +provides-extras = ["dev"] + +[[package]] +name = "typer" +version = "0.24.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "annotated-doc" }, + { name = "click" }, + { name = "rich" }, + { name = "shellingham" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f5/24/cb09efec5cc954f7f9b930bf8279447d24618bb6758d4f6adf2574c41780/typer-0.24.1.tar.gz", hash = "sha256:e39b4732d65fbdcde189ae76cf7cd48aeae72919dea1fdfc16593be016256b45", size = 118613, upload-time = "2026-02-21T16:54:40.609Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/4a/91/48db081e7a63bb37284f9fbcefda7c44c277b18b0e13fbc36ea2335b71e6/typer-0.24.1-py3-none-any.whl", hash = "sha256:112c1f0ce578bfb4cab9ffdabc68f031416ebcc216536611ba21f04e9aa84c9e", size = 56085, upload-time = "2026-02-21T16:54:41.616Z" }, +] + +[[package]] +name = "typing-extensions" +version = "4.15.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" }, +] + +[[package]] +name = "typing-inspection" +version = "0.4.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "typing-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" }, +]