Superclass for `gdb.ThreadExitedEvent` should be `gdb.ThreadEvent`

[malsyned]

The GDB Python Event API docs say:

events.thread_exited

    This is emitted when GDB notices a thread has exited. The event is of type gdb.ThreadExitedEvent which extends gdb.ThreadEvent. This has a single attribute:

    Variable: ThreadExitedEvent.inferior_thread

        The exiting thread.

But typeshed defines the superclass for gdb.ThreadExitedEvent as gdb.Event, not gdb.ThreadEvent, so the inferior_thread attribute is missing.

typeshed/stubs/gdb/gdb/__init__.pyi

Line 963 in 9354f93

class ThreadExitedEvent(Event): ...

[brianschubert]

Huh, interesting. This is how ThreadExitedEvent is defined in the source (gdb/python/py-event-types.def):

GDB_PY_DEFINE_EVENT_TYPE (continue,
			  "ContinueEvent",
			  "GDB continue event object",
			  thread_event_object_type);

GDB_PY_DEFINE_EVENT_TYPE (exited,
			  "ExitedEvent",
			  "GDB exited event object",
			  event_object_type);

/* <snip> */

GDB_PY_DEFINE_EVENT_TYPE (thread_exited,
			  "ThreadExitedEvent",
			  "GDB thread exited event object",
			  event_object_type);

(the definition is the same at the gdb-16.3-release tag -- which is the version that's reflected in the stubs -- and in the master branch)

My reading of this is that the declarations with event_object_type inherit from EventType and the declarations with thread_event_object_type inherit from ThreadEvent. That's consistent with the current stubs:

typeshed/stubs/gdb/gdb/__init__.pyi

Lines 957 to 963 in 9354f93

	class ContinueEvent(ThreadEvent): ...
	class ExitedEvent(Event):
	exit_code: int
	inferior: Inferior
	class ThreadExitedEvent(Event): ...

Is the runtime different? Could you check what the result of print(gdb.ThreadExitedEvent.__mro__) is?

[brianschubert]

Could you check what the result of print(gdb.ThreadExitedEvent.__mro__) is?

I was able to compile gdb 16.3 locally. I can confirm that ThreadExitedEvent inherits from Event at runtime:

(gdb) show version
GNU gdb (GDB) 16.3
...

(gdb) pi
>>> import gdb
>>> gdb.ThreadExitedEvent.__mro__
(<class 'gdb.ThreadExitedEvent'>, <class 'gdb.Event'>, <class 'object'>)

So, the typeshed stubs are accurate.

The discrepancy with the documentation is still curious. I'd suggest reporting that to gdb: https://sourceware.org/gdb/current/onlinedocs/gdb.html/GDB-Bugs.html#GDB-Bugs

I'll go ahead and close this since there's no change needed on the typeshed side. Thanks for the original report!

[malsyned]

I see what you mean. Looks like it's a bug on the GDB side, I'll report it over there. The actual event object that gets passed into registered handlers does have an inferior_thread attribute, but I see what you see, it's not reflected in the class hierarchy anywhere.

[brianschubert]

The actual event object that gets passed into registered handlers does have an inferior_thread attribute.

Ah, in that case, a PR adding the attribute and a comment explaining the discrepancy would be welcome.

[malsyned]

OK you got it. I'm going to try to get a fix merged into GDB as well.

Would you prefer an optimistic PR that adjusts the inheritance to match the docs and assumes that upstream will fix the inheritance as well, like

# Stub superclass ThreadEvent matches GDB docs. Actual implementation
# inherits from Event, but sets ThreadEvent attributes on new ThreadExitedEvent
# objects, so it walks like a duck.
class ThreadExitedEvent(ThreadEvent): ...

Or would you rather a stub that documents the current GDB implementation:

# GDB docs claim ThreadExitedEvent inherits from ThreadEvent, but the
# implementation actually just inherits from Event and adds an inferior_thread
# attribute directly to new ThreadExitedEvent objects.
class ThreadExitedEvent(Event):
    inferior_thread: InferiorThread

...possibly followed up by another PR down the road once GDB fixes it on their side?

[srittau]

In typeshed we generally follow the implementation rather than the docs.

[malsyned]

In typeshed we generally follow the implementation rather than the docs.

Understood. I reported this bug to GDB and now the maintainer has a patch in the pipeline for it that modifies the hierarchy to match the docs. How do you generally handle a situation like that? Does it make sense for me to just wait until the upstream issue is fixed and then send a PR that modifies the type hierarchy in typeshed?

[srittau]

Normally we wait until the change makes it into a release, but GDB is a special case, and I'm fine with waiting for the patch being merged.