Switch base methods to return Self instead of BoundLoggerBase

src/structlog/_base.py

@@ -9,13 +9,21 @@
 
 from __future__ import annotations
 
+import sys
+
 from typing import Any, Iterable, Mapping, Sequence
 
 from structlog.exceptions import DropEvent
 
 from .typing import BindableLogger, Context, Processor, WrappedLogger
 
 
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+
 class BoundLoggerBase:
     """
     Immutable context carrier.
@@ -62,7 +70,7 @@ def __eq__(self, other: object) -> bool:
     def __ne__(self, other: object) -> bool:
         return not self.__eq__(other)
 
-    def bind(self, **new_values: Any) -> BoundLoggerBase:
+    def bind(self, **new_values: Any) -> Self:
         """
         Return a new logger with *new_values* added to the existing ones.
         """
@@ -72,7 +80,7 @@ def bind(self, **new_values: Any) -> BoundLoggerBase:
             self._context.__class__(self._context, **new_values),
         )
 
-    def unbind(self, *keys: str) -> BoundLoggerBase:
+    def unbind(self, *keys: str) -> Self:
         """
         Return a new logger with *keys* removed from the context.
 
@@ -85,7 +93,7 @@ def unbind(self, *keys: str) -> BoundLoggerBase:
 
         return bl
 
-    def try_unbind(self, *keys: str) -> BoundLoggerBase:
+    def try_unbind(self, *keys: str) -> Self:
         """
         Like :meth:`unbind`, but best effort: missing keys are ignored.
 
@@ -97,7 +105,7 @@ def try_unbind(self, *keys: str) -> BoundLoggerBase:
 
         return bl
 
-    def new(self, **new_values: Any) -> BoundLoggerBase:
+    def new(self, **new_values: Any) -> Self:
         """
         Clear context and binds *new_values* using `bind`.
 

src/structlog/stdlib.py

@@ -156,7 +156,7 @@ def bind(self, **new_values: Any) -> BoundLogger:
         """
         Return a new logger with *new_values* added to the existing ones.
         """
-        return super().bind(**new_values)  # type: ignore[return-value]
+        return super().bind(**new_values)
 
     def unbind(self, *keys: str) -> BoundLogger:
         """
@@ -165,15 +165,15 @@ def unbind(self, *keys: str) -> BoundLogger:
         Raises:
             KeyError: If the key is not part of the context.
         """
-        return super().unbind(*keys)  # type: ignore[return-value]
+        return super().unbind(*keys)
 
     def try_unbind(self, *keys: str) -> BoundLogger:
         """
         Like :meth:`unbind`, but best effort: missing keys are ignored.
 
         .. versionadded:: 18.2.0
         """
-        return super().try_unbind(*keys)  # type: ignore[return-value]
+        return super().try_unbind(*keys)
 
     def new(self, **new_values: Any) -> BoundLogger:
         """
@@ -183,7 +183,7 @@ def new(self, **new_values: Any) -> BoundLogger:
         those wrapped by `structlog.threadlocal.wrap_dict` when threads
         are re-used.
         """
-        return super().new(**new_values)  # type: ignore[return-value]
+        return super().new(**new_values)
 
     def debug(self, event: str | None = None, *args: Any, **kw: Any) -> Any:
         """

tests/typing/api.py

@@ -323,6 +323,14 @@ async def typecheck_stdlib_async() -> None:
     await logger.alog(logging.CRITICAL, "async log")
 
 
+def typecheck_bound_logger_return() -> None:
+    blogger: structlog.BoundLogger = structlog.get_logger(__name__)
+    blog = blogger.bind(key1="value1", key2="value2", key3="value3")
+    blog = blog.unbind("key1")
+    blog = blog.try_unbind("bad_key")
+    blog = blog.new(new="value")
+
+
 # Structured tracebacks and ExceptionRenderer with ExceptionDictTransformer
 struct_tb: structlog.tracebacks.Trace = structlog.tracebacks.extract(
     ValueError, ValueError("onoes"), None