Feature: Add "Remove tab colour" method

[alifeee]

Closes #1166

Google colours

This ought to have been "simple", but it was a little more complex. Here are two tabs in a Google sheet:

The left is #ff007f, and the right is unset.

Google returns the tabColorStyle for each as:

{
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Data",
        "tabColor": {
          "red": 1,
          "blue": 0.49803922
        },
        "tabColorStyle": {
          "rgbColor": {
            "red": 1,
            "blue": 0.49803922
          }
        }
      }
    },
    {
      "properties": {
        "sheetId": 90870515,
        "title": "Information"
      }
    }
  ]
}

Thus, the returned colours do not include 0 values (i.e., there is no "green" in the rgbColor dict), and they are rounded to the nearest 8-bit decimal between 0 and 1 (i.e., "blue" is 127/255, or the result of setting "blue" to 0.5 with gspread).

Code to generate this output:

import gspread
import json

gc = gspread.service_account(filename="./creds.json")
worksheet = gc.open("gspread test spreadsheet")

params = {
    "fields": "sheets.properties.sheetId,sheets.properties.title,sheets.properties.tabColor,sheets.properties.tabColorStyle",
}
properties = worksheet.fetch_sheet_metadata(params=params)
with open("properties.json", "w", encoding="utf-8") as f:
    json.dump(properties, f, indent=2)

Changes

Worksheet.tab_color

• Expand docstring to explain the result you may get from Google's tab colour

Worksheet.update_tab_color

• Add type hint (dict)
• Remove "tabColor" (deprecated, see Add ability to remove tab color #1166)
• Method no longer sets `self._properties["tabColorStyle"] to color given by user
  • This is because of the above. The colour in Worksheet._properties would be different to the one returned by Spreadsheet.fetch_sheet_metadata().
  • The colour is fetched from the spreadsheet and used to update the internal _properties value. *
• Update test_update_tab_color to reflect this change
• Update test cassette WorksheetTest.test_update_tab_color.json

*this may be an unwanted extra API request

Worksheet.clear_tab_color

• Add new method clear_tab_color
• Add test test_clear_tab_color
• Add test cassette WorksheetTest.test_clear_tab_color.json

Docs

Add "Updating a Worksheet's name and color" to "Examples of gspread Usage"

[lavigne958]

Hi thank you for this contribution.

I need some time to look at it.

It looks nice at first glance. 👍

[lavigne958]

This is very interesting. thank you for catching it !

In gspread, users tend to reach their quotas very quickly, in this regard we try to minimize the number of API calls.

Do you instead of the getting the value back from the API (value that we just set) we could compute it locally instead ?

this is less reliable but should get us the same result and prevent us from having new API calls.

eg:

• we could round to the nearest lower positive integer value then divide by 255 which should give us the same value
  like:

green=0.5
real_green = rount(math.floor(green*255) / 255)
green
>>> 0.49803922

the above value is exactly what I get from the API but using computation only.

what do you think ?

[alifeee]

Minimising API requests is always nice.

The below assumes that strict equality between colours is required (e.g., if a user wants to use "==" to compare colors)

For this function, the problem is the rounding. Google returns colors inconsistently rounded:

We could:

• compute colours manually, and they will not be exactly the same as Google, but near enough (if this is done, there is not much point manually computing the coalescence, since the user input "0.5" will be just as "close enough" as our badly rounded attempt)
• keep the API call

[lavigne958]

Yeah I see 🧐 I don't think the user will compare so much the colors but as you mentioned: if someone wants to check the current color then they will read "0.495857" and so it won't latch so they will set it to "0.5" which will have not effect because it's already set and cost 1 API call 😬

Thinking about it:

• the API uses float values
• but colors are always set using integer between [0:255]
• why do we have to ask the user for a float and then change it 🧐

Can't we use whol numbers from 0 to 255 do the computation for the API and then return the appropriate value for the user ?

You see what I mean?

Btw: that's a breaking change 😛

[alifeee]

Yes, this sounds good.

If the color is set with 0-255 (i.e., with hex #RRGGBB), then it makes sense to use that to set/read color, rather than these 'random' floats.

Then, we could also offer either

• set_color("#FF0080")
• set_color(255, 0, 128)
• set_color({"red": 255, "green": 0, "blue": 128})

Not sure which you would prefer. You likely have a good idea from your signature typing adventure which is easiest/best.

Let's put this pull request in milestone v6.0.0?

[lavigne958]

Yes, this sounds good.

If the color is set with 0-255 (i.e., with hex #RRGGBB), then it makes sense to use that to set/read color, rather than these 'random' floats.

Then, we could also offer either

• set_color("#FF0080")
• set_color(255, 0, 128)
• set_color({"red": 255, "green": 0, "blue": 128})

Not sure which you would prefer. You likely have a good idea from your signature typing adventure which is easiest/best.

Let's put this pull request in milestone v6.0.0?

I was gonna say the same thing: this becomes a breaking change that we will put in 6.0.0 😆

currently we can keep the PR with:

• we remove the old field that we don't need to set anymore tabColorStyle, as it has been deprecated.
• we add the new method to remove the tab color, that is still useful for users
• we keep the way we set the colors in the properties: this way if a user sets a color of red: 0.5 when the user reads the value it gets: 0.5 what has been set previously. no fuzzing with float values.

the rest we can add later:

1. a new method to set the color of a tab, something like: set_tab_color(hex_color) that takes only a color as hex value
2. a new function in utils.py that can convert a color from 3 arguments to a hex value: convert_colors_to_hex_value(red, gree, blue) this way a user can use it 2 in ways seamlessly:
   1. using direct argument assignment: ..._hex_value(123,43,12)
   2. using named arguments: ..._hex_value(red=123, green=43, blue=12)

[alifeee]

Sounds good.

I can do the first step now to edit the PR.

For the additions: I am not that good at function decorators (so they can take multiple arguments). Perhaps something for you to look at.

Should we make an issue for it?

[alifeee]

I will be happy to merge this as it is the last branch left in my fork ^^

[lavigne958]

Looks good to me, merge time.