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

Author: dnicolodi

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

@@ -108,6 +108,74 @@ 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 update the text block below to 'meson' when
+.. meson lexer is updated to fix
+.. https://github.com/pygments/pygments/issues/2918
+
+.. code-block:: text
+
+   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',
+   )
+
+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:
+
+.. code-block:: python
+
+   import importlib.resources
+
+   data = importlib.resources.files().joinpath('data.txt').read_text()
+   uuid = importlib.resources.files().joinpath('uuid.txt').read_text()
+
+:mod:`importlib.resources` implements a virtual filesystem that allows
+to access individual files as if they were in their install location.
+However, there is not 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,13 @@
+# SPDX-FileCopyrightText: 2025 The meson-python developers
+#
+# SPDX-License-Identifier: MIT
+
+import importlib.resources
+import pathlib
+
+
+data = pathlib.Path(__file__).parent.joinpath('data.txt').read_text()
+uuid = pathlib.Path(__file__).parent.joinpath('uuid.txt').read_text() # WRONG!
+
+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('install-data', 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']