Order of keyword args between versions can cause breakage.

[dhermes]

In Python, keyword args can also be passed as positional args. So in gapic-google-logging-v2 (0.9.3), LoggingServiceV2Api.list_log_entries had the signature:

def list_log_entries(self,
                     project_ids,
                     filter_='',
                     order_by='',
                     page_size=0,
                     options=None):

but in gapic-google-logging-v2 (0.10.1), it became:

def list_log_entries(self,
                     project_ids,
                     resource_names=None,
                     filter_='',
                     order_by='',
                     page_size=0,
                     options=None):

i.e. it grew resource_names in the middle. Hence when we called via positional only

page_iter = self._gax_api.list_log_entries(
    projects, filter_, order_by, page_size, options)

that code broke on the upgrade from 0.9.x to 0.10.x.

---

This is somewhat fine, but if you wanted, you could force users to always use some arguments as keywords by using *args, **kwargs and then unpacking args according to a specified length needed for positional and then removing from kwargs to sanitize.

[geigerj]

@bjwatson and I discussed this, and our initial opinion is not to take such a strong definition of what constitutes a breaking change; that is, if code breaks because it calls keyword arguments as positional parameters, that's not our concern.

To support this would require either (1) moving the options parameter to always be the first argument, and ensuring new optional arguments always appear at the end of the parameter list, or (2) using *args, **kwargs as the signature for all functions as you suggested. We'd prefer not to do (1) for stylistic and pragmatic reasons, and (2) seems un-Pythonic.

Still open to more discussion before we settle, though. @jonparrott, do you have any thoughts on this?

[theacodes]

Please don't use *args, **kwargs as the signature for all functions.

In general, I feel that the calling code should specify keyword arguments explicitly. If we were in a Python 3-only world, we could use keyword only arguments.

[geigerj]

I don't think we intend to change GAPIC in this area; we'll consider it the responsibility of the calling code to specify kwargs explicitly.

[theacodes]

I think it's fair to expect callers to specify kwargs as kwargs and not let args overflow into kwargs. In Python 3, you can actually do keyword-only args.

…

On Wed, Nov 23, 2016, 3:53 PM Jacob Geiger ***@***.***> wrote: Closed #526 <#526>. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#526 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAPUc3RG5KyNhKnXiZaIdMoDDnn5N_4eks5rBNH8gaJpZM4KIMa6> .