Clarify parser specifications

[kruschk]

Having worked on a few parsers now, I've struggled with a few questions that I wasn't able to answer by reading the wiki pages, such as Building a new parser. This is probably a good opportunity to improve the documentation! Here are some of the questions I've encountered:

1. Is there any semantic difference between a returned dictionary's (consumption, production, etc.) value(s) being set to 0.0 versus None? If not, should there be?
2. I think that every parser I've seen returns a datetime.datetime object, but the wiki uses ISO 8601 date-time strings. Are both acceptable?
3. Which parser functions may, beyond returning a single dictionary, also return lists of dictionaries?
4. When a list of dictionaries is returned, does the order of the list matter?
5. When should a parser return a list of dictionaries?
6. What are the conventions for handling invalid or missing data? For example, if a target date-time is requested, and the source API is not able to provide historical data for that date, a parser could return None, or a dictionary whose values are all set to None, or an empty list, or a list of Nones, or a list of dictionaries whose values are all set to None, or raise an exception (which one?), or maybe something else entirely! 😵‍💫

[madsnedergaard]

Those are some very good (and hard) questions 😄
We should definitely address those both in wiki, but also in typing so that there's stricter rules and it's easier to not make mistakes. It's on our backlog, but not something we currently have a lot of time or resources to do, so we'd love some help on this! 🚀

[kruschk]

I had a feeling these weren't easy questions to answer! I would guess that the implementation of the back-end has already answered the first four questions (except for the second part of 1). If I'm right and we could document that behaviour, I think it would go a long way. The other, more philosophical questions may require a bit more discussion.

I don't believe there's any way to suggest wiki edits, but if you don't mind, I could try to make a few clarifying edits and add type hints. My current working assumptions are that for 2, the datetime value must be a timezone-aware datetime.datetime object, and for 5, the answer is "whenever the source API makes it convenient".

[q--]

I'd add, there appear to be parser functions for capacity data (I just encountered one in #4048) that seem entirely undocumented. The old Australia parser (IDK about the new one) even had e.g. exchange capacity change in real-time.

As for 0.0 vs None, I think the latter gives a ? whereas the former does not.