test/docs: add download() read-only mode test and env var interaction docs

- Add test_download_read_only_mode to tests/core/test_corpus.py:
  verifies download() returns False immediately when read-only mode is
  active (corpus not cached), and that without read-only mode the failure
  is for a different reason (corpus not found remotely).
- Add "Interaction between environment variables" section to
  docs/notes/installation.rst with a comparison table showing how
  PYTHAINLP_OFFLINE vs PYTHAINLP_READ_ONLY affect get_corpus_path()
  and download(), plus typical use-case examples.
- Add explanatory note in README.md read-only mode section clarifying
  that PYTHAINLP_READ_ONLY is more restrictive than PYTHAINLP_OFFLINE.

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

Author: Copilot

README.md

@@ -116,6 +116,14 @@ 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.
 
+> **Note:** Read-only mode is more restrictive than offline mode.
+> `PYTHAINLP_OFFLINE=1` blocks only *automatic* downloads triggered by
+> `get_corpus_path()`; explicit `pythainlp.corpus.download()` calls still work.
+> `PYTHAINLP_READ_ONLY=1` also blocks explicit `download()` calls, because any
+> download requires writing to the data directory.
+> Use `PYTHAINLP_READ_ONLY` when the data directory is on a read-only file system
+> (e.g., a read-only Docker volume or a shared cluster mount).
+
 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`).

docs/notes/installation.rst

@@ -213,6 +213,60 @@ Runtime configurations
 
       ``PYTHAINLP_READ_MODE=1`` is equivalent to ``PYTHAINLP_READ_ONLY=1``.
 
+Interaction between environment variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The table below shows how :envvar:`PYTHAINLP_OFFLINE` and :envvar:`PYTHAINLP_READ_ONLY`
+affect the two main corpus operations:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 32 33
+
+   * - Operation
+     - ``PYTHAINLP_OFFLINE=1``
+     - ``PYTHAINLP_READ_ONLY=1``
+   * - :func:`pythainlp.corpus.get_corpus_path` — corpus already cached locally
+     - Succeeds (returns path)
+     - Succeeds (no write needed)
+   * - :func:`pythainlp.corpus.get_corpus_path` — corpus **not** cached locally
+     - Fails (:exc:`FileNotFoundError`)
+     - Fails (:exc:`FileNotFoundError`)
+   * - :func:`pythainlp.corpus.download` — corpus already in local catalog
+     - Succeeds (download is an explicit user action)
+     - Fails (returns ``False``; all writes are blocked)
+   * - :func:`pythainlp.corpus.download` — corpus **not** in local catalog
+     - Succeeds (downloads the corpus)
+     - Fails (returns ``False``; all writes are blocked)
+
+Key differences:
+
+- :envvar:`PYTHAINLP_OFFLINE` blocks only **automatic** downloads.
+  Explicit calls to :func:`~pythainlp.corpus.download` (or the
+  ``thainlp data get`` CLI command) still work, because those are
+  deliberate user actions.
+
+- :envvar:`PYTHAINLP_READ_ONLY` is **more restrictive**: it blocks
+  *all* writes to the data directory, including explicit
+  :func:`~pythainlp.corpus.download` calls.
+  Use this when the data directory is on a read-only file system
+  (e.g., a read-only Docker volume or a shared cluster mount).
+
+- :envvar:`PYTHAINLP_DATA` sets the path of the data directory used by
+  both modes.  In read-only mode the directory is not created if it
+  does not already exist.
+
+Typical use cases:
+
+- **Offline laptop / air-gapped system**: set ``PYTHAINLP_OFFLINE=1``
+  after downloading all required corpora.  You can still call
+  ``download()`` manually if you have network access.
+
+- **Read-only container image with pre-bundled corpora**:
+  set ``PYTHAINLP_READ_ONLY=1`` so that no writes occur at all.
+  Any attempt to download a corpus that is missing from the image
+  will return ``False`` instead of raising a permission error.
+
 Installation FAQ
 ----------------
 

tests/core/test_corpus.py

@@ -8,6 +8,7 @@
 
 from pythainlp.corpus import (
     countries,
+    download,
     get_corpus_db,
     get_corpus_db_detail,
     get_corpus_default_db,
@@ -277,6 +278,35 @@ def test_get_corpus_path_offline_mode(self):
                     self.assertIsNotNone(result)
                     self.assertNotEqual(result, "")
 
+    def test_download_read_only_mode(self):
+        """Test that download() returns False when read-only mode is active.
+
+        When the data directory is read-only (e.g. a read-only mounted volume),
+        download() must not attempt any network or file-system operations and
+        must return False immediately.  This is stricter than offline mode:
+        PYTHAINLP_OFFLINE only prevents *automatic* downloads; PYTHAINLP_READ_ONLY
+        also prevents explicit download() calls.
+        """
+        # Corpus not in cache — must fail in read-only mode.
+        with patch(
+            "pythainlp.corpus.core.is_read_only_mode", return_value=True
+        ):
+            result = download("not_a_real_corpus_xyz123")
+            self.assertFalse(result)
+
+        # Sanity-check: with read-only mode off, the call is at least
+        # attempted (returns False because the corpus does not exist remotely,
+        # not because of read-only mode).
+        with patch(
+            "pythainlp.corpus.core.is_read_only_mode", return_value=False
+        ):
+            with patch(
+                "pythainlp.corpus.core.get_corpus_db",
+                return_value=None,
+            ):
+                result = download("not_a_real_corpus_xyz123")
+                self.assertFalse(result)
+
     def test_revise_wordset(self):
         training_data = [
             ["ถวิล อุดล", " ", "เป็น", "นักการเมือง", "หนึ่ง", "ใน"],