Refine read-only mode: only block implicit background writes, allow explicit user saves

Co-authored-by: bact <128572+bact@users.noreply.github.com>

Author: Copilot

README.md

@@ -93,7 +93,7 @@ See details in
 | `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 all write operations (downloads and catalog updates). | 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
@@ -111,8 +111,15 @@ print(pythainlp.is_offline_mode())  # True if PYTHAINLP_OFFLINE=1
 
 ### Read-only mode
 
-Set `PYTHAINLP_READ_ONLY=1` to disable **all** write operations,
-including both explicit and automatic corpus downloads as well as catalog updates.
+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

README_TH.md

@@ -124,7 +124,7 @@ PyThaiNLP ดาวน์โหลดข้อมูล (ดูแค็ตต
 | `PYTHAINLP_DATA` | พาธของไดเรกทอรีข้อมูล (ค่าเริ่มต้น: `~/pythainlp-data`) | ปัจจุบัน |
 | `PYTHAINLP_DATA_DIR` | ชื่อเดิมของ `PYTHAINLP_DATA` แสดง `DeprecationWarning` และหากตั้งค่าทั้งสองพร้อมกันจะเกิด `ValueError` | เลิกใช้แล้ว; ใช้ `PYTHAINLP_DATA` แทน |
 | `PYTHAINLP_OFFLINE` | ตั้งเป็น `1` เพื่อปิดการดาวน์โหลด corpus อัตโนมัติ การเรียก `download()` โดยตรงยังคงใช้งานได้ | ปัจจุบัน |
-| `PYTHAINLP_READ_ONLY` | ตั้งเป็น `1` เพื่อเปิดโหมดอ่านอย่างเดียว ซึ่งป้องกันการเขียนทั้งหมด (ดาวน์โหลดและอัปเดตแค็ตตาล็อก) | ปัจจุบัน |
+| `PYTHAINLP_READ_ONLY` | ตั้งเป็น `1` เพื่อเปิดโหมดอ่านอย่างเดียว ป้องกันการเขียนพื้นหลังที่ผู้ใช้อาจไม่ทราบ (ดาวน์โหลด corpus, อัปเดตแค็ตตาล็อก, สร้างไดเรกทอรี) การบันทึกไฟล์ที่ผู้ใช้ระบุเองไม่ได้รับผลกระทบ | ปัจจุบัน |
 | `PYTHAINLP_READ_MODE` | ชื่อเดิมของ `PYTHAINLP_READ_ONLY` แสดง `DeprecationWarning` และหากตั้งค่าทั้งสองพร้อมกันจะเกิด `ValueError` | เลิกใช้แล้ว; ใช้ `PYTHAINLP_READ_ONLY` แทน |
 
 ### โหมดออฟไลน์
@@ -142,8 +142,14 @@ print(pythainlp.is_offline_mode())  # True ถ้า PYTHAINLP_OFFLINE=1
 
 ### โหมดอ่านอย่างเดียว
 
-ตั้งค่า `PYTHAINLP_READ_ONLY=1` เพื่อปิดการเขียน**ทั้งหมด**
-รวมถึงการดาวน์โหลด corpus ทั้งแบบอัตโนมัติและแบบตั้งใจ รวมถึงการอัปเดตแค็ตตาล็อก
+ตั้งค่า `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

docs/notes/installation.rst

@@ -174,19 +174,32 @@ Runtime configurations
 .. envvar:: PYTHAINLP_READ_ONLY
 
    When set to a truthy value (``1``, ``true``, ``yes``, ``on``), PyThaiNLP operates in
-   *read-only mode*: all write operations are disabled, including corpus downloads and
-   corpus catalog updates.
+   *read-only mode*: implicit background writes to PyThaiNLP's internal data directory
+   are disabled.
 
-   In read-only mode:
+   **What read-only mode blocks** (implicit writes the user may not be aware of):
 
-   - :func:`pythainlp.corpus.download` refuses to download any corpus.
-   - :func:`pythainlp.corpus.remove` refuses to remove any corpus.
+   - 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::
-      For disabling only *automatic* downloads while still allowing explicit downloads,
-      use :envvar:`PYTHAINLP_OFFLINE` instead.
+      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`.

pythainlp/classify/param_free.py

@@ -96,12 +96,6 @@ def predict(self, x1: str, k: int = 1) -> str:
 
     def save(self, path: str) -> None:
         """:param str path: path to save model"""
-        from pythainlp.tools.path import is_read_only_mode
-
-        if is_read_only_mode():
-            raise PermissionError(
-                "PyThaiNLP is in read-only mode. Cannot save model."
-            )
         with open(path, "w", encoding="utf-8") as f:
             json.dump(
                 {

pythainlp/cli/benchmark.py

@@ -157,15 +157,6 @@ def __init__(self, name: str, argv: Sequence[str]) -> None:
             dir_name = os.path.dirname(args.input_file)
             file_name = args.input_file.split("/")[-1].split(".")[0]
 
-            from pythainlp.tools.path import is_read_only_mode
-
-            if is_read_only_mode():
-                safe_print(
-                    "PyThaiNLP is in read-only mode. "
-                    "Benchmark details cannot be saved."
-                )
-                return
-
             res_path = "%s/eval-%s.yml" % (dir_name, file_name)
             safe_print("Evaluation result is saved to %s" % res_path)
 

pythainlp/cli/misspell.py

@@ -70,14 +70,5 @@ def __init__(self, argv: Sequence[str]) -> None:
             base, ext = os.path.splitext(args.file)
             args.output = f"{base}-misspelled-r{args.misspell_ratio}-seed{args.seed}{ext}"
 
-        from pythainlp.tools.path import is_read_only_mode
-
-        if is_read_only_mode():
-            print(
-                "PyThaiNLP is in read-only mode. "
-                f"Cannot write output to {args.output!r}."
-            )
-            return
-
         with open(args.output, "w", encoding="utf-8") as f:
             f.writelines(misspelled_lines)

pythainlp/tag/_tag_perceptron.py

@@ -202,12 +202,6 @@ def train(
 
         # save the model
         if save_loc is not None:
-            from pythainlp.tools.path import is_read_only_mode
-
-            if is_read_only_mode():
-                raise PermissionError(
-                    "PyThaiNLP is in read-only mode. Cannot save model."
-                )
             data: dict[str, Union[dict, list]] = {}
             data["weights"] = self.model.weights
             data["tagdict"] = self.tagdict

pythainlp/tools/path.py

@@ -26,8 +26,9 @@
 def is_read_only_mode() -> bool:
     """Return whether PyThaiNLP is operating in read-only mode.
 
-    Read-only mode prevents any write operations such as corpus downloads
-    and catalog updates. It is activated by setting the
+    Read-only mode prevents **implicit background writes** to PyThaiNLP's
+    internal data directory — writes that happen as side effects the user
+    may not be aware of. It is activated by setting the
     ``PYTHAINLP_READ_ONLY`` environment variable to a truthy value
     (e.g. ``"1"``).
 
@@ -36,17 +37,27 @@ def is_read_only_mode() -> bool:
         Use ``PYTHAINLP_READ_ONLY`` instead.
         Setting both variables at the same time raises :exc:`ValueError`.
 
-    When read-only mode is active:
+    When read-only mode is active, the following implicit writes are blocked:
 
-    - :func:`pythainlp.corpus.download` refuses to download any corpus.
-    - :func:`pythainlp.corpus.remove` refuses to remove any corpus.
+    - Creating the PyThaiNLP data directory
+      (``~/pythainlp-data`` or as set by ``PYTHAINLP_DATA``).
+    - :func:`pythainlp.corpus.download` — corpus downloads and catalog
+      updates.
+    - :func:`pythainlp.corpus.remove` — corpus file and catalog deletions.
+
+    The following **explicit** user-initiated writes are **not** blocked,
+    because the user deliberately provided the destination path:
+
+    - Saving a trained model to a user-specified path
+      (e.g. ``model.save("my_model.json")``).
+    - Training a tagger with an explicit ``save_loc`` argument.
+    - Saving a tokenizer vocabulary to a user-specified directory.
+    - CLI output files written to a path the user specified or invoked.
 
     .. note::
-        Use :func:`~pythainlp.tools.path.is_offline_mode` to disable only
-        *automatic* downloads triggered by
-        :func:`~pythainlp.corpus.get_corpus_path`.  ``PYTHAINLP_OFFLINE``
-        still allows explicit :func:`~pythainlp.corpus.download` calls;
-        ``PYTHAINLP_READ_ONLY`` blocks all writes.
+        Use :func:`~pythainlp.tools.path.is_offline_mode` (``PYTHAINLP_OFFLINE``)
+        to disable only *automatic* background downloads while still allowing
+        explicit :func:`~pythainlp.corpus.download` calls.
 
     :return: ``True`` if PyThaiNLP is in read-only mode, ``False`` otherwise.
     :rtype: bool

pythainlp/translate/tokenization_small100.py

@@ -375,12 +375,6 @@ def __setstate__(self, d: dict) -> None:
     def save_vocabulary(
         self, save_directory: str, filename_prefix: Optional[str] = None
     ) -> tuple[str, str]:
-        from pythainlp.tools.path import is_read_only_mode
-
-        if is_read_only_mode():
-            raise PermissionError(
-                "PyThaiNLP is in read-only mode. Cannot save vocabulary."
-            )
         save_dir = Path(save_directory)
         if not save_dir.is_dir():
             raise OSError(f"{save_directory} should be a directory")
@@ -474,11 +468,5 @@ def load_json(path: str) -> Union[dict[str, str], list[str]]:
 def save_json(
     data: Union[Mapping[str, Union[str, int]], list[str]], path: str
 ) -> None:
-    from pythainlp.tools.path import is_read_only_mode
-
-    if is_read_only_mode():
-        raise PermissionError(
-            "PyThaiNLP is in read-only mode. Cannot save file."
-        )
     with open(path, "w") as f:
         json.dump(data, f, indent=2)

tests/core/test_tools.py

@@ -250,7 +250,11 @@ def test_is_read_only_mode_conflict(self):
             self.assertIn("PYTHAINLP_READ_MODE", str(ctx.exception))
 
     def test_get_pythainlp_data_path_no_makedirs_in_read_only(self):
-        """Test that get_pythainlp_data_path skips makedirs in read-only mode."""
+        """Test that get_pythainlp_data_path skips makedirs in read-only mode.
+
+        Directory creation is an implicit side-effect the user may not be
+        aware of.  Read-only mode must suppress it.
+        """
         with tempfile.TemporaryDirectory() as tmpdir:
             new_dir = os.path.join(tmpdir, "new-pythainlp-data")
             with patch.dict(
@@ -268,38 +272,36 @@ def test_get_pythainlp_data_path_no_makedirs_in_read_only(self):
                     "Data directory should not be created in read-only mode",
                 )
 
-    def test_param_free_save_blocked_in_read_only(self):
-        """Test that GzipModel.save raises PermissionError in read-only mode."""
+    def test_explicit_save_allowed_in_read_only(self):
+        """Test that user-explicit saves are allowed in read-only mode.
+
+        Read-only mode only blocks implicit background writes to PyThaiNLP's
+        internal data directory.  Operations where the user explicitly
+        specifies an output path must proceed normally.
+        """
         from pythainlp.classify.param_free import GzipModel
+        from pythainlp.tag._tag_perceptron import PerceptronTagger
 
-        # Bypass __init__ (which needs numpy) — only the guard is under test
-        model = object.__new__(GzipModel)
         with patch.dict(
             os.environ,
             {"PYTHAINLP_READ_ONLY": "1"},
             clear=False,
         ):
             os.environ.pop("PYTHAINLP_READ_MODE", None)
             with tempfile.TemporaryDirectory() as tmpdir:
-                with self.assertRaises(PermissionError):
-                    model.save(os.path.join(tmpdir, "model.json"))
+                # GzipModel.save — user explicitly provides the path
+                model = object.__new__(GzipModel)
+                import numpy as np
 
-    def test_perceptron_train_save_blocked_in_read_only(self):
-        """Test that PerceptronTagger.train raises PermissionError when saving in read-only mode."""
-        from pythainlp.tag._tag_perceptron import PerceptronTagger
+                model.training_data = np.array([("text", "label")])
+                model.cx2_list = [4]
+                out = os.path.join(tmpdir, "model.json")
+                model.save(out)
+                self.assertTrue(os.path.isfile(out))
 
-        tagger = PerceptronTagger()
-        sentences = [[("กิน", "VV"), ("ข้าว", "NN")]]
-        with patch.dict(
-            os.environ,
-            {"PYTHAINLP_READ_ONLY": "1"},
-            clear=False,
-        ):
-            os.environ.pop("PYTHAINLP_READ_MODE", None)
-            with tempfile.TemporaryDirectory() as tmpdir:
-                with self.assertRaises(PermissionError):
-                    tagger.train(
-                        sentences,
-                        save_loc=os.path.join(tmpdir, "tagger.json"),
-                        nr_iter=1,
-                    )
+                # PerceptronTagger.train — user explicitly provides save_loc
+                tagger = PerceptronTagger()
+                sentences = [[("กิน", "VV"), ("ข้าว", "NN")]]
+                tagger_out = os.path.join(tmpdir, "tagger.json")
+                tagger.train(sentences, save_loc=tagger_out, nr_iter=1)
+                self.assertTrue(os.path.isfile(tagger_out))