Expose effective class construction properties

changelog.d/1454.change.md

@@ -0,0 +1,5 @@
+Added a new **experimental** way to inspect classes:
+
+`attrs.inspect(cls)` returns the _effective_ class-wide parameters that were used by *attrs* to construct the class.
+
+The returned class is the same data structure that *attrs* uses internally to decide how to construct the final class.

docs/api.rst

@@ -190,6 +190,24 @@ Helpers
  >>> attrs.has(object)
  False
 
+.. autofunction:: attrs.inspect
+
+ For example:
+
+ .. doctest::
+
+ >>> @define
+ ... class CInspect:
+ ... pass
+ >>> attrs.inspect(CInspect) # doctest: +ELLIPSIS
+ ClassProps(is_exception=False, is_slotted=True, has_weakref_slot=True, is_frozen=False, kw_only=<KeywordOnly.NO: 'no'>, collected_fields_by_mro=True, added_init=True, added_repr=True, added_eq=True, added_ordering=False, hashability=<Hashability.UNHASHABLE: 'unhashable'>, added_match_args=True, added_str=False, added_pickling=True, on_setattr_hook=<function pipe.<locals>.wrapped_pipe at ...>, field_transformer=None)
+
+.. autoclass:: attrs.ClassProps
+.. autoclass:: attrs.ClassProps.Hashability
+ :members: HASHABLE, HASHABLE_CACHED, UNHASHABLE, LEAVE_ALONE
+.. autoclass:: attrs.ClassProps.KeywordOnly
+ :members: NO, YES, FORCE
+
 .. autofunction:: attrs.resolve_types
 
  For example:

docs/how-does-it-work.md

@@ -39,7 +39,7 @@ No magic, no meta programming, no expensive introspection at runtime.
 Everything until this point happens exactly *once* when the class is defined.
 As soon as a class is done, it's done.
 And it's just a regular Python class like any other, except for a single `__attrs_attrs__` attribute that *attrs* uses internally.
-Much of the information is accessible via {func}`attrs.fields` and other functions which can be used for introspection or for writing your own tools and decorators on top of *attrs* (like {func}`attrs.asdict`).
+Much of the information is accessible via {func}`attrs.inspect`, {func}`attrs.fields` and other functions which can be used for introspection or for writing your own tools and decorators on top of *attrs* (like {func}`attrs.asdict`).
 
 And once you start instantiating your classes, *attrs* is out of your way completely.