feat: add PyPI package support

Author: frankslin

.github/workflows/pypi-publish.yml

@@ -0,0 +1,38 @@
+name: Python Package
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi
+      url: https://pypi.org/p/opencc-data
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+/.venv-build/
+/build/
+/dist/
+/*.egg-info/
+__pycache__/

.npmignore

@@ -1,4 +1,12 @@
 /.github
 /.gitattributes
 /.opencc-resource-manifest.json
+/.venv-build
+/build
+/dist
 /scripts
+/*.egg-info
+/MANIFEST.in
+/opencc_data
+/pyproject.toml
+/setup.py

MANIFEST.in

@@ -0,0 +1,8 @@
+include LICENSE
+include README.md
+include README.zh-TW.md
+include package.json
+graft data
+graft test-data
+prune scripts
+global-exclude .DS_Store

README.md

@@ -20,3 +20,15 @@ This package syncs dictionary `.txt` files and config `.json` files from OpenCC'
 Use the config files shipped in `data/config/` as the source of truth for dictionary order and conversion-chain behavior. Config contents can change between OpenCC versions, so consumers should load the matching config file for the package version they depend on instead of hard-coding dictionary lists from this README.
 
 Dictionary text files are shipped in `data/`. Config files reference those dictionaries by file name and preserve OpenCC's stage/group ordering semantics.
+
+Python consumers can install the `opencc-data` package from PyPI and use the `opencc_data` module to locate packaged resources:
+
+```python
+import opencc_data
+
+config_file = opencc_data.config_path("s2t.json")
+dictionary_file = opencc_data.data_path("STCharacters.txt")
+testcases_file = opencc_data.test_data_path("testcases.json")
+```
+
+Release versions match across npm and PyPI, such as `1.3.2`. For `next` prereleases, PyPI uses the PEP 440 equivalent of the npm version: `1.3.2-next.20260628` is published to PyPI as `1.3.2.dev20260628`.

README.zh-TW.md

@@ -20,3 +20,15 @@
 請以套件內 `data/config/` 提供的設定檔作為詞典順序與轉換鏈行為的依據。設定內容可能隨 OpenCC 版本改變，因此使用端應載入其依賴版本對應的設定檔，而不是從 README 固定寫死詞典列表。
 
 詞典文字檔位於 `data/`。設定檔會以檔名引用這些詞典，並保留 OpenCC 的 stage/group 排序語意。
+
+Python 使用者可以從 PyPI 安裝 `opencc-data`，並透過 `opencc_data` module 定位套件內資源：
+
+```python
+import opencc_data
+
+config_file = opencc_data.config_path("s2t.json")
+dictionary_file = opencc_data.data_path("STCharacters.txt")
+testcases_file = opencc_data.test_data_path("testcases.json")
+```
+
+正式版在 npm 與 PyPI 會使用相同版本號，例如 `1.3.2`。`next` prerelease 則會在 PyPI 使用對應的 PEP 440 版本：`1.3.2-next.20260628` 會以 `1.3.2.dev20260628` 發佈到 PyPI。

opencc_data/__init__.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from importlib import resources
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import PurePosixPath
+
+
+try:
+    __version__ = version("opencc-data")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+
+def data_path(filename: str | None = None):
+    base = resources.files(__name__).joinpath("data")
+    return base if filename is None else base.joinpath(PurePosixPath(filename))
+
+
+def config_path(filename: str | None = None):
+    base = data_path("config")
+    return base if filename is None else base.joinpath(PurePosixPath(filename))
+
+
+def test_data_path(filename: str | None = None):
+    base = resources.files(__name__).joinpath("test_data")
+    return base if filename is None else base.joinpath(PurePosixPath(filename))
+
+
+__all__ = ["__version__", "config_path", "data_path", "test_data_path"]

package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencc-data",
   "version": "1.3.2-next.20260628",
-  "description": "Collection of OpenCC dictionary data",
+  "description": "Collection of OpenCC dictionary data, configs, and test data",
   "main": null,
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"

setup.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py as _build_py
+
+
+ROOT = Path(__file__).parent
+
+
+def read_package_json() -> dict:
+    return json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+
+
+def python_version(npm_version: str) -> str:
+    if re.fullmatch(r"\d+\.\d+\.\d+", npm_version):
+        return npm_version
+
+    dated_next = re.fullmatch(r"(\d+\.\d+\.\d+)-next\.(\d{8})", npm_version)
+    if dated_next:
+        return f"{dated_next.group(1)}.dev{dated_next.group(2)}"
+
+    numbered_next = re.fullmatch(r"(\d+\.\d+\.\d+)-next\.(\d+)", npm_version)
+    if numbered_next:
+        return f"{numbered_next.group(1)}.dev{numbered_next.group(2)}"
+
+    raise ValueError(
+        f"{npm_version!r} is not a supported PyPI version. "
+        "Use a release version like 1.3.2 or a next prerelease like "
+        "1.3.2-next.20260628."
+    )
+
+
+class build_py(_build_py):
+    def run(self) -> None:
+        super().run()
+        package_root = Path(self.build_lib) / "opencc_data"
+        self.copy_tree(ROOT / "data", package_root / "data")
+        self.copy_tree(ROOT / "test-data", package_root / "test_data")
+
+    @staticmethod
+    def copy_tree(src: Path, dst: Path) -> None:
+        if dst.exists():
+            shutil.rmtree(dst)
+        shutil.copytree(src, dst)
+
+
+package_json = read_package_json()
+
+setup(
+    name="opencc-data",
+    version=python_version(package_json["version"]),
+    description="OpenCC dictionary data, configs, and test data",
+    long_description=(ROOT / "README.md").read_text(encoding="utf-8"),
+    long_description_content_type="text/markdown",
+    author="The Ngiox Khyen 2028 Project",
+    license="Apache-2.0",
+    url="https://github.com/nk2028/opencc-data",
+    project_urls={
+        "Homepage": "https://github.com/nk2028/opencc-data",
+        "Bug Tracker": "https://github.com/nk2028/opencc-data/issues",
+        "Source": "https://github.com/nk2028/opencc-data",
+    },
+    packages=["opencc_data"],
+    include_package_data=True,
+    python_requires=">=3.9",
+    classifiers=[
+        "Development Status :: 4 - Beta",
+        "Intended Audience :: Developers",
+        "Natural Language :: Chinese (Simplified)",
+        "Natural Language :: Chinese (Traditional)",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "Topic :: Text Processing :: Linguistic",
+    ],
+    cmdclass={"build_py": build_py},
+)