Skip to content

docs: clarify copy_range destination behavior#1591

Merged
antoineeripret merged 1 commit into
burnash:masterfrom
Gardner-Programs:docs/copy-range-dest-behavior
Jun 23, 2026
Merged

docs: clarify copy_range destination behavior#1591
antoineeripret merged 1 commit into
burnash:masterfrom
Gardner-Programs:docs/copy-range-dest-behavior

Conversation

@Gardner-Programs

Copy link
Copy Markdown
Contributor

Summary

Closes #1550.

The dest parameter docstring for Worksheet.copy_range claimed the destination range size "has no effect" and that the source is always copied once regardless of dest. That is only true when dest is a single cell or smaller than the source. When dest is larger, the source is actually repeated to fill it, which is the behavior the issue reporter ran into and asked to have documented.

What changed

Doc-only. Rewrote the dest description to document the real behavior:

  • The destination range does not need to match the source dimensions.
  • If dest spans a multiple of the source's height or width, the source is repeated to fill the destination range.
  • If dest is smaller than the source, the entire source is copied anyway, beyond the end of dest.

Also fixed grammar ("paste" -> "pasted", "is copies" -> "is copied") and added a CopyPasteRequest reference link next to the existing Paste Types link.

Verification

The behavior was confirmed two ways:

  • Against Google's official CopyPasteRequest docs, which state: "If the range covers a span that's a multiple of the source's height or width, then the data will be repeated to fill in the destination range. If the range is smaller than the source range, the entire source data will still be copied."
  • Live against the Sheets API: a one-row source pasted into a multi-row destination is repeated into each row, and a multi-row source repeats on exact multiples.

No code changes, so no tests or cassettes are affected.

The dest docstring incorrectly stated the destination range size has no
effect. Document the actual behavior: when dest spans a multiple of the
source, the source is repeated to fill it; when smaller, the full source
is copied anyway. Also fix grammar and add a CopyPasteRequest reference.

Closes burnash#1550
@antoineeripret

Copy link
Copy Markdown
Collaborator

Great catch, thank you @Gardner-Programs !

@antoineeripret antoineeripret merged commit 93388f9 into burnash:master Jun 23, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

copy_range() doc enhancement

2 participants