Add stub file and shim for gdb.LazyString class.

Author: visemet

gdbmongo/printer_protocol.py

@@ -24,12 +24,21 @@
 # pylint: disable=too-few-public-methods
 
 if typing.TYPE_CHECKING:
+    import gdb._lazy_string
     import gdb.printing
+
+    LazyString = gdb._lazy_string.LazyString
     PrettyPrinterProtocol = gdb.printing._PrettyPrinterProtocol
     SupportsChildren = gdb.printing._SupportsChildren
     SupportsDisplayHint = gdb.printing._SupportsDisplayHint
     SupportsToString = gdb.printing._SupportsToString
 else:
+    import gdb
+
+    # gdb_pymodule_addobject() isn't called for its LazyString class so we expose the type here
+    # ourselves. This attribute won't be used to construct LazyString instances directly. Instead,
+    # it'll be used for type checking and satisfying Mypy.
+    LazyString = type(gdb.parse_and_eval("(char *) 0").lazy_string(length=0))
 
     class SupportsChildren(typing.Protocol):
         ...

gdbmongo/stdlib_printers.pyi

@@ -20,6 +20,8 @@ import typing
 
 import gdb
 
+from gdbmongo.printer_protocol import LazyString
+
 
 def num_elements(num: int, /) -> str:
     ...
@@ -36,7 +38,7 @@ class __PrettyPrinterProtocol(gdb.printing._PrettyPrinterProtocol, typing.Protoc
     def __init__(self, typename: str, val: gdb.Value, /) -> None:
         ...
 
-    def to_string(self) -> str | gdb.Value | None:
+    def to_string(self) -> str | gdb.Value | LazyString | None:
         ...
 
     def children(self) -> typing.Iterator[typing.Tuple[str, gdb.Value]]:
@@ -164,7 +166,10 @@ class StdDequeIteratorPrinter(__PrettyPrinterProtocol):
 
 class StdStringPrinter(__PrettyPrinterProtocol):
 
-    def __init__(self, typename: typing.Literal["std::basic_string"], val: gdb.Value, /):
+    # Intentionally not constraining `typename` to be typing.Literal["std::basic_string"] because
+    # the argument is used by StdStringPrinter to set its `new_string` attribute based on whether
+    # the type contains "::__cxx11::basic_string".
+    def __init__(self, typename: str, val: gdb.Value, /):
         ...
 
 

stubs/gdb/_lazy_string.pyi

@@ -0,0 +1,43 @@
+###
+# Copyright 2022-present MongoDB, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+###
+"""https://sourceware.org/gdb/onlinedocs/gdb/Lazy-Strings-In-Python.html"""
+
+import typing
+
+from gdb._type import Type
+from gdb._value import Value
+
+
+class LazyString:
+
+    @property
+    def address(self) -> int:
+        ...
+
+    @property
+    def length(self) -> int:
+        ...
+
+    @property
+    def encoding(self) -> typing.Optional[str]:
+        ...
+
+    @property
+    def type(self) -> Type:
+        ...
+
+    def value(self) -> Value:
+        ...

stubs/gdb/_value.pyi

@@ -17,6 +17,7 @@
 
 import typing
 
+from gdb._lazy_string import LazyString
 from gdb._type import Type
 
 ConstructibleFrom = bool | int | float | str | Value
@@ -87,6 +88,10 @@ class Value(typing.SupportsInt, typing.SupportsFloat):
     def dynamic_type(self) -> Type:
         ...
 
+    @property
+    def is_lazy(self) -> bool:
+        ...
+
     def cast(self, typ: Type, /) -> Value:
         ...
 
@@ -101,3 +106,12 @@ class Value(typing.SupportsInt, typing.SupportsFloat):
 
     def referenced_value(self) -> Value:
         ...
+
+    def string(self, *, encoding: str = "", errors: str = "", length: int = -1) -> str:
+        ...
+
+    def lazy_string(self, *, encoding: str = "", length: int = -1) -> LazyString:
+        ...
+
+    def fetch_lazy(self) -> None:
+        ...

stubs/gdb/printing.pyi

@@ -21,6 +21,7 @@ https://sourceware.org/gdb/onlinedocs/gdb/gdb_002eprinting.html
 import abc
 import typing
 
+from gdb._lazy_string import LazyString
 from gdb._objfile import Objfile
 from gdb._progspace import Progspace
 from gdb._value import Value
@@ -38,7 +39,7 @@ class _SupportsDisplayHint(typing.Protocol):
 class _SupportsToString(typing.Protocol):
 
     @abc.abstractmethod
-    def to_string(self) -> str | Value | None:
+    def to_string(self) -> str | Value | LazyString | None:
         raise NotImplementedError