feat(types): Allow setting types for attributes

[InvincibleRMC]

Description

Until now setting specific type annotation on module or class attributes has been impossible. By using __annotations__ we can automatically store that information for stub generators to use and be more accurate in their definitions. Also add the Final type to mark attributes as Final.

Suggested changelog entry:

add ``attr_with_type`` for declaring attribute types and ``Final``, ``ClassVar`` type annotations.

[InvincibleRMC]

Only works on C++ 17 and above. I honestly was getting many strange errors around make_caster<T>::name.text;. There might be some more proper way of accessing the internals of make_caster that I'm not aware of that could address them. My googling of the errors seemed to suggest it had something to do with the code not being Position Independent.

[InvincibleRMC]

@rwgk I have added the handle base implementation.

[rwgk]

Finally, there should be some form of documentation

@InvincibleRMC could you please add comments, similar in style to the existing comments for attr?

pybind11/include/pybind11/pytypes.h

Lines 104 to 114 in 5b503f7

	/** \rst
	Return an internal functor to access the object's attributes. Casting the
	returned ``detail::obj_attr_accessor`` instance to a `handle` or `object`
	subclass causes a corresponding call to ``getattr``. Assigning a `handle`
	or `object` subclass causes a call to ``setattr``.
	\endrst */
	obj_attr_accessor attr(handle key) const;
	/// See above (the only difference is that the key's reference is stolen)
	obj_attr_accessor attr(object &&key) const;
	/// See above (the only difference is that the key is provided as a string literal)
	str_attr_accessor attr(const char *key) const;

Other than that this PR looks good to me now.

[InvincibleRMC]

@rwgk I added some comments for attr_with_type_hint

[rwgk]

I added a couple minor commits (8f87e21, e6b1370).

@timohl could you please take a final quick look? Does it still look good to you?

[InvincibleRMC]

Looks great!

[timohl]

Just two minor comments.
Otherwise, looks good to me.

[timohl]

Python 3.10 adds a new function to the standard library: inspect.get_annotations(). In Python versions 3.10 and newer, calling this function is the best practice for accessing the annotations dict of any object that supports annotations

Is it maybe worth also adding a small test using inspect.get_annotations() for access?
(only for 3.10+: @pytest.mark.skipif(sys.version_info < (3, 10)))

[rwgk]

@InvincibleRMC could you please help with that?

[InvincibleRMC]

Done.

[rwgk]

Thanks @InvincibleRMC and @timohl!