MAINT: Changed class constructor init GL08 reporting #592

mattgebert · 2024-12-11T13:06:29Z

Changed validate function in validate.py for empty docstring error GL08 ("The object does not have a docstring"), specifically for __init__ constructors. If an empty docstring for __init__, will first check if class docstring is satisfied for parameter mismatches, before deciding to report GL08 (if mismatches exist, i.e. incomplete documentation).

Implemented new docstring test classes in test_validate.py to verify correct functionality.
Also updated readthedocs format.rst and validation.rst to reflect new changes to constructor checking behavior.

Solves #591.

Note, I think a modification to the readthedocs https://numpydoc.readthedocs.io/en/latest/validation.html#ignoring-validation-checks-with-inline-comments ought to be made

P.s. First time pull requesting to a public repo, let me know if anything is insufficient.

…lass docstring isn't complete

larsoner · 2024-12-16T16:27:34Z

Had a quick look at the code and this looks reasonable to me!

Note, I think a modification to the readthedocs https://numpydoc.readthedocs.io/en/latest/validation.html#ignoring-validation-checks-with-inline-comments ought to be made

Sounds good, do you want to add it here?

mattgebert · 2024-12-17T03:19:58Z

@larsoner I've added new doc comments in the diff in format.rst and validation.rst. I'll repeat the modifications here:

format.rst -> `Documenting classes`

Use the same sections as outlined above (all except :ref:`Returns <returns>`
are applicable).  The constructor (``__init__``) should also be documented
here, the :ref:`Parameters <params>` section of the docstring details the
constructor's parameters. The class docstring does not need to be repeated  <----
in a constructor, but is optional. <-----

validation.rst -> `Ignoring Validation Checks with Inline Comments`

def __init__(self):  # numpydoc ignore=GL08
    pass

Note, if the :ref:`class <classdoc>` docstring properly documents the <----
constructor, the ``GL08`` will be ignored by default. <----

This is supported by the :ref:`CLI <validation_via_cli>`,
:ref:`pre-commit hook <pre_commit_hook>`, and
:ref:`Sphinx extension <validation_during_sphinx_build>`.

larsoner · 2024-12-17T16:27:34Z

@larsoner I've added new doc comments in the diff

I think you maybe forgot to push (?), I don't see the changes in the files changed tab

larsoner · 2024-12-17T16:28:21Z

Ohh wait nevermind you already made the changes before I just didn't notice. And failed to notice again! 🤦

larsoner

@stefanv did you want to look?

stefanv

The general gist of this is correct, I think. I left some comments that I think may help future developers (ourselves, likely 😅) know what we did here.

doc/format.rst

doc/validation.rst

numpydoc/tests/test_validate.py

stefanv · 2024-12-17T19:59:47Z

numpydoc/tests/test_validate.py

        """


+class GoodConstructorInclusion:


Is it correct to have parameters both in class docstr and init? Maybe it's OK 🤔

This is a good point, particularly if both exist. I haven't captured this complexity.

I think it's logical to allow both; particularly as the class docstr can be comprehensive (i.e. listing atrributes and properties which wouldn't be listed on init). I think where this really makes a difference is in linting for UI interpret hints - for accessible hinting you want to enforce parameter documentation.

For example, Pylance (vscode) will use both the class docstr and init docstr to display documentation for references / initialisation. When a init docstr hasn't been provided, initialisation hinting defaults to the class docstr.

We might be missing one thing here. The current revision checks if the missing docstr belongs to a constructor, and if it is satisfied by the class docstr. Perhaps we should likewise check class docstrs, silencing parameters mismatch warnings if parameters are satisfied by an (existing) init docstr?

We can perhaps think of that as some additional follow-up logic, if you want?

(I meant separate PR, so as to not slow this one down.)

numpydoc/tests/test_validate.py

stefanv · 2024-12-17T20:02:42Z

numpydoc/validate.py

+        # Check if the object is a class and has a docstring in the constructor
+        if doc.name.endswith("__init__") and doc.is_function_or_method:
+            cls_name = doc.code_obj.__qualname__.split(".")[0]
+            cls = getattr(importlib.import_module(doc.code_obj.__module__), cls_name)


@larsoner I don't know enough about current internals to know if this is how we do things; no utility functions / class methods for this purpose?

Looks like Validator._load_obj(f"{doc.code_obj.__module__}.{doc.code_obj.__qualname__}") might do it, or maybe simpler Validator._load_obj(doc.name[:-9]) could work. @mattgebert do you want to try it (probably the second one)?

@larsoner I don't think the second one works; doc.name[:-9] is numpydoc.tests.test_validate.__init__ when testing IncompleteConstructorDocumentedInClass.__init__ (is this expected for doc.name, not including the class name?). This means you can't resolve the class without the __qualname__ like you used in the first suggestion. Two equivalent options seem to be:

cls = Validator._load_obj(f"{doc.code_obj.__module__}.{cls_name}") cls = Validator._load_obj(f"{doc.name[:-9]}.{cls_name}")

Any preference?

Either seems okay, hopefully they're equivalent!

…e conditions they're used to check

…uctor checking

…hen the constructor has no parameters, also modified docstring descriptions for clarity

…endency

stefanv

@larsoner Would appreciate your eyes on lines 641 through 652. Otherwise LGTM.

doc/format.rst

stefanv · 2024-12-18T06:17:45Z

doc/format.rst

-constructor's parameters.
+constructor's parameters. While repetition is unnecessary, a docstring for
+the class constructor (``__init__``) can be added optionally to provide
+detailed initialization documentation.


We recommended only the class docstring before. How do documentation writers decide what to put in the two docstrings?

Above my introductory pay grade, but I would stick to recommending class docstring only? The changes only allow flexibility for a constructor docstring if desired.

Yes:

There should be one-- and preferably only one --obvious way to do it.

And all that :)

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>

larsoner · 2024-12-30T16:45:15Z

numpydoc/validate.py

+        # Check if the object is a class and has a docstring in the constructor
+        if doc.name.endswith("__init__") and doc.is_function_or_method:
+            cls_name = doc.code_obj.__qualname__.split(".")[0]
+            cls = getattr(importlib.import_module(doc.code_obj.__module__), cls_name)


Looks like Validator._load_obj(f"{doc.code_obj.__module__}.{doc.code_obj.__qualname__}") might do it, or maybe simpler Validator._load_obj(doc.name[:-9]) could work. @mattgebert do you want to try it (probably the second one)?

numpydoc/validate.py

MAINT: Changed constructor identification in validation by including class method '.' Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

…fined when checking constructor docstring to decide if reporting GL08 error hooks/validate_docstrings.py implmements an ASTValidator class that does not define a 'code_obj' attribute. Possibly another way to link to the class docstring.

…getattr module accessors

larsoner · 2025-01-10T15:25:29Z

Thanks @mattgebert !

…checking for initialisation docstring Test written due to bug missed in numpy#592.

mgorny · 2025-07-19T06:17:12Z

This change has caused regressions in half a dozen packages, see #638.

mattgebert · 2025-07-19T08:14:12Z

numpydoc/validate.py

+            and doc.is_function_or_method
+            and hasattr(doc, "code_obj")
+        ):
+            cls_name = doc.code_obj.__qualname__.split(".")[0]


This line is incorrect and fixed by #622

mattgebert · 2025-07-19T15:02:13Z

This change has caused regressions in half a dozen packages, see #638.

Sorry this has happened!

This feature honestly wasn't fully complete and had an active pull request in #622 when 1.9.0 was released last month. FYI, This pull request has an update that also integrates the AST (abstract syntax tree) validator for hooks in #622.

I've added the suggested fix for #638 to #622, hopefully this is approved soon.

In upgrading via numpy#592 and numpy#622, requires stable use of __qualname__, not supported in dataclasses in python3.9 (solves numpy#637).

) * build(pyproject.toml): drop support for python 3.9 (require 3.10+) In upgrading via #592 and #622, requires stable use of __qualname__, not supported in dataclasses in python3.9 (solves #637). * style: Replace isinstance calls that use tuples to the `|` operator as per ruff UP038 * refactor(cli.py): exchange union use for '|' as per ruff UP007 * refactor(test_docscrape): explicitly declare strict=True for testing zips * test(test_docscrape.py): use strict and include 4th parameter check for the docscrape test * refactor(validate.py): remove `Optional[X]` for use of `X | None` ruff UP007, UP045 * refactor(test_docscrape.py): ruff formatting

* fix(validate.py): Considers subclass nesting when checking GL08 constructor Introduced GL08 checking for constructors (i.e. __init__) but didn't traverse the parent class heireacy when importing the __init__ parent from a module. * test(validate.py): Added a test to check nested class docstring when checking for initialisation docstring Test written due to bug missed in #592. * fix(validate.py): Allows the validator to check AST constructor docstrings compliance with parent class The abstract syntax tree doesn't provide any link to a parent class at node level, so special traversal is required to check constructor parent implementation of docstrings. * test(test_validate_hook.py,-example_module.py): Wrote new example_module tests for AST (AbstractSyntaxTree) discovery of constructor method parent class. * ci(test.yml): Added --pre option to prerelease job to ensure pre-release installation, and changed pytest invocation to use `numpydoc` instead of `.`, for consistency with `test` job In response to discussion on #591 * refactor(tests): Remove `__init__.py` module status of `tests\hooks\` to match `tests\` directory * ci(test.yml): Added explicit call to hook tests to see if included in pytest execution * test(tests\hooks\test_validate_hook.py): Changed constructor validation to use AST ancestry, fixed hook tests and added Windows support for test_utils * ci(test.yml): Added file existance check for hook tests Workflows do not seem to be running hook pytests. * ci(test.yml): Correct the workflow task name/version * ci(test.yml): Added explicit pytest call to the hooks directory * ci(test.yml): Removed file existance test, after explicit call to hooks verifies execution * fix(validate.py): switched conditional GL08 check order to avoid property class failure for Validator.name Solves Issue #638, though lacks property support for property class attributes. * test(test_validate.py): add coverage for existing / expected functionality of property and dataclass objects * test(test_validate_hook.py): modify test strings and remove unused os.sep replacement Updates to make this PR compatible with the recent merge from #653

mattgebert added 3 commits December 11, 2024 23:40

MAINT: Changed class constructor __init__ GL08 reporting to only if c…

bd64a7d

…lass docstring isn't complete

DOC: Described new class docstring and constructor GL08 interaction

998d72f

DOC: Fixed invalid classdoc reference

a43b5b9

larsoner added the type: Bug fix label Dec 16, 2024

Merge branch 'numpy:main' into GL08_Constructor_Checking

cc5fe97

larsoner approved these changes Dec 17, 2024

View reviewed changes

stefanv reviewed Dec 17, 2024

View reviewed changes

mattgebert and others added 5 commits December 18, 2024 14:08

Merge branch 'numpy:main' into GL08_Constructor_Checking

ea2c5e3

test(test_validate.py): Changed test class names to better reflect th…

3f51f53

…e conditions they're used to check

docs(validation.rst,-format.rst): Cleaned up doc references to constr…

66818ea

…uctor checking

test(test_validate.py): Extra test case for a constructor docstring w…

b22eb3b

…hen the constructor has no parameters, also modified docstring descriptions for clarity

docs(validation.rst): Changed words to better articular docstring dep…

be2bd62

…endency

stefanv approved these changes Dec 18, 2024

View reviewed changes

mattgebert and others added 2 commits December 18, 2024 22:34

doc(doc/format.rst): Grammar

296043d

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>

Merge branch 'main' into GL08_Constructor_Checking

e0edc18

larsoner reviewed Dec 30, 2024

View reviewed changes

mattgebert and others added 4 commits January 9, 2025 07:25

Merge branch 'numpy:main' into GL08_Constructor_Checking

b7eb310

Update numpydoc/validate.py

de00113

MAINT: Changed constructor identification in validation by including class method '.' Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

refactor(validate.py): Used Validator._load_obj instead of importlib/…

8fb92b5

…getattr module accessors

larsoner merged commit 6d5eb42 into numpy:main Jan 10, 2025
25 checks passed

stefanv added this to the 1.9.0 milestone Jan 10, 2025

stefmolin mentioned this pull request Feb 15, 2025

Fix typo in validation.rst #605

Merged

mattgebert added a commit to mattgebert/numpydoc that referenced this pull request Apr 6, 2025

test(validate.py): Added a test to check nested class docstring when …

c7da072

…checking for initialisation docstring Test written due to bug missed in numpy#592.

mattgebert mentioned this pull request May 11, 2025

Constructor checking for AST validator #622

Merged

argerlt mentioned this pull request Jul 3, 2025

Numpydoc 1.9.0: AttributeError: 'property' object has no attribute '__module__'. #638

Closed

mattgebert commented Jul 19, 2025

View reviewed changes

mattgebert mentioned this pull request Jul 27, 2025

build(pyproject.toml): drop support for python 3.9 (require 3.10+) #641

Merged

Uh oh!

MAINT: Changed class constructor __init__ GL08 reporting #592

MAINT: Changed class constructor __init__ GL08 reporting #592

Uh oh!

Conversation

mattgebert commented Dec 11, 2024

Uh oh!

larsoner commented Dec 16, 2024

Uh oh!

mattgebert commented Dec 17, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

format.rst -> Documenting classes

validation.rst -> Ignoring Validation Checks with Inline Comments

Uh oh!

larsoner commented Dec 17, 2024

Uh oh!

larsoner commented Dec 17, 2024

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

stefanv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stefanv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

larsoner commented Jan 10, 2025

Uh oh!

mgorny commented Jul 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattgebert commented Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MAINT: Changed class constructor init GL08 reporting #592

MAINT: Changed class constructor init GL08 reporting #592

mattgebert commented Dec 17, 2024 •

edited

Loading

format.rst -> `Documenting classes`

validation.rst -> `Ignoring Validation Checks with Inline Comments`

mattgebert commented Jul 19, 2025 •

edited

Loading