Expose effective class construction properties (#1454)

* Implement _AttrsParams

ref #602

* Set __attrs_base_of_slotted__ for unused base classes

* Rename to ClassProps

This reflects that the instance is NOT just the parameters as passed to
the decorator, but how the class is actually constructed.

* Start renaming fields so it's clearer these aren't just arguments

* Reorder

* Dont's expose has_custom_setattr

* Make KeywordOnly an Enum

And make Hashability public

* Make cache_hash part of the Hashability Enum

* Add attrs.inspect()

* Refactor enums into class since they're only used by that class

* Docs

* Move back, rip out type hints

* Revert "Move back, rip out type hints"

This reverts commit 84bb6da.

* Use internal mechanisms instead of NamedTuple

Mostly to prevent Mypy from looking at our code, but sadly it wasn't
enough courtesy of enums for some reason.

* Add news fragment

* Document it's experimental

* Improve ClassProps documentation

* Add type information to docs

* Improve field names

To make it clearer these are derived values and nothing you can pass
into define/attr.s

* Avoid repeated attribute lookups

* More more helpful field names

* Add warning to class too

* Add explanation

* Add to changelog, too

* Nicer phrasing

* Grammar

* docs

* Consistency

* Make inspect/ClassProps NG-only

* Remove stray empty line

* Don't half-ass next_gen-ing

_funcs is terribly generic too

* Avoid attribute lookups in hot loop

* Add field access type tests

* A docstring is not appropriate here

* Move typing example to baseline

Author: hynek

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.