fix: unsetting clustering fields on Table is now possible

[plamut]

Closes #615.

Support for mutable clustering configuration already existed, but due to a bug it was not possible to unset the clustering fields altogether. This PR fixes that, and makes some refactoring changes to table.py.

PR checklist:

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)
  • "Documentation reflects this capability, and possibly links to the cloud.google.com content above to describe the behavior when clustering is added/changed." - DONE in #330 (samples using clustering on a non-partitioned table).
  • "Stale comments indicating that clustering requires a partitioning config are removed (you can cluster a table without partitioning it)" - DONE in #286

[tswast]

Sweet! Just one suggestion, but otherwise looks good. Thanks for adding that system test.

[tswast]

Ah! That makes sense. I bet we could go one level further and do some metaclass magic to generate properties, but metaclasses are one level of magic too far in my opinion. This looks good to me.

[plamut]

I always thought a custom dict subtype could be useful here, but never convinced myself that we really need it - even though it would be less arcane than using metaclasses.

Proof of concept (untested):

class ApiProperties(dict):
    def __getitem__(self, key):
        if not isinstance(key, tuple):
            return super().__getitem__(key)
        result = super()
        for item in key:
            result = result.__getitem__(item)
        return result

>>> p = ApiProperties({"foo": {"subfoo": "bar"}})
>>> p
{'foo': {'subfoo': 'bar'}}
>>> p["foo"]["subfoo"]
'bar'
>>> p["foo", "subfoo"]  # also works, without _helpers
'bar'

The customized dict would assume that the keys are never tuples (which is true, we just use strings), and it could override __setitem__() in a similar fashion. An it could also automatically create subdictionaries if a (sub) key does not exist yet, similarly to defaultdict. And more...

We could consider this a a possible P3 improvement at some point in the future...

Edit: Ah, you mean generating the properties on the basis of _PROPERTY_TO_API_FIELD declarations? That would be fun, but probably indeed too magical.

[tswast]

I hadn't thought about subclassing what we use for dictionaries. That would indeed help clean thing up a bit, assuming it's still JSON-serializable.