Add chart functionality to gspread

[darkfiberiru]

This commit adds comprehensive chart support to gspread, enabling users to create, update, delete, and list charts in Google Sheets.

New features:

• Worksheet.add_chart() - Create charts with customizable properties
• Worksheet.update_chart() - Modify existing chart specifications
• Worksheet.delete_chart() - Remove charts by ID
• Worksheet.list_charts() - List all charts in a worksheet

New enums in utils:

• ChartType - Chart types (column, line, area, bar, scatter, combo, stepped_area)
• ChartLegendPosition - Legend positions (bottom, left, right, top, no_legend)
• ChartAxisPosition - Axis positions (bottom_axis, left_axis, right_axis)

Implementation details:

• Uses Google Sheets API v4 batchUpdate endpoint
• Supports multiple data series per chart
• Handles both single-range (auto-generated domain) and multi-range (explicit domain) data
• Includes input validation for data ranges and dimensions
• Converts A1 notation to GridRange format
• Properly handles enum to string conversion for API calls

Documentation:

• Added comprehensive user guide section with examples
• Includes usage examples for all chart operations
• Documents all chart types and configuration options

Fixes applied during code review:

• Fixed enum string conversion for ChartAxisPosition
• Corrected data range logic for single vs multiple ranges
• Added KeyError protection in list_charts()
• Added input validation for empty ranges and invalid dimensions
• Validated non-empty series before chart creation

🤖 Generated with Claude Code

[darkfiberiru]

@burnash I understand if you not a fan of AI for personal reason or more complicated one but realizing gap in lack of ability to create graphs with gspread library I added them with help of claude-code from anthropic. So here it is.

[darkfiberiru]

I see this repo is in freeze due to lack of maintainer

[alifeee]

I see this repo is in freeze due to lack of maintainer

hi :] thanks for the suggestion. yes it is.

please see #1570

[brianjmurrell]

@darkfiberiru Something is unclear about updating an existing chart. Let's say I have this chart data range currently defined:

How do I extend the data range, axis and series down to say line 575? I didn't see anything in Worksheet.update_chart() to update those.

[antoineeripret]

@darkfiberiru, love the idea of adding this chart feature, thank you for the PR. I think the bare-bone logic is quite strong, but:

1/ @brianjmurrell's comments are valid. I've managed to add this feature in a local branch because it's an important use case that we need to cover
2/ We need to add tests and validations to cover the new features because a lot of things can go wrong (especially with user inputs)

Do you want to keep working on this feature? I'd create a dedicate branch that we'd work on.

[darkfiberiru]

Sorry about this I didn't even click back on the notifcations. due to #1570. I would be happy to move to internal branch and put some more work in on this. @antoineeripret

[antoineeripret]

Hey @darkfiberiru,

I've published https://github.com/burnash/gspread/tree/graphs-feature-branch which is heavily based on what you did.

You can use the new methods through:

#add a chart 
worksheet.add_chart(
    data_ranges="C1:C20",
    domain_range="A1:A20",
    chart_type=ChartType.bar,
    title="Sales by Region",
    anchor_cell="E4",
    legend_position=ChartLegendPosition.right,
    width_pixels=600,
    height_pixels=400
)

#list charts 
charts = worksheet.list_charts()

#update chart 
worksheet.update_chart(
    chart_id=chart_id,
    data_ranges=["C1:C20", "D1:D20"],
    domain_range="A1:A20",
    title="Sales and Revenue by Region",
)

I'll be OOO next week but you can continue when you have a moment and I'll have a look at the beginning of May.

What needs to be done:

• Test heavily the create / list / update / delete methods to ensure that they work as expected and make some adjustments if needed
• Update documentation
• Update tests
• Record new cassettes (I'd take care of this part)

Will that work for you? What would you like to work on?

[antoineeripret]

Hey @darkfiberiru,

Did you have time to look at my previous message? This feature could be great, but it will take time if I have to work by myself on it :)

Thanks,