DataLayer type checking / broadcasting / documentation / examples / helpful errors

[dodamih]

DataLayer is currently not very well-documented, and the exceptions that it raises are not very helpful, with unintuitive failures. The interface is pretty specific, so it's important to add examples for new users.

• It's not very intuitive that in order to set multiple column keys for multiple row keys, you have to do layer[["row1", "row2"], ("col_key1", "col_key2")] = [{"col_key1": row1col1, "col_key2": row1col2}, {"col_key1": row2col1, "col_key2": row2col2}], with the keys being specifically a tuple (list of rows, tuple of cols). If any keys are forgotten in the setter, then the code runs without complaining but doesn't set the key - there should be an info or even a warning in my opinion.

• Broadcasting is not supported, but there's no error message raised. The user might expect layer["row1", "row2"] = val to work, but it doesn't do anything while returning without issue. Similarly, layer[["row1", "row2"], "col"] = val or layer[["row1", "row2"], "col"] = val or layer[["row1", "row2"], "col"] = [val1, val2] doesn't work, but the former at least throws a RetryError. It'd be better to support it, but even if we can't it should not look like it did something when it didn't.

• The overloading for DataLayer and the default behaviour of using "value" as the column key results in unhelpful error KeyError: 'value' when a nonexistent row value is requested. The error message should be more descriptive - surely we can let the user know that the row key doesn't exist instead.

• When using DataLayer, it's important to use batched writes since individual writes are pretty slow. This should be documented somewhere.