Update docs

Author: jacob720

docs/how-to/config-server-guide.md

@@ -15,7 +15,13 @@ You can then make a request through this client through its `get_file_contents`
 ```python
 config_server.get_file_contents(FILE_PATH,reset_cached_result=True)
 ```
-By default, this will return the file's raw string output - which includes things like linebreaks. It is up to you to format this output - using `splitlines()` will get you a list where each item is a line in the file. `get_file_contents` has a `desired_return_type` parameter where you can instead ask for a `dict` or `bytes`. The server will try and do the conversion, and respond with an HTTP error if the requested file is incompatible with that type.
+By default, this will return the file's raw string output - which includes things like linebreaks. It is up to you to format this output - using `splitlines()` will get you a list where each item is a line in the file. `get_file_contents` has a `desired_return_type` parameter where you can instead ask for a `dict`, `bytes` or a `pydantic model`. The server will try and do the conversion, and respond with an HTTP error if the requested file is incompatible with that type, or a pydantic validation error if the data cannot be converted to the pydantic model provided. Custom [file converters](#file-converters) can be used to specify how a file should be converted to a dict or pydantic model.
+
+# File converters
+
+Converters can be used to turn a file into a standard format server-side, reducing the complexity of reading config files client-side. Converters can convert config files to a `dict` or `pydantic model`, and the same `pydantic model` can be reconstructed client-side by the `get_file_contents` method. Available converters exist [here](https://github.com/DiamondLightSource/daq-config-server/blob/main/converters._converters.py) - see if there's a suitable converter you can use before adding your own. [This dictionary](https://github.com/DiamondLightSource/daq-config-server/blob/main/converters._file_converter_map.py) maps files to converters. Add the path of your config file and a suitable converter to this dictionary and it will automatically be used by the config server when a request for that file is made.
+
+A request for `str` or `bytes` will fetch the raw file with no conversion.
 
 # Adding files to the whitelist
 
@@ -24,9 +30,3 @@ For [security reasons](../explanations/whitelist_info.md), only files existing o
 # Reading sensitive information
 
 If you need to read a file which contains sensitive information, or `dls-dasc` doesn't have the permissions to read your file, you should encrypt this file as a [sealed secret](https://github.com/bitnami-labs/sealed-secrets) on your beamline cluster, and mount this in your BlueAPI service.
-
-# File converters
-
-Converters can be used to turn a file into a standard format server-side, reducing the complexity of reading config files client-side. Available converters exist [here](https://github.com/DiamondLightSource/daq-config-server/blob/main/converters._converters.py) - see if there's a suitable converter you can use before adding your own. [This dictionary](https://github.com/DiamondLightSource/daq-config-server/blob/main/converters._file_converter_map.py) maps files to converters. Add the path of your config file and a suitable converter to this dictionary and it will automatically be used by the config server when a request for that file is made.
-
-A request for `str` or `bytes` will fetch the raw file with no conversion.

docs/reference/current_and_planned_features.md

@@ -6,7 +6,7 @@
 - Periodically check the main branch's to update the whitelist.
 - Provide a client module for users to easily communicate with the server, with caching.
 - Have this service hosted on diamond's central argus cluster - with url `https://daq-config-server.diamond.ac.uk`
-- Provide server-side formatting for commonly used configuration files - eg `beamline_parameters.txt` should be returned as a dictionary.
+- Provide server-side json and pydantic model formatting for commonly used configuration files - eg `beamline_parameters.txt` should be returned as a dictionary.
 
 
 ## Future features

src/daq_config_server/converters/_converter_utils.py

@@ -28,8 +28,8 @@ def parse_value(value: str, convert_to: type | None = None) -> Any:
 
 
 def parse_lut(contents: str, *params: tuple[str, type | None]) -> GenericLut:
-    """Converts a lookup table to a dict, containing the names of each column and
-    the rows as a 2D list.
+    """Converts a lookup table to a pydantic model, containing the names of each column
+    and the rows as a 2D list.
 
     Any args after the contents provide the column names and optionally, python types
     for values in a column to be converted to. e.g: (energy_EV, float), (pixels, int).

src/daq_config_server/converters/_converters.py

@@ -35,22 +35,7 @@ def beamline_parameters_to_dict(contents: str) -> dict[str, Any]:
     return dict(config_pairs)
 
 
-def display_config_to_dict(contents: str) -> DisplayConfig:
-    """Converts a display config file into a dict. Every zoom level entry in the
-    configuration file forms a key in the dict, with value being another dict. This
-    inner dict contains all the key value pairs of the rows following each zoom level.
-
-    Example input:
-
-    zoomLevel = 1.0
-    crosshairX = 500
-    crosshairY = 600
-    zoomLevel = 2.0
-    crosshairX = 700
-    crosshairY = 800
-
-    Example output:
-    """
+def display_config_to_model(contents: str) -> DisplayConfig:
     lines = contents.splitlines()
     config_dict: dict[float, dict[str, int | float]] = {}
     zoom_level = None

src/daq_config_server/converters/_file_converter_map.py

@@ -8,18 +8,18 @@
     beamline_pitch_lut,
     beamline_roll_lut,
     detector_xy_lut,
-    display_config_to_dict,
+    display_config_to_model,
     undulator_energy_gap_lut,
     xml_to_dict,
 )
 
 FILE_TO_CONVERTER_MAP: dict[str, Callable[[str], BaseModel | dict[str, Any]]] = {  # type: ignore
     "/tests/test_data/test_good_lut.txt": undulator_energy_gap_lut,  # For system tests # noqa
-    "/dls_sw/i23/software/aithre/aithre_display.configuration": display_config_to_dict,
-    "/dls_sw/i03/software/gda_versions/var/display.configuration": display_config_to_dict,  # noqa
-    "/dls_sw/i04/software/bluesky/scratch/display.configuration": display_config_to_dict,  # noqa
-    "/dls_sw/i19-1/software/daq_configuration/domain/display.configuration": display_config_to_dict,  # noqa
-    "/dls_sw/i24/software/gda_versions/var/display.configuration": display_config_to_dict,  # noqa
+    "/dls_sw/i23/software/aithre/aithre_display.configuration": display_config_to_model,
+    "/dls_sw/i03/software/gda_versions/var/display.configuration": display_config_to_model,  # noqa
+    "/dls_sw/i04/software/bluesky/scratch/display.configuration": display_config_to_model,  # noqa
+    "/dls_sw/i19-1/software/daq_configuration/domain/display.configuration": display_config_to_model,  # noqa
+    "/dls_sw/i24/software/gda_versions/var/display.configuration": display_config_to_model,  # noqa
     "/dls_sw/i03/software/gda/configurations/i03-config/xml/jCameraManZoomLevels.xml": xml_to_dict,  # noqa
     "/dls_sw/i04/software/bluesky/scratch/jCameraManZoomLevels.xml": xml_to_dict,
     "/dls_sw/i19-1/software/gda_versions/gda/config/xml/jCameraManZoomLevels.xml": xml_to_dict,  # noqa

tests/conftest.py

@@ -6,7 +6,7 @@
 
 from daq_config_server.converters._converters import (
     beamline_parameters_to_dict,
-    display_config_to_dict,
+    display_config_to_model,
     undulator_energy_gap_lut,
     xml_to_dict,
 )
@@ -23,7 +23,7 @@ def mock_file_converter_map() -> Generator[dict[str, Callable[[str], Any]], None
                 TestDataPaths.TEST_BEAMLINE_PARAMETERS_PATH
             ): beamline_parameters_to_dict,
             str(TestDataPaths.TEST_GOOD_LUT_PATH): undulator_energy_gap_lut,
-            str(TestDataPaths.TEST_GOOD_DISPLAY_CONFIG_PATH): display_config_to_dict,
+            str(TestDataPaths.TEST_GOOD_DISPLAY_CONFIG_PATH): display_config_to_model,
             str(ServerFilePaths.GOOD_LUT): undulator_energy_gap_lut,
         },
     ) as mock_map:

tests/unit_tests/test_converters.py

@@ -16,7 +16,7 @@
     beamline_pitch_lut,
     beamline_roll_lut,
     detector_xy_lut,
-    display_config_to_dict,
+    display_config_to_model,
     undulator_energy_gap_lut,
     xml_to_dict,
 )
@@ -87,7 +87,7 @@ def test_lut_with_different_number_of_row_items_to_column_names_causes_error():
         GenericLut(column_names=["column1", "column2"], rows=[[1, 2], [1, 2, 3]])
 
 
-def test_display_config_to_dict_gives_expected_result_and_can_be_jsonified():
+def test_display_config_to_model_gives_expected_result_and_can_be_jsonified():
     with open(TestDataPaths.TEST_GOOD_DISPLAY_CONFIG_PATH) as f:
         contents = f.read()
     expected = DisplayConfig(
@@ -110,7 +110,7 @@ def test_display_config_to_dict_gives_expected_result_and_can_be_jsonified():
             ),
         }
     )
-    result = display_config_to_dict(contents)
+    result = display_config_to_model(contents)
     assert result == expected
     json.dumps(result.model_dump())