Design for xml writer

[AdRiley]

Some initial design ideas for a simple XML writer.

These mock ups show a to_xml method on Table, but the same API could be applied to a file writer with some additional design.

to_xml takes 5 parameters (all optional)

• attribute_columns = []
• element_columns = []
• root_element_name="root"
• row_element_name="row"
• error_on_missing_columns=True

In the default case where nothing is set we get an XML document where each row of data is an xml element called row and all columns become attributes.

If you specify a column to be an attribute, all unspecified columns become elements

Likewise if you specify a column to be an attribute, all unspecified columns become attributes

If you specify attributes and elements then you will only get those specified columns in the xml. Plus a warning that you have fields you are not using. (The warning can be hushed via the error_on_missing_columns parameter)

The root_element_name and row_element_name parameters allow customising of the respective element names

[jdunkerley]

I'd prefer defaulting to being child nodes rather than attributes and liked the idea of using @ to allow controlling this just from column names.

We should have the option of a "value column" as well. So you could have attributes and text as an output.

What will we do if a column is invalid XML node name - normalise?

[AdRiley]

I don't like the idea of "magic" column names.
Agree value column is needed.
Yes we will normalise names to valid xml.

[AdRiley]

Don't mind on what the default is so happy to switch it to child nodes.

[radeusgd]

(The warning can be hushed via the error_on_missing_columns parameter)

I'm not sure if this is right to control a warning through a parameter called error_*. Wouldn't the 'standard' on_problems parameter suit here?

[AdRiley]

Yes you are right. That would be better.

[GregoryTravis]

There are two behaviors here that are implicitly set by the values of attribute_columns and element_columns:

• Should a column be included in the output?
• If a column is included, is it an attribute or an element?

A column is included if it is explicitly mentioned, or if only one (but not both) of attribute_columns and element_columns are expclitily set.
A column is assigned to be an attribute or element (1) if it is explicitly included in one of the two column lists, or implicitly if it is not mentioned in column lists and only one of the column list parameters is used.

I worry that this might be tricky to understand.

A simpler model might be: a column is only included if it is specified in one of the two column lists. Also, we default attribute_columns to contain all fields, giving the user a way to immediately see why columns are included and in what way. (But this would require that the default value be visible in the node immediately on creation, which I don't think we support.)

[radeusgd]

+1 to that approach.

What I don't like about

If you specify a column to be an attribute, all unspecified columns become elements
is that - what if I want to just keep that column as attribute and ignore other columns altogether?

Well of course I can just drop (remove_columns) them in an earlier step.

But it feel strange that setting one column to be attribute may automatically 'flip' all the other columns to be elements instead.

I like the more explicit approach that @GregoryTravis is suggesting - it feels more predictable

[AdRiley]

Yes maybe the default behaviour is trying to be too clever. Odds are if you are creating XML you are doing it to an existing specification so are going to need to configure the component.

[AdRiley]

I am convinced by the more explicit (and less clever) approach.

[AdRiley]

Latest API design

element_columns defaults to all columns as per @GregoryTravis's suggestion.

I feel like there was feedback on what the parameter names should be, but I can't see it now.

[AdRiley]

Any objections if I remove error_on_missing_columns? And make the component always error in that case.