DM-36108: move Ellipsis typing workaround from daf_butler

doc/changes/DM-36108.misc.md

@@ -0,0 +1 @@
+Moved a module with a typing workaround for the built-in `Ellipsis` (`...`) singleton here, from `daf_butler`.

python/lsst/utils/ellipsis.py

@@ -0,0 +1,38 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+from __future__ import annotations
+
+__all__ = ("Ellipsis", "EllipsisType")
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Workaround for `...` not having an exposed type in Python, borrowed from
+    # https://github.com/python/typing/issues/684#issuecomment-548203158
+    # Along with that, we need to either use `Ellipsis` instead of `...` for
+    # the actual sentinal value internally, and tell MyPy to ignore conversions
+    # from `...` to `Ellipsis` at the public-interface boundary.
+    #
+    # `Ellipsis` and `EllipsisType` should be directly imported from this
+    # module by related code that needs them; hopefully that will stay confined
+    # to `lsst.daf.butler.registry`.  Putting these in __all__ is bad for
+    # Sphinx, and probably more confusing than helpful overall.
+    from enum import Enum
+
+    class EllipsisType(Enum):
+        Ellipsis = "..."
+
+    Ellipsis = EllipsisType.Ellipsis
+
+else:
+    EllipsisType = type(Ellipsis)
+    Ellipsis = Ellipsis

python/lsst/utils/packages.py

@@ -27,7 +27,7 @@
 import types
 from collections.abc import Mapping
 from functools import lru_cache
-from typing import Any, Dict, Tuple, Type
+from typing import Any, Dict, Optional, Tuple, Type
 
 import yaml
 
@@ -147,7 +147,7 @@ def getPythonPackages() -> Dict[str, str]:
     return packages
 
 
-_eups = None  # Singleton Eups object
+_eups: Optional[Any] = None  # Singleton Eups object
 
 
 @lru_cache(maxsize=1)

tests/test_ellipsis.py

@@ -0,0 +1,30 @@
+# This file is part of utils.
+#
+# Developed for the LSST Data Management System.
+# This product includes software developed by the LSST Project
+# (https://www.lsst.org).
+# See the COPYRIGHT file at the top-level directory of this distribution
+# for details of code ownership.
+#
+# Use of this source code is governed by a 3-clause BSD-style
+# license that can be found in the LICENSE file.
+
+import unittest
+
+import lsst.utils
+import lsst.utils.tests
+from lsst.utils.ellipsis import Ellipsis, EllipsisType
+
+
+class EllipsisTestCase(lsst.utils.tests.TestCase):
+    def test_ellipsis(self):
+        # These are true at runtime because of typing.TYPE_CHECKING guards in
+        # the module.  When MyPy or other type-checkers run, these assertions
+        # would not be true, and `Ellipsis` must be used instead of the literal
+        # `...` to be understood by mypy.
+        self.assertIs(Ellipsis, ...)
+        self.assertIs(EllipsisType, type(...))
+
+
+if __name__ == "__main__":
+    unittest.main()