From: Vladimír Vondruš Date: Mon, 3 Jan 2022 12:22:45 +0000 (+0100) Subject: documentation/python: adapt for attrs 20.1+. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=c05758f496907c81c55dcf0324273b0e1ac0c1db;p=blog.git documentation/python: adapt for attrs 20.1+. Also starting to use the 3.6 CI job to test hacks for older packages. --- diff --git a/documentation/python.py b/documentation/python.py index ac6028b9..0955da75 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -329,6 +329,7 @@ _automatically_created_by_attrs = """ _automatically_created_by_attrs_even_more_indented = """ Automatically created by attrs. """ +_generated_by_attrs_template = "Method generated by attrs for class XXX." _filtered_attrs_functions = set([ ('__ne__', """ Check equality and either forward a NotImplemented or return the result @@ -340,7 +341,19 @@ _filtered_attrs_functions = set([ ('__ge__', _automatically_created_by_attrs), ('__repr__', _automatically_created_by_attrs), ('__getstate__', _automatically_created_by_attrs_even_more_indented), - ('__setstate__', _automatically_created_by_attrs_even_more_indented) + ('__setstate__', _automatically_created_by_attrs_even_more_indented), + # Attrs 20.1 override the above with a generic doc afterwards (ew, dirty) + # and add __eq__() as well (before it had no docstring at all). + # The __init__() has this generic doc as well, but we don't want to hide it + # because it contains vital information on how to construct the class + # TODO remove the originals once support for older attrs is dropped + ('__eq__', _generated_by_attrs_template), + ('__ne__', _generated_by_attrs_template), + ('__lt__', _generated_by_attrs_template), + ('__le__', _generated_by_attrs_template), + ('__gt__', _generated_by_attrs_template), + ('__ge__', _generated_by_attrs_template), + ('__repr__', _generated_by_attrs_template), ]) def crawl_enum(state: State, path: List[str], enum_, parent_url): @@ -452,9 +465,14 @@ def crawl_class(state: State, path: List[str], class_): continue # ... or are auto-generated by attrs if state.config['ATTRS_COMPATIBILITY']: - if (name, object.__doc__) in _filtered_attrs_functions: continue - # Unfortunately the __eq__ doesn't have a docstring, - # try to match it just from the param names + # All methods generated by attrs 20.1+ have a generic + # docstring that contains the class name. + if (name, (object.__doc__ or '').replace(path[-1], 'XXX')) in _filtered_attrs_functions: + continue + # Before 20.1, the __eq__() unfortunately doesn't have + # a docstring, try to match it just from the param + # names + # TODO remove once support for older attrs is dropped if name == '__eq__' and object.__doc__ is None: try: signature = inspect.signature(object) diff --git a/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs-attrs193.html b/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs-attrs193.html new file mode 100644 index 00000000..e2c23002 --- /dev/null +++ b/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs-attrs193.html @@ -0,0 +1,77 @@ + + + + + inspect_attrs.MyClassAutoAttribs | My Python Project + + + + + +
+
+
+
+
+

+ inspect_attrs.MyClassAutoAttribs class +

+

A class with automatic attr-defined properties

+
+

Contents

+ +
+
+

Special methods

+
+
+ def __init__(self, + annotated: float, + complex_annotation: typing.List[typing.Tuple[int, float]] = []) -> None +
+
+
+
+
+

Properties

+
+
+ annotated: float get set del +
+
+
+ complex_annotation: typing.List[typing.Tuple[int, float]] get set del +
+
This is complex.
+
+
+
+

Data

+
+
+ unannotated = 4 +
+
+
+
+
+
+
+
+ + diff --git a/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs.html b/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs.html index e2c23002..bf951880 100644 --- a/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs.html +++ b/documentation/test_python/inspect_attrs/inspect_attrs.MyClassAutoAttribs.html @@ -44,7 +44,7 @@ annotated: float, complex_annotation: typing.List[typing.Tuple[int, float]] = []) -> None -
+
Method generated by attrs for class MyClassAutoAttribs.
diff --git a/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass-attrs193.html b/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass-attrs193.html new file mode 100644 index 00000000..bfc0571c --- /dev/null +++ b/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass-attrs193.html @@ -0,0 +1,72 @@ + + + + + inspect_attrs.MySlotClass | My Python Project + + + + + +
+
+
+
+
+

+ inspect_attrs.MySlotClass class +

+

A class with attr-defined slots

+
+

Contents

+ +
+
+

Special methods

+
+
+ def __init__(self, + annotated: float, + complex_annotation: typing.List[typing.Tuple[int, float]] = [], + complex_annotation_in_attr: typing.List[typing.Tuple[int, float]] = []) -> None +
+
+
+
+
+

Properties

+
+
+ annotated: float get set del +
+
+
+ complex_annotation: typing.List[typing.Tuple[int, float]] get set del +
+
+
+ complex_annotation_in_attr: typing.List[typing.Tuple[int, float]] get set del +
+
+
+
+
+
+
+
+ + diff --git a/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass.html b/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass.html index bfc0571c..eb8b3fca 100644 --- a/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass.html +++ b/documentation/test_python/inspect_attrs/inspect_attrs.MySlotClass.html @@ -44,7 +44,7 @@ complex_annotation: typing.List[typing.Tuple[int, float]] = [], complex_annotation_in_attr: typing.List[typing.Tuple[int, float]] = []) -> None -
+
Method generated by attrs for class MySlotClass.
diff --git a/documentation/test_python/test_inspect.py b/documentation/test_python/test_inspect.py index 8c5a642a..feb38552 100644 --- a/documentation/test_python/test_inspect.py +++ b/documentation/test_python/test_inspect.py @@ -249,8 +249,12 @@ class Attrs(BaseInspectTestCase): 'ATTRS_COMPATIBILITY': True }) self.assertEqual(*self.actual_expected_contents('inspect_attrs.MyClass.html')) - self.assertEqual(*self.actual_expected_contents('inspect_attrs.MyClassAutoAttribs.html')) - self.assertEqual(*self.actual_expected_contents('inspect_attrs.MySlotClass.html')) + if attr.__version_info__ >= (20, 1): + self.assertEqual(*self.actual_expected_contents('inspect_attrs.MyClassAutoAttribs.html')) + self.assertEqual(*self.actual_expected_contents('inspect_attrs.MySlotClass.html')) + else: + self.assertEqual(*self.actual_expected_contents('inspect_attrs.MyClassAutoAttribs.html', 'inspect_attrs.MyClassAutoAttribs-attrs193.html')) + self.assertEqual(*self.actual_expected_contents('inspect_attrs.MySlotClass.html', 'inspect_attrs.MySlotClass-attrs193.html')) class Underscored(BaseInspectTestCase): def test(self): diff --git a/package/ci/circleci.yml b/package/ci/circleci.yml index 06727fcc..9f500a52 100644 --- a/package/ci/circleci.yml +++ b/package/ci/circleci.yml @@ -45,6 +45,9 @@ commands: install-python-deps: parameters: + attrs-version: + type: string + default: "" matplotlib-version: type: string default: "" @@ -53,14 +56,12 @@ commands: name: Install Python dependencies # Matplotlib 3.5.1 has different order of attributes than 3.4, so can't # just use the latest (and 3.4 is not on the Python 3.6 image) - # Attrs 20.3 add some new properties that I need to ignore first, using - # 19.3 instead # Pygments 2.11 (and apparently 2.10 as well) treats certain whitespace # differently, I have to update the expected output first. # Docutils 0.18 drops some attribute that htmlsanity relies on, I need # to update the code first. command: | - pip install jinja2 docutils==0.17.1 pygments==2.9.0 pelican Pyphen Pillow coverage codecov qrcode matplotlib<< parameters.matplotlib-version >> attrs==19.3.0 + pip install jinja2 docutils==0.17.1 pygments==2.9.0 pelican Pyphen Pillow coverage codecov qrcode matplotlib<< parameters.matplotlib-version >> attrs<< parameters.attrs-version >> - run: name: Fix unheard-of cursed issues # otherwise i get Error: unsupported locale setting @@ -181,6 +182,9 @@ jobs: - install-base: extra: graphviz cmake ninja-build wget - install-python-deps: + # Since 3.6 is EOL'd, using this job to test with older versions of + # various packages to avoid regressions + attrs-version: ==19.3.0 matplotlib-version: ==3.3.4 - checkout - test-theme