Fix: docs: fix DataArray.pad constant_values default documentation

The Bug

Repo: pydata/xarray Issue: #11373 Status: PR-submitted PR: https://github.com/pydata/xarray/pull/11447

Description: The docstring for DataArray.pad claimed the constant_values parameter defaults to 0, but the actual default is None (which pads with np.nan).

Fix scope: 2 lines changed in xarray/core/dataarray.py

Root Cause

The DataArray.pad() method’s docstring had two inaccuracies:

1. The type annotation stated default: 0 when the actual default is None.
2. The description said “Default is 0” when the actual behavior is to pad with np.nan.

This appears to be a copy-paste error from an earlier version of the API where constant_values did default to 0. When the implementation was changed (likely during the NamedArray migration), the default was switched to None — meaning “pad with np.nan” — but the docstring was never updated to match. Notably, the Dataset.pad documentation was already correct, suggesting the DataArray.pad docs were maintained separately and missed during synchronization.

Impact: Low. The bug is a documentation inaccuracy, not a code defect. Users could read the docstring and expect padding with 0 by default, when in fact they’d get np.nan. For most numeric workflows this doesn’t cause hard errors, but it could lead to subtle bugs in downstream calculations if the user relied on zero-padding semantics without explicitly passing constant_values=0. A user building an ML pipeline who assumed zero-padding from the docs would silently introduce NaN values into their feature array, potentially corrupting model training.

The Fix

A two-line change in the docstring of DataArray.pad:

- constant_values : scalar, tuple or mapping of Hashable to tuple, default: 0
+ constant_values : scalar, tuple or mapping of Hashable to tuple, default: None
...
- Default is 0.
+ Default is ``None``, pads with ``np.nan``.

This brings DataArray.pad’s documentation in line with Dataset.pad and the actual runtime behavior. The fix ensures users see accurate information directly in their IDE tooltips and API docs, eliminating a potential source of confusion.

Pattern & Takeaways

Pattern: Docstrings and runtime defaults drift apart when code is refactored but documentation is not updated. This is especially common when the same API is exposed on multiple classes (DataArray and Dataset) — one gets updated, the other is forgotten.

Key insight: Any time a default parameter value changes during refactoring, grep for all docstring references to that default. Better yet, use a documentation testing framework (like doctest or pytest with --doctest-docs) to catch drift between docstrings and actual behavior automatically.

Transfer Potential

High — documentation/code drift is one of the most common maintenance issues across all open-source projects. The pattern of checking sibling APIs for consistency (DataArray vs Dataset in this case) is a lightweight way to catch these discrepancies before they reach users.

---

Auto-generated from PR #11447. View all patches on GitHub.

References

[1] pydata/xarray [2] #11373 [3] https://github.com/pydata/xarray/pull/11447