From 6f880d6fa70bbc919e2de7683034662be2bf1524 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Fri, 7 Sep 2018 15:47:35 -0700 Subject: [PATCH] Add an important note about Python < 3.7 Closes #64 --- importlib_resources/docs/using.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/importlib_resources/docs/using.rst b/importlib_resources/docs/using.rst index fa7446416a58bb1..f232a1b88187339 100644 --- a/importlib_resources/docs/using.rst +++ b/importlib_resources/docs/using.rst @@ -150,6 +150,27 @@ manager that you can use in a ``with``-statement:: You can use all the standard :py:mod:`contextlib` APIs to manage this context manager. +.. attention:: + + There is an odd interaction with Python 3.4, 3.5, and 3.6 regarding adding + zip or wheel file paths to ``sys.path``. Due to limitations in `zipimport + `_, which can't be + changed without breaking backward compatibility, you **must** use an + absolute path to the zip/wheel file. If you use a relative path, you will + not be able to find resources inside these zip files. E.g.: + + **No**:: + + sys.path.append('relative/path/to/foo.whl') + resource_bytes('foo/data.dat') # This will fail! + + **Yes**:: + + sys.path.append(os.path.abspath('relative/path/to/foo.whl')) + resource_bytes('foo/data.dat') + +Both relative and absolute paths work for Python 3.7 and newer. + .. rubric:: Footnotes