twlaw 0.1.0__tar.gz

twlaw-0.1.0/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 Yihsuan Chen
+
+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.
+
+---
+
+This license covers the twlaw source code only.
+
+twlaw does not contain or distribute any legal data. Laws and regulations are
+downloaded at runtime by LawDB.refresh() from the Ministry of Justice's
+"Laws & Regulations Database of the Republic of China (Taiwan)"
+(全國法規資料庫), and are licensed separately by the MOJ under the Open
+Government Data License, version 1.0 (政府資料開放授權條款-第1版).
+
+Users of that data must comply with its terms, including the requirement to
+attribute the source. See https://data.gov.tw/license and
+https://law.moj.gov.tw/ for details.

twlaw-0.1.0/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: twlaw
+Version: 0.1.0
+Summary: Queryable local access to Taiwan's national laws and regulations database
+Keywords: taiwan,law,legal,regulations,sqlite,全國法規資料庫
+Author: Yihsuan Chen
+Author-email: Yihsuan Chen <yhc0712.tw@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Text Processing :: Indexing
+Classifier: Natural Language :: Chinese (Traditional)
+Classifier: Natural Language :: English
+Requires-Dist: requests>=2.34.2
+Requires-Dist: truststore>=0.10.4
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/yhc0712/twlaw
+Project-URL: Repository, https://github.com/yhc0712/twlaw
+Project-URL: Issues, https://github.com/yhc0712/twlaw/issues
+Description-Content-Type: text/markdown
+
+# twlaw
+
+Queryable local access to Taiwan's national laws and regulations database
+(全國法規資料庫).
+
+繁體中文說明：[README.zh-TW.md](README.zh-TW.md)
+
+## Why
+
+The MOJ Open API only serves whole-database zip dumps. There is no search, no
+per-record lookup, and chapter headings are flattened into the article list with
+indentation as the only clue to structure. `twlaw` downloads those dumps,
+reconstructs the hierarchy for every article, and stores the result in a local
+SQLite database you can query.
+
+## Install
+
+```bash
+uv add twlaw          # or: pip install twlaw
+```
+
+## Getting started
+
+Building the local database is a separate, explicit step. Do it once:
+
+```python
+from twlaw import LawDB
+
+db = LawDB()          # opens ~/.twlaw/law.db (created if missing)
+db.refresh()          # downloads all 4 datasets — ~2 min, ~520 MB on disk
+```
+
+After that, every query is local and fast (single-digit milliseconds). Nothing
+touches the network again until you call `refresh()` yourself.
+
+```python
+from twlaw import LawDB
+
+db = LawDB()                              # reopens the existing database
+if db.is_empty:                           # guard for first run
+    db.refresh()
+
+for hit in db.search("扣繳義務人", limit=5):
+    print(hit["law_name"], hit["article_no"])
+    print("  ", hit["chapter_path"])
+```
+
+```
+所得稅法 第 94 條
+   第 四 章 稽徵程序 / 第 四 節 扣繳
+```
+
+## API
+
+### `LawDB(path=None)`
+
+Opens (and creates if needed) the SQLite store. Defaults to `~/.twlaw/law.db`;
+pass a path to keep it elsewhere. Usable as a context manager.
+
+```python
+with LawDB("./law.db") as db:
+    ...
+```
+
+### `db.refresh(categories=("law", "order"), langs=("zh", "en"))`
+
+Re-downloads datasets and replaces their rows. Takes ~2 minutes for everything.
+Returns how many laws were stored per dataset. Narrow the scope if you only
+need part of it:
+
+```python
+db.refresh(categories=("law",), langs=("zh",))   # Chinese statutes only, ~20 s
+```
+
+Safe to re-run — rows are replaced, not duplicated.
+
+### `db.search(query, lang="zh", category=None, limit=50, include_repealed=False)`
+
+Full-text search over article text. Returns a list of dicts, best match first:
+
+| key | meaning |
+| --- | --- |
+| `law_id` | law code, e.g. `G0340003` |
+| `law_name` | e.g. `所得稅法` |
+| `category` | `law` or `order` |
+| `article_no` | e.g. `第 94 條` |
+| `article_key` | citable number, e.g. `94` or `4-1` |
+| `content` | the article text |
+| `chapter_path` | reconstructed hierarchy |
+| `seq` | article position within the law |
+
+```python
+db.search("營業稅", category="law")        # statutes only, skip 命令
+db.search("income tax", lang="en")        # English corpus
+db.search("設籍", include_repealed=True)   # include （刪除） articles
+```
+
+### `db.get_law(law, lang="zh")`
+
+One law with all its articles, or `None` if not found. Takes a law **name** or
+a MOJ law code — use whichever you have. Returns the metadata fields plus an
+`articles` list of `{seq, article_no, content, chapter_path}`.
+
+```python
+law = db.get_law("所得稅法")        # by name
+law = db.get_law("G0340003")       # same law, by code
+
+law["name"]              # 所得稅法
+law["id"]                # G0340003
+law["modified_date"]     # 20260911
+len(law["articles"])     # 198
+```
+
+Names match exactly, not by prefix — `"所得稅法"` gives you 所得稅法, never
+所得稅法施行細則. Use `list_laws(name_like=...)` or `search()` when you don't
+know the exact name.
+
+### `db.get_article(law, article, lang="zh")`
+
+One article by the number you'd cite it by, or `None` if there is no such
+article. `4` is 第 4 條 and `"4-1"` is 第 4 條之一 — you never deal with list
+positions or MOJ's label strings.
+
+```python
+db.get_article("所得稅法", 1)       # 第 1 條
+db.get_article("所得稅法", "4-1")   # 第 4 條之一 — a distinct article from 第 4 條
+```
+
+```python
+{'seq': 8, 'article_no': '第 4-1 條', 'article_key': '4-1',
+ 'content': '自中華民國七十九年一月一日起，證券交易所得停止課徵所得稅…',
+ 'chapter_path': '第 一 章 總則 / 第 一 節 一般規定',
+ 'law_id': 'G0340003', 'law_name': '所得稅法'}
+```
+
+Every article everywhere carries this `article_key`, so a `search()` hit can be
+re-fetched or cited directly:
+
+```python
+hit = db.search("扣繳義務人")[0]
+db.get_article(hit["law_name"], hit["article_key"])
+```
+
+### `db.list_laws(category=None, lang="zh", name_like=None)`
+
+Law metadata without article bodies — for browsing or building a picker.
+
+```python
+db.list_laws(name_like="所得稅")
+db.list_laws(category="law")
+```
+
+### `db.update_date()` / `db.is_empty`
+
+MOJ's own publication date for the stored data, and whether anything is stored
+yet. Use `update_date()` to decide if a `refresh()` is worthwhile.
+
+## Examples
+
+Look up a single article:
+
+```python
+print(db.get_article("所得稅法", "4-1")["content"])
+```
+
+Read one law article by article:
+
+```python
+law = db.get_law("所得稅法")
+
+for a in law["articles"]:
+    print(a["article_no"], a["chapter_path"])
+    print(a["content"])
+```
+
+Find which laws mention a term:
+
+```python
+for hit in db.search("營業稅", limit=10):
+    print(hit["law_name"], hit["article_no"])
+```
+
+List every tax law, using MOJ's own classification:
+
+```python
+for l in db.list_laws():
+    if "賦稅" in l["moj_category"]:
+        print(l["id"], l["name"])
+```
+
+### Chunking for RAG
+
+Each article already carries its chapter path, so a chunk is interpretable on
+its own without extra work:
+
+```python
+law = db.get_law("所得稅法")
+
+for a in law["articles"]:
+    chunk = f"{law['name']} {a['article_no']}\n{a['chapter_path']}\n{a['content']}"
+    print(chunk)
+```
+
+## Coverage
+
+| dataset | records |
+| --- | --- |
+| laws, Chinese | 1,347 |
+| orders, Chinese | 10,451 |
+| laws, English | 972 |
+| orders, English | 2,206 |
+
+English records are a separate, smaller corpus — not a translation of every
+Chinese record. A law present in both shares the same `law_id`, so
+`get_law(id, lang="en")` gives you the English text of the same statute.
+
+## Notes
+
+- **Concurrency.** WAL mode is on, so many processes can read at once. Only
+  `refresh()` writes.
+- **Search.** FTS5 with the `trigram` tokenizer, which is what makes Chinese
+  substring search work: the default `unicode61` treats an unbroken run of CJK
+  as one token, which would find 50 articles for 所得稅 instead of ~1,400.
+  Queries under 3 characters fall back to `LIKE`.
+- **Storage.** Plain SQLite tables (`laws`, `articles`), so the file is readable
+  from any language, not only Python.
+
+## Data source and licensing
+
+`twlaw` itself is MIT licensed, and the package ships **no legal data**. Laws
+and regulations are downloaded at runtime by `refresh()` from the
+[MOJ Open API](https://law.moj.gov.tw/api/swagger/index.html).
+
+That data is published by the Ministry of Justice under the
+[Open Government Data License v1.0](https://data.gov.tw/license)
+(政府資料開放授權條款-第1版), which permits free reuse, modification and
+redistribution — **provided you attribute the source**. If you ship a product
+built on this data, credit it, for example:
+
+> Data source: Laws & Regulations Database of the Republic of China (Taiwan),
+> Ministry of Justice — https://law.moj.gov.tw/
+
+Two things worth knowing if you build on this:
+
+- **The MOJ database is authoritative; this is a convenience mirror.** `twlaw`
+  reconstructs chapter hierarchy and splits articles, which is ordinary
+  permitted adaptation — but the result is a *parsed* view. Cite the official
+  text for anything that matters.
+- **Don't misrepresent the content.** The license asks that the data not be
+  altered in ways that make the displayed information contradict the original.
+
+This section is a summary, not legal advice. Read the license if the
+distinction matters to you.

twlaw-0.1.0/README.md

@@ -0,0 +1,253 @@
+# twlaw
+
+Queryable local access to Taiwan's national laws and regulations database
+(全國法規資料庫).
+
+繁體中文說明：[README.zh-TW.md](README.zh-TW.md)
+
+## Why
+
+The MOJ Open API only serves whole-database zip dumps. There is no search, no
+per-record lookup, and chapter headings are flattened into the article list with
+indentation as the only clue to structure. `twlaw` downloads those dumps,
+reconstructs the hierarchy for every article, and stores the result in a local
+SQLite database you can query.
+
+## Install
+
+```bash
+uv add twlaw          # or: pip install twlaw
+```
+
+## Getting started
+
+Building the local database is a separate, explicit step. Do it once:
+
+```python
+from twlaw import LawDB
+
+db = LawDB()          # opens ~/.twlaw/law.db (created if missing)
+db.refresh()          # downloads all 4 datasets — ~2 min, ~520 MB on disk
+```
+
+After that, every query is local and fast (single-digit milliseconds). Nothing
+touches the network again until you call `refresh()` yourself.
+
+```python
+from twlaw import LawDB
+
+db = LawDB()                              # reopens the existing database
+if db.is_empty:                           # guard for first run
+    db.refresh()
+
+for hit in db.search("扣繳義務人", limit=5):
+    print(hit["law_name"], hit["article_no"])
+    print("  ", hit["chapter_path"])
+```
+
+```
+所得稅法 第 94 條
+   第 四 章 稽徵程序 / 第 四 節 扣繳
+```
+
+## API
+
+### `LawDB(path=None)`
+
+Opens (and creates if needed) the SQLite store. Defaults to `~/.twlaw/law.db`;
+pass a path to keep it elsewhere. Usable as a context manager.
+
+```python
+with LawDB("./law.db") as db:
+    ...
+```
+
+### `db.refresh(categories=("law", "order"), langs=("zh", "en"))`
+
+Re-downloads datasets and replaces their rows. Takes ~2 minutes for everything.
+Returns how many laws were stored per dataset. Narrow the scope if you only
+need part of it:
+
+```python
+db.refresh(categories=("law",), langs=("zh",))   # Chinese statutes only, ~20 s
+```
+
+Safe to re-run — rows are replaced, not duplicated.
+
+### `db.search(query, lang="zh", category=None, limit=50, include_repealed=False)`
+
+Full-text search over article text. Returns a list of dicts, best match first:
+
+| key | meaning |
+| --- | --- |
+| `law_id` | law code, e.g. `G0340003` |
+| `law_name` | e.g. `所得稅法` |
+| `category` | `law` or `order` |
+| `article_no` | e.g. `第 94 條` |
+| `article_key` | citable number, e.g. `94` or `4-1` |
+| `content` | the article text |
+| `chapter_path` | reconstructed hierarchy |
+| `seq` | article position within the law |
+
+```python
+db.search("營業稅", category="law")        # statutes only, skip 命令
+db.search("income tax", lang="en")        # English corpus
+db.search("設籍", include_repealed=True)   # include （刪除） articles
+```
+
+### `db.get_law(law, lang="zh")`
+
+One law with all its articles, or `None` if not found. Takes a law **name** or
+a MOJ law code — use whichever you have. Returns the metadata fields plus an
+`articles` list of `{seq, article_no, content, chapter_path}`.
+
+```python
+law = db.get_law("所得稅法")        # by name
+law = db.get_law("G0340003")       # same law, by code
+
+law["name"]              # 所得稅法
+law["id"]                # G0340003
+law["modified_date"]     # 20260911
+len(law["articles"])     # 198
+```
+
+Names match exactly, not by prefix — `"所得稅法"` gives you 所得稅法, never
+所得稅法施行細則. Use `list_laws(name_like=...)` or `search()` when you don't
+know the exact name.
+
+### `db.get_article(law, article, lang="zh")`
+
+One article by the number you'd cite it by, or `None` if there is no such
+article. `4` is 第 4 條 and `"4-1"` is 第 4 條之一 — you never deal with list
+positions or MOJ's label strings.
+
+```python
+db.get_article("所得稅法", 1)       # 第 1 條
+db.get_article("所得稅法", "4-1")   # 第 4 條之一 — a distinct article from 第 4 條
+```
+
+```python
+{'seq': 8, 'article_no': '第 4-1 條', 'article_key': '4-1',
+ 'content': '自中華民國七十九年一月一日起，證券交易所得停止課徵所得稅…',
+ 'chapter_path': '第 一 章 總則 / 第 一 節 一般規定',
+ 'law_id': 'G0340003', 'law_name': '所得稅法'}
+```
+
+Every article everywhere carries this `article_key`, so a `search()` hit can be
+re-fetched or cited directly:
+
+```python
+hit = db.search("扣繳義務人")[0]
+db.get_article(hit["law_name"], hit["article_key"])
+```
+
+### `db.list_laws(category=None, lang="zh", name_like=None)`
+
+Law metadata without article bodies — for browsing or building a picker.
+
+```python
+db.list_laws(name_like="所得稅")
+db.list_laws(category="law")
+```
+
+### `db.update_date()` / `db.is_empty`
+
+MOJ's own publication date for the stored data, and whether anything is stored
+yet. Use `update_date()` to decide if a `refresh()` is worthwhile.
+
+## Examples
+
+Look up a single article:
+
+```python
+print(db.get_article("所得稅法", "4-1")["content"])
+```
+
+Read one law article by article:
+
+```python
+law = db.get_law("所得稅法")
+
+for a in law["articles"]:
+    print(a["article_no"], a["chapter_path"])
+    print(a["content"])
+```
+
+Find which laws mention a term:
+
+```python
+for hit in db.search("營業稅", limit=10):
+    print(hit["law_name"], hit["article_no"])
+```
+
+List every tax law, using MOJ's own classification:
+
+```python
+for l in db.list_laws():
+    if "賦稅" in l["moj_category"]:
+        print(l["id"], l["name"])
+```
+
+### Chunking for RAG
+
+Each article already carries its chapter path, so a chunk is interpretable on
+its own without extra work:
+
+```python
+law = db.get_law("所得稅法")
+
+for a in law["articles"]:
+    chunk = f"{law['name']} {a['article_no']}\n{a['chapter_path']}\n{a['content']}"
+    print(chunk)
+```
+
+## Coverage
+
+| dataset | records |
+| --- | --- |
+| laws, Chinese | 1,347 |
+| orders, Chinese | 10,451 |
+| laws, English | 972 |
+| orders, English | 2,206 |
+
+English records are a separate, smaller corpus — not a translation of every
+Chinese record. A law present in both shares the same `law_id`, so
+`get_law(id, lang="en")` gives you the English text of the same statute.
+
+## Notes
+
+- **Concurrency.** WAL mode is on, so many processes can read at once. Only
+  `refresh()` writes.
+- **Search.** FTS5 with the `trigram` tokenizer, which is what makes Chinese
+  substring search work: the default `unicode61` treats an unbroken run of CJK
+  as one token, which would find 50 articles for 所得稅 instead of ~1,400.
+  Queries under 3 characters fall back to `LIKE`.
+- **Storage.** Plain SQLite tables (`laws`, `articles`), so the file is readable
+  from any language, not only Python.
+
+## Data source and licensing
+
+`twlaw` itself is MIT licensed, and the package ships **no legal data**. Laws
+and regulations are downloaded at runtime by `refresh()` from the
+[MOJ Open API](https://law.moj.gov.tw/api/swagger/index.html).
+
+That data is published by the Ministry of Justice under the
+[Open Government Data License v1.0](https://data.gov.tw/license)
+(政府資料開放授權條款-第1版), which permits free reuse, modification and
+redistribution — **provided you attribute the source**. If you ship a product
+built on this data, credit it, for example:
+
+> Data source: Laws & Regulations Database of the Republic of China (Taiwan),
+> Ministry of Justice — https://law.moj.gov.tw/
+
+Two things worth knowing if you build on this:
+
+- **The MOJ database is authoritative; this is a convenience mirror.** `twlaw`
+  reconstructs chapter hierarchy and splits articles, which is ordinary
+  permitted adaptation — but the result is a *parsed* view. Cite the official
+  text for anything that matters.
+- **Don't misrepresent the content.** The license asks that the data not be
+  altered in ways that make the displayed information contradict the original.
+
+This section is a summary, not legal advice. Read the license if the
+distinction matters to you.

twlaw-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "twlaw"
+version = "0.1.0"
+description = "Queryable local access to Taiwan's national laws and regulations database"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "taiwan",
+    "law",
+    "legal",
+    "regulations",
+    "sqlite",
+    "全國法規資料庫",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Legal Industry",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Text Processing :: Indexing",
+    "Natural Language :: Chinese (Traditional)",
+    "Natural Language :: English",
+]
+dependencies = [
+    "requests>=2.34.2",
+    "truststore>=0.10.4",
+]
+
+[[project.authors]]
+name = "Yihsuan Chen"
+email = "yhc0712.tw@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/yhc0712/twlaw"
+Repository = "https://github.com/yhc0712/twlaw"
+Issues = "https://github.com/yhc0712/twlaw/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]

twlaw-0.1.0/pyproject.toml.orig

@@ -0,0 +1,44 @@
+[project]
+name = "twlaw"
+version = "0.1.0"
+description = "Queryable local access to Taiwan's national laws and regulations database"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Yihsuan Chen", email = "yhc0712.tw@gmail.com" }]
+keywords = ["taiwan", "law", "legal", "regulations", "sqlite", "全國法規資料庫"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Legal Industry",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Text Processing :: Indexing",
+    "Natural Language :: Chinese (Traditional)",
+    "Natural Language :: English",
+]
+dependencies = [
+    "requests>=2.34.2",
+    "truststore>=0.10.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/yhc0712/twlaw"
+Repository = "https://github.com/yhc0712/twlaw"
+Issues = "https://github.com/yhc0712/twlaw/issues"
+
+[build-system]
+requires = ["uv_build>=0.12.10,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]

twlaw-0.1.0/src/twlaw/__init__.py

@@ -0,0 +1,15 @@
+"""Queryable local access to Taiwan's national laws and regulations database.
+
+    from twlaw import LawDB
+
+    db = LawDB()
+    db.refresh()                       # download and build the local store
+    db.search("所得稅")                 # full-text search across articles
+    db.get_law("所得稅法")              # one law with chapter-aware articles
+    db.get_article("所得稅法", "4-1")   # 第 4 條之一
+"""
+
+from .db import DEFAULT_PATH, SCHEMA_VERSION, LawDB
+from .fetch import CATEGORIES, LANGS
+
+__all__ = ["LawDB", "DEFAULT_PATH", "SCHEMA_VERSION", "CATEGORIES", "LANGS"]

twlaw-0.1.0/src/twlaw/db.py

@@ -0,0 +1,319 @@
+"""Local SQLite store and query API."""
+
+import sqlite3
+from pathlib import Path
+
+from .fetch import CATEGORIES, LANGS, fetch_dataset
+from .parse import iter_rows
+
+DEFAULT_PATH = Path.home() / ".twlaw" / "law.db"
+
+# Bump whenever the table layout changes. A database built by an older version
+# is discarded and rebuilt rather than migrated: it is a cache of an upstream
+# dataset, so re-downloading is simpler and cheaper than writing migrations.
+SCHEMA_VERSION = 1
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS laws (
+    id             TEXT NOT NULL,
+    lang           TEXT NOT NULL,
+    category       TEXT NOT NULL,
+    name           TEXT NOT NULL,
+    name_en        TEXT,
+    level          TEXT,
+    moj_category   TEXT,
+    modified_date  TEXT,
+    effective_date TEXT,
+    effective_note TEXT,
+    abandon_note   TEXT,
+    foreword       TEXT,
+    histories      TEXT,
+    url            TEXT,
+    update_date    TEXT,
+    PRIMARY KEY (id, lang)
+);
+
+CREATE TABLE IF NOT EXISTS articles (
+    rowid        INTEGER PRIMARY KEY,
+    law_id       TEXT NOT NULL,
+    lang         TEXT NOT NULL,
+    seq          INTEGER NOT NULL,
+    article_no   TEXT,
+    article_key  TEXT,
+    content      TEXT,
+    chapter_path TEXT,
+    UNIQUE (law_id, lang, seq)
+);
+
+CREATE INDEX IF NOT EXISTS idx_articles_key ON articles(law_id, lang, article_key);
+
+CREATE INDEX IF NOT EXISTS idx_laws_name ON laws(name);
+CREATE INDEX IF NOT EXISTS idx_laws_category ON laws(category, lang);
+
+-- 'trigram' rather than the default tokenizer: unicode61 treats an unbroken
+-- run of CJK as a single token, so searching 所得稅 would miss every article
+-- where it sits mid-phrase (50 hits instead of ~1400). Trigram indexes
+-- 3-character windows, which matches Chinese substrings correctly. Its
+-- tradeoff is that queries shorter than 3 characters never match, so search()
+-- falls back to LIKE for those.
+-- content='articles' makes this an external-content index: FTS stores only the
+-- index, not a second copy of the text (which cost ~180MB).
+CREATE VIRTUAL TABLE IF NOT EXISTS articles_fts USING fts5(
+    content,
+    chapter_path,
+    content = 'articles',
+    content_rowid = 'rowid',
+    tokenize = 'trigram'
+);
+"""
+
+_FTS_MIN_QUERY = 3
+
+_LAW_COLUMNS = (
+    "id", "lang", "category", "name", "name_en", "level", "moj_category",
+    "modified_date", "effective_date", "effective_note", "abandon_note",
+    "foreword", "histories", "url", "update_date",
+)
+
+
+class LawDB:
+    """Query interface over a local copy of the MOJ law database."""
+
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else DEFAULT_PATH
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._connect()
+
+        if self._stored_version() not in (0, SCHEMA_VERSION):
+            self._rebuild()
+        self._conn.executescript(_SCHEMA)
+        self._conn.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+
+    def _stored_version(self) -> int:
+        """0 for a database this version can still use as-is, else its version."""
+        version = self._conn.execute("PRAGMA user_version").fetchone()[0]
+        if version:
+            return version
+        # Written before versioning existed; usable only if it already has the
+        # current columns.
+        columns = {r[1] for r in self._conn.execute("PRAGMA table_info(articles)")}
+        return 0 if not columns or "article_key" in columns else -1
+
+    def _connect(self) -> None:
+        self._conn = sqlite3.connect(self.path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+
+    def _rebuild(self) -> None:
+        """Discard a database written by an incompatible version of twlaw.
+
+        Drops the objects rather than deleting the file: on Windows the file
+        cannot be unlinked while another process still has it open.
+        """
+        with self._conn:
+            for kind, name in self._conn.execute(
+                "SELECT type, name FROM sqlite_master"
+                " WHERE type IN ('table','view') AND name NOT LIKE 'sqlite_%'"
+            ).fetchall():
+                self._conn.execute(f'DROP {kind} IF EXISTS "{name}"')
+
+    def close(self) -> None:
+        self._conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    @property
+    def is_empty(self) -> bool:
+        return self._conn.execute("SELECT COUNT(*) FROM laws").fetchone()[0] == 0
+
+    def update_date(self, category: str = "law", lang: str = "zh") -> str | None:
+        row = self._conn.execute(
+            "SELECT update_date FROM laws WHERE category=? AND lang=? LIMIT 1",
+            (category, lang),
+        ).fetchone()
+        return row[0] if row else None
+
+    def refresh(self, categories=CATEGORIES, langs=LANGS) -> dict[tuple[str, str], int]:
+        """Re-download the given datasets and replace their rows.
+
+        Returns the number of laws stored per ``(category, lang)``.
+        """
+        counts = {}
+        for category in categories:
+            for lang in langs:
+                dataset = fetch_dataset(category, lang)
+                counts[(category, lang)] = self._replace(dataset, category, lang)
+        # Replacing rows leaves the FTS index in many small segments; merging
+        # them keeps the file from growing on every refresh.
+        with self._conn:
+            self._conn.execute("INSERT INTO articles_fts (articles_fts) VALUES ('optimize')")
+        self._conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        return counts
+
+    def _replace(self, dataset: dict, category: str, lang: str) -> int:
+        law_params = []
+        article_params = []
+
+        for law_row, article_rows in iter_rows(dataset, category, lang):
+            law_params.append(tuple(law_row[c] for c in _LAW_COLUMNS))
+            for a in article_rows:
+                article_params.append(
+                    (
+                        a["law_id"], lang, a["seq"], a["article_no"],
+                        a["article_key"], a["content"], a["chapter_path"],
+                    )
+                )
+
+        placeholders = ",".join("?" * len(_LAW_COLUMNS))
+        with self._conn:
+            # The FTS index mirrors `articles` by rowid, so drop its entries for
+            # the rows being replaced before those rows disappear.
+            self._conn.execute(
+                "INSERT INTO articles_fts (articles_fts, rowid, content, chapter_path)"
+                " SELECT 'delete', a.rowid, a.content, a.chapter_path FROM articles a"
+                "  JOIN laws l ON l.id = a.law_id AND l.lang = a.lang"
+                " WHERE l.category = ? AND l.lang = ?",
+                (category, lang),
+            )
+            self._conn.execute(
+                "DELETE FROM articles WHERE lang = ? AND law_id IN"
+                " (SELECT id FROM laws WHERE category = ? AND lang = ?)",
+                (lang, category, lang),
+            )
+            self._conn.execute("DELETE FROM laws WHERE category=? AND lang=?", (category, lang))
+
+            self._conn.executemany(f"INSERT INTO laws VALUES ({placeholders})", law_params)
+            self._conn.executemany(
+                "INSERT INTO articles"
+                " (law_id, lang, seq, article_no, article_key, content, chapter_path)"
+                " VALUES (?,?,?,?,?,?,?)",
+                article_params,
+            )
+            self._conn.execute(
+                "INSERT INTO articles_fts (rowid, content, chapter_path)"
+                " SELECT a.rowid, a.content, a.chapter_path FROM articles a"
+                "  JOIN laws l ON l.id = a.law_id AND l.lang = a.lang"
+                " WHERE l.category = ? AND l.lang = ?",
+                (category, lang),
+            )
+        return len(law_params)
+
+    def _ensure_data(self) -> None:
+        if self.is_empty:
+            raise RuntimeError("Local database is empty; call refresh() first.")
+
+    def list_laws(self, category: str | None = None, lang: str = "zh", name_like: str | None = None) -> list[dict]:
+        sql = "SELECT * FROM laws WHERE lang=?"
+        params: list = [lang]
+        if category:
+            sql += " AND category=?"
+            params.append(category)
+        if name_like:
+            sql += " AND name LIKE ?"
+            params.append(f"%{name_like}%")
+        sql += " ORDER BY name"
+        return [dict(r) for r in self._conn.execute(sql, params)]
+
+    def get_law(self, law: str, lang: str = "zh") -> dict | None:
+        """Return one law with its articles, each carrying its chapter path.
+
+        ``law`` may be a law name (``"所得稅法"``) or a MOJ law code
+        (``"G0340003"``). Names are matched exactly, never by prefix, because
+        法規 names nest — 所得稅法 is a prefix of 所得稅法施行細則.
+        """
+        self._ensure_data()
+        row = self._conn.execute(
+            "SELECT * FROM laws WHERE lang=? AND (id=? OR name=? OR name_en=?)",
+            (lang, law, law, law),
+        ).fetchone()
+        if row is None:
+            return None
+        result = dict(row)
+        result["articles"] = [
+            dict(r)
+            for r in self._conn.execute(
+                "SELECT seq, article_no, article_key, content, chapter_path FROM articles"
+                " WHERE law_id=? AND lang=? ORDER BY seq",
+                (result["id"], lang),
+            )
+        ]
+        return result
+
+    def get_article(self, law: str, article: str | int, lang: str = "zh") -> dict | None:
+        """Return one article by its number, or ``None`` if there is no such article.
+
+        ``article`` is the number as it is cited: ``4`` or ``"4"`` for 第 4 條,
+        ``"4-1"`` for 第 4 條之一. ``law`` accepts a name or a law code, as in
+        :meth:`get_law`.
+        """
+        self._ensure_data()
+        row = self._conn.execute(
+            "SELECT a.seq, a.article_no, a.article_key, a.content, a.chapter_path,"
+            "       l.id AS law_id, l.name AS law_name"
+            "  FROM articles a"
+            "  JOIN laws l ON l.id = a.law_id AND l.lang = a.lang"
+            " WHERE a.lang = ? AND a.article_key = ?"
+            "   AND (l.id = ? OR l.name = ? OR l.name_en = ?)",
+            (lang, str(article).strip(), law, law, law),
+        ).fetchone()
+        return dict(row) if row else None
+
+    def search(
+        self,
+        query: str,
+        lang: str = "zh",
+        category: str | None = None,
+        limit: int = 50,
+        include_repealed: bool = False,
+    ) -> list[dict]:
+        """Full-text search over article content.
+
+        Returns article rows annotated with their law's id and name, best match
+        first. ``chapter_path`` is searchable but weighted far below ``content``
+        so that matching a chapter title alone does not outrank a real hit.
+        Repealed articles (``（刪除）`` / "(Deleted)") are excluded by default.
+        """
+        self._ensure_data()
+        query = query.strip()
+        if not query:
+            return []
+
+        select = (
+            "SELECT a.law_id, l.name AS law_name, l.category, a.seq,"
+            "       a.article_no, a.article_key, a.content, a.chapter_path"
+        )
+        params: list = []
+
+        if len(query) >= _FTS_MIN_QUERY:
+            sql = (
+                f"{select}"
+                "  FROM articles_fts f"
+                "  JOIN articles a ON a.rowid = f.rowid"
+                "  JOIN laws l ON l.id = a.law_id AND l.lang = a.lang"
+                " WHERE articles_fts MATCH ? AND a.lang = ?"
+            )
+            params += [f'"{query}"', lang]
+            order = " ORDER BY bm25(articles_fts, 10.0, 1.0)"
+        else:
+            # Trigram FTS cannot match queries this short.
+            sql = (
+                f"{select}"
+                "  FROM articles a"
+                "  JOIN laws l ON l.id = a.law_id AND l.lang = a.lang"
+                " WHERE a.lang = ? AND a.content LIKE ?"
+            )
+            params += [lang, f"%{query}%"]
+            order = " ORDER BY a.law_id, a.seq"
+
+        if category:
+            sql += " AND l.category = ?"
+            params.append(category)
+        if not include_repealed:
+            sql += " AND a.content NOT LIKE '%刪除%' AND a.content NOT LIKE '%(Deleted)%'"
+
+        params.append(limit)
+        return [dict(r) for r in self._conn.execute(sql + order + " LIMIT ?", params)]

twlaw-0.1.0/src/twlaw/fetch.py

@@ -0,0 +1,40 @@
+"""Download raw law datasets from the MOJ Open API."""
+
+import io
+import json
+import zipfile
+
+import truststore
+
+truststore.inject_into_ssl()
+
+import requests
+
+BASE_URL = "https://law.moj.gov.tw/api"
+
+LANGS = ("zh", "en")
+CATEGORIES = ("law", "order")
+
+_LANG_PATH = {"zh": "Ch", "en": "En"}
+_CATEGORY_PATH = {"law": "Law", "order": "Order"}
+
+
+def fetch_dataset(category: str, lang: str, timeout: int = 120) -> dict:
+    """Return the decoded dataset for one (category, lang) pair.
+
+    The endpoint serves a zip archive; the payload is the single .json member.
+    """
+    if lang not in LANGS:
+        raise ValueError(f"lang must be one of {LANGS}, got {lang!r}")
+    if category not in CATEGORIES:
+        raise ValueError(f"category must be one of {CATEGORIES}, got {category!r}")
+
+    url = f"{BASE_URL}/{_LANG_PATH[lang]}/{_CATEGORY_PATH[category]}/JSON"
+    resp = requests.get(url, timeout=timeout)
+    resp.raise_for_status()
+
+    with zipfile.ZipFile(io.BytesIO(resp.content)) as zf:
+        name = next(n for n in zf.namelist() if n.lower().endswith(".json"))
+        with zf.open(name) as fh:
+            # The MOJ files carry a UTF-8 BOM.
+            return json.loads(fh.read().decode("utf-8-sig"))

twlaw-0.1.0/src/twlaw/parse.py

@@ -0,0 +1,124 @@
+"""Normalize MOJ records into flat law/article rows.
+
+MOJ interleaves structural headings and real articles in one article list:
+``ArticleType == "C"`` rows are headings whose leading indentation encodes depth
+(0=編, 3=章, 6=節, 9=款, 12=目), while ``ArticleType == "A"`` rows are articles
+carrying no hierarchy of their own. Each article's position in the hierarchy is
+therefore implicit, and is resolved here by walking the list and tracking the
+heading stack.
+
+The English datasets use the same layout but prefix every field name with
+``Eng`` and omit the category/effective-date fields, so field access goes
+through a per-language field map.
+"""
+
+import re
+
+_PCODE_RE = re.compile(r"pcode=([A-Za-z0-9]+)", re.IGNORECASE)
+_INDENT_RE = re.compile(r"^(\s*)")
+_INDENT_UNIT = 3
+
+# "第 4-1 條" / "Article 4-1" -> "4-1". Both languages also use a bare number
+# for a handful of appendix-style entries.
+_ARTICLE_NO_RE = re.compile(r"(\d+(?:-\d+)?)")
+
+
+def article_key(article_no: str) -> str:
+    """Return the citable number in an article label, e.g. ``第 4-1 條`` -> ``4-1``."""
+    match = _ARTICLE_NO_RE.search(article_no or "")
+    return match.group(1) if match else ""
+
+# The two language variants name the same fields differently.
+_FIELDS = {
+    "zh": {
+        "url": "LawURL",
+        "modified_date": "LawModifiedDate",
+        "abandon_note": "LawAbandonNote",
+        "foreword": "LawForeword",
+        "histories": "LawHistories",
+        "articles": "LawArticles",
+        "article_type": "ArticleType",
+        "article_no": "ArticleNo",
+        "article_content": "ArticleContent",
+    },
+    "en": {
+        "url": "EngLawURL",
+        "modified_date": "EngLawModifiedDate",
+        "abandon_note": "EngLawAbandonNote",
+        "foreword": "EngLawForeword",
+        "histories": "EngLawHistories",
+        "articles": "EngLawArticles",
+        "article_type": "EngArticleType",
+        "article_no": "EngArticleNo",
+        "article_content": "EngArticleContent",
+    },
+}
+
+
+def _pcode(law: dict, url_field: str) -> str | None:
+    match = _PCODE_RE.search(law.get(url_field, "") or "")
+    return match.group(1) if match else None
+
+
+def _heading_depth(content: str) -> int:
+    return len(_INDENT_RE.match(content).group(1)) // _INDENT_UNIT
+
+
+def iter_rows(dataset: dict, category: str, lang: str):
+    """Yield ``(law_row, article_rows)`` pairs for one fetched dataset."""
+    update_date = dataset.get("UpdateDate", "")
+    f = _FIELDS[lang]
+
+    for law in dataset.get("Laws", []):
+        law_id = _pcode(law, f["url"])
+        if law_id is None:
+            continue
+
+        law_row = {
+            "id": law_id,
+            "lang": lang,
+            "category": category,
+            "name": law.get("LawName", ""),
+            "name_en": law.get("EngLawName", ""),
+            "level": law.get("LawLevel", ""),
+            "moj_category": law.get("LawCategory", ""),
+            "modified_date": law.get(f["modified_date"], ""),
+            "effective_date": law.get("LawEffectiveDate", ""),
+            "effective_note": law.get("LawEffectiveNote", ""),
+            "abandon_note": law.get(f["abandon_note"], ""),
+            "foreword": law.get(f["foreword"], ""),
+            "histories": law.get(f["histories"], ""),
+            "url": law.get(f["url"], ""),
+            "update_date": update_date,
+        }
+
+        article_rows = []
+        stack: list[str] = []
+        seq = 0
+
+        for entry in law.get(f["articles"]) or []:
+            content = entry.get(f["article_content"], "") or ""
+
+            if entry.get(f["article_type"]) == "C":
+                depth = _heading_depth(content)
+                del stack[depth:]
+                # Pad when a level is skipped so depth stays the index.
+                while len(stack) < depth:
+                    stack.append("")
+                stack.append(content.strip())
+                continue
+
+            article_no = (entry.get(f["article_no"]) or "").strip()
+            article_rows.append(
+                {
+                    "law_id": law_id,
+                    "seq": seq,
+                    "article_no": article_no,
+                    "article_key": article_key(article_no),
+                    "content": content,
+                    "chapter_path": " / ".join(p for p in stack if p),
+                }
+            )
+            seq += 1
+
+        yield law_row, article_rows