Merge pull request #1317 from PyThaiNLP/copilot/fix-db-json-creation-issue

Lazy create db.json; Introduce PYTHAINLP_READ_ONLY with scoped write protection

Author: bact

CHANGELOG.md

@@ -35,6 +35,8 @@ The minimum requirement is now Python 3.9.
   (`dependency_parsing`, engine="attaparse") (#1303)
 - `pythainlp.is_offline_mode()` helper function (#1306)
 - Thai consonant cluster detection (`check_khuap_klam`) (#1308)
+- `pythainlp.is_read_only_mode()` helper function;
+  use `PYTHAINLP_READ_ONLY=1` to prevent all write operations
 
 ### Changed
 
@@ -59,6 +61,8 @@ The minimum requirement is now Python 3.9.
 - `PYTHAINLP_DATA_DIR` env var; use `PYTHAINLP_DATA` instead
   (follows `NLTK_DATA` convention from NLTK)
   `PYTHAINLP_DATA_DIR` will be removed in future version (#1306)
+- `PYTHAINLP_READ_MODE` env var; use `PYTHAINLP_READ_ONLY` instead.
+  Setting both at the same time raises `ValueError`.
 
 ### Removed
 
@@ -75,6 +79,8 @@ The minimum requirement is now Python 3.9.
 - Kho Khon alphabet issue in `tltk` transliteration (#1187)
 - Suppress Gensim duplicate-word warnings when loading word2vec
   binary files (#1316)
+- `db.json` is no longer created on import; it is created lazily only
+  when a corpus is first downloaded (#1317)
 
 ## [5.2.0] - 2025-12-20
 

README.md

@@ -86,18 +86,47 @@ inside the function that will be distributed to worker nodes.
 See details in
 [the documentation](https://pythainlp.org/dev-docs/notes/installation.html).
 
+## Environment variables
+
+| Variable | Description | Status |
+|---|---|---|
+| `PYTHAINLP_DATA` | Path to the data directory (default: `~/pythainlp-data`). | Current |
+| `PYTHAINLP_DATA_DIR` | Legacy alias for `PYTHAINLP_DATA`. Emits a `DeprecationWarning`. Setting both raises `ValueError`. | Deprecated; use `PYTHAINLP_DATA` |
+| `PYTHAINLP_OFFLINE` | Set to `1` to disable automatic corpus downloads. Explicit `download()` calls still work. | Current |
+| `PYTHAINLP_READ_ONLY` | Set to `1` to enable read-only mode, which prevents implicit background writes to PyThaiNLP's internal data directory (corpus downloads, catalog updates, directory creation). Explicit user-initiated saves to user-specified paths are unaffected. | Current |
+| `PYTHAINLP_READ_MODE` | Legacy alias for `PYTHAINLP_READ_ONLY`. Emits a `DeprecationWarning`. Setting both raises `ValueError`. | Deprecated; use `PYTHAINLP_READ_ONLY` |
+
 ### Offline mode
 
-Set `PYTHAINLP_OFFLINE=1` to disable automatic corpus downloads.
+Set `PYTHAINLP_OFFLINE=1` to disable **automatic** corpus downloads.
 When this variable is set and a corpus is not already cached locally,
 a `FileNotFoundError` is raised instead of attempting a network download.
+Explicit calls to `pythainlp.corpus.download()` are unaffected.
 Use `pythainlp.is_offline_mode()` to check the current state programmatically.
 
 ```python
 import pythainlp
 print(pythainlp.is_offline_mode())  # True if PYTHAINLP_OFFLINE=1
 ```
 
+### Read-only mode
+
+Set `PYTHAINLP_READ_ONLY=1` to prevent implicit background writes to PyThaiNLP's
+internal data directory. This blocks corpus downloads, catalog updates, and
+automatic data directory creation — writes that happen as side effects the user
+may not be aware of.
+
+Operations where the user explicitly specifies an output path are unaffected
+(e.g., `model.save("path")`, `tagger.train(..., save_loc="path")`,
+`thainlp misspell --output myfile.txt`).
+
+Use `pythainlp.is_read_only_mode()` to check the current state programmatically.
+
+```python
+import pythainlp
+print(pythainlp.is_read_only_mode())  # True if PYTHAINLP_READ_ONLY=1
+```
+
 ## Testing
 
 We test core functionalities on all officially supported Python versions.

README_TH.md

@@ -117,6 +117,46 @@ PyThaiNLP ดาวน์โหลดข้อมูล (ดูแค็ตต
 ภายในฟังก์ชันที่จะถูกกระจายไปยัง worker nodes
 ดูรายละเอียดใน[เอกสาร](https://pythainlp.org/dev-docs/notes/installation.html)
 
+## Environment variables
+
+| ตัวแปร | คำอธิบาย | สถานะ |
+|---|---|---|
+| `PYTHAINLP_DATA` | พาธของไดเรกทอรีข้อมูล (ค่าเริ่มต้น: `~/pythainlp-data`) | ปัจจุบัน |
+| `PYTHAINLP_DATA_DIR` | ชื่อเดิมของ `PYTHAINLP_DATA` แสดง `DeprecationWarning` และหากตั้งค่าทั้งสองพร้อมกันจะเกิด `ValueError` | เลิกใช้แล้ว; ใช้ `PYTHAINLP_DATA` แทน |
+| `PYTHAINLP_OFFLINE` | ตั้งเป็น `1` เพื่อปิดการดาวน์โหลด corpus อัตโนมัติ การเรียก `download()` โดยตรงยังคงใช้งานได้ | ปัจจุบัน |
+| `PYTHAINLP_READ_ONLY` | ตั้งเป็น `1` เพื่อเปิดโหมดอ่านอย่างเดียว ป้องกันการเขียนพื้นหลังที่ผู้ใช้อาจไม่ทราบ (ดาวน์โหลด corpus, อัปเดตแค็ตตาล็อก, สร้างไดเรกทอรี) การบันทึกไฟล์ที่ผู้ใช้ระบุเองไม่ได้รับผลกระทบ | ปัจจุบัน |
+| `PYTHAINLP_READ_MODE` | ชื่อเดิมของ `PYTHAINLP_READ_ONLY` แสดง `DeprecationWarning` และหากตั้งค่าทั้งสองพร้อมกันจะเกิด `ValueError` | เลิกใช้แล้ว; ใช้ `PYTHAINLP_READ_ONLY` แทน |
+
+### โหมดออฟไลน์
+
+ตั้งค่า `PYTHAINLP_OFFLINE=1` เพื่อปิดการดาวน์โหลด corpus **อัตโนมัติ**
+เมื่อตั้งค่าตัวแปรนี้และ corpus ไม่มีในเครื่อง จะเกิด `FileNotFoundError`
+แทนที่จะพยายามดาวน์โหลดจากเครือข่าย
+การเรียก `pythainlp.corpus.download()` โดยตรงยังคงทำงานได้ตามปกติ
+ใช้ `pythainlp.is_offline_mode()` เพื่อตรวจสอบสถานะปัจจุบันในโค้ด
+
+```python
+import pythainlp
+print(pythainlp.is_offline_mode())  # True ถ้า PYTHAINLP_OFFLINE=1
+```
+
+### โหมดอ่านอย่างเดียว
+
+ตั้งค่า `PYTHAINLP_READ_ONLY=1` เพื่อป้องกันการเขียนพื้นหลังที่เกิดขึ้นโดยอัตโนมัติ
+ในไดเรกทอรีข้อมูลภายในของ PyThaiNLP ได้แก่ การดาวน์โหลด corpus, การอัปเดตแค็ตตาล็อก
+และการสร้างไดเรกทอรีข้อมูล — การเขียนเหล่านี้เกิดขึ้นเป็นผลข้างเคียงที่ผู้ใช้อาจไม่ทราบ
+
+การดำเนินการที่ผู้ใช้ระบุ path เอาไว้อย่างชัดเจนจะไม่ได้รับผลกระทบ
+เช่น `model.save("path")`, `tagger.train(..., save_loc="path")`,
+`thainlp misspell --output myfile.txt`
+
+ใช้ `pythainlp.is_read_only_mode()` เพื่อตรวจสอบสถานะปัจจุบันในโค้ด
+
+```python
+import pythainlp
+print(pythainlp.is_read_only_mode())  # True ถ้า PYTHAINLP_READ_ONLY=1
+```
+
 ## การทดสอบ
 
 เราทดสอบฟังก์ชันหลักบน Python ทุกเวอร์ชันที่รองรับอย่างเป็นทางการ

docs/notes/installation.rst

@@ -160,16 +160,58 @@ Runtime configurations
 .. envvar:: PYTHAINLP_OFFLINE
 
    When set to a truthy value (``1``, ``true``, ``yes``, ``on``), PyThaiNLP operates in
-   *offline mode*: corpus downloads are disabled, and :func:`pythainlp.corpus.get_corpus_path`
-   raises :exc:`FileNotFoundError` for any corpus that is not already cached locally.
+   *offline mode*: automatic corpus downloads are disabled, and
+   :func:`pythainlp.corpus.get_corpus_path` raises :exc:`FileNotFoundError`
+   for any corpus that is not already cached locally.
+
+   Explicit calls to :func:`pythainlp.corpus.download` or ``thainlp data get``
+   still work normally, because those are deliberate user actions.
 
    Use :func:`pythainlp.is_offline_mode` to check the current state programmatically.
 
    This follows the same convention as ``HF_HUB_OFFLINE`` in `huggingface_hub`.
 
+.. envvar:: PYTHAINLP_READ_ONLY
+
+   When set to a truthy value (``1``, ``true``, ``yes``, ``on``), PyThaiNLP operates in
+   *read-only mode*: implicit background writes to PyThaiNLP's internal data directory
+   are disabled.
+
+   **What read-only mode blocks** (implicit writes the user may not be aware of):
+
+   - Creating the PyThaiNLP data directory (``~/pythainlp-data`` or
+     as configured by :envvar:`PYTHAINLP_DATA`).
+   - :func:`pythainlp.corpus.download` — corpus file downloads and catalog
+     (``db.json``) updates.
+   - :func:`pythainlp.corpus.remove` — corpus file and catalog deletions.
+
+   **What read-only mode does NOT block** (explicit user-initiated writes):
+
+   - Saving trained models or vocabularies to a user-specified path
+     (e.g., ``model.save("my_model.json")``, ``tagger.train(..., save_loc="...")``,
+     ``tokenizer.save_vocabulary("my_dir/")``) — the user explicitly provided the
+     destination path.
+   - CLI output files written to a user-specified location
+     (e.g., ``thainlp benchmark --save-details``,
+     ``thainlp misspell --output myfile.txt``).
+
+   Use :func:`pythainlp.is_read_only_mode` to check the current state programmatically.
+
+   .. note::
+      To disable only *automatic* background downloads while keeping explicit
+      ``download()`` calls working, use :envvar:`PYTHAINLP_OFFLINE` instead.
+
+   If both :envvar:`PYTHAINLP_READ_ONLY` and :envvar:`PYTHAINLP_READ_MODE` are set at the
+   same time, PyThaiNLP raises :exc:`ValueError`.
+
 .. envvar:: PYTHAINLP_READ_MODE
 
-   Configures PyThaiNLP to operate in read-only mode (0 = False, 1 = True).
+   .. deprecated::
+      Use :envvar:`PYTHAINLP_READ_ONLY` instead. Setting ``PYTHAINLP_READ_MODE`` triggers a
+      :class:`DeprecationWarning` at runtime. If both ``PYTHAINLP_READ_ONLY`` and
+      ``PYTHAINLP_READ_MODE`` are set simultaneously, PyThaiNLP raises :exc:`ValueError`.
+
+      ``PYTHAINLP_READ_MODE=1`` is equivalent to ``PYTHAINLP_READ_ONLY=1``.
 
 Installation FAQ
 ----------------
@@ -194,4 +236,5 @@ For more discussion, see `PermissionError: [Errno 13] Permission denied: /home/p
 
 Q: How do I enable read-only mode for PyThaiNLP?
 
-A: Set the environment variable ``PYTHAINLP_READ_MODE`` to ``1``.
+A: Set the environment variable ``PYTHAINLP_READ_ONLY`` to ``1``.
+The legacy ``PYTHAINLP_READ_MODE=1`` is still accepted but deprecated.

pythainlp/__init__.py

@@ -56,6 +56,7 @@
     "collate",
     "correct",
     "is_offline_mode",
+    "is_read_only_mode",
     "pos_tag",
     "romanize",
     "spell",
@@ -77,6 +78,6 @@
     subword_tokenize,
     word_tokenize,
 )
-from pythainlp.tools.path import is_offline_mode
+from pythainlp.tools.path import is_offline_mode, is_read_only_mode
 from pythainlp.transliterate import romanize, transliterate
 from pythainlp.util import collate, thai_strftime

pythainlp/corpus/__init__.py

@@ -47,17 +47,13 @@
 ]
 
 import os
-from typing import Optional
 
 from pythainlp.tools import get_full_data_path, get_pythainlp_path
 
 # Remote and local corpus databases
 
 _CORPUS_DIRNAME: str = "corpus"
 _CORPUS_PATH: str = os.path.join(get_pythainlp_path(), _CORPUS_DIRNAME)
-_CHECK_MODE: Optional[str] = os.getenv("PYTHAINLP_READ_MODE")
-
-# URL of remote corpus catalog
 _CORPUS_DB_URL: str = "https://pythainlp.org/pythainlp-corpus/db.json"
 
 # filename of local corpus catalog
@@ -66,11 +62,6 @@
 # full path of local corpus catalog
 _CORPUS_DB_PATH: str = get_full_data_path(_CORPUS_DB_FILENAME)
 
-# create a local corpus database if it does not already exist
-if not os.path.exists(_CORPUS_DB_PATH) and _CHECK_MODE != "1":
-    with open(_CORPUS_DB_PATH, "w", encoding="utf-8") as f:
-        f.write(r'{"_default": {}}')
-
 
 def corpus_path() -> str:
     """Get path where corpus files are kept locally."""

pythainlp/corpus/core.py

@@ -17,13 +17,12 @@
 from pythainlp import __version__
 from pythainlp.corpus import corpus_db_path, corpus_db_url, corpus_path
 from pythainlp.tools import get_full_data_path
-from pythainlp.tools.path import is_offline_mode
+from pythainlp.tools.path import is_offline_mode, is_read_only_mode
 
 if TYPE_CHECKING:
     from http.client import HTTPMessage, HTTPResponse
     from typing import Any, Optional
 
-_CHECK_MODE: Optional[str] = os.getenv("PYTHAINLP_READ_MODE")
 _USER_AGENT: str = (
     f"PyThaiNLP/{__version__} "
     f"(Python/{sys.version_info.major}.{sys.version_info.minor}; "
@@ -85,7 +84,10 @@ def get_corpus_db_detail(name: str, version: str = "") -> dict[str, Any]:
     :return: details about corpus
     :rtype: dict
     """
-    with open(corpus_db_path(), encoding="utf-8-sig") as f:
+    db_path = corpus_db_path()
+    if not os.path.exists(db_path):
+        return {}
+    with open(db_path, encoding="utf-8-sig") as f:
         local_db = json.load(f)
 
     if not version:
@@ -658,8 +660,8 @@ def download(
     ``$HOME/pythainlp-data/``
     (e.g. ``/Users/bact/pythainlp-data/wiki_lm_lstm.pth``).
     """
-    if _CHECK_MODE == "1":
-        print("PyThaiNLP is read-only mode. It can't download.")
+    if is_read_only_mode():
+        print("PyThaiNLP is in read-only mode. It cannot download.")
         return False
 
     if not url:
@@ -674,8 +676,12 @@ def download(
 
     # check if corpus is available
     if name in corpus_db_dict:
-        with open(corpus_db_path(), encoding="utf-8-sig") as f:
-            local_db = json.load(f)
+        db_path = corpus_db_path()
+        if os.path.exists(db_path):
+            with open(db_path, encoding="utf-8-sig") as f:
+                local_db = json.load(f)
+        else:
+            local_db = {"_default": {}}
 
         corpus = corpus_db_dict[name]
         print("Corpus:", name)
@@ -802,10 +808,13 @@ def remove(name: str) -> bool:
         # FileNotFoundError: [Errno 2] No such file or directory:
         # '/usr/local/lib/python3.6/dist-packages/pythainlp/corpus/ttc'
     """
-    if _CHECK_MODE == "1":
-        print("PyThaiNLP is read-only mode. It can't download.")
+    if is_read_only_mode():
+        print("PyThaiNLP is in read-only mode. It cannot remove corpus.")
+        return False
+    db_path = corpus_db_path()
+    if not os.path.exists(db_path):
         return False
-    with open(corpus_db_path(), encoding="utf-8-sig") as f:
+    with open(db_path, encoding="utf-8-sig") as f:
         db = json.load(f)
     data = [
         corpus for corpus in db["_default"].values() if corpus["name"] == name

pythainlp/tools/__init__.py

@@ -7,6 +7,7 @@
     "get_pythainlp_data_path",
     "get_pythainlp_path",
     "is_offline_mode",
+    "is_read_only_mode",
     "safe_print",
     "warn_deprecation",
 ]
@@ -18,4 +19,5 @@
     get_pythainlp_data_path,
     get_pythainlp_path,
     is_offline_mode,
+    is_read_only_mode,
 )