QueryList exception do not inherit from libtmux.exc.LibTmuxException

I was porting today a legacy piece of software (written by another co-worker, I only maintain it) that was using libtmux-0.8.5 und made an upgrade to libtmux-0.24.0 and I was getting a lot of deprecation errors because of session.find_where usage.

The code looked mostly like this:

try:
    session = libtmux.Server().find_where({"session_name":session_name})
except libtmux.exc.LibTmuxException:
    session = libtmux.Server().new_session(session_name=session_name)

and I changed it to

tmux_server = libtmux.server.Server()
try:
    session = tmux_server.sessions.get(session_name=session_name)
except libtmux.exc.LibTmuxException:
    session = tmux_server.new_session(session_name=session_name)

I realized that when sessions.get does not found a session, it raises ObjectDoesNotExist. But ObjectDoesNotExist is declared like this:

class ObjectDoesNotExist(Exception):
    """The requested object does not exist."""

The problem is that ObjectDoesNotExist is actually defined in libtmux._internal.query_list.py while the the documentation says here https://libtmux.git-pull.com/reference/exceptions.html

exception libtmux.exc.LibTmuxException
    Base Exception for libtmux Errors.

I don't want to start importing stuff from submodules with a leading underscore as this is mostly used by "private" modules and cannot be considered part of the public API.

I think you should either expose those exception directly in the top __init__.py and at least make ObjectDoesNotExist and ObjectDoesNotExist both inherit from libtmux.exc.LibTmuxException to keep it consistent.

Is there a reason why the the query_list implementation is the ._internal private submodule and why those exceptions do not inherit from libtmux.exc.LibTmuxException?

Start with libtmux._internal.query_list.py and libtmux.exc to compare ObjectDoesNotExist with LibTmuxException, then inspect the top-level init.py and the documented exceptions reference. Done means the query exception hierarchy and public exposure match the supported API, with the intended behavior for sessions.get established.