funapi-sciencedb 1.0.1__tar.gz → 1.1.2__tar.gz

funapi_sciencedb-1.1.2/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [farfarfun]

funapi_sciencedb-1.1.2/.gitignore

@@ -0,0 +1,195 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.db
+*.rar
+.run/
+logs/
+.idea/
+.vscode/
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# ---- AI 编码助手 ----
+# 只忽略本地状态；团队有意共享的 agent / 命令 / 规则定义仍然版本化。
+# 必须写 `dir/*` 而不是 `dir/`：父目录被整体排除后 git 不会下探，
+# 下面的 `!` 取消规则就永远不会生效。
+.claude/*
+!.claude/agents/
+!.claude/commands/
+!.claude/skills/
+!.claude/settings.json
+.codex/*
+!.codex/prompts/
+.cursor/*
+!.cursor/agents/
+!.cursor/rules/
+
+# 其余助手：目前没有共享内容，整体忽略
+.aider*
+.gemini/
+.continue/
+.windsurf/
+.roo/
+.cline/
+.specstory/
+CLAUDE.local.md
+AGENTS.local.md
+uv.lock

funapi_sciencedb-1.1.2/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## [1.1.2] - 2026-11-12
+
+### 修复
+
+- 生成的客户端代码 docstring 全面中文化（SPEC §7）。此前只有 `client.py` 的两个类
+  docstring 和 `search_using_get.py` 被手工翻过，其余 28 个文件（全部模型、
+  `sushi_controller` 下的接口、`errors.py`、`types.py`、各级 `__init__.py`）以及
+  `client.py` 的方法 docstring 都还是英文，而且手工翻译在下次重新生成时会被覆盖掉。
+- `tests/test_smoke.py` 的模块/用例 docstring 与注释改为中文。
+
+### 新增
+
+- `localize.py`：生成产物中文化脚本，两张精确文案映射表分别处理上游 OpenAPI 文档里的
+  `summary` / `description` 和 `openapi-python-client` 模板写死的英文。`generate.py`
+  已接入——拉取文档后先中文化文档，生成代码后再中文化模板文案，所以重新生成客户端
+  不会再退回英文。映射表只做精确匹配，上游新增文案原样保留，
+  `uv run python localize.py --check` 可以把漏网的 docstring 列出来。
+- `tests/test_localize.py`：覆盖中文化的幂等性、折行长文案的匹配、只改 docstring 不动
+  代码、未登记文案不乱翻，以及「已提交的生成代码里没有残留英文 docstring」这条守卫。
+- 仓库根目录 `conftest.py`：把根目录加进 `sys.path`，让测试能 import 根目录下的
+  `generate` / `localize` 这两个开发期脚本。
+
+### 变更
+
+- `pyproject.toml` 补上 `authors` 与 `license-files = ["LICENSE"]`，构建产物的
+  METADATA 里才会带作者和许可证文件（SPEC §4.2）。
+- `localize.py` 的状态/诊断输出改用 `farlog`（SPEC §8.1：不要裸 `print`，也不要裸用
+  标准库 `logging`）。logger 在 `main()` 里创建，这样单纯 import 本模块不会建
+  `logs/` 目录。`farlog` 只进 `dev` / `generate` 依赖组，不进发布包。
+- `openapi-ori.json` / `openapi-v3.json` 里的接口与模型说明同步改为中文，并补上文件
+  末尾换行。
+- README 的「重新生成客户端」补充中文化步骤与 `localize.py --check` 用法。
+- `uv.lock` 中的传递依赖 urllib3 由 2.7.0 升到 2.8.0，修掉 GitHub dependabot 报出的
+  3 个漏洞（2 个 HIGH：`HTTPResponse.stream()/read_chunked()` 无界缓冲、HTTPS 代理的
+  TLS 配置可能被忽略；1 个 MEDIUM：chunked deflate 可进入无限循环）。本包代码未改动。
+- `generate.py`、`localize.py`、`tests/test_localize.py` 按仓库当前 ruff 配置补跑
+  `ruff format`，清掉一直存在的格式漂移，SPEC §14.2 发布前清单的
+  `ruff format` 一项现在能通过。纯格式化，无行为变更。
+
+### 废弃
+
+- 无。
+
+## [1.1.1] - 2026-09-03
+
+### 修复
+
+- `generate.py` 不再把 `acw_tc`、`cdn_sec_tc` 这两个反爬会话 cookie 和 `traceId`
+  写死在代码里，改为从环境变量（`SCIDB_ACW_TC` / `SCIDB_CDN_SEC_TC`）读取，
+  `traceId` 每次运行随机生成。
+- `pyproject.toml` 的 `description` 从占位符 `Add your description here` 改成
+  实际的中文一句话说明，并同步更新了 GitHub 仓库的 description。
+- `sciencedb` 兼容层的 `DeprecationWarning` 明确了移除版本：将于 2.0 移除
+  （此前只写“未来某个版本”）。
+
+### 新增
+
+- README 补充「重新生成客户端」使用说明，以及末尾统一的「关于 farfarfun」组织
+  介绍区块。
+- `generate.py` 运行所需的 `requests`、`funapi`、`openapi-python-client` 纳入
+  `pyproject.toml` 的 `generate` 依赖组，`uv sync --group generate` 即可复现。
+- `tests/test_smoke.py` 补充 `metrics_using_get`、`json_using_get`、
+  `get_reports`、`get_report_by_id_using_get` 以及 `asyncio`/`asyncio_detailed`
+  异步调用路径的 mock HTTP 测试。
+
+### 变更
+
+- `pyproject.toml` 补充 `license = "MIT"` 字段。
+- `[tool.ruff]` 按 Python 3.10 规则检查生成客户端代码。
+- 本文件历史条目按「新增/修复/变更/废弃」四分类重新归类整理，不改变实际内容含义。
+
+### 废弃
+
+- 无。
+
+## [1.1.0] - 2026-08-28
+
+### 变更（破坏性变更）
+
+- 包内导入路径从 `sciencedb` 统一改为 `funapi_sciencedb`，与仓库名、PyPI 发布名
+  （一直都是 `funapi-sciencedb`）保持一致。`generate.py` 里 OpenAPI 客户端代码的
+  生成目标目录也同步改为 `src/funapi_sciencedb`，以后重新生成不会再退回旧名。
+
+### 新增
+
+- 保留了 `sciencedb` 兼容层（`src/sciencedb/__init__.py`，仅一个文件）：
+  `import sciencedb` 仍然可用，会转发到 `funapi_sciencedb` 并抛出
+  `DeprecationWarning`。计划在下一次破坏性版本中删除这个兼容层，请尽快把代码里的
+  `import sciencedb` / `from sciencedb...` 换成
+  `import funapi_sciencedb` / `from funapi_sciencedb...`。
+
+### 修复
+
+- 无。
+
+### 废弃
+
+- `sciencedb` 兼容导入将在 2.0 移除，请迁移到 `funapi_sciencedb`。

funapi_sciencedb-1.1.2/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: funapi-sciencedb
+Version: 1.1.2
+Summary: 科学数据银行（ScienceDB）Open API 的 Python 客户端，由 openapi-python-client 根据官方 OpenAPI 文档自动生成
+Author-email: 牛哥 <farfarfun@qq.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: httpx>=0.20.0
+Requires-Dist: python-dateutil>=2.8.2
+Description-Content-Type: text/markdown
+
+# funapi-sciencedb
+
+科学数据银行（[ScienceDB](https://www.scidb.cn)）Open API 的 Python 客户端，由 `openapi-python-client` 根据 ScienceDB 官方 OpenAPI 文档（`https://www.scidb.cn/open-api/v2/api-docs`）自动生成，仓库里的 `generate.py` 就是重新拉取该文档并重新生成客户端代码的脚本。
+
+## 安装
+
+```bash
+pip install funapi-sciencedb
+```
+
+## 用法示例
+
+```python
+from funapi_sciencedb import Client
+from funapi_sciencedb.api.open_api_controller import search_using_get
+
+client = Client(base_url="https://www.scidb.cn/open-api/v2")
+
+# 按发布时间倒序分页搜索数据集
+result = search_using_get.sync(client=client, page=1, size=10)
+```
+
+除了开放接口（`open_api_controller`，搜索/harvest/metrics/json 等），还包含 COUNTER 标准的用量统计报表接口（`sushi_controller`：`get_api_status`、`get_reports`、`get_report_by_id_using_get`）。每个接口都提供 `sync` / `sync_detailed` / `asyncio` / `asyncio_detailed` 四种调用方式，返回值是 `models/` 目录下对应的强类型模型对象。
+
+由于是自动生成的客户端，具体字段和返回结构以 `src/funapi_sciencedb/models/` 下的类定义为准。
+
+## 重新生成客户端
+
+`generate.py` 会重新拉取 ScienceDB 官方 OpenAPI 文档并重新生成 `src/funapi_sciencedb/` 下的全部代码，运行前需要安装 `generate` 依赖组：
+
+```bash
+uv sync --group generate
+uv run python generate.py
+ruff check --fix . && ruff format .
+```
+
+生成器模板和上游 OpenAPI 文档都是英文的，`generate.py` 会自动调用 `localize.py` 把 docstring 换成中文：拉取文档后替换文档里的 `summary` / `description`，生成代码后再替换模板自带的 `Args:`、`Client` 类说明等。
+
+映射表是精确匹配的，上游新增文案不会被瞎翻、而是原样保留。补完映射后可以单独重跑或自查：
+
+```bash
+uv run python localize.py          # 重新应用中文化
+uv run python localize.py --check  # 只检查，列出还没中文化的 docstring
+```
+
+---
+
+## 关于 farfarfun
+
+[farfarfun](https://github.com/farfarfun) 是一个专注于实用工具库的开源组织，
+涵盖云存储、数据处理、AI、多媒体与开发工具链等方向。
+
+- 🏠 组织主页：<https://github.com/farfarfun>
+- 📦 PyPI：<https://pypi.org/user/niuliangtao/>
+- 📧 联系：farfarfun@qq.com
+
+本项目基于 [MIT](LICENSE) 协议开源。

funapi_sciencedb-1.1.2/README.md

@@ -0,0 +1,57 @@
+# funapi-sciencedb
+
+科学数据银行（[ScienceDB](https://www.scidb.cn)）Open API 的 Python 客户端，由 `openapi-python-client` 根据 ScienceDB 官方 OpenAPI 文档（`https://www.scidb.cn/open-api/v2/api-docs`）自动生成，仓库里的 `generate.py` 就是重新拉取该文档并重新生成客户端代码的脚本。
+
+## 安装
+
+```bash
+pip install funapi-sciencedb
+```
+
+## 用法示例
+
+```python
+from funapi_sciencedb import Client
+from funapi_sciencedb.api.open_api_controller import search_using_get
+
+client = Client(base_url="https://www.scidb.cn/open-api/v2")
+
+# 按发布时间倒序分页搜索数据集
+result = search_using_get.sync(client=client, page=1, size=10)
+```
+
+除了开放接口（`open_api_controller`，搜索/harvest/metrics/json 等），还包含 COUNTER 标准的用量统计报表接口（`sushi_controller`：`get_api_status`、`get_reports`、`get_report_by_id_using_get`）。每个接口都提供 `sync` / `sync_detailed` / `asyncio` / `asyncio_detailed` 四种调用方式，返回值是 `models/` 目录下对应的强类型模型对象。
+
+由于是自动生成的客户端，具体字段和返回结构以 `src/funapi_sciencedb/models/` 下的类定义为准。
+
+## 重新生成客户端
+
+`generate.py` 会重新拉取 ScienceDB 官方 OpenAPI 文档并重新生成 `src/funapi_sciencedb/` 下的全部代码，运行前需要安装 `generate` 依赖组：
+
+```bash
+uv sync --group generate
+uv run python generate.py
+ruff check --fix . && ruff format .
+```
+
+生成器模板和上游 OpenAPI 文档都是英文的，`generate.py` 会自动调用 `localize.py` 把 docstring 换成中文：拉取文档后替换文档里的 `summary` / `description`，生成代码后再替换模板自带的 `Args:`、`Client` 类说明等。
+
+映射表是精确匹配的，上游新增文案不会被瞎翻、而是原样保留。补完映射后可以单独重跑或自查：
+
+```bash
+uv run python localize.py          # 重新应用中文化
+uv run python localize.py --check  # 只检查，列出还没中文化的 docstring
+```
+
+---
+
+## 关于 farfarfun
+
+[farfarfun](https://github.com/farfarfun) 是一个专注于实用工具库的开源组织，
+涵盖云存储、数据处理、AI、多媒体与开发工具链等方向。
+
+- 🏠 组织主页：<https://github.com/farfarfun>
+- 📦 PyPI：<https://pypi.org/user/niuliangtao/>
+- 📧 联系：farfarfun@qq.com
+
+本项目基于 [MIT](LICENSE) 协议开源。

funapi_sciencedb-1.1.2/conftest.py

@@ -0,0 +1,11 @@
+"""把仓库根目录加进 `sys.path`，让测试能 import 根目录下的 `generate` / `localize`。
+
+这两个模块是开发期脚本（不进发布包），所以不在 `src/` 里，默认不在导入路径上。
+"""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))

funapi_sciencedb-1.1.2/generate.py

@@ -0,0 +1,98 @@
+import json
+import os
+import uuid
+from pathlib import Path
+
+import requests
+from funapi.convert import convert_openapi_v3
+from funapi.generate import generate_api
+from openapi_python_client import MetaType
+
+from localize import localize_generated, localize_openapi
+
+OPENAPI_FILEPATH_ORI = "openapi-ori.json"
+OPENAPI_FILEPATH_V3 = "openapi-v3.json"
+OUTPUT_DIR = Path("./src/funapi_sciencedb")
+OPENAPI_REQUEST_TIMEOUT = 30
+
+
+def load_openapi_ori() -> None:
+    """拉取 ScienceDB 官方 OpenAPI 文档，写入本地 `openapi-ori.json`。
+
+    `acw_tc` / `cdn_sec_tc` 是阿里云 WAF 下发的反爬会话 cookie（不是账号凭据），
+    每次访问都会重新生成、很快过期，不应该写死在代码里。这里改为从环境变量读取，
+    留空时也能直接访问——大多数情况下 ScienceDB 的这个文档地址不依赖这两个 cookie
+    也能正常返回；如果本地实测确实需要，临时用
+    `SCIDB_ACW_TC` / `SCIDB_CDN_SEC_TC` 环境变量传入即可，不要提交到仓库。
+    """
+    url = "https://www.scidb.cn/open-api/v2/api-docs"
+    headers = {
+        "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
+        "accept-language": "zh-CN,zh;q=0.9,en;q=0.8",
+        "cache-control": "max-age=0",
+        "priority": "u=0, i",
+        "referer": "https://www.scidb.cn/open-api/swagger-ui.html",
+        "sec-ch-ua": '"Google Chrome";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+        "sec-ch-ua-mobile": "?1",
+        "sec-ch-ua-platform": '"Android"',
+        "sec-fetch-dest": "document",
+        "sec-fetch-mode": "navigate",
+        "sec-fetch-site": "same-origin",
+        "sec-fetch-user": "?1",
+        "upgrade-insecure-requests": "1",
+        "user-agent": "Mozilla/5.0 (Linux; Android 6.0; Nexus 5 Build/MRA58N) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Mobile Safari/537.36",
+    }
+    cookies = {
+        "acw_tc": os.environ.get("SCIDB_ACW_TC", ""),
+        "cdn_sec_tc": os.environ.get("SCIDB_CDN_SEC_TC", ""),
+        "lang": "zh",
+        "traceId": str(uuid.uuid4()),
+    }
+    cookies = {k: v for k, v in cookies.items() if v}
+
+    try:
+        response = requests.get(
+            url,
+            headers=headers,
+            cookies=cookies,
+            timeout=OPENAPI_REQUEST_TIMEOUT,
+        )
+        response.raise_for_status()
+    except requests.HTTPError as exc:
+        status = exc.response.status_code if exc.response is not None else "未知"
+        raise RuntimeError(
+            f"下载 ScienceDB OpenAPI 文档失败：{url}（HTTP {status}，{exc}）"
+        ) from exc
+    except requests.RequestException as exc:
+        raise RuntimeError(f"下载 ScienceDB OpenAPI 文档失败：{url}（{exc}）") from exc
+
+    try:
+        openapi = response.json()
+    except ValueError as exc:
+        raise RuntimeError(
+            f"ScienceDB OpenAPI 文档不是合法 JSON：{url}（HTTP {response.status_code}）"
+        ) from exc
+    # 上游文档是英文的，先按 localize.py 的映射表换成中文再落盘，这样后面生成出来的
+    # docstring 直接就是中文（SPEC §7），不用事后再补。
+    openapi = localize_openapi(openapi)
+    with open(OPENAPI_FILEPATH_ORI, "w", encoding="utf-8") as f:
+        f.write(json.dumps(openapi, indent=4, ensure_ascii=False) + "\n")
+
+
+def main() -> None:
+    """拉取并转换 OpenAPI 文档，然后重新生成客户端代码。"""
+    load_openapi_ori()
+    convert_openapi_v3()
+    generate_api(
+        path=Path(OPENAPI_FILEPATH_V3),
+        output_path=OUTPUT_DIR,
+        meta=MetaType.NONE,
+        overwrite=True,
+    )
+    # 生成器模板自带的英文（`Args:`、`Client` 类说明等）不在 OpenAPI 文档里，
+    # 只能生成完再替换一遍。
+    localize_generated(OUTPUT_DIR)
+
+
+if __name__ == "__main__":
+    main()