matchina 0.1.0__tar.gz

matchina-0.1.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release preparation
+- GitHub Actions CI workflow
+- Comprehensive documentation (README, CONTRIBUTING, CHANGELOG)
+- PyPI publish script
+- Project renamed to Matchina
+
+### Changed
+- Enhanced README with API documentation and examples
+- Improved test coverage
+- Project name updated from cn-entity-resolver to Matchina
+
+### Fixed
+- None yet
+
+## [0.1.0] - 2026-03-14
+
+### Added
+- 四层匹配策略（精确匹配、别名匹配、规则匹配、模糊匹配）
+- 中英文企业名称匹配支持
+- 别名/简称识别
+- 批量匹配功能 `resolve_batch()`
+- 模糊搜索功能 `search()`
+- 完整的类型注解和 mypy 支持
+- 约 30+ 企业数据（中文、英文、别名）
+- 单元测试覆盖核心功能
+- MIT 许可证
+
+### Technical Stack
+- Python 3.8+
+- pytest 测试框架
+- mypy 类型检查
+- ruff 代码检查
+- setuptools 构建系统
+
+### Data Format
+- SQLite 数据库存储企业数据
+- JSON 别名映射表
+- 离线数据，无需网络连接
+
+### API
+- `resolve(name, top_k=5)` - 单个名称匹配
+- `search(query, limit=10)` - 模糊搜索
+- `resolve_batch(names, top_k=5)` - 批量匹配
+- `EntityMatcher` 类接口
+- `Entity` 数据模型
+- `MatchResult` 结果对象
+
+### Performance
+- 批量匹配优化
+- 懒加载全局 matcher 实例
+- 缓存匹配结果
+
+### Documentation
+- 快速开始指南
+- API 文档
+- 示例代码
+- 匹配策略说明
+
+---
+
+## Version History
+
+- **0.1.0** (2026-03-14) - Initial release (Matchina)
+
+---
+
+## Upcoming
+
+### Planned Features
+- 更多企业数据（目标 100+）
+- 拼音匹配支持
+- 行业分类过滤
+- 置信度阈值配置
+- 自定义数据加载
+- 性能优化（缓存、索引）
+
+### Future Considerations
+- 异步 API 支持
+- 增量数据更新
+- 企业关联关系
+- 行业知识图谱

matchina-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# 贡献指南
+
+感谢你对 Matchina 的关注！欢迎贡献代码、文档、测试或数据。
+
+## 如何贡献
+
+### 1. 报告问题
+
+在 GitHub Issues 中报告 bug 或提出功能请求：
+- 描述清楚问题
+- 提供复现步骤
+- 附上预期行为和实际行为
+
+### 2. 提交代码
+
+#### Fork 仓库
+
+```bash
+git clone https://github.com/YOUR_USERNAME/matchina.git
+cd matchina
+```
+
+#### 创建开发环境
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # macOS/Linux
+pip install -e ".[dev]"
+```
+
+#### 创建分支
+
+```bash
+git checkout -b feature/your-feature-name
+# 或
+git checkout -b fix/issue-123
+```
+
+### 3. 开发流程
+
+1. **编写代码**：遵循现有代码风格
+2. **添加测试**：确保新功能有测试覆盖
+3. **运行检查**：
+   ```bash
+   # 运行测试
+   pytest
+   
+   # 类型检查
+   mypy matchina
+   
+   # 代码风格检查
+   ruff check matchina tests
+   
+   # 格式化代码
+   ruff format matchina tests
+   ```
+4. **提交更改**：
+   ```bash
+   git add .
+   git commit -m "feat: add new feature"
+   ```
+
+### 4. 提交 Pull Request
+
+1. 推送分支到 GitHub
+2. 在原始仓库创建 Pull Request
+3. 描述更改内容和原因
+4. 等待代码审查
+
+### 5. 添加企业数据
+
+如果要添加新的企业数据：
+
+1. 在 `data/` 目录中添加数据文件
+2. 更新 `matchina/data/storage.py` 加载新数据
+3. 添加测试验证数据正确性
+4. 在文档中说明数据来源
+
+## 代码规范
+
+### 命名约定
+
+- 变量/函数：`snake_case`
+- 类：`PascalCase`
+- 常量：`UPPER_CASE`
+- 私有方法：`_prefix`
+
+### 文档规范
+
+- 所有公共函数/类必须有 docstring
+- 使用 Google 风格 docstring
+- 包含 Example 部分
+
+### 类型注解
+
+- 所有函数必须有类型注解
+- 使用 `typing` 模块
+- 运行 mypy 确保类型正确
+
+### 提交信息规范
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
+
+```
+feat: 新功能
+fix: 修复 bug
+docs: 文档更新
+style: 代码格式（不影响功能）
+refactor: 重构（既不修复 bug也不添加功能）
+test: 添加测试
+chore: 构建/工具/配置
+```
+
+示例：
+```bash
+git commit -m "feat: add batch processing support"
+git commit -m "fix: resolve fuzzy match edge case"
+git commit -m "docs: update API documentation"
+```
+
+## 测试要求
+
+### 单元测试
+
+- 新功能必须有单元测试
+- 保持测试覆盖率
+- 测试边界情况和错误处理
+
+### 运行测试
+
+```bash
+# 运行所有测试
+pytest
+
+# 运行特定测试
+pytest tests/test_matcher.py -v
+
+# 查看覆盖率
+pytest --cov=matchina
+```
+
+## 发布流程
+
+维护者发布新版本：
+
+1. 更新 `CHANGELOG.md`
+2. 更新版本号 `matchina/__version__.py`
+3. 创建 release tag
+4. 运行发布脚本
+5. 上传到 PyPI
+
+详见发布流程文档。
+
+## 社区准则
+
+- 尊重他人，友好交流
+- 对事不对人
+- 欢迎不同背景的贡献者
+- 遵守开源社区最佳实践
+
+## 联系方式
+
+- GitHub Issues: 问题和讨论
+- Email: 联系维护者
+
+感谢你的贡献！🎉

matchina-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cn-entity-resolver 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.

matchina-0.1.0/MANIFEST.in

@@ -0,0 +1,19 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include pyproject.toml
+recursive-include matchina *.py
+recursive-include matchina/data *.db *.json
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude .gitignore
+global-exclude .mypy_cache
+global-exclude .pytest_cache
+global-exclude .ruff_cache
+global-exclude .venv
+global-exclude dist
+global-exclude build
+global-exclude *.egg-info

matchina-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: matchina
+Version: 0.1.0
+Summary: 中国企业中英文名称对齐匹配库
+Author: Matchina contributors
+License: MIT
+Project-URL: Homepage, https://github.com/xxx/matchina
+Project-URL: Repository, https://github.com/xxx/matchina
+Project-URL: Documentation, https://github.com/xxx/matchina#readme
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Matchina
+
+[English](README_en.md) | 中文
+
+中国企业中英文名称对齐匹配库。支持精确匹配、别名匹配、模糊搜索，离线使用，无需网络。
+
+## 特性
+
+- 🔍 **四层匹配策略**：精确匹配 → 别名匹配 → 规则匹配 → 模糊匹配
+- 🇨🇳 **中英文支持**：同时支持中文和英文名称
+- 📦 **离线使用**：所有数据打包在库内，无需网络
+- ⚡ **高性能**：单次匹配 < 100ms
+- 🐍 **Python 3.8+**：支持 Python 3.8 及以上版本
+
+## 安装
+
+```bash
+pip install matchina
+```
+
+## 快速开始
+
+```python
+from matchina import resolve, search, resolve_batch
+
+# 精确匹配
+result = resolve("华为")
+print(result[0].name_cn)      # 华为技术有限公司
+print(result[0].name_en)      # Huawei Technologies Co., Ltd.
+print(result[0].confidence)   # 1.0
+
+# 英文匹配
+result = resolve("Alibaba")
+print(result[0].name_cn)       # 阿里巴巴集团控股有限公司
+
+# 别名匹配
+result = resolve("抖音")
+print(result[0].name_cn)       # 北京字节跳动科技有限公司
+print(result[0].confidence)    # 0.95
+
+# 批量匹配
+names = ["腾讯", "百度", "小米", "比亚迪"]
+results = resolve_batch(names)
+for name, matches in results.items():
+    if matches:
+        print(f"{name} → {matches[0].name_cn}")
+
+# 模糊搜索
+results = search("科技", limit=5)
+for r in results:
+    print(f"{r.name_cn} (置信度: {r.confidence:.2f})")
+```
+
+## 匹配策略
+
+| 匹配类型 | 说明 | 置信度 |
+|----------|------|--------|
+| `exact` | 完全匹配 | 1.0 |
+| `alias` | 别名匹配 | 0.95 |
+| `rule` | 规则匹配（后缀/缩写） | 0.85 |
+| `fuzzy` | 模糊匹配（编辑距离） | 0.6-0.8 |
+
+## 数据覆盖
+
+当前版本包含：
+
+- **1132 家企业实体**
+- **112 个企业别名**
+- 覆盖 A 股、港股、中概股、独角兽、知名出海品牌
+
+## API 文档
+
+### `resolve(name, top_k=5)`
+
+匹配企业名称。
+
+**参数**:
+- `name` (str): 企业名称（中文或英文）
+- `top_k` (int): 返回结果数量，默认 5
+
+**返回**: `List[MatchResult]`
+
+### `search(query, limit=10)`
+
+模糊搜索企业名称。
+
+**参数**:
+- `query` (str): 搜索关键词
+- `limit` (int): 返回结果数量，默认 10
+
+**返回**: `List[MatchResult]`
+
+### `resolve_batch(names, top_k=5)`
+
+批量匹配企业名称。
+
+**参数**:
+- `names` (List[str]): 企业名称列表
+- `top_k` (int): 每个名称返回结果数量
+
+**返回**: `Dict[str, List[MatchResult]]`
+
+### `MatchResult`
+
+匹配结果对象。
+
+```python
+@dataclass
+class MatchResult:
+    entity_id: str      # 实体 ID
+    name_cn: str        # 中文名称
+    name_en: str        # 英文名称
+    confidence: float   # 置信度 (0.0-1.0)
+    aliases: List[str]  # 别名列表
+    match_type: str     # 匹配类型
+```
+
+## 示例企业
+
+| 中文名 | 英文名 | 别名 |
+|--------|--------|------|
+| 华为技术有限公司 | Huawei Technologies Co., Ltd. | 华为、HUAWEI |
+| 腾讯控股有限公司 | Tencent Holdings Limited | 腾讯、微信、QQ、Tencent |
+| 阿里巴巴集团控股有限公司 | Alibaba Group Holding Limited | 阿里、淘宝、天猫、Alibaba |
+| 北京字节跳动科技有限公司 | Beijing ByteDance Technology Co., Ltd. | 字节跳动、抖音、TikTok、今日头条 |
+| 小米科技有限责任公司 | Xiaomi Technology Co., Ltd. | 小米、MI、Xiaomi |
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/xxx/matchina.git
+cd matchina
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 类型检查
+mypy matchina
+
+# 代码检查
+ruff check matchina
+```
+
+## 贡献
+
+欢迎贡献代码、报告问题或提出建议！
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+## 许可证
+
+[MIT License](LICENSE)
+
+## 更新日志
+
+### v0.1.0 (2026-03-14)
+
+- 首次发布
+- 支持 1132 家企业实体
+- 四层匹配策略
+- 中英文支持
+
+---
+
+**Matchina** - Match China, Match Enterprise Names.

matchina-0.1.0/README.md

@@ -0,0 +1,173 @@
+# Matchina
+
+[English](README_en.md) | 中文
+
+中国企业中英文名称对齐匹配库。支持精确匹配、别名匹配、模糊搜索，离线使用，无需网络。
+
+## 特性
+
+- 🔍 **四层匹配策略**：精确匹配 → 别名匹配 → 规则匹配 → 模糊匹配
+- 🇨🇳 **中英文支持**：同时支持中文和英文名称
+- 📦 **离线使用**：所有数据打包在库内，无需网络
+- ⚡ **高性能**：单次匹配 < 100ms
+- 🐍 **Python 3.8+**：支持 Python 3.8 及以上版本
+
+## 安装
+
+```bash
+pip install matchina
+```
+
+## 快速开始
+
+```python
+from matchina import resolve, search, resolve_batch
+
+# 精确匹配
+result = resolve("华为")
+print(result[0].name_cn)      # 华为技术有限公司
+print(result[0].name_en)      # Huawei Technologies Co., Ltd.
+print(result[0].confidence)   # 1.0
+
+# 英文匹配
+result = resolve("Alibaba")
+print(result[0].name_cn)       # 阿里巴巴集团控股有限公司
+
+# 别名匹配
+result = resolve("抖音")
+print(result[0].name_cn)       # 北京字节跳动科技有限公司
+print(result[0].confidence)    # 0.95
+
+# 批量匹配
+names = ["腾讯", "百度", "小米", "比亚迪"]
+results = resolve_batch(names)
+for name, matches in results.items():
+    if matches:
+        print(f"{name} → {matches[0].name_cn}")
+
+# 模糊搜索
+results = search("科技", limit=5)
+for r in results:
+    print(f"{r.name_cn} (置信度: {r.confidence:.2f})")
+```
+
+## 匹配策略
+
+| 匹配类型 | 说明 | 置信度 |
+|----------|------|--------|
+| `exact` | 完全匹配 | 1.0 |
+| `alias` | 别名匹配 | 0.95 |
+| `rule` | 规则匹配（后缀/缩写） | 0.85 |
+| `fuzzy` | 模糊匹配（编辑距离） | 0.6-0.8 |
+
+## 数据覆盖
+
+当前版本包含：
+
+- **1132 家企业实体**
+- **112 个企业别名**
+- 覆盖 A 股、港股、中概股、独角兽、知名出海品牌
+
+## API 文档
+
+### `resolve(name, top_k=5)`
+
+匹配企业名称。
+
+**参数**:
+- `name` (str): 企业名称（中文或英文）
+- `top_k` (int): 返回结果数量，默认 5
+
+**返回**: `List[MatchResult]`
+
+### `search(query, limit=10)`
+
+模糊搜索企业名称。
+
+**参数**:
+- `query` (str): 搜索关键词
+- `limit` (int): 返回结果数量，默认 10
+
+**返回**: `List[MatchResult]`
+
+### `resolve_batch(names, top_k=5)`
+
+批量匹配企业名称。
+
+**参数**:
+- `names` (List[str]): 企业名称列表
+- `top_k` (int): 每个名称返回结果数量
+
+**返回**: `Dict[str, List[MatchResult]]`
+
+### `MatchResult`
+
+匹配结果对象。
+
+```python
+@dataclass
+class MatchResult:
+    entity_id: str      # 实体 ID
+    name_cn: str        # 中文名称
+    name_en: str        # 英文名称
+    confidence: float   # 置信度 (0.0-1.0)
+    aliases: List[str]  # 别名列表
+    match_type: str     # 匹配类型
+```
+
+## 示例企业
+
+| 中文名 | 英文名 | 别名 |
+|--------|--------|------|
+| 华为技术有限公司 | Huawei Technologies Co., Ltd. | 华为、HUAWEI |
+| 腾讯控股有限公司 | Tencent Holdings Limited | 腾讯、微信、QQ、Tencent |
+| 阿里巴巴集团控股有限公司 | Alibaba Group Holding Limited | 阿里、淘宝、天猫、Alibaba |
+| 北京字节跳动科技有限公司 | Beijing ByteDance Technology Co., Ltd. | 字节跳动、抖音、TikTok、今日头条 |
+| 小米科技有限责任公司 | Xiaomi Technology Co., Ltd. | 小米、MI、Xiaomi |
+
+## 开发
+
+```bash
+# 克隆仓库
+git clone https://github.com/xxx/matchina.git
+cd matchina
+
+# 安装开发依赖
+pip install -e ".[dev]"
+
+# 运行测试
+pytest
+
+# 类型检查
+mypy matchina
+
+# 代码检查
+ruff check matchina
+```
+
+## 贡献
+
+欢迎贡献代码、报告问题或提出建议！
+
+1. Fork 本仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交更改 (`git commit -m 'Add amazing feature'`)
+4. 推送到分支 (`git push origin feature/amazing-feature`)
+5. 创建 Pull Request
+
+## 许可证
+
+[MIT License](LICENSE)
+
+## 更新日志
+
+### v0.1.0 (2026-03-14)
+
+- 首次发布
+- 支持 1132 家企业实体
+- 四层匹配策略
+- 中英文支持
+
+---
+
+**Matchina** - Match China, Match Enterprise Names.