You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Enable numpydoc docstring validation for astropy.cosmology - #20774
Remove astropy/cosmology from the numpydoc-validation exclude list and fix the reported docstring issues: document missing parameters and return values, fix punctuation/capitalization, remove extra blank lines, and fix stale or misordered parameter docs.
Some reports are false positives of the static (AST-based) hook and are silenced inline with # numpydoc ignore=...:
dataclass-generated __init__ (Cosmology subclasses, Parameter, ParametersAttribute) whose parameters are documented on the class;
the unified I/O descriptor classes, which document __call__;
format, which is added by _comparison_decorator;
small private closures / helpers that defer to another docstring.
AI Disclosure
I ran numpydoc and fed it to an agent to fix. I reviewed.
I certify that I am human and that I take full responsibility for this pull request including all interactions with reviewers.
Merge method
By checking this box, the PR author has requested that maintainers do NOT use the "Squash and Merge" button. Maintainers should respect this when possible; however, the final decision is at the discretion of the maintainer that merges the PR.
…e issues
Remove astropy/cosmology from the numpydoc-validation exclude list and fix
the reported docstring issues: document missing parameters and return
values, fix punctuation/capitalization, remove extra blank lines, and fix
stale or misordered parameter docs.
Some reports are false positives of the static (AST-based) hook and are
silenced inline with ``# numpydoc ignore=...``:
- dataclass-generated ``__init__`` (Cosmology subclasses, Parameter,
ParametersAttribute) whose parameters are documented on the class;
- the unified I/O descriptor classes, which document ``__call__``;
- ``format``, which is added by ``_comparison_decorator``;
- small private closures / helpers that defer to another docstring.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.
Do the proposed changes actually accomplish desired goals?
Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.
The reason will be displayed to describe this comment to others. Learn more.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🟡 Changes recommended
The change still has unresolved documentation nits—including misleading/inaccurate docstrings and minor grammar—that should be corrected to avoid confusion and potential future lint failures.
This PR enables numpydoc docstring validation for astropy.cosmology by removing the package from the validation exclude list and bringing cosmology docstrings into compliance, with targeted inline ignore annotations for known static-check false positives.
Changes:
Remove astropy/cosmology from the numpydoc-validation exclude list (pyproject.toml).
Fix/complete numerous docstrings in astropy.cosmology (parameters/returns, punctuation/capitalization, ordering, and blank-line cleanup).
Add scoped # numpydoc ignore=... markers for dataclass-generated/decorated signatures and small helper closures that confuse the AST-based validator.
File
Description
pyproject.toml
Stops excluding astropy/cosmology from numpydoc validation.
astropy/cosmology/__init__.py
Documents lazy __getattr__ realization access.
astropy/cosmology/realizations.py
Documents lazy __getattr__ realization construction and return type.
astropy/cosmology/parameters.py
Expands __getattr__ docstring for lazy parameter mapping access.
astropy/cosmology/_src/core.py
Adds/cleans docstrings for dataclass/signature helpers and base Cosmology class behavior; adds numpydoc ignores for dataclass signature noise.
astropy/cosmology/_src/default.py
Clarifies default_cosmology.validate parameter/return semantics in docstring.
astropy/cosmology/_src/utils.py
Docstring cleanup plus numpydoc ignore for vectorize_redshift_method wrapper; documents aszarr and docstring formatting fixes.
astropy/cosmology/_src/units_equivalencies.py
Docstring capitalization/punctuation fixes; adds numpydoc ignores for small closure helpers in equivalency factories.
astropy/cosmology/_src/funcs/optimize.py
Adds numpydoc ignore for private scalar helper; reorders docstring sections to satisfy numpydoc expectations.
The reason will be displayed to describe this comment to others. Learn more.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🟡 Changes recommended
The change still has active findings: one introduces a runtime error by placing numpydoc section headers outside a docstring in __getattr__, and another leaves misleading docstring content/types for mrt_identify under enabled numpydoc validation.
The reason will be displayed to describe this comment to others. Learn more.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🔵 Needs a closer look
Several identifier functions call filepath.endswith(...) even though UnifiedIORegistry may supply filepath as an os.PathLike (e.g., pathlib.Path), risking AttributeError at runtime, and there is also a stale docstring in mrt_identify that needs updating.
UnifiedIORegistry passes path as stroros.PathLike (see astropy/io/registry/core.py), so calling filepath.endswith(...) can raise AttributeError when filepath is a pathlib.Path. Consider accepting PathLike here and normalizing with str() (or os.fspath) before checking the suffix.
UnifiedIORegistry can pass filepath as an os.PathLike (e.g. pathlib.Path). Using filepath.endswith(...) will fail for those inputs. Converting with str() (or os.fspath) avoids the AttributeError and makes the identifier work for path-like objects.
mrt_identify docstring and path handling are outdated
astropy/cosmology/_src/io/builtin/mrt.py:291
The mrt_identify docstring still says “HTML Table format”, and filepath.endswith(...) will raise AttributeError if filepath is an os.PathLike (e.g. pathlib.Path). UnifiedIORegistry can pass path-like objects as the path argument, so this identifier should normalize filepath (e.g. str(filepath) / os.fspath) before checking the suffix.
The reason will be displayed to describe this comment to others. Learn more.
I checked, and it's safe to remove. The I/O registry appends its table of formats to the Notes section of Cosmology.read and Cosmology.write. Those docstrings live in connect.py and are unchanged here. The empty Notes in write_mrt was just a leftover.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
pllim
left a comment
github-project-automation
Bot
moved this from In Progress
to Reviewer approved
in Cosmology, the Expansion
Description
Remove astropy/cosmology from the numpydoc-validation exclude list and fix the reported docstring issues: document missing parameters and return values, fix punctuation/capitalization, remove extra blank lines, and fix stale or misordered parameter docs.
Some reports are false positives of the static (AST-based) hook and are silenced inline with
# numpydoc ignore=...:__init__(Cosmology subclasses, Parameter, ParametersAttribute) whose parameters are documented on the class;__call__;format, which is added by_comparison_decorator;AI Disclosure
I ran numpydoc and fed it to an agent to fix. I reviewed.
Merge method