feat: colors parameter for easy color assignment

[FBumann]

Summary

Add a unified colors parameter to all plotting functions for easier color customization. Instead of remembering whether to use color_discrete_sequence, color_continuous_scale, or color_discrete_map, users can now simply use colors and the library automatically maps it to the correct Plotly parameter based on the input type.

Type-based mapping

Input Type	Example	Maps To
String (qualitative palette)	colors="D3"	color_discrete_sequence
String (continuous scale)	colors="Viridis"	color_continuous_scale
List of colors	colors=["red", "blue"]	color_discrete_sequence
Dict mapping	colors={"A": "red"}	color_discrete_map

Examples

# Named qualitative palette
da.plotly.line(colors="D3")

# Named continuous scale
da.plotly.imshow(colors="Viridis")

# Custom color list
da.plotly.line(colors=["#E63946", "#457B9D", "#2A9D8F"])

# Explicit mapping
da.plotly.line(colors={"scenario_A": "blue", "scenario_B": "red"})

Precedence

Explicit color_* kwargs in px_kwargs take precedence over colors. A warning is issued when colors is ignored due to explicit kwargs.

Changes

• Add Colors type alias and resolve_colors() helper in common.py
• Add colors parameter to all 8 plotting functions in plotting.py
• Add colors parameter to all 16 accessor methods in accessor.py
• Export Colors type from package
• Add 12 tests for the new parameter
• Add documentation examples in docs/examples/kwargs.ipynb

Test plan

• All existing tests pass (109 tests)
• New tests for colors parameter (12 tests)
• Manual verification of type detection (qualitative vs continuous scales)
• Warning behavior when colors conflicts with explicit color_* kwargs

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• New Features

  • Added a unified colors parameter across all plotting functions (line, bar, area, scatter, imshow, pie, and others), supporting qualitative color palettes, color lists, color mappings, and continuous scales for flexible visualization customization.

• Tests

  • Added comprehensive test coverage for the colors parameter across all plotting functions and data structures.

• Documentation

  • Added usage examples demonstrating the colors parameter with various input types and plotting scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Warning

Rate limit exceeded

@FBumann has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 11 minutes and 29 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Adds a unified colors parameter and Colors type, implements resolve_colors() to map flexible color specs to Plotly Express kwargs, and threads colors through plotting functions and accessor methods; includes tests and docs examples for the new behavior.

Changes

Cohort / File(s)	Summary
Color Handling Infrastructure xarray_plotly/common.py	Add Colors type alias, _get_qualitative_scale_names() cache, and resolve_colors(colors, px_kwargs) to validate inputs, detect qualitative vs continuous scales, map to px kwargs, and warn on conflicts.
Plotting Function Updates xarray_plotly/plotting.py	Add colors: Colors = None to 8 public plotting functions (line, bar, area, fast_bar, box, scatter, imshow, pie) and apply px_kwargs = resolve_colors(colors, px_kwargs) before figure creation.
Accessor Method Updates xarray_plotly/accessor.py	Add colors: Colors = None to corresponding DataArray and Dataset accessor methods (16 methods total) and forward the parameter to underlying plotting functions.
Module Exports xarray_plotly/__init__.py	Export Colors in package public API by importing and adding it to __all__.
Tests tests/test_accessor.py	Add TestColorsParameter with tests covering list/dict/string/qualitative continuous inputs, px kwargs warning behavior, defaults, and compatibility across plotting helpers and dataset/unnamed dataarray cases.
Docs / Examples docs/examples/kwargs.ipynb	Add examples and explanation demonstrating the unified colors parameter and mapping rules (qualitative palettes, lists, dicts, continuous scales, heatmap example).

Sequence Diagram

sequenceDiagram
    participant User as User Code
    participant Accessor as Accessor Method
    participant Plotting as Plotting Function
    participant Resolver as resolve_colors()
    participant PX as Plotly Express

    User->>Accessor: call accessor(..., colors=...)
    Accessor->>Plotting: call plotting(..., colors=..., **px_kwargs)
    Plotting->>Resolver: resolve_colors(colors, px_kwargs)
    Resolver->>Resolver: validate type & detect scale (qualitative/continuous)
    Resolver->>Resolver: map to px kwarg(s) (color_discrete_sequence / color_continuous_scale / color_discrete_map)
    Resolver-->>Plotting: return modified px_kwargs
    Plotting->>PX: px.* with resolved px_kwargs
    PX-->>Plotting: Figure
    Plotting-->>Accessor: Figure
    Accessor-->>User: Figure

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Add pie plots #8: Shares modifications to pie() plotting codepaths and may overlap with accessor/plotting changes for pie handling.

Poem

🐰 I stitched a ribbon of color through plots one by one,
From accessor to px the hues now run,
Lists, maps, or scales—each finds its place,
resolve_colors() hops in with elegant grace,
Happy charts all around, a rainbow well-spun! 🎨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat: colors parameter for easy color assignment' clearly and concisely summarizes the main feature added: a unified colors parameter for simplified color assignment across plotting functions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@tests/test_accessor.py`:
- Around line 462-476: The test
test_colors_ignored_with_warning_when_px_kwargs_present is brittle because it
asserts len(w) == 1; instead, change the assertion to verify that the expected
warning about "colors" being "ignored" is present in the captured warnings
(e.g., use any("colors" in str(m.message).lower() and "ignored" in
str(m.message).lower() for m in w) or similar) and remove the strict count check
so unrelated warnings won't break the test; keep the subsequent assertion that
fig.data[0].line.color == "orange" to ensure px kwargs take precedence.