Type annotation for unittest assertLogs() context manager

[jeremyn]

To make a type annotation for the context manager returned by the unittest.TestCase.assertLogs() method, I need to refer to the private class _LoggingWatcher, for example:

import logging
import unittest
from unittest._log import _LoggingWatcher

def get_msgs(cm: _LoggingWatcher) -> list[str]:
    return [r.getMessage() for r in cm.records]

class Test(unittest.TestCase):
    def test(self) -> None:
        with self.assertLogs() as cm:
            logging.info("test msg")
        self.assertSequenceEqual(["test msg"], get_msgs(cm))

if __name__ == "__main__":
    unittest.main()

It doesn't feel right importing a private class. Is this worth creating an issue about somewhere?

[jeremyn]

Maybe I can answer my own question: I found a comment about a similar situation at python/typeshed#2928 (comment) from a couple months ago, where the poster used typing.TYPE_CHECKING.

Applying that comment here, I would change the first lines above to:

import logging
import unittest
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from unittest._log import _LoggingWatcher

def get_msgs(cm: "_LoggingWatcher") -> list[str]:
    return [r.getMessage() for r in cm.records]

That seems to work. Is this the current best practice?

[AlexWaygood]

Most interfaces in the stdlib were designed in a pre-typing era, when returning private classes from public APIs was less of an issue. In today's post-PEP-484 world, I'd agree with you that it's generally bad to do this.

[erictraut]

If a class is private and used only as the return type for an API, perhaps the typeshed stub should define a public protocol class (a duck type) instead of a private nominal class definition.

[jeremyn]

@erictraut Yes, I completely agree that using a protocol would have been better in my _LoggingWatcherInterface example above or in any place where the intent is to mock/stub a type definition.

[srittau]

Current best practice in typeshed is not to introduce public items that don't exist at runtime. I originally introduced @typing.type_check_only to solve this problem, but that never took off. Maybe we should re-evaluate using this decorator in cases like this in the future.

[AlexWaygood]

If a class is private and used only as the return type for an API, perhaps the typeshed stub should define a public protocol class (a duck type) instead of a private nominal class definition.

I'm not sure I see how this would help. It would be hard to stop the fictional protocol from drifting out of sync with the actual class returned at runtime, whereas if we're faithful to the implementation we have tools like stubtest which will warn us when the runtime changes but the stub doesn't. Moreover, if users want to import a fictional protocol, they have to import it inside an if TYPE_CHECKING guard, whereas if we're faithful to the implementation, users don't need to.

I see this more as a problem with the implementation than a problem with typeshed.