DOC: fix signature/docstring parameter mismatches in internal functions by taldcroft · Pull Request #20438 · astropy/astropy

taldcroft · 2026-09-18T12:59:51Z

Summary

Companion to #20437. That PR fixed the docstrings of public functions whose Parameters section disagreed with the signature; this one covers the remaining 29 hits from the same scan, which are private helpers or functions that are importable but not exported to the API docs (e.g. astropy.modeling.fitting.fitter_to_model_params, astropy.io.ascii.qdp._line_type, astropy.wcs.utils._sip_fit). Nothing here renders on docs.astropy.org, so this is lower priority than #20437 and only matters to people reading the source.

The problems are the same two kinds: parameters missing from or misnamed in the docstring (SAMPHubServer._retry_method documents recipient_public_key for an argument named recipient_public_id; periodic_fit in lombscargle_multiband documents a single nterms where the signature has nterms_base, nterms_band, reg_base, reg_band, regularize_by_trace and bands_fit), and numpydoc formatting (name: type with no space, so the type is parsed as part of the name).

# astropy/io/ascii/misc.py, sortmore()
    Parameters
    ----------
    One or more lists            # main: a prose line, plus a non-numpydoc "Keywords" section
    *args : list                 # this branch: proper entries for *args, globalkey and key
        One or more lists to sort.

Docstrings only; no signature or behavior changes. _cosmology_not_equal was flagged but left alone: its documented format/out keywords are injected by @_comparison_decorator, so the docstring is right for the wrapped callable.

AI disclosure

This PR includes AI-generated content using Claude Opus 5. I have carefully reviewed the content and fully understand the changes.

I certify that I am human and take responsibility for the code and interactions with reviewers.

Details

Click to expand

Make the docstring Parameters section of 29 internal functions and methods match their signature.

1. How the mismatches were found

Same scan as #20437: ast for the signature, numpydoc.docscrape.NumpyDocString for the docstring, and a lookup in the stable docs' objects.inv to split public from internal. Of 75 mismatches in total, 46 are public (fixed in #20437) and 29 are handled here.

2. Real mismatches (missing or wrong names)

Missing entries added:

io.ascii.qdp._line_type / _get_type_from_list_of_lines: delimiter.
io.fits.column._VLF.__new__: dtype.
io.fits.connect.is_fits: origin was described as "path or file object"; it is the "read"/"write" string. Now documents origin, filepath, fileobj, *args, **kwargs the way the unified I/O identifier protocol passes them (same text as is_votable in DOC: fix signature/docstring parameter mismatches in the public API #20437).
modeling.fitting.fitter_to_model_params_array: fit_param_indices.
nddata.NDArithmeticMixin._arithmetic_mask: axis (text from _arithmetic).
table.scripts.showtable.showtable: args.
timeseries...fastchi2_impl.lombscargle_fastchi2: use_fft, trig_sum_kwds (text from fast_impl).
timeseries...lombscargle_multiband.implementations.mle.periodic_fit: bands_fit, nterms_base, nterms_band, reg_base, reg_band, regularize_by_trace (text from LombScargleMultiband), replacing the stale nterms entry.
visualization.wcsaxes.CoordinateHelper._draw_ticks: renderer.
wcs.utils._sip_fit: order, coeff_names, including how params[6:] is laid out.
wcs.WCS._fix_ctype: log_message.

Wrong names corrected:

cosmology._src.io.builtin.mrt.write_mrt: cosmology -> cosmo (positional-only).
nddata.NDArithmeticMixin._arithmetic: kwargs -> **kwds; _prepare_then_do_arithmetic: operations -> operation, and its Result section heading (not a numpydoc section) -> Returns.
samp.SAMPHubServer._retry_method: recipient_public_key -> recipient_public_id.

3. Format mismatches

name: type -> name : type in cosmology._src.utils.deprecated_keywords (*kws), io.misc.ecsv.read_data (engine_name), modeling.fitting.fitter_to_model_params and fitter_to_model_params_array (use_min_max_bounds), modeling.utils._SpecialOperatorsDict.add (operator_name, operator), uncertainty.Distribution._result_as_distribution (ncore_out, axis), utils.decorators.future_keyword_only (names, since), wcs.utils._linear_wcs_fit (lon, lat, x, y, w_obj).

io.ascii.misc.sortmore: the Parameters block was a prose line followed by a non-standard Keywords section with if key: None style entries. Rewritten as *args, globalkey, key entries carrying the same information, and the Returns entry given a name and type.

io.fits.util._array_to_file: a trailing paragraph inside the Parameters block moved into the extended summary.

units.Quantity._wrap_function: unit and out were listed after a prose line ("If present, the following arguments are treated specially") rather than as entries; now all five parameters are entries, in signature order.

4. Implementation

All edits are inside docstrings; git diff --stat upstream/main is 21 files, 112 insertions, 64 deletions. pre-commit run --files <changed> passes (ruff, codespell, numpydoc-validation). Doctests in the changed modules (qdp.py has several): python -m pytest <changed files> gives 19 passed.

5. Backwards compatibility

No API or behavior change. No changelog fragment, per the "pure doc changes" rule.

Fix docstrings whose Parameters section did not match the function signature, for private helpers and functions not exported to the API docs. - Add missing parameter entries (e.g. qdp._line_type delimiter, _sip_fit order/coeff_names, periodic_fit nterms_base/nterms_band/reg_*, is_fits filepath/fileobj). - Correct wrong names (SAMPHubServer._retry_method recipient_public_id, write_mrt cosmo, _prepare_then_do_arithmetic operation). - Fix numpydoc formatting: 'name: type' -> 'name : type'; rewrite the sortmore docstring with a proper Parameters section; move a trailing paragraph out of the Parameters section in _array_to_file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

github-actions · 2026-09-18T13:00:07Z

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?
Do the proposed changes follow the Astropy coding guidelines?
Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
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.

pllim · 2026-09-18T15:09:06Z

Same comment as #20437 (comment)

astrofrog · 2026-09-18T16:08:45Z

@taldcroft just FYI I am fixing all the WCSAxes docstrings in #20434 (review)

mhvk

OK for table, uncertainty, units (numpydoc should be less picky about the space before the colon!).

github-actions Bot added wcs table io.fits io.ascii nddata units modeling cosmology utils io.misc unified-io samp visualization.wcsaxes uncertainty timeseries labels Sep 18, 2026

github-project-automation Bot added this to Cosmology, the Expansion Sep 18, 2026

github-project-automation Bot moved this to Triage in Cosmology, the Expansion Sep 18, 2026

taldcroft mentioned this pull request Sep 18, 2026

Add type annotations to the astropy.table subpackage #20276

Open

1 task

pllim added this to the v8.1.0 milestone Sep 18, 2026

mhvk approved these changes Sep 18, 2026

View reviewed changes

github-project-automation Bot moved this from Triage to Reviewer approved in Cosmology, the Expansion Sep 18, 2026

Navigation Menu

Uh oh!

DOC: fix signature/docstring parameter mismatches in internal functions - #20438

DOC: fix signature/docstring parameter mismatches in internal functions#20438
taldcroft wants to merge 1 commit into
astropy:mainfrom
taldcroft:fix-docstring-params-internal

taldcroft commented Sep 18, 2026

Uh oh!

github-actions Bot commented Sep 18, 2026

Uh oh!

pllim commented Sep 18, 2026

Uh oh!

astrofrog commented Sep 18, 2026

Uh oh!

mhvk left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

taldcroft commented Sep 18, 2026

Summary

AI disclosure

Details

1. How the mismatches were found

2. Real mismatches (missing or wrong names)

3. Format mismatches

4. Implementation

5. Backwards compatibility

Uh oh!

github-actions Bot commented Sep 18, 2026

Uh oh!

pllim commented Sep 18, 2026

Uh oh!

astrofrog commented Sep 18, 2026

Uh oh!

mhvk left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants