From f391851d2ed7517b7475216e6d66e4b828434fed Mon Sep 17 00:00:00 2001
From: Artur Mostowski <artur.mostowski@protonmail.com>
Date: Tue, 18 Aug 2026 14:22:20 +0200
Subject: [PATCH 1/3] titlecase: add package stubs

---
 stubs/titlecase/@tests/stubtest_allowlist.txt |  3 ++
 stubs/titlecase/METADATA.toml                 |  3 ++
 stubs/titlecase/titlecase/__init__.pyi        | 48 +++++++++++++++++++
 3 files changed, 54 insertions(+)
 create mode 100644 stubs/titlecase/@tests/stubtest_allowlist.txt
 create mode 100644 stubs/titlecase/METADATA.toml
 create mode 100644 stubs/titlecase/titlecase/__init__.pyi

diff --git a/stubs/titlecase/@tests/stubtest_allowlist.txt b/stubs/titlecase/@tests/stubtest_allowlist.txt
new file mode 100644
index 000000000000..fbd73f7c2cd8
--- /dev/null
+++ b/stubs/titlecase/@tests/stubtest_allowlist.txt
@@ -0,0 +1,3 @@
+titlecase.CallbackProtocol
+titlecase.Pattern
+titlecase.tests
diff --git a/stubs/titlecase/METADATA.toml b/stubs/titlecase/METADATA.toml
new file mode 100644
index 000000000000..bdb09992847b
--- /dev/null
+++ b/stubs/titlecase/METADATA.toml
@@ -0,0 +1,3 @@
+version = "2.4.*"
+upstream-repository = "https://github.com/ppannuto/python-titlecase"
+optional-dependencies = ["types-regex", "regex"]
diff --git a/stubs/titlecase/titlecase/__init__.pyi b/stubs/titlecase/titlecase/__init__.pyi
new file mode 100644
index 000000000000..630beb563904
--- /dev/null
+++ b/stubs/titlecase/titlecase/__init__.pyi
@@ -0,0 +1,48 @@
+import logging
+import re
+from typing import Final, Protocol, TypeAlias, overload
+from typing_extensions import LiteralString
+
+import regex
+
+Pattern: TypeAlias = re.Pattern[str] | regex.Pattern[str]
+
+__all__ = ["titlecase"]
+__version__: Final[str]
+logger: Final[logging.Logger]
+
+REGEX_AVAILABLE: Final[bool]
+
+SMALL: Final[str]
+PUNCT: Final[str]
+
+SMALL_WORDS: Pattern
+SMALL_FIRST: Pattern
+SMALL_LAST: Pattern
+SUBPHRASE: Pattern
+
+MAC_MC: Final[Pattern]
+MR_MRS_MS_DR: Final[Pattern]
+INLINE_PERIOD: Final[Pattern]
+UC_ELSEWHERE: Final[Pattern]
+CAPFIRST: Final[Pattern]
+APOS_SECOND: Final[Pattern]
+UC_INITIALS: Final[Pattern]
+
+class CallbackProtocol(Protocol):
+    def __call__(self, word: str, /, *, all_caps: bool) -> str | None: ...
+
+class Immutable: ...
+class ImmutableString(str, Immutable): ...
+class ImmutableBytes(bytes, Immutable): ...
+
+@overload
+def set_small_word_list() -> None: ...
+@overload
+def set_small_word_list(small: str) -> None: ...
+
+def titlecase(
+    text: str, callback: CallbackProtocol | None = None, small_first_last: bool = True, preserve_blank_lines: bool = False
+) -> LiteralString: ...
+def create_wordlist_filter_from_file(file_path: str | None) -> CallbackProtocol: ...
+def cmd() -> None: ...

From 3bfb469d398c619ba5b0b8ab80a6be4eb3909fa3 Mon Sep 17 00:00:00 2001
From: Artur Mostowski <artur.mostowski@protonmail.com>
Date: Wed, 19 Aug 2026 14:56:45 +0200
Subject: [PATCH 2/3] Update stubs/titlecase/METADATA.toml

Co-authored-by: Sebastian Rittau <sebastian.rittau@zfutura.de>
---
 stubs/titlecase/METADATA.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/stubs/titlecase/METADATA.toml b/stubs/titlecase/METADATA.toml
index bdb09992847b..27294bf4c630 100644
--- a/stubs/titlecase/METADATA.toml
+++ b/stubs/titlecase/METADATA.toml
@@ -1,3 +1,3 @@
 version = "2.4.*"
 upstream-repository = "https://github.com/ppannuto/python-titlecase"
-optional-dependencies = ["types-regex", "regex"]
+optional-dependencies = ["types-regex"]

From d1238de294c4b92fa148304598df60249c496ed4 Mon Sep 17 00:00:00 2001
From: Artur Mostowski <artur.mostowski@protonmail.com>
Date: Thu, 20 Aug 2026 13:46:59 +0200
Subject: [PATCH 3/3] feedback addressed

---
 stubs/titlecase/@tests/stubtest_allowlist.txt |  3 +-
 stubs/titlecase/METADATA.toml                 |  2 +-
 stubs/titlecase/titlecase/__init__.pyi        | 37 ++++++++++---------
 3 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/stubs/titlecase/@tests/stubtest_allowlist.txt b/stubs/titlecase/@tests/stubtest_allowlist.txt
index fbd73f7c2cd8..a283eb12159b 100644
--- a/stubs/titlecase/@tests/stubtest_allowlist.txt
+++ b/stubs/titlecase/@tests/stubtest_allowlist.txt
@@ -1,3 +1,2 @@
-titlecase.CallbackProtocol
-titlecase.Pattern
+# typing the tests would present a requiremnt of effort with zero gain for the end user
 titlecase.tests
diff --git a/stubs/titlecase/METADATA.toml b/stubs/titlecase/METADATA.toml
index 27294bf4c630..9928c8163ede 100644
--- a/stubs/titlecase/METADATA.toml
+++ b/stubs/titlecase/METADATA.toml
@@ -1,3 +1,3 @@
 version = "2.4.*"
 upstream-repository = "https://github.com/ppannuto/python-titlecase"
-optional-dependencies = ["types-regex"]
+dependencies = ["types-regex"]
diff --git a/stubs/titlecase/titlecase/__init__.pyi b/stubs/titlecase/titlecase/__init__.pyi
index 630beb563904..440dd637180b 100644
--- a/stubs/titlecase/titlecase/__init__.pyi
+++ b/stubs/titlecase/titlecase/__init__.pyi
@@ -1,11 +1,11 @@
 import logging
 import re
-from typing import Final, Protocol, TypeAlias, overload
+from typing import Final, Protocol, TypeAlias, overload, type_check_only
 from typing_extensions import LiteralString
 
 import regex
 
-Pattern: TypeAlias = re.Pattern[str] | regex.Pattern[str]
+_Pattern: TypeAlias = re.Pattern[str] | regex.Pattern[str]
 
 __all__ = ["titlecase"]
 __version__: Final[str]
@@ -16,20 +16,21 @@ REGEX_AVAILABLE: Final[bool]
 SMALL: Final[str]
 PUNCT: Final[str]
 
-SMALL_WORDS: Pattern
-SMALL_FIRST: Pattern
-SMALL_LAST: Pattern
-SUBPHRASE: Pattern
-
-MAC_MC: Final[Pattern]
-MR_MRS_MS_DR: Final[Pattern]
-INLINE_PERIOD: Final[Pattern]
-UC_ELSEWHERE: Final[Pattern]
-CAPFIRST: Final[Pattern]
-APOS_SECOND: Final[Pattern]
-UC_INITIALS: Final[Pattern]
-
-class CallbackProtocol(Protocol):
+SMALL_WORDS: _Pattern
+SMALL_FIRST: _Pattern
+SMALL_LAST: _Pattern
+SUBPHRASE: _Pattern
+
+MAC_MC: Final[_Pattern]
+MR_MRS_MS_DR: Final[_Pattern]
+INLINE_PERIOD: Final[_Pattern]
+UC_ELSEWHERE: Final[_Pattern]
+CAPFIRST: Final[_Pattern]
+APOS_SECOND: Final[_Pattern]
+UC_INITIALS: Final[_Pattern]
+
+@type_check_only
+class _CallbackProtocol(Protocol):
     def __call__(self, word: str, /, *, all_caps: bool) -> str | None: ...
 
 class Immutable: ...
@@ -42,7 +43,7 @@ def set_small_word_list() -> None: ...
 def set_small_word_list(small: str) -> None: ...
 
 def titlecase(
-    text: str, callback: CallbackProtocol | None = None, small_first_last: bool = True, preserve_blank_lines: bool = False
+    text: str, callback: _CallbackProtocol | None = None, small_first_last: bool = True, preserve_blank_lines: bool = False
 ) -> LiteralString: ...
-def create_wordlist_filter_from_file(file_path: str | None) -> CallbackProtocol: ...
+def create_wordlist_filter_from_file(file_path: str | None) -> _CallbackProtocol: ...
 def cmd() -> None: ...