Metadata-Version: 2.5
Name: journapi
Version: 1.0.1
Summary: A standard, extensible SDK for fetching scholarly artifact metadata (journals via ISSN Portal first, more sources to come)
Project-URL: Homepage, https://cnb.cool/xqitw/journapi
Project-URL: Repository, https://cnb.cool/xqitw/journapi
Project-URL: Issues, https://cnb.cool/xqitw/journapi/-/issues
Author: journapi Contributors
License: MIT
License-File: LICENSE
Keywords: cli,issn,journal,metadata,scholarly,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: hishel<0.2,>=0.1.5
Requires-Dist: httpx>=0.27
Requires-Dist: parsel>=1.9
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: stamina>=24.3
Requires-Dist: typer>=0.12
Provides-Extra: chinese
Requires-Dist: jieba>=0.42; extra == 'chinese'
Requires-Dist: pypinyin>=0.51; extra == 'chinese'
Provides-Extra: dev
Requires-Dist: mcp<2,>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2.0; extra == 'mcp'
Description-Content-Type: text/markdown

# journapi

[![Latest Release](https://cnb.cool/xqitw/journapi/-/badge/release)](https://cnb.cool/xqitw/journapi/-/badge/release.link)
[![PyPI](https://img.shields.io/pypi/v/journapi.svg)](https://pypi.org/project/journapi/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB.svg)](https://www.python.org)
![badge](https://cnb.cool/xqitw/journapi/-/badge/git/latest/ci/pipeline-as-code?branch=main)
![badge](https://cnb.cool/xqitw/journapi/-/badge/git/latest/ci/git-clone-yyds)
![badge](https://cnb.cool/xqitw/journapi/-/badge/star)
![badge](https://cnb.cool/xqitw/journapi/-/badge/fork)

标准、可扩展的学术制品元数据检索 SDK + CLI —— 首个数据源为期刊（通过公开的 ISSN Portal），提供 Provider 抽象层，为后续更多数据源（文献、DOI 等）预留扩展能力。

> **项目状态**：stable。ISSN Portal 公开网页接口已实现并经独立复审验证；官方订阅 API（api.issn.org, REST + JWT）提供完整 Provider 骨架（需订阅凭据端到端验证）。

## 功能特性

- **期刊检索** — 按刊名 / ISSN / eISSN / ISSN-L 搜索与精确查询
- **ISSN-L / ISSN-H** — 同刊多介质（Print/Online）聚合与历史沿革（更名前后继）家族
- **多数据源** — ISSN Portal（国际）+ 中国 ISSN 中心 nlc（**中文刊名检索优先使用**）+ 官方订阅 API；注册式 Provider 便于扩展
- **多使用方式** — Python SDK / CLI / Web UI / MCP 服务器 / Agent Skill
- **礼貌抓取** — 限速（robots.txt Crawl-delay 1s）、重试退避、可选磁盘缓存（RFC 9111）

## 安装

包已发布到 PyPI（包名 `journapi`）：

```bash
uvx journapi --help              # 免安装直接运行（推荐）
pip install "journapi[chinese]"  # 或 pip 安装（含中文刊名分词）
uv tool install journapi         # 或全局工具安装
```

开发环境搭建见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 快速开始

```bash
# 搜索（刊名 / ISSN 均可；已知 ISSN 优先传 ISSN）
journapi search "Hearing research"
journapi search 0378-5955 --json

# 中文刊名检索优先走中国 ISSN 中心源
journapi search 自动化学报 --provider nlc_issn

# 单条记录 / ISSN-L 集群 / Web UI
journapi get 0964-1998
journapi cluster 0378-5955
journapi web   # 浏览器打开 http://127.0.0.1:8787
```

```python
import asyncio
from journapi import ArtifactSearchClient


async def main():
    async with ArtifactSearchClient() as client:
        results = await client.search("Hearing research")
        print([(r.issn, r.title) for r in results.items])


asyncio.run(main())
```

检索策略（search 与 get 的取舍、中文刊三步链路）见 [docs/API.md](docs/API.md)；可运行示例见 [examples/](examples/)。

## 使用方式

| 方式 | 入口 | 文档 |
| --- | --- | --- |
| Python SDK | `from journapi import ArtifactSearchClient` | [docs/API.md](docs/API.md) |
| CLI | `journapi --help` | [docs/API.md](docs/API.md) |
| Web UI | `journapi web` → `http://127.0.0.1:8787` | [docs/API.md](docs/API.md)（路由与 JSON API） |
| MCP 服务器 | `journapi mcp`（需 `[mcp]` extra） | [docs/MCP.md](docs/MCP.md) |
| Agent Skill | `npx skills add https://cnb.cool/xqitw/journapi.git` | [skills/journapi-skill/SKILL.md](skills/journapi-skill/SKILL.md) |

## 文档

- [API 参考](docs/API.md) — 客户端、模型、错误、数据源选择与检索策略、Web 服务路由
- [MCP 接入指南](docs/MCP.md) — 智能体接入配置、工具清单、推荐查询链路
- [架构与设计](docs/ARCHITECTURE.md) — 分层架构、项目结构、模块说明、关键设计、环境变量
- [数据源调研](docs/sources.md) — ISSN Portal / 中国 ISSN 中心接口能力边界与实测结论
- [示例](examples/) — 可运行脚本

## 合规

journapi 遵循公开门户 `robots.txt`（目录级允许/禁止 + 1s 爬取延迟）。生产 / 批量场景请订阅[官方搜索 API](https://portal.issn.org/services)，细节见[数据源调研](docs/sources.md)。

## 贡献指南

欢迎参与贡献！详细的贡献规范和开发流程请参考 [CONTRIBUTING.md](./CONTRIBUTING.md)。

## 许可证

[MIT](./LICENSE)
