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-
+
+: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

pyproject.toml

@@ -51,6 +51,7 @@ changelog = 'https://mesonbuild.com/meson-python/changelog.html'
 [dependency-groups]
 test = [
   'build',
+  'importlib_resources >= 5.10; python_version < "3.12"',
   'pytest >= 6.0',
   'pytest-cov[toml]',
   'pytest-mock',
@@ -109,6 +110,11 @@ known-first-party = [
   'mesonpy',
 ]
 
+[tool.ruff.lint.per-file-ignores]
+# this file is included literally in the documentation and the double
+# empty lines forced by the import sorting style look odd there
+'tests/packages/isntall-data/__init__.py' = ['I001']
+
 
 [tool.coverage.run]
 disable_warnings = [

tests/packages/install-data/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 The meson-python developers
+#
+# SPDX-License-Identifier: MIT
+
+import sys
+
+if sys.version_info < (3, 12):
+    import importlib_resources as resources
+else:
+    from importlib import resources
+
+data = resources.files().joinpath('data.txt').read_text()
+uuid = 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']

tests/test_editable.py

@@ -344,3 +344,8 @@ def test_editable_rebuild_error(package_purelib_and_platlib, tmp_path, verbose):
             del sys.meta_path[0]
             sys.modules.pop('pure', None)
             path.write_text(code)
+
+
+def test_install_data(venv, editable_install_data, tmp_path):
+    venv.pip('install', os.fspath(editable_install_data))
+    venv.python('-c', 'import package')