Add variable metadata

openfisca_core/variables/variable.py

@@ -124,6 +124,7 @@ def __init__(self, baseline_variable = None):
         self.set_input = self.set_set_input(attr.pop('set_input', None))
         self.calculate_output = self.set_calculate_output(attr.pop('calculate_output', None))
         self.is_period_size_independent = self.set(attr, 'is_period_size_independent', allowed_type = bool, default = config.VALUE_TYPES[self.value_type]['is_period_size_independent'])
+        self.metadata = self.set(attr, 'metadata', allowed_type = dict, setter = self.set_metadata, default = {})
 
         formulas_attr, unexpected_attrs = helpers._partition(attr, lambda name, value: name.startswith(config.FORMULA_NAME_PREFIX))
         self.formulas = self.set_formulas(formulas_attr)
@@ -203,6 +204,10 @@ def set_documentation(self, documentation):
         if documentation:
             return textwrap.dedent(documentation)
 
+    def set_metadata(self, metadata):
+        if metadata:
+            return metadata
+
     def set_set_input(self, set_input):
         if not set_input and self.baseline_variable:
             return self.baseline_variable.set_input

openfisca_web_api/loader/variables.py

@@ -73,6 +73,7 @@ def build_variable(variable, country_package_metadata, tax_benefit_system):
         'defaultValue': get_default_value(variable),
         'definitionPeriod': variable.definition_period.upper(),
         'entity': variable.entity.key,
+        'metadata': variable.metadata
         }
 
     if source_code:

tests/core/variables/test_variables.py

@@ -473,3 +473,69 @@ class variable_with_strange_attr(Variable):
 
     with raises(ValueError):
         tax_benefit_system.add_variable(variable_with_strange_attr)
+
+
+# variable with `metadata` attribute
+
+
+def test_variable_metadata_defaults_to_empty_dict():
+
+    class variable_with_no_metadata(Variable):
+        value_type = int
+        entity = Person
+        definition_period = MONTH
+        label = "Variable with metadata attribute. Metadata is a dict of integers, strings, dicts and lists."
+
+    tax_benefit_system.add_variable(variable_with_no_metadata)
+    variable = tax_benefit_system.variables['variable_with_no_metadata']
+    assert variable.metadata == {}
+
+
+# `example_variable_metadata` must be a dictionary, but can contain any
+# keys and can be nested to any depth.
+example_variable_metadata = {"Part": 5,
+                             "Schedule": "A",
+                             "Labels": [5, "test_label", {"foo": "bar"}],
+                             "Dates": {"commmencement": "01-01-2000", "expiry": "01-01-2000"}
+                             }
+
+
+def test_variable_metadata_returns_dictionary():
+
+    class variable_with_valid_metadata(Variable):
+        value_type = int
+        entity = Person
+        definition_period = MONTH
+        label = "Variable with metadata attribute. Metadata is a dict of integers, strings, dicts and lists."
+        metadata = example_variable_metadata
+
+    tax_benefit_system.add_variable(variable_with_valid_metadata)
+    variable = tax_benefit_system.variables['variable_with_valid_metadata']
+
+    assert variable.metadata == example_variable_metadata
+    assert isinstance(variable.metadata, dict)
+    assert variable.metadata["Part"] == 5
+    assert variable.metadata["Dates"]["commmencement"] == "01-01-2000"
+
+
+def test_variable_with_invalid_metadata_raises_valueerror():
+
+    class variable_with_invalid_metadata_string(Variable):
+        value_type = int
+        entity = Person
+        definition_period = MONTH
+        label = "Variable with invalid metadata attribute."
+        metadata = "ABCDEFG"
+
+    class variable_with_invalid_metadata_array(Variable):
+        value_type = int
+        entity = Person
+        definition_period = MONTH
+        label = "Variable with invalid metadata attribute."
+        metadata = [1, 5, {"foo": "bar"}]
+
+    with raises(ValueError):
+        tax_benefit_system.add_variable(variable_with_invalid_metadata_string)
+
+    with raises(ValueError):
+        tax_benefit_system.add_variable(variable_with_invalid_metadata_array)