From 4d03de3329ed8daa9c1107b1aedbb0fa280bddb6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= <filipe.lains@gmail.com>
Date: Mon, 18 Oct 2021 23:58:13 +0100
Subject: [PATCH] bpo-45516: add protocol description to the Traversable
 documentation (#29039)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* bpo-45516: add protocol description to the Traversable documentation

Signed-off-by: Filipe Laíns <lains@riseup.net>

* Update Doc/library/importlib.rst

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

* Update Lib/importlib/abc.py

* Update Doc/library/importlib.rst

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

Co-authored-by: Jason R. Coombs <jaraco@jaraco.com>
---
 Doc/library/importlib.rst                     | 40 +++++++++++++++++++
 .../2021-10-18-20-12-18.bpo-45516.EJh4K8.rst  |  2 +
 2 files changed, 42 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Documentation/2021-10-18-20-12-18.bpo-45516.EJh4K8.rst

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index b5ee7a6b965..3576941efa4 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -815,6 +815,46 @@ ABC hierarchy::
 
     .. versionadded:: 3.9
 
+    .. abstractmethod:: name()
+
+       The base name of this object without any parent references.
+
+    .. abstractmethod:: iterdir()
+
+       Yield Traversable objects in self.
+
+    .. abstractmethod:: is_dir()
+
+       Return True if self is a directory.
+
+    .. abstractmethod:: is_file()
+
+       Return True if self is a file.
+
+    .. abstractmethod:: joinpath(child)
+
+       Return Traversable child in self.
+
+    .. abstractmethod:: __truediv__(child)
+
+       Return Traversable child in self.
+
+    .. abstractmethod:: open(mode='r', *args, **kwargs)
+
+       *mode* may be 'r' or 'rb' to open as text or binary. Return a handle
+       suitable for reading (same as :attr:`pathlib.Path.open`).
+
+       When opening as text, accepts encoding parameters such as those
+       accepted by :attr:`io.TextIOWrapper`.
+
+    .. method:: read_bytes()
+
+       Read contents of self as bytes.
+
+    .. method:: read_text(encoding=None)
+
+       Read contents of self as text.
+
 
 .. class:: TraversableResources
 
diff --git a/Misc/NEWS.d/next/Documentation/2021-10-18-20-12-18.bpo-45516.EJh4K8.rst b/Misc/NEWS.d/next/Documentation/2021-10-18-20-12-18.bpo-45516.EJh4K8.rst
new file mode 100644
index 00000000000..98f5d3432db
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2021-10-18-20-12-18.bpo-45516.EJh4K8.rst
@@ -0,0 +1,2 @@
+Add protocol description to the :class:`importlib.abc.Traversable`
+documentation.