wcp32-client 0.1.1__tar.gz

wcp32_client-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+.env
+

wcp32_client-0.1.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.1
+
+- Parse resource-file documents that contain both authored content and attachments.
+- Read resource document content from `#textsBoxId`.
+- Extract the real attachment name, size, and download URL from resource cards.
+
+## 0.1.0
+
+- Initial read-only client for WCP 3.2.0.
+- Session login and logout.
+- Typed category, document, content, attachment, user, and search services.
+- Streaming attachment downloads and a read-only raw GET escape hatch.

wcp32_client-0.1.1/LICENSE

@@ -0,0 +1,22 @@
+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.
+

wcp32_client-0.1.1/PKG-INFO

@@ -0,0 +1,237 @@
+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
+```
+
+集成测试只调用查询、登录和退出接口。

wcp32_client-0.1.1/README.md

@@ -0,0 +1,185 @@
+# 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
+```
+
+集成测试只调用查询、登录和退出接口。

wcp32_client-0.1.1/examples/basic_usage.py

@@ -0,0 +1,26 @@
+"""Minimal read-only usage example."""
+
+from __future__ import annotations
+
+import os
+
+from wcp32 import WcpClient
+
+
+def main() -> None:
+    base_url = os.environ["WCP_BASE_URL"]
+    username = os.environ["WCP_USERNAME"]
+    password = os.environ["WCP_PASSWORD"]
+
+    with WcpClient(base_url) as client:
+        client.login(username, password)
+        me = client.users.me()
+        print(f"Logged in as {me.name} ({me.id})")
+
+        for category in client.categories.iter_all():
+            print(category.id, category.name)
+
+
+if __name__ == "__main__":
+    main()
+

wcp32_client-0.1.1/examples/export_category.py

@@ -0,0 +1,40 @@
+"""Export all documents in one category as JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from dataclasses import asdict
+from pathlib import Path
+
+from wcp32 import WcpClient
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("category_id")
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--recursive", action="store_true")
+    args = parser.parse_args()
+
+    with WcpClient(os.environ["WCP_BASE_URL"]) as client:
+        client.login(os.environ["WCP_USERNAME"], os.environ["WCP_PASSWORD"])
+        documents = [
+            asdict(document)
+            for document in client.documents.iter(
+                args.category_id,
+                recursive=args.recursive,
+            )
+        ]
+
+    args.output.write_text(
+        json.dumps(documents, ensure_ascii=False, indent=2),
+        encoding="utf-8",
+    )
+    print(f"Exported {len(documents)} documents to {args.output}")
+
+
+if __name__ == "__main__":
+    main()
+

wcp32_client-0.1.1/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wcp32-client"
+version = "0.1.1"
+description = "A typed, read-only Python client for WCP 3.2.x knowledge management systems."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "WCP32 Client Contributors" }
+]
+keywords = ["wcp", "knowledge-management", "sdk", "client"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "requests>=2.31,<3",
+  "beautifulsoup4>=4.12,<5",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "mypy>=1.10",
+  "pytest>=8",
+  "responses>=0.25",
+  "ruff>=0.6",
+  "twine>=5",
+  "types-requests>=2.31",
+]
+
+[project.urls]
+"WCP upstream" = "https://gitee.com/macplus/WCP"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/wcp32"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/demo.py",
+  "/dist",
+  "/SHA256SUMS",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+  "integration: read-only tests against a live WCP server",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true

wcp32_client-0.1.1/src/wcp32/__init__.py

@@ -0,0 +1,46 @@
+"""Typed, read-only Python client for WCP 3.2.x."""
+
+from .client import WcpClient
+from .exceptions import (
+    WcpAuthenticationError,
+    WcpError,
+    WcpNotFoundError,
+    WcpParseError,
+    WcpPermissionError,
+    WcpTransportError,
+    WcpVersionError,
+)
+from .models import (
+    Attachment,
+    Category,
+    CategoryNode,
+    Document,
+    DocumentContent,
+    DocumentVersion,
+    Page,
+    SessionInfo,
+    User,
+)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Attachment",
+    "Category",
+    "CategoryNode",
+    "Document",
+    "DocumentContent",
+    "DocumentVersion",
+    "Page",
+    "SessionInfo",
+    "User",
+    "WcpAuthenticationError",
+    "WcpClient",
+    "WcpError",
+    "WcpNotFoundError",
+    "WcpParseError",
+    "WcpPermissionError",
+    "WcpTransportError",
+    "WcpVersionError",
+    "__version__",
+]