Metadata-Version: 2.1
Name: symbol-tool
Version: 1.4.2.0
Summary: 符号管理工具
Author-email: Vorga <qiujuncheng@up3dtech.com>
Project-URL: Homepage, http://www.vorga.cn:8081/up3d/software/tool/symbol-tool
Keywords: up3d,symbol,tool
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev

# symbol-tool

用于管理符号文件仓库的命令行工具。

## 1.4.2.0

- 每条删除结果前显示 `[已处理数/本次总数]`，例如 `[1/100]`；失败也计入已处理数。
- 并行删除的进度按结果输出顺序递增，本次总数为查询实际返回的文件数。

## 1.4.1.0

- `delete` 查询一次后最多并行执行 16 个删除请求，不再显示查询结果及时间信息。
- 单个删除请求发生 HTTP 或网络错误时继续处理其余文件，最终返回非零退出码。
- `query` 命令保持原有输出及筛选行为。

## 1.4.0.0

- 移除旧 `clean` 命令，改用与 `query` 参数完全相同的 `delete`，删除查询返回的文件。
- `query` 和 `delete` 默认最多处理 100 个文件，可通过 `--limit` 调整。

## 1.3.0.0

- 命令语法参考 Conan：文件模式作为位置参数，使用 `-r/--remote` 选择仓库。
- `transfer` 使用 `-r <源> --remote-to <目标>`，`remote add` 使用名称及 URL 位置参数。
- 不再兼容旧上传 `-p/--pattern`、`-t/--target`、迁移 `-s/--source`、
  名称筛选 `-n/--name`、`-nn/--nname`、时间筛选 `-cb/-ub` 及
  `remote add --url`；查询仍保留 `-p/--path`。
- `--help`、`--version` 和参数解析不读取或下载配置。

## 1.2.0.1

- 移除安装包内置凭据；本地 JSON 不存在时从内网 tool 仓库下载默认配置，已有配置保持不变。

## 1.2.0.0

- 新增 `upload --dry-run`：检查并列出待上传符号文件，不执行实际上传。

## 快速开始

```bash
pip install -e .
symbol-tool --version
```

## 打包

```bash
pyinstaller symbol_tool.spec --clean
```

## 命令示例

```bash
symbol-tool upload ".\**\*.pdb" -r local --dry-run
symbol-tool upload ".\**\*.pdb" --remote denture
symbol-tool query "*.pdb" -r local --exclude "UP*" --created-before 180d
symbol-tool query -r local --path "*/release/*" --limit 20
symbol-tool fix -r local
symbol-tool transfer "*.pdb" -r local --remote-to denture
symbol-tool delete -r local --exclude "UP*"
symbol-tool delete -r local --created-before 365d
symbol-tool remote list
symbol-tool remote add office http://repo/artifactory --repo symbol-office
symbol-tool remote disable office
symbol-tool remote enable office
symbol-tool remote remove office
```

`upload` 必须提供本地文件模式。`query`、`delete` 和 `transfer` 的符号名称模式可省略，
省略时不过滤名称；`--exclude` 排除匹配的名称。模式应加引号，避免 shell 展开。
`transfer --delete-old` 仍保持原语义：目标已存在时删除源文件。
`remote add` 必须提供名称和 URL；仓库、用户名和密码未通过选项提供时交互输入。
密码输入隐藏，不建议通过 `--password` 将真实密码写入命令历史。

`delete` 先执行与 `query` 相同的查询，再删除返回的文件，不删除整个仓库或父目录。
查询只执行一次，不显示查询结果列表及时间信息；`query` 命令仍显示完整结果。
删除最多并行执行 16 个请求，并限制待处理任务数；逐文件输出删除结果，输出顺序不固定。
每条结果前显示进度，例如 `[1/100]`；已处理数包含成功和失败，总数为本次查询返回的文件数。
这是直接删除操作，没有确认提示；执行前应先用相同参数运行 `query` 核对范围。
不加筛选条件会删除查询返回的所有文件。默认最多处理 100 个文件，
可用 `--limit` 调整查询及删除的文件数；不会自动循环处理后续批次。
名称、排除名称、路径及时间条件同时生效；`--created-before` 按创建时间、
`--updated-before` 按更新时间筛选。删除失败输出 HTTP 状态并返回非零退出码，
网络请求失败也会输出错误，继续处理其余文件并返回非零退出码。
查询失败也报错，不将服务端错误视为空结果。

`upload --dry-run` 使用与实际上传相同的 glob 匹配和符号文件解析，
计算符号索引并通过只读 HEAD 请求检查远端是否已存在。
未存在的有效文件输出 `Would upload: <本地文件> -> <目标地址>`，
已存在或无效文件仍输出跳过原因。检查失败（例如 HTTP 401、403、500）
会输出 `Check failed`，不会误报为待上传文件。
此模式需要网络和目标访问权限，但不会发送 PUT 上传请求，也不会修改本地符号文件。
不指定 `--dry-run` 时保持原有上传行为。

`target` 是别名。每个别名对应“某个服务器 + 某个路径”，配置保存在
`~\.symbol-tool\remote.json`，凭据仍以 JSON 字段存储。

本地 JSON 不存在时，首次运行自动从以下内网地址下载默认配置并保存；
已有本地 JSON 不会被下载内容覆盖，也不会自动合并或刷新：

```text
http://artifactory:8082/artifactory/tool/symbol-tool/remote.json
```

安装包不再内置默认用户名和密码。下载设置连接与读取超时，HTTP 错误、
网络错误及无效 JSON 均明确报错，不回退到内置凭据，也不保存无效下载内容。
离线使用前须预先准备本地 JSON。可通过 `symbol-tool remote` 子命令管理配置。

此地址使用明文 HTTP，配置包含密码；能访问该文件的用户可获得其中的凭据，
网络监听也可能暴露凭据。内网地址不构成加密或身份验证，请限制仓库访问和
本地 JSON 的读取权限，勿将配置或其内容纳入源码、安装包及日志。

## 测试

```bash
pytest tests
```

## 发布到 PyPI

```bash
python -m pip install --upgrade build twine
python -m build .
python -m twine upload --repository-url ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/pypi dist/*
```

CI 在所有分支及合并请求中运行 `pytest tests`。仅默认主分支在测试通过后
构建并上传到 GitLab PyPI 软件包仓库；其他分支只运行测试，不构建发布包、
不上传。标签不触发此流水线。合并请求存在时，推送只运行合并请求流水线，
避免重复测试。主分支上传同样受测试结果约束，测试失败不会发布。

发布任务中配置：
- `TWINE_USERNAME=gitlab-ci-token`
- `TWINE_PASSWORD=$CI_JOB_TOKEN`
