get, get_values filling empty values response from Google Sheet (with expected cells dimension) [Proposal]

This issue is made to share clear status for solving problem

Point of Contention (1 / 2)

I wrote replies at other issue get_values does not return all data in some scenarios…

But I just want to share some opinions before making a PR.

get() method https://github.com/burnash/gspread/blob/6d01d7b5bb79601d0eece20255eabed9d13aa5bf/gspread/worksheet.py#L551

and get_values() method https://github.com/burnash/gspread/blob/6d01d7b5bb79601d0eece20255eabed9d13aa5bf/gspread/worksheet.py#L254

has no difference but returning value after wrapping with util function fill_gaps() https://github.com/burnash/gspread/blob/6d01d7b5bb79601d0eece20255eabed9d13aa5bf/gspread/utils.py#L424

so I thought “is it really necessary to separate those two methods?”

Also in Documentation,

Worksheet.get

Workshhet.get_values

has no difference in explanation, because the only difference is, as I mentioned above,

get_values() returns value got from get() after wrapping with fill_gaps()

https://github.com/burnash/gspread/blob/6d01d7b5bb79601d0eece20255eabed9d13aa5bf/gspread/worksheet.py#L320

I think it’s better to integrate by separating the slight difference by kwargs and it could be more clear

---

Point of Contention (2 / 2)

Just like issue #910, when people use method like

values = MyWorksheet.get('A1:C2')
# or
values = MyWorksheet.get_values('A1:C2')

people those who are first to use this method would have expected 2-D list A1 to C2, even when every cell is empty

just like this:

# values
[
   [ None, None, None ],
   [ None, None, None ]
]

for more clear examples, see my explanation from issue comment : https://github.com/burnash/gspread/issues/910#issuecomment-952612525

I know google send just empty value, literally no values, when cells in range is empty like this

https://github.com/burnash/gspread/blob/6d01d7b5bb79601d0eece20255eabed9d13aa5bf/gspread/worksheet.py#L595

print(response)
# {'range': 'test!A2:C2', 'majorDimension': 'ROWS'}

This could be handled like this from my comment

def getMember(self, name: str, replace_empty=None) -> Member:
        result: Cell = self.memberSheet.find(name, in_column=USER_NAME_COL)

        if not result or not result.value == name:
            return MEMBER_UNKNOWN

        # y, x
        start = rowcol_to_a1(result.row, result.col - 1)
        end = rowcol_to_a1(result.row, result.col - 1 + MEMBER_INFO_width - 1)

        # edit : in this case, it's 1-D list, see that I used [0] indexing below
        # expected column length
        data = [replace_empty  for _ in range(MEMBER_INFO_width + 1)]

        reply = self.memberSheet.get_values(
            f'{start}:{end}',
            value_render_option='UNFORMATTED_VALUE'
        )[0]

        emptyFilled = [val if val else dafault for val, dafault in zip_longest(
            reply, data, fillvalue=replace_empty)]
        return emptyFilled

---

Conclusion

My proposals are…

1. integrate get() and get_value() to get()

add kwargs like maintain_shape to get expected dimension from given range

result = worksheet.get('A1:D2')

# result
[
 ['', 123 ] ,
 [ '',   ''  , 42]
]

# result(after fix), default = None
result = worksheet.get('A1:D2', maintain_shape = True)

# result
[
 [ '', 123, '',''],
 [ '', '', 42, '']
]

1. add another kwargs option(default value) to fill empty values

result = worksheet.get('A1:D2', maintain_shape = True, default = None)
# result(after fix), default = None
[
 [ None, 123, None ,None],
 [ None, None , 42, None]
]

[lavigne958]

I agree by merging the 2 methods into 1.

we could:

• update get_values so it always return a matrix of the expected size (with empty values that can be configured using default:string argument value)
• update the method get so it prints a warning that this function is deprecated and users should use get_values instead. this can be done using the package warning, one can use the following example

I just double checked and I was wrong sorry, the method get_values does not return the sheet header, it is the method get_all_records which has a different purpose.

Please don’t hesitate to open a new PR with your changes, please read the contributing documentation first 🙂

[lavigne958]

can’t plan this feature for 5.3.0 it will most probably bring breaking change (at least by the fact that the method get will disappear).

must wait for next major release