[Lldb-commits] [lldb] e8566f8 - [lldb][python] Add polymorphic `__getitem__` to `SBModuleSpecList` for Pythonic indexing (#189125)

[via lldb-commits]

Author: Piyush Jaiswal
Date: 2026-04-06T14:48:18-07:00
New Revision: e8566f83d2541734ad9b66c474e7f500ce98a280

URL: https://github.com/llvm/llvm-project/commit/e8566f83d2541734ad9b66c474e7f500ce98a280
DIFF: https://github.com/llvm/llvm-project/commit/e8566f83d2541734ad9b66c474e7f500ce98a280.diff

LOG: [lldb][python] Add polymorphic `__getitem__` to `SBModuleSpecList` for Pythonic indexing (#189125)

### Summary

`SBModuleSpecList` already supports `len()` and iteration via `__len__`
and `__iter__`, but is not subscriptable — `specs[0]` raises
`TypeError`.

This adds a `__getitem__` method that supports integer indexing (with
negative index support) and string lookup using `endswith()` matching,
which works for both Unix and Windows paths.

### Supported key types

| Key type | Example | Behavior |
|---|---|---|
| `int` | `specs[0]`, `specs[-1]` | Direct index with negative index
support |
| `str` | `specs['a.out']`, `specs['/usr/lib/liba.dylib']` | Lookup by
basename or partial/full path via `endswith()`. Returns first match or
`None` |

### Error handling

- **`IndexError`** for out-of-bounds integer indices
- **`TypeError`** for unsupported key types (e.g., `float`)
- **`None`** for string lookups with no match

### Before

```python
>>> specs = lldb.SBModuleSpecList.GetModuleSpecifications('/bin/ls')
>>> specs[0]
Traceback (most recent call last):
  File "<console>", line 1, in <module>
TypeError: 'SBModuleSpecList' object is not subscriptable
```

### After

```python
>>> import lldb, re
>>> specs = lldb.SBModuleSpecList.GetModuleSpecifications('/bin/ls')

>>> specs[0]
file = '/bin/ls', arch = x86_64-*-linux, uuid = 3CCC0D8A-..., object size = 140928
>>> specs[-1]
file = '/bin/ls', arch = x86_64-*-linux, uuid = 3CCC0D8A-..., object size = 140928

>>> specs['ls']
file = '/bin/ls', arch = x86_64-*-linux, uuid = 3CCC0D8A-..., object size = 140928

>>> specs[999]
IndexError: list index out of range
>>> specs[1.5]
TypeError: unsupported index type: <class 'float'>
```

### Test plan

Added test_module_spec_list_indexing to TestSBModule.py covering:

- Positive and negative integer indexing
- Out-of-bounds raises IndexError
- Unsupported key type raises TypeError
- String lookup by basename and full path (endswith() matching)
- Missing key returns None

```
bin/llvm-lit -sv lldb/test/API/python_api/sbmodule/TestSBModule.py
```

```
PASS: LLDB :: test_GetObjectName_dwarf (TestSBModule.SBModuleAPICase)
PASS: LLDB :: test_GetObjectName_dwo (TestSBModule.SBModuleAPICase)
PASS: LLDB :: test_module_spec_list_indexing_dwarf (TestSBModule.SBModuleAPICase)
PASS: LLDB :: test_module_spec_list_indexing_dwo (TestSBModule.SBModuleAPICase)
----------------------------------------------------------------------
Ran 12 tests in 1.854s

OK (skipped=6)
```

Co-authored-by: Piyush Jaiswal <piyushjais at meta.com>

Added: 
    

Modified: 
    lldb/bindings/interface/SBModuleSpecListExtensions.i
    lldb/test/API/python_api/sbmodule/TestSBModule.py

Removed: 
    


################################################################################
diff  --git a/lldb/bindings/interface/SBModuleSpecListExtensions.i b/lldb/bindings/interface/SBModuleSpecListExtensions.i
index 073e9d06738f5..2dab521bbd628 100644
--- a/lldb/bindings/interface/SBModuleSpecListExtensions.i
+++ b/lldb/bindings/interface/SBModuleSpecListExtensions.i
@@ -11,16 +11,28 @@ STRING_EXTENSION_OUTSIDE(SBModuleSpecList)
       '''Iterate over all ModuleSpecs in a lldb.SBModuleSpecList object.'''
       return lldb_iter(self, 'GetSize', 'GetSpecAtIndex')
 
-    def __getitem__(self, idx):
-      '''Get the ModuleSpec at a given index in an lldb.SBModuleSpecList object.'''
-      if not isinstance(idx, int):
-        raise TypeError("unsupported index type: %s" % type(idx))
+    def __getitem__(self, key):
+      '''Access module specs by index or by file path.
+         specs[0]                      - access by integer index
+         specs[-1]                     - access by negative integer index
+         specs['a.out']                - find first spec matching file basename
+         specs['/usr/lib/liba.dylib']  - find first spec matching full or partial path
+      '''
       count = len(self)
-      if not (-count <= idx < count):
-        raise IndexError("list index out of range")
-      idx %= count
-      return self.GetSpecAtIndex(idx)
+      if type(key) is int:
+          if -count <= key < count:
+              key %= count
+              return self.GetSpecAtIndex(key)
+          else:
+              raise IndexError("list index out of range")
+      elif type(key) is str:
+          for idx in range(count):
+              spec = self.GetSpecAtIndex(idx)
+              if str(spec.GetFileSpec()).endswith(key):
+                  return spec
+          return None
+      else:
+          raise TypeError("unsupported index type: %s" % type(key))
     %}
 #endif
 }
-

diff  --git a/lldb/test/API/python_api/sbmodule/TestSBModule.py b/lldb/test/API/python_api/sbmodule/TestSBModule.py
index 1e6cdefc8d8f0..f6edef22aef5f 100644
--- a/lldb/test/API/python_api/sbmodule/TestSBModule.py
+++ b/lldb/test/API/python_api/sbmodule/TestSBModule.py
@@ -110,3 +110,63 @@ def test_module_is_file_backed(self):
         self.assertSuccess(
             error, "couldn't destroy process %s" % background_process.pid
         )
+
+    @skipIfRemote
+    def test_module_spec_list_indexing(self):
+        """Test that SBModuleSpecList supports Pythonic indexing."""
+        self.build()
+        libfoo_path = self.getBuildArtifact("libfoo.a")
+        specs = lldb.SBModuleSpecList.GetModuleSpecifications(libfoo_path)
+        count = specs.GetSize()
+        self.assertGreater(count, 0, "Archive should have at least one module spec")
+
+        # Integer indexing: positive indices
+        for i in range(count):
+            self.assertEqual(
+                str(specs[i]),
+                str(specs.GetSpecAtIndex(i)),
+                "specs[%d] should match GetSpecAtIndex(%d)" % (i, i),
+            )
+
+        # Integer indexing: negative indices
+        self.assertEqual(
+            str(specs[-1]),
+            str(specs.GetSpecAtIndex(count - 1)),
+            "specs[-1] should match last element",
+        )
+        self.assertEqual(
+            str(specs[-count]),
+            str(specs.GetSpecAtIndex(0)),
+            "specs[-count] should match first element",
+        )
+
+        # Integer indexing: out of bounds raises IndexError
+        self.assertRaises(IndexError, lambda: specs[count])
+        self.assertRaises(IndexError, lambda: specs[-count - 1])
+
+        # Unsupported key type raises TypeError
+        self.assertRaises(TypeError, lambda: specs[1.5])
+
+        # String indexing: lookup by file basename
+        spec0 = specs.GetSpecAtIndex(0)
+        basename = spec0.GetFileSpec().GetFilename()
+        if basename:
+            found = specs[basename]
+            self.assertIsNotNone(found, "Should find spec by basename '%s'" % basename)
+            self.assertEqual(
+                found.GetFileSpec().GetFilename(),
+                basename,
+                "Found spec basename should match",
+            )
+
+        # String indexing: lookup by partial path (endswith matching)
+        fullpath = str(spec0.GetFileSpec())
+        if fullpath:
+            found = specs[fullpath]
+            self.assertIsNotNone(found, "Should find spec by full path '%s'" % fullpath)
+
+        # String indexing: missing basename returns None
+        self.assertIsNone(
+            specs["nonexistent_file.xyz"],
+            "Lookup of nonexistent basename should return None",
+        )