DOC: document how to use installed data files with editable installs

Author: dnicolodi

docs/how-to-guides/editable-installs.rst

@@ -108,6 +108,52 @@ An alternative build directory can be specified using the
 :option:`build-dir` config setting.
 
 
+Data files
+----------
+
+It is relatively common to install data files needed at runtime
+alongside the package's Python code or extension modules. For a Python
+package named ``package`` this would look like this:
+
+.. TODO the :force: option should be removed once the pygments meson lexer is
+   updated to fix https://github.com/pygments/pygments/issues/2918
+
+.. literalinclude:: ../../tests/packages/install-data/meson.build
+   :language: meson
+   :force:
+   :lines: 5-
+
+In most circumstances, these files can be accessed deriving their
+filesystem path from the filesystem path of the Python module next to
+them via the ``__file__`` special variable. For example, within the
+package ``__init__.py``:
+
+.. code-block:: python
+
+   import pathlib
+
+   data = pathlib.Path(__file__).parent.joinpath('data.txt').read_text()
+   uuid = pathlib.Path(__file__).parent.joinpath('uuid.txt').read_text()  # WRONG!
+
+However, this does not work when modules are not loaded from a package
+installed in the Python library path in the filesystem but with a
+special module loader, as used to implement editable installs in
+``meson-python``. In the example above, the second read would fail
+when the package is installed in editable mode.  For this reason, data
+files need to be accessed using :mod:`importlib.resources`. The code
+above should be replaced with:
+
+.. literalinclude:: ../../tests/packages/install-data/__init__.py
+   :lines: 5,7-
+
+:mod:`importlib.resources` implements a virtual filesystem that allows
+to access individual files as if they were in their install location.
+However, there is no way to expose this file structure outside of the
+python runtime. In the example above, it is not possible to make the
+``data.txt`` and ``uuid.txt`` files appear in the same fileystem
+directory.
+
+
 .. _how-to-guides-editable-installs-verbose:
 
 Verbose mode

tests/packages/install-data/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2025 The meson-python developers
+#
+# SPDX-License-Identifier: MIT
+
+import importlib.resources
+
+
+data = importlib.resources.files().joinpath('data.txt').read_text()
+uuid = importlib.resources.files().joinpath('uuid.txt').read_text()

tests/packages/install-data/data.txt

@@ -0,0 +1 @@
+DATA

tests/packages/install-data/data.txt.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 The meson-python developers
+#
+# SPDX-License-Identifier: MIT

tests/packages/install-data/meson.build

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2025 The meson-python developers
+#
+# SPDX-License-Identifier: MIT
+
+project('package', version: '1.0.0')
+
+py = import('python').find_installation()
+
+py.install_sources(
+    '__init__.py',
+    subdir: 'package',
+)
+
+install_data(
+    'data.txt',
+    install_dir: py.get_install_dir() / 'package',
+)
+
+custom_target(
+    output: 'uuid.txt',
+    command: [py, '-m', 'uuid'],
+    capture: true,
+    install: true,
+    install_dir: py.get_install_dir() / 'package',
+)

tests/packages/install-data/pyproject.toml

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2023 The meson-python developers
+#
+# SPDX-License-Identifier: MIT
+
+[build-system]
+build-backend = 'mesonpy'
+requires = ['meson-python']