[python] Rename yaml.Config file_id parameter

[lblackstone]

Proposed changes

All of the other SDKs call this parameter file,
so rename it from file_id with deprecated
support for the old name.

Related issues (optional)

Fix #1247

[justinvp]

Technically this will break the following:

cf = ConfigFile("name", file_id="file")

Traceback (most recent call last):
  File "main.py", line 10, in <module>
    cf = ConfigFile("name", file_id="file")
TypeError: __init__() missing 1 required positional argument: 'file'

Which makes me wonder if we should even bother adding the file_id=None?

[lblackstone]

Do you have an alternate suggestion? It seems like that's a bit of an obscure edge case, and it would be nice to have this line up across the SDKs.

[justinvp]

I think we have two options (aside from keeping the name as-is):

1. If we think specifying file_id by name is rare enough, and therefore don't care so much about breaking someone, we could just rename it to file without any other changes. Any folks referring to it by name would get the error above when they run their program and will have to fix the file_id to file (or just not specify this param by name).

2. We rename file_id to file and make it optional, in addition to adding file_id=None at the end, and include the deprecation warning, and add a runtime check to ensure it is set.

   def __init__(self, name, file=None, opts=None, transformations=None, resource_prefix=None, file_id=None):
       # ...
       if file_id is not None:
           warnings.warn("explicit use of file_id is deprecated, use 'file' instead", DeprecationWarning)
           file = file_id
       if file is None:
           raise TypeError("Missing file argument")

   The benefit is that we wouldn't break anyone, but the downside is the function signature would indicate that file is optional, when it really is required.

If we're ok with the minor breaking change, I'd lean towards (1).

[lblackstone]

Oh, I realized I misunderstood your initial comment, and that this would cause an error in many cases. It's probably better to go with option 2 for now, and maybe we can make it required in a future update.

[lblackstone]

Updated with option 2. Glad you caught that @justinvp!

[justinvp]

LGTM