Feature: respect newline characters in strings

[davemfish]

Instead of dumping a string with newline characters directly, we can add a yaml block indicator ( | ) to indicate that the dumper should treat newline chars as newlines. https://yaml-multiline.info/

The upshot is that we get this "literal" block,

lineage: |-
  Created by natcap.invest.annual_water_yield.execute(
  {'biophysical_table_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\biophysical_table_gura.csv',
   'depth_to_root_rest_layer_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\depth_to_root_restricting_layer_gura.tif',
   'eto_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\reference_ET_gura.tif',
   'lulc_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\land_use_gura.tif',
   'pawc_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\plant_available_water_fraction_gura.tif',
   'precipitation_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\precipitation_gura.tif',
   'results_suffix': 'gura',
   'seasonality_constant': '5',
   'sub_watersheds_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\subwatersheds_gura.shp',
   'watersheds_path': 'C:\\Users\\dmf\\projects\\invest\\data\\invest-sample-data\\Annual_Water_Yield\\watershed_gura.shp',
   'workspace_dir': 'runs/awy'})
  Version 3.14.1.post384+g36834555f.d20241029

instead of this double-quoted block,

lineage: "Created by natcap.invest.annual_water_yield.execute(\n{'biophysical_table_path':\
  \ 'C:\\\\Users\\\\dmf\\\\projects\\\\invest\\\\data\\\\invest-sample-data\\\\Annual_Water_Yield\\\
  \\biophysical_table_gura.csv',\n 'depth_to_root_rest_layer_path': 'C:\\\\Users\\\
  \\dmf\\\\projects\\\\invest\\\\data\\\\invest-sample-data\\\\Annual_Water_Yield\\\
  \\depth_to_root_restricting_layer_gura.tif',\n 'eto_path': 'C:\\\\Users\\\\dmf\\\
  \\projects\\\\invest\\\\data\\\\invest-sample-data\\\\Annual_Water_Yield\\\\reference_ET_gura.tif',\n\
  \ 'lulc_path': 'C:\\\\Users\\\\dmf\\\\projects\\\\invest\\\\data\\\\invest-sample-data\\\
  \\Annual_Water_Yield\\\\land_use_gura.tif',\n 'pawc_path': 'C:\\\\Users\\\\dmf\\\
  \\projects\\\\invest\\\\data\\\\invest-sample-data\\\\Annual_Water_Yield\\\\plant_available_water_fraction_gura.tif',\n\
  \ 'precipitation_path': 'C:\\\\Users\\\\dmf\\\\projects\\\\invest\\\\data\\\\invest-sample-data\\\
  \\Annual_Water_Yield\\\\precipitation_gura.tif',\n 'results_suffix': 'gura',\n 'seasonality_constant':\
  \ '5',\n 'sub_watersheds_path': 'C:\\\\Users\\\\dmf\\\\projects\\\\invest\\\\data\\\
  \\invest-sample-data\\\\Annual_Water_Yield\\\\subwatersheds_gura.shp',\n 'watersheds_path':\
  \ 'C:\\\\Users\\\\dmf\\\\projects\\\\invest\\\\data\\\\invest-sample-data\\\\Annual_Water_Yield\\\
  \\watershed_gura.shp',\n 'workspace_dir': 'runs/awy'})\nVersion 3.14.1.post384+g36834555f.d20241029"

[davemfish]

Not related to the rest of the PR, but we should have been using the human-readable names all along.

[phargogh]

Thanks, @davemfish ! This makes sense to me, and thank you for illuminating the | vs > behavior in YAML ... that was a really helpful resource.

I really just have one question, which has to do with the modification of the yaml module's state and whether it might make sense to put that into the dumper subclass we have defined here in utils. I don't know enough about the yaml module to be able to say for sure what would be best, but it would be very common to have these functional updates represented in a subclass. Curious what you think!

[phargogh]

Since we are subclassing _NoAliasDumper from yaml.SafeDumper, is self.add_representer something that we could or should call in an __init__(...) method of _NoAliasDumper? It makes sense to me that we would want to modify behavior, but I guess I'm just wondering if we can do this without modifying global state, which would put us at risk of a race condition that could break expected behavior.

[davemfish]

@phargogh great idea, thank you! I pushed this change.

[phargogh]

Thanks @davemfish !