Add maintain_size to keep asked for size in get, get_values

[alifeee]

closes #1289

Users can now specify maintain_size=True, so that "A1:C3" will always be a 3x3 array, regardless of whether the cells are full or not. See #1289 more more explanation.

>>> worksheet.get_values("A1:D4")
[
    ["1", "2"],
    ["3", "4"],
    ["5", "6"],
]

>>> worksheet.get_values("A1:D4", maintain_size=True)
[
    ["1", "2", "", ""],
    ["3", "4", "", ""],
    ["5", "6", "", ""],
    ["",  "",  "", ""],
]

In the future (6.0.0), this could be changed to be default behaviour. Thoughts?

[lavigne958]

Hi I'll look at the code when I get a chance.

About the default behavior I'm not too sure. This might be a big thing or not. I have no clue what users expect and if that's gonna break something.

We can introduce it. Introduce all the breaking change we have first then maybe, do a release 7.0.0 not too far later with this kind of breaking change. What do you think ?

[alifeee]

What do you think ?

I'm not sure. I don't have a good enough understanding of who uses gspread and how they use it to say whether this would have a large or small affect on people.

I think: people could call "A1:C4" and get a range that is not 3x4, and then be confused. They could then either:

• make their own function to pad the values
• read the gspread documentation and find "maintain_size"

I think the latter is less likely, which is why I suggested to make it default behaviour. If people did option 1 above, then their code would break, but they would just have to remove their padding function becase we provide it natively.

[lavigne958]

What do you think ?

I'm not sure. I don't have a good enough understanding of who uses gspread and how they use it to say whether this would have a large or small affect on people.

I think: people could call "A1:C4" and get a range that is not 3x4, and then be confused. They could then either:

• make their own function to pad the values
• read the gspread documentation and find "maintain_size"

I think the latter is less likely, which is why I suggested to make it default behaviour. If people did option 1 above, then their code would break, but they would just have to remove their padding function becase we provide it natively.

I agree, I would expect it too, the size of what I request to match.

What I am afraid of is if users have some kind of code around that, would it break ?

for sure the new parameter allows users to change using it for now, and then next major release we make default and then boom it's automatic.

[alifeee]

This line of the CI fails now

gspread/.github/workflows/main.yaml

Line 33 in 07aab27

- run: shopt -s globstar && pyupgrade --py3-only **/*.py # --py36-plus

Not sure why...

[alifeee]

CI fixed with #1319. Now ready for review

[lavigne958]

In order for the users to notice the new parameter we should probably:

• update the examples on the readme.md and use it about everywhere ?
• add a mention in the readme.md about the new argument ?

[alifeee]

Yes, that sounds good to me. I will be able to do it from next week.