Clean up the API for release

[JamesWrigley]

Leaving this as a draft for now because it's still missing a lot of edge cases, notably around user-editable variables.

Example:

damn_db = Damnit(6156)            # Create an object to refer to a database for a specific proposal
run_vars = damn_db[311]           # Select a specific run
run_vars.keys()                   # Long list of variable names
run_vars["peak_dataset"].read()   # Read one of them

Fixes #33.

[JamesWrigley]

I made some more tests and added a VariableData.title property in d9e9f9b, I think the API itself is feature complete now. Last thing to do is the docs...

[JamesWrigley]

Should we treat empty strings as being 'available' for .keys()? 🤔

[JamesWrigley]

Added docs in 2e3c4be.

[takluyver]

You mean, if a key is only in the database and its value there is '' rather than None? Interesting one. I don't think you can easily get that state with user-editable variables, because we special case the empty string and save None instead:

DAMNIT/damnit/gui/table.py

Line 670 in bb7ad08

parsed = variable_type_class.parse(value) if value != '' else None

You probably can for comments, though. I'd say it's probably more friendly to say you can always look up comment, even if it's empty. But I don't feel strongly about that. You could argue that treating empty comments as absent from that run is in keeping with what we do for other missing variables.

[JamesWrigley]

I moved the API to the toplevel module in af7bbc9. I also tried out the include-missing-variables API but didn't really like it, it's annoying to have an extra step to check which variables are actually present 🤷

[JamesWrigley]

If there's no objections, I'd like to merge and deploy this tomorrow.