Make os.path.join() first parameter pos-only (#6812)

AlexWaygood · web-flow · commit 582f1e9c5f13 · 2022-01-04T15:38:46.000+01:00
diff --git a/stdlib/ntpath.pyi b/stdlib/ntpath.pyi
@@ -48,11 +48,13 @@ altsep: str
 if sys.version_info < (3, 7) and sys.platform == "win32":
     def splitunc(p: AnyStr) -> tuple[AnyStr, AnyStr]: ...  # deprecated
 
-# Similar to posixpath, but have slightly different argument names
+# First parameter is not actually pos-only,
+# but must be defined as pos-only in the stub or cross-platform code doesn't type-check,
+# as the parameter name is different in posixpath.join()
 @overload
-def join(path: StrPath, *paths: StrPath) -> str: ...
+def join(__path: StrPath, *paths: StrPath) -> str: ...
 @overload
-def join(path: BytesPath, *paths: BytesPath) -> bytes: ...
+def join(__path: BytesPath, *paths: BytesPath) -> bytes: ...
 
 if sys.platform == "win32":
     if sys.version_info >= (3, 10):
diff --git a/stdlib/posixpath.pyi b/stdlib/posixpath.pyi
@@ -60,10 +60,14 @@ def normpath(path: AnyStr) -> AnyStr: ...
 def commonpath(paths: Sequence[StrPath]) -> str: ...
 @overload
 def commonpath(paths: Sequence[BytesPath]) -> bytes: ...
+
+# First parameter is not actually pos-only,
+# but must be defined as pos-only in the stub or cross-platform code doesn't type-check,
+# as the parameter name is different in ntpath.join()
 @overload
-def join(a: StrPath, *paths: StrPath) -> str: ...
+def join(__a: StrPath, *paths: StrPath) -> str: ...
 @overload
-def join(a: BytesPath, *paths: BytesPath) -> bytes: ...
+def join(__a: BytesPath, *paths: BytesPath) -> bytes: ...
 
 if sys.version_info >= (3, 10):
     @overload
diff --git a/tests/stubtest_allowlists/py310.txt b/tests/stubtest_allowlists/py310.txt
@@ -115,6 +115,10 @@ contextlib.AbstractContextManager.__exit__
 io.IncrementalNewlineDecoder.setstate
 typing.SupportsRound.__round__
 types.DynamicClassAttribute..*  # In the stub we pretend it's an alias for property, but it has positional-only differences
+# These three have a pos-or-keyword first parameter at runtime, but deliberately have a pos-only first parameter in the stub. #6812
+posixpath.join
+ntpath.join
+os.path.join
 
 # These enums derive from (str, Enum). See comment in py3_common.txt
 pstats.SortKey.__new__
