From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 28 Mar 2021 00:48:53 +0000 (-0700)
Subject: bpo-43644: Add docs for importlib.resources.as_file. (GH-25048)
X-Git-Tag: v3.9.3~18
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=138e039ff9e5330709643b1bfe623eeac8fdc681;p=thirdparty%2FPython%2Fcpython.git

bpo-43644: Add docs for importlib.resources.as_file. (GH-25048)

(cherry picked from commit af50c84643ce21cfbdfdabbdfae6bd5e1368c542)

Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
---

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index cb2a5686a95a..61a81e02ff88 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -888,6 +888,22 @@ The following functions are available.
 
     .. versionadded:: 3.9
 
+.. function:: as_file(traversable)
+
+    Given a :class:`importlib.resources.abc.Traversable` object representing
+    a file, typically from :func:`importlib.resources.files`, return
+    a context manager for use in a :keyword:`with` statement.
+    The context manager provides a :class:`pathlib.Path` object.
+
+    Exiting the context manager cleans up any temporary file created when the
+    resource was extracted from e.g. a zip file.
+
+    Use ``as_file`` when the Traversable methods
+    (``read_text``, etc) are insufficient and an actual file on
+    the file system is required.
+
+    .. versionadded:: 3.9
+
 .. function:: open_binary(package, resource)
 
     Open for binary reading the *resource* within *package*.