https://github.com/python/cpython/commit/b04b307e0ebad0d9c7cc311fe6018b8d31b... commit: b04b307e0ebad0d9c7cc311fe6018b8d31b2ac8d branch: 3.9 author: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> committer: miss-islington <31488909+miss-islington@users.noreply.github.com> date: 2021-10-31T12:27:49-07:00 summary: bpo-45516: add protocol description to the Traversable documentation (GH-29039) * 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> (cherry picked from commit 4d03de3329ed8daa9c1107b1aedbb0fa280bddb6) Co-authored-by: Filipe Laíns <filipe.lains@gmail.com> files: A Misc/NEWS.d/next/Documentation/2021-10-18-20-12-18.bpo-45516.EJh4K8.rst M Doc/library/importlib.rst diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 69e311298221c..c7fbcb21274a1 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -805,6 +805,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 0000000000000..98f5d3432db05 --- /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.