search

dhermes / bezier

Helper for Bézier Curves, Triangles, and Higher Order Objects
Apache License 2.0
261 stars 36 forks source link

Re-enable the `missing-type-doc` Pylint warning #279

Open dhermes opened 2 years ago

dhermes commented 2 years ago

See https://github.com/dhermes/bezier/commit/e6925aad702842ae3637dfac9ff0da556ef0d980. This was a regression introduced in Pylint 2.12.0.

dhermes commented 2 years ago

To pinpoint when the regression occurred (at e6925aad702842ae3637dfac9ff0da556ef0d980)

2.12.0

diff --git a/noxfile.py b/noxfile.py
index 6cb05fa5..0e7078fc 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -43,7 +43,7 @@ DEPS = {
     "numpy": "numpy >= 1.21.4",
     "pycobertura": "pycobertura >= 2.1.0",
     "Pygments": "Pygments",
-    "pylint": "pylint >= 2.12.1",
+    "pylint": "pylint == 2.12.0",
     "pytest": "pytest >= 6.2.5",
     "pytest-cov": "pytest-cov",
     "scipy": "scipy >= 1.7.2",
@@ -391,7 +391,6 @@ def lint(session):
         "--rcfile",
         "pylintrc",
         "--max-module-lines=3035",
-        "--disable=missing-type-doc",
         get_path("src", "python", "bezier"),
     )
     # Run Pylint over the tests source.

yields

$ nox --session lint
...
nox > flake8 --import-order-style=google --application-import-names=bezier,tests /home/dhermes/bezier/src/python/bezier /home/dhermes/bezier/tests
nox > pylint --rcfile pylintrc --max-module-lines=3035 /home/dhermes/bezier/src/python/bezier
************* Module bezier.hazmat.algebraic_intersection
src/python/bezier/hazmat/algebraic_intersection.py:1063:0: W9016: "s_val" missing in parameter type documentation (missing-type-doc)
************* Module bezier.hazmat.triangle_intersection
src/python/bezier/hazmat/triangle_intersection.py:393:0: W9016: "duplicates" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_intersection.py:485:0: W9016: "duplicates, intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_intersection.py:525:0: W9016: "duplicates, intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_intersection.py:561:0: W9016: "duplicates, interior_curve, intersections" missing in parameter type documentation (missing-type-doc)
************* Module bezier.hazmat.triangle_helpers
src/python/bezier/hazmat/triangle_helpers.py:2142:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2210:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2267:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2324:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2416:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2597:0: W9016: "all_types" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2660:0: W9016: "intersections" missing in parameter type documentation (missing-type-doc)
src/python/bezier/hazmat/triangle_helpers.py:2731:0: W9016: "all_types, intersections" missing in parameter type documentation (missing-type-doc)

------------------------------------------------------------------
Your code has been rated at 9.95/10 (previous run: 9.95/10, +0.00)

nox > Command pylint --rcfile pylintrc --max-module-lines=3035 /home/dhermes/bezier/src/python/bezier failed with exit code 4
nox > Session lint failed.
$
$ .nox/lint/bin/pip show pylint | grep '^\(Name\|Version\)'
Name: pylint
Version: 2.12.0

2.11.1

diff --git a/noxfile.py b/noxfile.py
index 6cb05fa5..47b199f2 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -43,7 +43,7 @@ DEPS = {
     "numpy": "numpy >= 1.21.4",
     "pycobertura": "pycobertura >= 2.1.0",
     "Pygments": "Pygments",
-    "pylint": "pylint >= 2.12.1",
+    "pylint": "pylint == 2.11.1",
     "pytest": "pytest >= 6.2.5",
     "pytest-cov": "pytest-cov",
     "scipy": "scipy >= 1.7.2",
@@ -391,7 +391,6 @@ def lint(session):
         "--rcfile",
         "pylintrc",
         "--max-module-lines=3035",
-        "--disable=missing-type-doc",
         get_path("src", "python", "bezier"),
     )
     # Run Pylint over the tests source.

yields

$ nox --session lint
...
nox > flake8 --import-order-style=google --application-import-names=bezier,tests /home/dhermes/bezier/src/python/bezier /home/dhermes/bezier/tests
nox > pylint --rcfile pylintrc --max-module-lines=3035 /home/dhermes/bezier/src/python/bezier

------------------------------------
Your code has been rated at 10.00/10

nox > pylint --rcfile pylintrc --disable=missing-docstring --disable=protected-access --disable=too-many-public-methods --disable=import-outside-toplevel --disable=arguments-out-of-order --max-module-lines=2473 /home/dhermes/bezier/tests

------------------------------------
Your code has been rated at 10.00/10

nox > cmake-format --in-place /home/dhermes/bezier/src/fortran/CMakeLists.txt
nox > Session lint was successful.
$
$ .nox/lint/bin/pip show pylint | grep '^\(Name\|Version\)'
Name: pylint
Version: 2.11.1
dhermes commented 2 years ago

I started the process of filing an issue on https://github.com/PyCQA/pylint and made some more progress in understanding:

$ git log -1 --pretty=%H
e6925aad702842ae3637dfac9ff0da556ef0d980
$ mkdir tmp/
$ cd tmp/
$
$ # Edit tmp/min_repro.py
$ cat min_repro.py 
# pylint: disable=missing-module-docstring
# pylint: disable=unnecessary-pass
# pylint: disable=unused-argument
def verify_duplicates(duplicates, uniques):
    """Verify that a set of intersections had expected duplicates.

    .. note::

       This is a helper used only by :func:`generic_intersect`.

    Args:
        duplicates (List[~bezier.hazmat.intersection_helpers.Intersection]):
            List of intersections corresponding to duplicates that were
            filtered out.
        uniques (List[~bezier.hazmat.intersection_helpers.Intersection]): List
            of "final" intersections with duplicates filtered out.

    Raises:
        ValueError: If the ``uniques`` are not actually all unique.
        ValueError: If one of the ``duplicates`` does not correspond to
            an intersection in ``uniques``.
        ValueError: If a duplicate occurs only once but does not have
            exactly one of ``s`` and ``t`` equal to ``0.0``.
        ValueError: If a duplicate occurs three times but does not have
            exactly both ``s == t == 0.0``.
        ValueError: If a duplicate occurs a number other than one or three
            times.
    """
    pass
$
$ virtualenv venv2-11-1
$ venv2-11-1/bin/pip install 'pylint==2.11.1'
$ virtualenv venv2-12-0
$ venv2-12-0/bin/pip install 'pylint==2.12.0'
$
$
$ ./venv2-11-1/bin/pylint ./min_repro.py 

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

$ ./venv2-11-1/bin/pylint --rcfile ../pylintrc ./min_repro.py 

--------------------------------------------------------------------
Your code has been rated at 10.00/10 (previous run: 10.00/10, +0.00)

$ ./venv2-12-0/bin/pylint ./min_repro.py 

------------------------------------
Your code has been rated at 10.00/10

$ ./venv2-12-0/bin/pylint --rcfile ../pylintrc ./min_repro.py 
************* Module min_repro
min_repro.py:4:0: W9016: "duplicates" missing in parameter type documentation (missing-type-doc)

-------------------------------------------------------------------
Your code has been rated at 5.00/10 (previous run: 10.00/10, -5.00)