Better document that records should be a list/iterable of data dictionaries

As mentioned in https://github.com/fastavro/fastavro/issues/252#issuecomment-407165534, it’s not as clear as it should be that records is an iterable of data dictionaries. If someone provides just a dictionary they get a confusing exception. Perhaps we could also add a small check to make sure data is an acceptable format.

[scottbelden]

@300LiterPropofol Are you trying to use writer or schemaless_writer?

Suppose you have a record like this:

record = {...}

If you are using writer, it expects an iterable of records. An easy way to write a single record would be like this:

writer(fp, schema, [record])  # Notice how the single record dictionary is wrapped in a list

If you are using schemaless_writer, it expects a single record (since it can only be used to encode a single record). Therefore, it is called like this:

schemaless_writer(fp, schema, record)  # Notice how we pass the single dictionary without wrapping it in a list

Does this answer your question?

[300LiterPropofol]

Thank you very much for your reply! I noticed this difference after re-reading the source code a couple of times. Also I finally found my exception is not essentially caused by schemaless-writer function’s record input format but something’s format inside the record, your explanation is really clear and really helpful. Thank you for being so patient and helpful all way along.