[0.2.dev6] Introducing settings objects

[smmaurer]

This PR adds the first "settings objects," as proposed in issue #54 and sketched out for the column templates in issue #98 (comment). This lets common sets of parameters be defined in a single place, improving consistency and reducing the amount of repeated code.

New classes

• shared.CoreTemplateSettings, with parameters for all templates
• shared.OutputColumnSettings, for any template that generates or modifies a column
• data.ExpressionSettings, with custom parameters for the ColumnFromExpression template

New shared functions

• shared.register_column(), to register a callable as an Orca column
• utils.col_in_expression(), to extract column names from a df.eval()-style expression

Update to ColumnFromExpression

This allows us to restructure the inputs of the first column template:

meta : CoreTemplateSettings
- name
- tags
- notes
- autorun
data : ExpressionSettings
- table
- expression
output : OutputColumnSettings
- column_name
- table  # set to data.table by default
- data_type
- missing_values
- cache
- cache_scope

Old usage:

c = ColumnFromExpression()
c.table = 'zones'
c.expression = 'residential_vacancy_rate * 100'
c.column_name = 'residential_vacancy_pct'

New usage:

c = ColumnFromExpression()
c.data.table = 'zones'
c.data.expression = 'residential_vacancy_rate * 100'
c.output.column_name = 'residential_vacancy_pct'

User migration

This breaks the API for ColumnFromExpression, but the fixes are easy, as shown above.

For saved YAML files, i've written a converter. When ModelManager opens a saved ColumnFromExpression that uses the older format, it will automatically be loaded correctly: column_from_expression.py#L73-L104.

(ColumnFromExpression was only added in the prior PR, so i wrote this mostly as a proof of concept for how we can roll out similar updates for other templates.)

Versioning

0.2.dev6

To do before merging

• CoreTemplateSettings
• OutputColumnSettings
• ExpressionSettings
• factor out shared functions
• test yaml converter
• update documentation
• finalize versioning

[coveralls]

Coverage decreased (-0.2%) to 92.043% when pulling 7744ad4 on settings-objects into f5bd26e on master.

[coveralls]

Coverage decreased (-0.2%) to 92.043% when pulling 7744ad4 on settings-objects into f5bd26e on master.