From bd3dbe04812156d71c9599cd3c3ea311b9fb89d6 Mon Sep 17 00:00:00 2001 From: aatle <168398276+aatle@users.noreply.github.com> Date: Thu, 29 Aug 2024 17:52:08 -0700 Subject: [PATCH 1/3] Make typing.PathLike private --- buildconfig/stubs/pygame/rwobject.pyi | 6 +++--- buildconfig/stubs/pygame/typing.pyi | 5 ++--- buildconfig/stubs/typing_sample_app.py | 4 ++-- src_py/typing.py | 5 ++--- 4 files changed, 9 insertions(+), 11 deletions(-) diff --git a/buildconfig/stubs/pygame/rwobject.pyi b/buildconfig/stubs/pygame/rwobject.pyi index 38161fab81..d14c62a804 100644 --- a/buildconfig/stubs/pygame/rwobject.pyi +++ b/buildconfig/stubs/pygame/rwobject.pyi @@ -1,16 +1,16 @@ from typing import Any, Optional, overload, Type -from pygame.typing import PathLike +from pygame.typing import _PathLike def encode_string( - obj: Optional[PathLike], + obj: Optional[_PathLike], encoding: Optional[str] = "unicode_escape", errors: Optional[str] = "backslashreplace", etype: Optional[Type[Exception]] = UnicodeEncodeError, ) -> bytes: ... @overload def encode_file_path( - obj: Optional[PathLike], etype: Optional[Type[Exception]] = UnicodeEncodeError + obj: Optional[_PathLike], etype: Optional[Type[Exception]] = UnicodeEncodeError ) -> bytes: ... @overload def encode_file_path( diff --git a/buildconfig/stubs/pygame/typing.pyi b/buildconfig/stubs/pygame/typing.pyi index f3f7aad434..2707a37557 100644 --- a/buildconfig/stubs/pygame/typing.pyi +++ b/buildconfig/stubs/pygame/typing.pyi @@ -7,7 +7,6 @@ __all__ = [ "RectLike", "SequenceLike", "FileLike", - "PathLike", "ColorLike", "RGBATuple", "Coordinate", @@ -29,9 +28,9 @@ else: # For functions that take a file name -PathLike = Union[str, bytes, _PathProtocol[str], _PathProtocol[bytes]] +_PathLike = Union[str, bytes, _PathProtocol[str], _PathProtocol[bytes]] # Most pygame functions that take a file argument should be able to handle a FileLike type -FileLike = Union[PathLike, IO[bytes], IO[str]] +FileLike = Union[_PathLike, IO[bytes], IO[str]] _T_co = TypeVar("_T_co", covariant=True) diff --git a/buildconfig/stubs/typing_sample_app.py b/buildconfig/stubs/typing_sample_app.py index 33b3bac0a8..58e853cbc8 100644 --- a/buildconfig/stubs/typing_sample_app.py +++ b/buildconfig/stubs/typing_sample_app.py @@ -44,12 +44,12 @@ def validator_SequenceLikeTypes( ) -# validate PathLike +# validate _PathLike class MyPath: def __fspath__(self) -> str: return "file.py" -def validator_PathLike(path: typing.PathLike) -> int: +def validator_PathLike(path: typing._PathLike) -> int: return 0 # must pass diff --git a/src_py/typing.py b/src_py/typing.py index f3f7aad434..2707a37557 100644 --- a/src_py/typing.py +++ b/src_py/typing.py @@ -7,7 +7,6 @@ "RectLike", "SequenceLike", "FileLike", - "PathLike", "ColorLike", "RGBATuple", "Coordinate", @@ -29,9 +28,9 @@ def __fspath__(self) -> _AnyStr_co: ... # For functions that take a file name -PathLike = Union[str, bytes, _PathProtocol[str], _PathProtocol[bytes]] +_PathLike = Union[str, bytes, _PathProtocol[str], _PathProtocol[bytes]] # Most pygame functions that take a file argument should be able to handle a FileLike type -FileLike = Union[PathLike, IO[bytes], IO[str]] +FileLike = Union[_PathLike, IO[bytes], IO[str]] _T_co = TypeVar("_T_co", covariant=True) From 7af301d1add2db8fd5f2f0de12e984a75df95813 Mon Sep 17 00:00:00 2001 From: aatle <168398276+aatle@users.noreply.github.com> Date: Thu, 29 Aug 2024 17:58:21 -0700 Subject: [PATCH 2/3] Undocument typing._PathLike type --- docs/reST/ref/typing.rst | 15 +++------------ src_c/doc/typing_doc.h | 1 - 2 files changed, 3 insertions(+), 13 deletions(-) diff --git a/docs/reST/ref/typing.rst b/docs/reST/ref/typing.rst index 764f05a28d..4e4380a74f 100644 --- a/docs/reST/ref/typing.rst +++ b/docs/reST/ref/typing.rst @@ -14,20 +14,11 @@ A lot of pygame functions and methods allow the user to provide different types for the same value like colors or coordinates. This module exports the most common type aliases for proper typehint annotations. - .. data:: PathLike - - An object representing a file path, i.e.: - - * ``"my/string/path.txt"`` - * ``pathlib.Path("my/pathlib/path.txt")`` - * ``b"my/bytes/path.txt"`` - * Any object implementing the path protocol (with a ``__fspath__`` magic method) - .. data:: FileLike - An object representing a file. Same as :mod:`pygame.typing.PathLike` with - the addition of file buffers (``IO`` of strings or bytes) such as the - return value of ``open()``. + An object representing a file. This includes any path-like objects such as + ``str`` or ``pathlib.Path()`` and file buffers (``IO`` of strings or bytes) + such as the return value of ``open()``. .. data:: SequenceLike diff --git a/src_c/doc/typing_doc.h b/src_c/doc/typing_doc.h index ed354c8439..28bc35fd91 100644 --- a/src_c/doc/typing_doc.h +++ b/src_c/doc/typing_doc.h @@ -1,6 +1,5 @@ /* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */ #define DOC_TYPING "pygame module providing common typehints" -#define DOC_TYPING_PATHLIKE "" #define DOC_TYPING_FILELIKE "" #define DOC_TYPING_SEQUENCELIKE "" #define DOC_TYPING_COORDINATE "" From e9aeb03cdee398fddb3cfa82e6308cd964bd962f Mon Sep 17 00:00:00 2001 From: aatle <168398276+aatle@users.noreply.github.com> Date: Fri, 30 Aug 2024 18:51:39 -0700 Subject: [PATCH 3/3] List possible types for FileLike docs --- docs/reST/ref/typing.rst | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/reST/ref/typing.rst b/docs/reST/ref/typing.rst index 4e4380a74f..7c71f6e18b 100644 --- a/docs/reST/ref/typing.rst +++ b/docs/reST/ref/typing.rst @@ -16,9 +16,15 @@ type aliases for proper typehint annotations. .. data:: FileLike - An object representing a file. This includes any path-like objects such as - ``str`` or ``pathlib.Path()`` and file buffers (``IO`` of strings or bytes) - such as the return value of ``open()``. + An object representing a file. This includes both path-like + objects and file-like objects, i.e.: + + * ``"my/string/path.txt"`` + * ``open("my/file/path.txt")`` + * ``pathlib.Path("my/pathlib/path.txt")`` + * ``io.BytesIO(b"my data: \x00\x01")`` + * ``b"my/bytes/path.txt"`` + * Any object implementing the path protocol or file protocol. .. data:: SequenceLike