From ccd8e05aa8b7e53e09134102909397d5b85e134d Mon Sep 17 00:00:00 2001
From: ANSHUL SINGH <72524975+ekanshul@users.noreply.github.com>
Date: Thu, 20 Aug 2026 02:16:29 +0530
Subject: [PATCH] [docutils] Improve types in docutils.io

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 stubs/docutils/docutils/io.pyi | 47 ++++++++++++++++++----------------
 1 file changed, 25 insertions(+), 22 deletions(-)

diff --git a/stubs/docutils/docutils/io.pyi b/stubs/docutils/docutils/io.pyi
index 34fad7790bb4..9147cc0d6438 100644
--- a/stubs/docutils/docutils/io.pyi
+++ b/stubs/docutils/docutils/io.pyi
@@ -4,11 +4,12 @@ from _typeshed import (
     OpenBinaryModeWriting,
     OpenTextModeReading,
     OpenTextModeWriting,
+    StrPath,
     SupportsWrite,
     Unused,
 )
 from re import Pattern
-from typing import IO, Any, ClassVar, Final, Generic, Literal, TextIO, TypeVar
+from typing import IO, Any, BinaryIO, ClassVar, Final, Generic, Literal, TextIO, TypeVar
 from typing_extensions import deprecated
 
 from docutils import TransformSpec, nodes
@@ -49,21 +50,25 @@ class Input(TransformSpec, Generic[_S]):
 class Output(TransformSpec):
     component_type: ClassVar[str]
     default_destination_path: ClassVar[str | None]
-    encoding: Incomplete
-    error_handler: Incomplete
+    encoding: str | None
+    error_handler: str
     destination: Incomplete
-    destination_path: Incomplete
+    destination_path: StrPath | None
     def __init__(
-        self, destination=None, destination_path=None, encoding: str | None = None, error_handler: str = "strict"
+        self,
+        destination=None,
+        destination_path: StrPath | None = None,
+        encoding: str | None = None,
+        error_handler: str | None = "strict",
     ) -> None: ...
     def write(self, data: str) -> Any: ...  # returns bytes or str
     def encode(self, data: str) -> Any: ...  # returns bytes or str
 
 class ErrorOutput:
-    destination: Incomplete
-    encoding: Incomplete
-    encoding_errors: Incomplete
-    decoding_errors: Incomplete
+    destination: TextIO | BinaryIO | Literal[False]
+    encoding: str
+    encoding_errors: str
+    decoding_errors: str
     def __init__(
         self,
         destination: str | SupportsWrite[str] | SupportsWrite[bytes] | Literal[False] | None = None,
@@ -80,9 +85,9 @@ class FileInput(Input[IO[str]]):
     def __init__(
         self,
         source=None,
-        source_path=None,
+        source_path: StrPath | None = None,
         encoding: str | None = "utf-8",
-        error_handler: str = "strict",
+        error_handler: str | None = "strict",
         autoclose: bool = True,
         mode: OpenTextModeReading | OpenBinaryModeReading = "r",
     ) -> None: ...
@@ -94,21 +99,19 @@ class FileOutput(Output):
     default_destination_path: ClassVar[str]
     mode: ClassVar[OpenTextModeWriting | OpenBinaryModeWriting]
     opened: bool
-    autoclose: Incomplete
-    destination: Incomplete
-    destination_path: Incomplete
+    autoclose: bool
     def __init__(
         self,
         destination=None,
-        destination_path=None,
-        encoding=None,
-        error_handler: str = "strict",
+        destination_path: StrPath | None = None,
+        encoding: str | None = None,
+        error_handler: str | None = "strict",
         autoclose: bool = True,
-        handle_io_errors=None,
-        mode=None,
+        handle_io_errors: None = None,
+        mode: OpenTextModeWriting | OpenBinaryModeWriting | None = None,
     ) -> None: ...
     def open(self) -> None: ...
-    def write(self, data): ...
+    def write(self, data: str | bytes) -> str | bytes: ...
     def close(self) -> None: ...
 
 @deprecated("The `BinaryFileOutput` is deprecated by `FileOutput` and will be removed in Docutils 0.24.")
@@ -116,12 +119,12 @@ class BinaryFileOutput(FileOutput): ...
 
 class StringInput(Input[str]):
     default_source_path: ClassVar[str]
-    def read(self): ...
+    def read(self) -> str: ...
 
 class StringOutput(Output):
     default_destination_path: ClassVar[str]
     destination: str | bytes  # only defined after call to write()
-    def write(self, data): ...
+    def write(self, data: str | bytes) -> str | bytes: ...
 
 class NullInput(Input[Any]):
     default_source_path: ClassVar[str]