Add missing cmp_using to stub files (#949)

* Add missing cmp_using to stub files

Signed-off-by: Hynek Schlawack <hs@ox.cx>

* Add newsfragment

changelog.d/949.change.rst

@@ -0,0 +1 @@
+Added missing stub for ``attr(s).cmp_using()``.

docs/comparison.rst

@@ -50,7 +50,7 @@ It is then used as a key function like you may know from `sorted`:
 This is especially useful when you have fields with objects that have atypical comparison properties.
 Common examples of such objects are `NumPy arrays <https://github.com/python-attrs/attrs/issues/435>`_.
 
-To save you unnecessary boilerplate, ``attrs`` comes with the `attr.cmp_using` helper to create such functions.
+To save you unnecessary boilerplate, ``attrs`` comes with the `attrs.cmp_using` helper to create such functions.
 For NumPy arrays it would look like this::
 
    import numpy

src/attr/__init__.pyi

@@ -23,6 +23,7 @@ from . import filters as filters
 from . import setters as setters
 from . import validators as validators
 from ._version_info import VersionInfo
+from ._cmp import cmp_using as cmp_using
 
 __version__: str
 __version_info__: VersionInfo
@@ -51,7 +52,6 @@ _OnSetAttrArgType = Union[
 _FieldTransformer = Callable[
     [type, List[Attribute[Any]]], List[Attribute[Any]]
 ]
-_CompareWithType = Callable[[Any, Any], bool]
 # FIXME: in reality, if multiple validators are passed they must be in a list
 # or tuple, but those are invariant and so would prevent subtypes of
 # _ValidatorType from working when passed in a list or tuple.

src/attr/_cmp.pyi

@@ -1,6 +1,6 @@
-from typing import Type
+from typing import Any, Callable, Optional, Type
 
-from . import _CompareWithType
+_CompareWithType = Callable[[Any, Any], bool]
 
 def cmp_using(
     eq: Optional[_CompareWithType],

src/attrs/__init__.pyi

@@ -23,6 +23,7 @@ from attr import __version_info__ as __version_info__
 from attr import _FilterType
 from attr import assoc as assoc
 from attr import Attribute as Attribute
+from attr import cmp_using as cmp_using
 from attr import converters as converters
 from attr import define as define
 from attr import evolve as evolve

tests/typing_example.py

@@ -403,6 +403,7 @@ def accessing_from_attr() -> None:
     attr.filters.include
     attr.setters.frozen
     attr.validators.and_
+    attr.cmp_using
 
 
 def accessing_from_attrs() -> None:
@@ -414,3 +415,4 @@ def accessing_from_attrs() -> None:
     attrs.filters.include
     attrs.setters.frozen
     attrs.validators.and_
+    attrs.cmp_using