refactor(common): factor out base classes to ibis.common.bases from…

… `ibis.common.grounds`

this enables us to use the base classes like `Slotted`, `Immutable` and `Singleton`
in `ibis.common.patterns`

ibis/common/bases.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from abc import ABCMeta, abstractmethod
+from typing import TYPE_CHECKING, Any, Mapping
+from weakref import WeakValueDictionary
+
+from ibis.common.caching import WeakCache
+from ibis.common.collections import FrozenDict
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class BaseMeta(ABCMeta):
+    """Base metaclass for many of the ibis core classes.
+
+    This metaclass enforces the subclasses to define a `__slots__` attribute and
+    provides a `__create__` classmethod that can be used to change the class
+    instantiation behavior.
+    """
+
+    __slots__ = ()
+
+    def __new__(metacls, clsname, bases, dct, **kwargs):
+        # enforce slot definitions
+        dct.setdefault("__slots__", ())
+        return super().__new__(metacls, clsname, bases, dct, **kwargs)
+
+    def __call__(cls, *args, **kwargs):
+        """Create a new instance of the class.
+
+        The subclass may override the `__create__` classmethod to change the
+        instantiation behavior. This is similar to overriding the `__new__`
+        method, but without conditionally calling the `__init__` based on the
+        return type.
+
+        Parameters
+        ----------
+        args : tuple
+            Positional arguments eventually passed to the `__init__` method.
+        kwargs : dict
+            Keyword arguments eventually passed to the `__init__` method.
+
+        Returns
+        -------
+        The newly created instance of the class. No extra initialization
+        """
+        return cls.__create__(*args, **kwargs)
+
+
+class Base(metaclass=BaseMeta):
+    """Base class for many of the ibis core classes.
+
+    This class enforces the subclasses to define a `__slots__` attribute and
+    provides a `__create__` classmethod that can be used to change the class
+    instantiation behavior. Also enables weak references for the subclasses.
+    """
+
+    __slots__ = ("__weakref__",)
+    __create__ = classmethod(type.__call__)  # type: ignore
+
+
+class Immutable(Base):
+    """Prohibit attribute assignment on the instance."""
+
+    def __copy__(self):
+        return self
+
+    def __deepcopy__(self, memo):
+        return self
+
+    def __setattr__(self, name: str, _: Any) -> None:
+        raise AttributeError(
+            f"Attribute {name!r} cannot be assigned to immutable instance of "
+            f"type {type(self)}"
+        )
+
+
+class Singleton(Base):
+    """Cache instances of the class based on instantiation arguments."""
+
+    __instances__: Mapping[Any, Self] = WeakValueDictionary()
+
+    @classmethod
+    def __create__(cls, *args, **kwargs):
+        key = (cls, args, FrozenDict(kwargs))
+        try:
+            return cls.__instances__[key]
+        except KeyError:
+            instance = super().__create__(*args, **kwargs)
+            cls.__instances__[key] = instance
+            return instance
+
+
+class Final(Base):
+    """Prohibit subclassing."""
+
+    def __init_subclass__(cls, **kwargs):
+        cls.__init_subclass__ = cls.__prohibit_inheritance__
+
+    @classmethod
+    def __prohibit_inheritance__(cls, **kwargs):
+        raise TypeError(f"Cannot inherit from final class {cls}")
+
+
+class Comparable(Base):
+    """Enable quick equality comparisons.
+
+    The subclasses must implement the `__equals__` method that returns a boolean
+    value indicating whether the two instances are equal. This method is called
+    only if the two instances are of the same type and the result is cached for
+    future comparisons.
+
+    Since the class holds a global cache of comparison results, it is important
+    to make sure that the instances are not kept alive longer than necessary.
+    This is done automatically by using weak references for the compared objects.
+    """
+
+    __cache__ = WeakCache()
+
+    def __eq__(self, other) -> bool:
+        try:
+            return self.__cached_equals__(other)
+        except TypeError:
+            return NotImplemented
+
+    @abstractmethod
+    def __equals__(self, other) -> bool:
+        ...
+
+    def __cached_equals__(self, other) -> bool:
+        if self is other:
+            return True
+
+        # type comparison should be cheap
+        if type(self) is not type(other):
+            return False
+
+        # reduce space required for commutative operation
+        if id(self) < id(other):
+            key = (self, other)
+        else:
+            key = (other, self)
+
+        try:
+            result = self.__cache__[key]
+        except KeyError:
+            result = self.__equals__(other)
+            self.__cache__[key] = result
+
+        return result
+
+
+class Slotted(Base):
+    """A lightweight alternative to `ibis.common.grounds.Concrete`.
+
+    This class is used to create immutable dataclasses with slots and a precomputed
+    hash value for quicker dictionary lookups.
+    """
+
+    __slots__ = ("__precomputed_hash__",)
+
+    def __init__(self, **kwargs) -> Self:
+        for name, value in kwargs.items():
+            object.__setattr__(self, name, value)
+        hashvalue = hash(tuple(kwargs.values()))
+        object.__setattr__(self, "__precomputed_hash__", hashvalue)
+
+    def __eq__(self, other) -> bool:
+        if self is other:
+            return True
+        if type(self) is not type(other):
+            return NotImplemented
+        return all(getattr(self, n) == getattr(other, n) for n in self.__slots__)
+
+    def __hash__(self) -> int:
+        return self.__precomputed_hash__
+
+    def __setattr__(self, name, value) -> None:
+        raise AttributeError("Can't set attributes on an immutable instance")
+
+    def __repr__(self):
+        fields = {k: getattr(self, k) for k in self.__slots__}
+        fieldstring = ", ".join(f"{k}={v!r}" for k, v in fields.items())
+        return f"{self.__class__.__name__}({fieldstring})"
+
+    def __rich_repr__(self):
+        for name in self.__slots__:
+            yield name, getattr(self, name)

ibis/common/grounds.py

@@ -1,17 +1,14 @@
 from __future__ import annotations
 
 import contextlib
-from abc import ABCMeta, abstractmethod
 from copy import copy
 from typing import (
     Any,
     ClassVar,
-    Mapping,
     Tuple,
     Union,
     get_origin,
 )
-from weakref import WeakValueDictionary
 
 from typing_extensions import Self, dataclass_transform
 
@@ -23,29 +20,19 @@
     Signature,
     attribute,
 )
-from ibis.common.caching import WeakCache
-from ibis.common.collections import FrozenDict
+from ibis.common.bases import (  # noqa: F401
+    Base,
+    BaseMeta,
+    Comparable,
+    Final,
+    Immutable,
+    Singleton,
+)
+from ibis.common.collections import FrozenDict  # noqa: TCH001
 from ibis.common.patterns import Pattern
 from ibis.common.typing import evaluate_annotations
 
 
-class BaseMeta(ABCMeta):
-    __slots__ = ()
-
-    def __new__(metacls, clsname, bases, dct, **kwargs):
-        # enforce slot definitions
-        dct.setdefault("__slots__", ())
-        return super().__new__(metacls, clsname, bases, dct, **kwargs)
-
-    def __call__(cls, *args, **kwargs):
-        return cls.__create__(*args, **kwargs)
-
-
-class Base(metaclass=BaseMeta):
-    __slots__ = ("__weakref__",)
-    __create__ = classmethod(type.__call__)  # type: ignore
-
-
 class AnnotableMeta(BaseMeta):
     """Metaclass to turn class annotations into a validatable function signature."""
 
@@ -187,79 +174,6 @@ def copy(self, **overrides: Any) -> Annotable:
         return this
 
 
-class Immutable(Base):
-    def __copy__(self):
-        return self
-
-    def __deepcopy__(self, memo):
-        return self
-
-    def __setattr__(self, name: str, _: Any) -> None:
-        raise AttributeError(
-            f"Attribute {name!r} cannot be assigned to immutable instance of "
-            f"type {type(self)}"
-        )
-
-
-class Singleton(Base):
-    __instances__: Mapping[Any, Self] = WeakValueDictionary()
-
-    @classmethod
-    def __create__(cls, *args, **kwargs):
-        key = (cls, args, FrozenDict(kwargs))
-        try:
-            return cls.__instances__[key]
-        except KeyError:
-            instance = super().__create__(*args, **kwargs)
-            cls.__instances__[key] = instance
-            return instance
-
-
-class Final(Base):
-    def __init_subclass__(cls, **kwargs):
-        cls.__init_subclass__ = cls.__prohibit_inheritance__
-
-    @classmethod
-    def __prohibit_inheritance__(cls, **kwargs):
-        raise TypeError(f"Cannot inherit from final class {cls}")
-
-
-class Comparable(Base):
-    __cache__ = WeakCache()
-
-    def __eq__(self, other) -> bool:
-        try:
-            return self.__cached_equals__(other)
-        except TypeError:
-            return NotImplemented
-
-    @abstractmethod
-    def __equals__(self, other) -> bool:
-        ...
-
-    def __cached_equals__(self, other) -> bool:
-        if self is other:
-            return True
-
-        # type comparison should be cheap
-        if type(self) is not type(other):
-            return False
-
-        # reduce space required for commutative operation
-        if id(self) < id(other):
-            key = (self, other)
-        else:
-            key = (other, self)
-
-        try:
-            result = self.__cache__[key]
-        except KeyError:
-            result = self.__equals__(other)
-            self.__cache__[key] = result
-
-        return result
-
-
 class Concrete(Immutable, Comparable, Annotable):
     """Opinionated base class for immutable data classes."""