From 6101bcfac7629981319a46bcf7bc45fc216c1ced Mon Sep 17 00:00:00 2001
From: Diego Escalante Urrelo <diegoe@gnome.org>
Date: Tue, 16 Mar 2021 23:20:38 -0500
Subject: [PATCH] bpo-43525: Highlight pathlib operator behavior with anchored
 paths

Add a warning describing the behavior of Path objects when combining a
Path object with an anchored-path string, using the  `/` operator.
---
 Doc/library/pathlib.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Doc/library/pathlib.rst b/Doc/library/pathlib.rst
index ac96de334b3290..13ca1c8d669c5a 100644
--- a/Doc/library/pathlib.rst
+++ b/Doc/library/pathlib.rst
@@ -217,6 +217,16 @@ The slash operator helps create child paths, similarly to :func:`os.path.join`::
    >>> '/usr' / q
    PurePosixPath('/usr/bin')
 
+Note that a string containing a leading '`/`' character will be considered
+an absolute path, making the last to be taken as the anchor for the new
+path object (mimicking :func:`os.path.join`'s behaviour)::
+
+   >>> p = PurePath('/usr')
+   >>> p / '/bin'
+   PurePosixPath('/bin')
+   >>> p / '/bin' / '/python'
+   PurePosixPath('/python')
+
 A path object can be used anywhere an object implementing :class:`os.PathLike`
 is accepted::