Metadata-Version: 2.4
Name: wcp32-client
Version: 0.1.1
Summary: A typed, read-only Python client for WCP 3.2.x knowledge management systems.
Project-URL: WCP upstream, https://gitee.com/macplus/WCP
Author: WCP32 Client Contributors
License: MIT License
        
        Copyright (c) 2026 WCP32 Client Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: client,knowledge-management,sdk,wcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: requests<3,>=2.31
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: responses>=0.25; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5; extra == 'dev'
Requires-Dist: types-requests>=2.31; extra == 'dev'
Description-Content-Type: text/markdown

# wcp32-client

`wcp32-client` 是面向太原扁舟 WCP 3.2.x 知识管理系统的同步、只读 Python
客户端。它封装了 WCP 旧版的 JSESSIONID 登录、后台 EasyUI JSON 接口、前台
HTML 文档页和附件下载地址。

> 该项目不是 WCP 官方 SDK。首个验收版本以 WCP 3.2.0 为基线，不兼容 WCP5。

## 安装

```bash
python -m pip install wcp32-client
```

从源码安装：

```bash
python -m pip install .
```

## 快速开始

```python
from wcp32 import WcpClient

with WcpClient("https://wcp.example.com/") as client:
    client.login("username", "password")

    for category in client.categories.iter_all():
        print(category.id, category.name)

    page = client.documents.list(category_id="分类ID", page_size=100)
    for document in page.items:
        print(document.id, document.title)

    content = client.documents.get_content("文档ID")
    print(content.text)

    for attachment in client.attachments.list("文档ID"):
        print(attachment.name, attachment.size)

    current_user = client.users.me()
    print(current_user.id, current_user.name)
```

凭据只在运行时传给 `login()`；请勿把账号、密码或 JSESSIONID 写入源码。

## API

### 分类

```python
roots = client.categories.list()
children = client.categories.list(parent_id="父分类ID")
category = client.categories.get("分类ID")
tree = client.categories.tree()
all_categories = list(client.categories.iter_all())
```

### 文档

```python
page = client.documents.list(
    category_id="分类ID",
    page=1,
    page_size=100,
    recursive=False,
)

all_documents = list(
    client.documents.iter("分类ID", recursive=True, page_size=100)
)

document = client.documents.get("文档ID")
html_content = client.documents.get_content("文档ID", format="html")
text_content = client.documents.get_content("文档ID", format="text")
versions = client.documents.versions("文档ID")
```

`recursive=False` 只查询当前分类。开启递归后，客户端遍历后代分类并按文档 ID
去重。

### 附件

```python
attachments = client.attachments.list("文档ID")
attachment = client.attachments.get("附件ID")

data = client.attachments.read("附件ID", max_bytes=10 * 1024 * 1024)

for chunk in client.attachments.iter_bytes("附件ID"):
    process(chunk)

saved_path = client.attachments.download(
    "附件ID",
    "downloads/report.pdf",
    overwrite=False,
)
```

`download()` 默认不覆盖文件，并使用临时文件完成原子替换。

### 用户和搜索

```python
users = client.users.list(page=1, page_size=100)
user = client.users.get("用户ID")
me = client.users.me()
user_documents = client.users.documents("用户ID")

results = client.search.documents("关键词", page=1)
```

用户后台接口通常需要管理员权限。权限不足会抛出
`WcpPermissionError`，不会返回伪造的空列表。

### 原始只读请求

```python
response = client.raw.get("home/PubrecommendServiceList.do")
payload = response.json()
```

`raw` 只提供 GET，不暴露通用 POST/PUT/DELETE。

## 返回模型

列表接口返回 `Page[T]`，其中包含：

- `items`：类型模型列表；
- `total`：服务端报告的总数；
- `page`、`page_size`；
- `raw`：WCP 原始响应字段。

`Category`、`Document`、`Attachment`、`User` 等模型也保留 `raw`，用于访问尚未
标准化的旧版字段。

## 异常

- `WcpAuthenticationError`：登录失败或会话失效；
- `WcpPermissionError`：当前账号没有后台接口权限；
- `WcpNotFoundError`：文档、分类、附件或用户不存在；
- `WcpTransportError`：超时、连接失败或 HTTP 错误；
- `WcpParseError`：WCP 页面/JSON 结构与预期不符；
- `WcpVersionError`：检测到不兼容的服务器版本。

## 代理、TLS 和超时

```python
client = WcpClient(
    "https://wcp.example.com/",
    timeout=30,
    verify_tls=True,
    proxies={"https": "http://proxy.example.com:8080"},
    retries=2,
)
```

## 运行测试

```bash
python -m pip install -e ".[dev]"
pytest
ruff check .
mypy src
python -m build
twine check dist/*
```

内网集成测试默认跳过。显式提供以下环境变量后运行：

```text
WCP_BASE_URL
WCP_USERNAME
WCP_PASSWORD
WCP_TEST_CATEGORY_ID   # 可选
WCP_TEST_DOCUMENT_ID   # 可选
WCP_TEST_ATTACHMENT_DOCUMENT_ID  # 可选，包含附件的文档
```

```bash
pytest -m integration
```

集成测试只调用查询、登录和退出接口。
