Add attrs.inspect()

Author: hynek

docs/api.rst

@@ -190,6 +190,18 @@ Helpers
       >>> attrs.has(object)
       False
 
+.. autofunction:: attrs.inspect
+
+   For example:
+
+   .. doctest::
+
+      >>> @define
+      ... class C:
+      ...     pass
+      >>> attrs.inspect(C)
+      ClassProps(is_exception=False, is_slotted=False, has_weakref_slot=True, is_frozen=False, kw_only=KeywordOnly.NO, collect_by_mro=False, init=True, repr=True, eq=True, order=True, hash=Hashability.UNHASHABLE, match_args=True, str=False, getstate_setstate=False, on_setattr=None, field_transformer=None)
+
 .. autofunction:: attrs.resolve_types
 
     For example:

src/attr/__init__.py

@@ -26,6 +26,7 @@
     validate,
 )
 from ._next_gen import define, field, frozen, mutable
+from ._props import ClassProps, inspect
 from ._version_info import VersionInfo
 
 
@@ -44,6 +45,7 @@ class AttrsInstance(Protocol):
     "NOTHING",
     "Attribute",
     "AttrsInstance",
+    "ClassProps",
     "Converter",
     "Factory",
     "NothingType",
@@ -67,6 +69,7 @@ class AttrsInstance(Protocol):
     "get_run_validators",
     "has",
     "ib",
+    "inspect",
     "make_class",
     "mutable",
     "resolve_types",

src/attr/__init__.pyi

@@ -20,6 +20,8 @@ from . import filters as filters
 from . import setters as setters
 from . import validators as validators
 from ._cmp import cmp_using as cmp_using
+from ._funcs import inspect as inspect
+from ._props import ClassProps as ClassProps
 from ._typing_compat import AttrsInstance_
 from ._version_info import VersionInfo
 from attrs import (

src/attr/_make.py

@@ -18,6 +18,8 @@
 from functools import cached_property
 from typing import Any, NamedTuple, TypeVar
 
+from attr._props import ClassProps, Hashability, KeywordOnly
+
 # We need to import _compat itself in addition to the _compat members to avoid
 # having the thread-local in the globals here.
 from . import _compat, _config, setters
@@ -103,60 +105,6 @@ def __reduce__(self, _none_constructor=type(None), _args=()):  # noqa: B008
         return _none_constructor, _args
 
 
-class Hashability(enum.Enum):
-    """
-    The hashability of a class.
-    """
-
-    HASHABLE = "hashable"  # write a __hash__
-    HASHABLE_CACHED = "hashable_cache"  # write a __hash__ and cache the hash
-    UNHASHABLE = "unhashable"  # set __hash__ to None
-    LEAVE_ALONE = "leave_alone"  # don't touch __hash__
-
-
-class KeywordOnly(enum.Enum):
-    """
-    How attributes should be treated regarding keyword-only parameters.
-    """
-
-    NO = "no"  # attributes are not keyword-only
-    YES = "yes"  # attributes in current class without kw_only=False are keyword-only
-    FORCE = "force"  # all attributes are keyword-only
-
-
-class ClassProps(NamedTuple):
-    """
-    Effective class properties as derived from parameters to attr.s() or
-    define() decorators.
-
-    .. versionadded:: 25.4.0
-    """
-
-    is_exception: bool
-    is_slotted: bool
-    has_weakref_slot: bool
-    is_frozen: bool
-    kw_only: KeywordOnly
-    collect_by_mro: bool
-    init: bool
-    repr: bool
-    eq: bool
-    order: bool
-    hash: Hashability
-    match_args: bool
-    str: bool
-    getstate_setstate: bool
-    on_setattr: Callable[[str, Any], Any]
-    field_transformer: Callable[[Attribute], Attribute]
-
-    @property
-    def is_hashable(self):
-        return (
-            self.hash is Hashability.HASHABLE
-            or self.hash is Hashability.HASHABLE_CACHED
-        )
-
-
 def attrib(
     default=NOTHING,
     validator=None,

src/attr/_props.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import enum
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+from .exceptions import NotAnAttrsClassError
+
+
+if TYPE_CHECKING:
+    from ._make import Attribute
+
+
+class Hashability(enum.Enum):
+    """
+    The hashability of a class.
+    """
+
+    HASHABLE = "hashable"  # write a __hash__
+    HASHABLE_CACHED = "hashable_cache"  # write a __hash__ and cache the hash
+    UNHASHABLE = "unhashable"  # set __hash__ to None
+    LEAVE_ALONE = "leave_alone"  # don't touch __hash__
+
+
+class KeywordOnly(enum.Enum):
+    """
+    How attributes should be treated regarding keyword-only parameters.
+    """
+
+    NO = "no"  # attributes are not keyword-only
+    YES = "yes"  # attributes in current class without kw_only=False are keyword-only
+    FORCE = "force"  # all attributes are keyword-only
+
+
+class ClassProps(NamedTuple):
+    """
+    Effective class properties as derived from parameters to attr.s() or
+    define() decorators.
+
+    .. versionadded:: 25.4.0
+    """
+
+    is_exception: bool
+    is_slotted: bool
+    has_weakref_slot: bool
+    is_frozen: bool
+    kw_only: KeywordOnly
+    collect_by_mro: bool
+    init: bool
+    repr: bool
+    eq: bool
+    order: bool
+    hash: Hashability
+    match_args: bool
+    str: bool
+    getstate_setstate: bool
+    on_setattr: Callable[[str, Any], Any]
+    field_transformer: Callable[[Attribute], Attribute]
+
+    @property
+    def is_hashable(self):
+        return (
+            self.hash is Hashability.HASHABLE
+            or self.hash is Hashability.HASHABLE_CACHED
+        )
+
+
+def inspect(cls: type) -> ClassProps:
+    """
+    Inspect the class and return it's effective build parameters.
+
+    Args:
+        cls: The class to inspect.
+
+    Returns:
+        The effective build parameters of the class.
+
+    Raises:
+        NotAnAttrsClassError: If the class is not an *attrs*-decorated class.
+
+    .. versionadded:: 25.4.0
+    """
+    try:
+        return cls.__dict__["__attrs_props__"]
+    except IndexError:
+        msg = f"{cls!r} is not an attrs-decorated class."
+        raise NotAnAttrsClassError(msg) from None

src/attrs/__init__.py

@@ -4,6 +4,7 @@
     NOTHING,
     Attribute,
     AttrsInstance,
+    ClassProps,
     Converter,
     Factory,
     NothingType,
@@ -17,6 +18,7 @@
     fields_dict,
     frozen,
     has,
+    inspect,
     make_class,
     mutable,
     resolve_types,
@@ -31,6 +33,7 @@
     "NOTHING",
     "Attribute",
     "AttrsInstance",
+    "ClassProps",
     "Converter",
     "Factory",
     "NothingType",
@@ -58,6 +61,7 @@
     "filters",
     "frozen",
     "has",
+    "inspect",
     "make_class",
     "mutable",
     "resolve_types",

src/attrs/__init__.pyi

@@ -41,6 +41,8 @@ from attr import validate as validate
 from attr import validators as validators
 from attr import attrib, asdict as asdict, astuple as astuple
 from attr import NothingType as NothingType
+from attr import ClassProps as ClassProps
+from attr import inspect as inspect
 
 if sys.version_info >= (3, 11):
     from typing import dataclass_transform

tests/test_make.py

@@ -21,6 +21,7 @@
 from hypothesis.strategies import booleans, integers, lists, sampled_from, text
 
 import attr
+import attrs
 
 from attr import _config
 from attr._compat import PY_3_10_PLUS
@@ -531,27 +532,24 @@ def test_sets_attrs_props(self):
         class C:
             x: int = attr.ib()
 
-        assert (
-            ClassProps(
-                is_exception=False,
-                is_slotted=True,
-                is_frozen=True,
-                init=True,
-                repr=True,
-                eq=True,
-                order=True,
-                hash=Hashability.HASHABLE_CACHED,
-                match_args=False,
-                kw_only=KeywordOnly.FORCE,
-                has_weakref_slot=True,
-                collect_by_mro=False,
-                str=True,
-                getstate_setstate=True,
-                on_setattr=None,
-                field_transformer=None,
-            )
-            == C.__attrs_props__
-        )
+        assert ClassProps(
+            is_exception=False,
+            is_slotted=True,
+            is_frozen=True,
+            init=True,
+            repr=True,
+            eq=True,
+            order=True,
+            hash=Hashability.HASHABLE_CACHED,
+            match_args=False,
+            kw_only=KeywordOnly.FORCE,
+            has_weakref_slot=True,
+            collect_by_mro=False,
+            str=True,
+            getstate_setstate=True,
+            on_setattr=None,
+            field_transformer=None,
+        ) == attrs.inspect(C)
 
     def test_sets_attrs_props_defaults(self):
         """
@@ -563,27 +561,24 @@ def test_sets_attrs_props_defaults(self):
         class CDef:
             x = attr.ib()
 
-        assert (
-            ClassProps(
-                is_exception=False,
-                is_slotted=False,
-                is_frozen=False,
-                init=True,
-                repr=True,
-                eq=True,
-                order=True,
-                hash=Hashability.UNHASHABLE,
-                match_args=True,
-                kw_only=KeywordOnly.NO,
-                has_weakref_slot=True,
-                collect_by_mro=False,
-                str=False,
-                getstate_setstate=False,
-                on_setattr=None,
-                field_transformer=None,
-            )
-            == CDef.__attrs_props__
-        )
+        assert ClassProps(
+            is_exception=False,
+            is_slotted=False,
+            is_frozen=False,
+            init=True,
+            repr=True,
+            eq=True,
+            order=True,
+            hash=Hashability.UNHASHABLE,
+            match_args=True,
+            kw_only=KeywordOnly.NO,
+            has_weakref_slot=True,
+            collect_by_mro=False,
+            str=False,
+            getstate_setstate=False,
+            on_setattr=None,
+            field_transformer=None,
+        ) == attrs.inspect(CDef)
 
     def test_empty(self):
         """

tests/typing_example.py

@@ -513,3 +513,6 @@ class Hashable:
 def test(cls: type) -> None:
     if attr.has(cls):
         attr.resolve_types(cls)
+
+
+cp: attrs.ClassProps = attrs.inspect(Hashable)