Updated olefile types (#12097)

stubs/olefile/olefile/olefile.pyi

@@ -4,8 +4,8 @@ import io
 import logging
 import traceback
 from collections.abc import Sequence
-from typing import IO
-from typing_extensions import Self
+from typing import IO, AnyStr, Generic
+from typing_extensions import Self, TypeAlias
 
 __date__: str
 __version__: str
@@ -137,7 +137,7 @@ class OleMetadata:
     DOCSUM_ATTRIBS: list[str]
 
     def __init__(self) -> None: ...
-    def parse_properties(self, ole_file: OleFileIO) -> None: ...
+    def parse_properties(self, ole_file: OleFileIO[AnyStr]) -> None: ...
     def dump(self) -> None: ...
 
 class OleFileIONotClosed(RuntimeWarning):
@@ -153,29 +153,34 @@ class OleStream(io.BytesIO):
         sectorsize: int,
         fat: list[int],
         filesize: int,
-        olefileio: OleFileIO,
+        olefileio: OleFileIO[AnyStr],
     ) -> None: ...
 
-class OleDirectoryEntry:
+class OleDirectoryEntry(Generic[AnyStr]):
     STRUCT_DIRENTRY: str
     DIRENTRY_SIZE: int
+    clsid: str
 
-    def __init__(self, entry: bytes, sid: int, ole_file: OleFileIO) -> None: ...
-    def build_sect_chain(self, ole_file: OleFileIO) -> None: ...
+    def __init__(self, entry: bytes, sid: int, ole_file: OleFileIO[AnyStr]) -> None: ...
+    def build_sect_chain(self, ole_file: OleFileIO[AnyStr]) -> None: ...
     def build_storage_tree(self) -> None: ...
     def append_kids(self, child_sid: int) -> None: ...
-    def __eq__(self, other: OleDirectoryEntry) -> bool: ...  # type: ignore[override]
-    def __lt__(self, other: OleDirectoryEntry) -> bool: ...  # type: ignore[override]
-    def __ne__(self, other: OleDirectoryEntry) -> bool: ...  # type: ignore[override]
-    def __le__(self, other: OleDirectoryEntry) -> bool: ...  # type: ignore[override]
+    def __eq__(self, other: OleDirectoryEntry[AnyStr]) -> bool: ...  # type: ignore[override]
+    def __lt__(self, other: OleDirectoryEntry[AnyStr]) -> bool: ...  # type: ignore[override]
+    def __ne__(self, other: OleDirectoryEntry[AnyStr]) -> bool: ...  # type: ignore[override]
+    def __le__(self, other: OleDirectoryEntry[AnyStr]) -> bool: ...  # type: ignore[override]
     def dump(self, tab: int = 0) -> None: ...
     def getmtime(self) -> datetime.datetime | None: ...
     def getctime(self) -> datetime.datetime | None: ...
 
-class OleFileIO:
+_Property: TypeAlias = int | str | bytes | bool | None
+
+class OleFileIO(Generic[AnyStr]):
+    root: OleDirectoryEntry[AnyStr] | None
+
     def __init__(
         self,
-        filename: IO[bytes] | bytes | str | None = None,
+        filename: IO[bytes] | AnyStr | None = None,
         raise_defects: int = 40,
         write_mode: bool = False,
         debug: bool = False,
@@ -187,8 +192,8 @@ class OleFileIO:
     def _raise_defect(
         self, defect_level: int, message: str, exception_type: type[Exception] = OleFileError  # noqa: Y011
     ) -> None: ...
-    def _decode_utf16_str(self, utf16_str: bytes, errors: str = "replace") -> bytes: ...
-    def open(self, filename: IO[bytes] | bytes | str, write_mode: bool = False) -> None: ...
+    def _decode_utf16_str(self, utf16_str: bytes, errors: str = "replace") -> str | bytes: ...
+    def open(self, filename: IO[bytes] | AnyStr, write_mode: bool = False) -> None: ...
     def close(self) -> None: ...
     def _close(self, warn: bool = False) -> None: ...
     def _check_duplicate_stream(self, first_sect: int, minifat: bool = False) -> None: ...
@@ -202,36 +207,41 @@ class OleFileIO:
     def write_sect(self, sect: int, data: bytes, padding: bytes = b"\x00") -> None: ...
     def _write_mini_sect(self, fp_pos: int, data: bytes, padding: bytes = b"\x00") -> None: ...
     def loaddirectory(self, sect: int) -> None: ...
-    def _load_direntry(self, sid: int) -> OleDirectoryEntry: ...
+    def _load_direntry(self, sid: int) -> OleDirectoryEntry[AnyStr]: ...
     def dumpdirectory(self) -> None: ...
     def _open(self, start: int, size: int = 0x7FFFFFFF, force_FAT: bool = False) -> OleStream: ...
     def _list(
-        self, files: list[list[bytes]], prefix: list[bytes], node: OleDirectoryEntry, streams: bool = True, storages: bool = False
+        self,
+        files: list[list[AnyStr]],
+        prefix: list[AnyStr],
+        node: OleDirectoryEntry[AnyStr],
+        streams: bool = True,
+        storages: bool = False,
     ) -> None: ...
-    def listdir(self, streams: bool = True, storages: bool = False) -> list[list[bytes]]: ...
+    def listdir(self, streams: bool = True, storages: bool = False) -> list[list[AnyStr]]: ...
     def _find(self, filename: str | Sequence[str]) -> int: ...
-    def openstream(self, filename: str | Sequence[str]) -> OleStream: ...
-    def _write_mini_stream(self, entry: OleDirectoryEntry, data_to_write: bytes) -> None: ...
+    def openstream(self, filename: AnyStr | Sequence[AnyStr]) -> OleStream: ...
+    def _write_mini_stream(self, entry: OleDirectoryEntry[AnyStr], data_to_write: bytes) -> None: ...
     def write_stream(self, stream_name: str | Sequence[str], data: bytes) -> None: ...
-    def get_type(self, filename: str | Sequence[str]) -> bool | int: ...
-    def getclsid(self, filename: str | Sequence[str]) -> str: ...
-    def getmtime(self, filename: str | Sequence[str]) -> datetime.datetime | None: ...
-    def getctime(self, filename: str | Sequence[str]) -> datetime.datetime | None: ...
-    def exists(self, filename: str | Sequence[str]) -> bool: ...
-    def get_size(self, filename: str | Sequence[str]) -> int: ...
+    def get_type(self, filename: AnyStr | Sequence[AnyStr]) -> bool | int: ...
+    def getclsid(self, filename: AnyStr | Sequence[AnyStr]) -> str: ...
+    def getmtime(self, filename: AnyStr | Sequence[AnyStr]) -> datetime.datetime | None: ...
+    def getctime(self, filename: AnyStr | Sequence[AnyStr]) -> datetime.datetime | None: ...
+    def exists(self, filename: AnyStr | Sequence[AnyStr]) -> bool: ...
+    def get_size(self, filename: AnyStr | Sequence[AnyStr]) -> int: ...
     def get_rootentry_name(self) -> bytes: ...
     def getproperties(
-        self, filename: str | Sequence[str], convert_time: bool = False, no_conversion: list[int] | None = None
-    ) -> dict[int, list[int | str | bytes | bool | None]]: ...
+        self, filename: AnyStr | Sequence[AnyStr], convert_time: bool = False, no_conversion: list[int] | None = None
+    ) -> dict[int, list[_Property] | _Property]: ...
     def _parse_property(
         self, s: bytes, offset: int, property_id: int, property_type: int, convert_time: bool, no_conversion: list[int]
-    ) -> list[int | str | bytes | bool | None] | None: ...
+    ) -> list[_Property] | _Property: ...
     def _parse_property_basic(
         self, s: bytes, offset: int, property_id: int, property_type: int, convert_time: bool, no_conversion: list[int]
-    ) -> tuple[int | str | bytes | bool | None, int]: ...
+    ) -> tuple[_Property, int]: ...
     def get_metadata(self) -> OleMetadata: ...
     def get_userdefined_properties(
-        self, filename: str | Sequence[str], convert_time: bool = False, no_conversion: list[int] | None = None
+        self, filename: AnyStr | Sequence[AnyStr], convert_time: bool = False, no_conversion: list[int] | None = None
     ) -> list[dict[str, bytes | int | None]]: ...
 
 def main() -> None: ...