Rename functions of serialization.py to be meaningful and consistent

See the updated docstring of the module for the info on the
convention.

qcodes/dataset/data_set.py

@@ -458,7 +458,7 @@ def _get_run_description_from_db(self) -> RunDescriber:
         Look up the run_description from the database
         """
         desc_str = get_run_description(self.conn, self.run_id)
-        return serial.read_json_to_current(desc_str)
+        return serial.from_json_to_current(desc_str)
 
     def toggle_debug(self):
         """
@@ -584,7 +584,7 @@ def _perform_start_actions(self) -> None:
         for spec in paramspecs:
             add_parameter(self.conn, self.table_name, spec)
 
-        desc_str = serial.make_json_for_storage(self.description)
+        desc_str = serial.to_json_for_storage(self.description)
 
         update_run_description(self.conn, self.run_id, desc_str)
 

qcodes/dataset/database_fix_functions.py

@@ -100,11 +100,11 @@ def _convert_run_describer_v1_like_dict_to_v0_like_dict(
     new_desc_dict['version'] = 1
     # Out of that dict we create RunDescriber object of the current version
     # (regardless of what the current version is).
-    new_desc = serial.deserialize_to_current(new_desc_dict)
+    new_desc = serial.from_dict_to_current(new_desc_dict)
     # The RunDescriber of the current version gets converted to a dictionary
     # that represents a RunDescriber object of version 0 - this is the one
     # that has InterDependencies object in it (not the InterDependencies_ one).
-    old_desc_dict = serial.serialize_to_version(new_desc, 0)
+    old_desc_dict = serial.to_dict_as_version(new_desc, 0)
     # Lastly, the "version" field is removed.
     old_desc_dict.pop('version')
     return old_desc_dict
@@ -142,7 +142,7 @@ def fix_wrong_run_descriptions(conn: ConnectionPlus,
                                            "run_description",
                                            "run_id", run_id)
 
-        trusted_json = serial.make_json_in_version(trusted_desc, 0)
+        trusted_json = serial.to_json_as_version(trusted_desc, 0)
 
         if actual_desc_str == trusted_json:
             log.info(f'[+] Run id: {run_id} had an OK description')

qcodes/dataset/descriptions/versioning/serialization.py

@@ -15,6 +15,10 @@
 QCoDeS
 - storage version: the version of RunDescriber object that is used by the
 data storage infrastructure of QCoDeS
+
+The names of the functions in this module follow the "to_*"/"from_*"
+convention where "*" stands for the storage format. Also note the
+"as_version", "for_storage", "to_current", "to_native" suffixes.
 """
 import io
 import json
@@ -27,7 +31,10 @@
     v0_to_v1, v1_to_v0)
 
 CURRENT_VERSION = 1
+# the version of :class:`RunDescriber` object that is used within :mod:`qcodes`
 STORAGE_VERSION = 0
+# the version of :class:`RunDescriber` object that is used by the data storage
+# infrastructure of :mod:`qcodes`
 
 
 SomeRunDescriber = Union[current.RunDescriber, v0.RunDescriber]
@@ -41,93 +48,102 @@
                (1, 1): lambda x: x}
 
 
-def deserialize(ser: Dict[str, Any]) -> SomeRunDescriber:
+# python dict
+
+
+def from_dict_to_native(dct: Dict[str, Any]) -> SomeRunDescriber:
     """
-    Deserialize a dict (usually coming from json.loads) into a RunDescriber
+    Convert a dict (usually coming from json.loads) into a RunDescriber
     object according to the version specified in the dict
     """
     run_describers: Dict[int, SomeRunDescriberType]
     run_describers = {0: v0.RunDescriber,
                       1: current.RunDescriber}
 
-    return run_describers[ser['version']]._from_dict(ser)
+    return run_describers[dct['version']]._from_dict(dct)
 
 
-def deserialize_to_current(ser: Dict[str, Any]) -> current.RunDescriber:
+def from_dict_to_current(dct: Dict[str, Any]) -> current.RunDescriber:
     """
-    Deserialize a dict into a RunDescriber of the current version
+    Convert a dict into a RunDescriber of the current version
     """
-    desc = deserialize(ser)
+    desc = from_dict_to_native(dct)
 
     return _converters[(desc.version, CURRENT_VERSION)](desc)
 
 
-def serialize_to_version(desc: SomeRunDescriber,
-                         version: int) -> Dict[str, Any]:
+def to_dict_as_version(desc: SomeRunDescriber,
+                       version: int) -> Dict[str, Any]:
     """
-    Serialize a RunDescriber to a particular version
+    Convert the given RunDescriber into a dictionary that represents a
+    RunDescriber of the given version
     """
     return _converters[(desc.version, version)](desc)._to_dict()
 
 
-def serialize_to_storage(desc: SomeRunDescriber) -> Dict[str, Any]:
+def to_dict_for_storage(desc: SomeRunDescriber) -> Dict[str, Any]:
     """
-    Serialize a RunDescriber into the storage version
+    Convert a RunDescriber into a dictionary that represents the
+    RunDescriber of the storage version
     """
-    return serialize_to_version(desc, STORAGE_VERSION)
+    return to_dict_as_version(desc, STORAGE_VERSION)
+
 
+# JSON
 
-def make_json_for_storage(desc: SomeRunDescriber) -> str:
+
+def to_json_for_storage(desc: SomeRunDescriber) -> str:
     """
-    Serialize a RunDescriber to the storage version and dump that as a JSON
-    string
+    Serialize the given RunDescriber to JSON as a RunDescriber of the
+    version for storage
     """
-    return json.dumps(serialize_to_storage(desc))
+    return json.dumps(to_dict_for_storage(desc))
 
 
-def make_json_in_version(desc: SomeRunDescriber, version: int) -> str:
+def to_json_as_version(desc: SomeRunDescriber, version: int) -> str:
     """
-    Serialize a RunDescriber to a particular version and JSON dump that.
-    Only to be used in tests and upgraders
+    Serialize the given RunDescriber to JSON as a RunDescriber of the
+    given version. Only to be used in tests and upgraders
     """
-    return json.dumps(serialize_to_version(desc, version))
+    return json.dumps(to_dict_as_version(desc, version))
 
 
-def read_json_to_current(json_str: str) -> current.RunDescriber:
+def from_json_to_current(json_str: str) -> current.RunDescriber:
     """
-    Load a dict from JSON string and deserialize it into a RunDescriber of
-    the current version
+    Deserialize a JSON string into a RunDescriber of the current version
     """
-    return deserialize_to_current(json.loads(json_str))
+    return from_dict_to_current(json.loads(json_str))
 
 
-def read_json_to_native_version(json_str: str) -> SomeRunDescriber:
+def from_json_to_native(json_str: str) -> SomeRunDescriber:
     """
-    Load a dict from JSON string and deserialize it into a RunDescriber of the
-    version given in the JSON (native version)
+    Deserialize a JSON string into a RunDescriber of the version given in
+    the JSON (native version)
     """
-    return deserialize(json.loads(json_str))
+    return from_dict_to_native(json.loads(json_str))
+
+
+# YAML
 
 
-def make_yaml_for_storage(desc: SomeRunDescriber) -> str:
+def to_yaml_for_storage(desc: SomeRunDescriber) -> str:
     """
-    Serialize a RunDescriber to the storage version and dump that as a yaml
-    string
+    Serialize the given RunDescriber to YAML as a RunDescriber of the
+    version for storage
     """
     yaml = YAML()
     with io.StringIO() as stream:
-        yaml.dump(serialize_to_storage(desc), stream=stream)
+        yaml.dump(to_dict_for_storage(desc), stream=stream)
         output = stream.getvalue()
 
     return output
 
 
-def read_yaml_to_current(yaml_str: str) -> current.RunDescriber:
+def from_yaml_to_current(yaml_str: str) -> current.RunDescriber:
     """
-    Load a dict from yaml string and deserialize it into a RunDescriber of
-    the current version
+    Deserialize a YAML string into a RunDescriber of the current version
     """
     yaml = YAML()
     # yaml.load returns an OrderedDict, but we need a dict
     ser = dict(yaml.load(yaml_str))
-    return deserialize_to_current(ser)
+    return from_dict_to_current(ser)

qcodes/dataset/sqlite/queries.py

@@ -925,7 +925,7 @@ def _insert_run(conn: ConnectionPlus, exp_id: int, name: str,
     parameters = parameters or []
 
     run_desc = RunDescriber(old_to_new(InterDependencies(*parameters)))
-    desc_str = serial.make_json_for_storage(run_desc)
+    desc_str = serial.to_json_for_storage(run_desc)
 
     with atomic(conn) as conn:
 
@@ -1098,7 +1098,7 @@ def update_run_description(conn: ConnectionPlus, run_id: int,
     string must be a valid JSON string representation of a RunDescriber object
     """
     try:
-        serial.read_json_to_current(description)
+        serial.from_json_to_current(description)
     except Exception as e:
         raise ValueError("Invalid description string. Must be a JSON string "
                          "representaion of a RunDescriber object.") from e

qcodes/tests/dataset/test_database_creation_and_upgrading.py

@@ -692,7 +692,7 @@ def test_perform_actual_upgrade_5_to_6():
             deser = json.loads(json_str)
             assert deser['version'] == 0
 
-            desc = serial.read_json_to_current(json_str)
+            desc = serial.from_json_to_current(json_str)
             assert desc._version == 1
 
 

qcodes/tests/dataset/test_descriptions.py

@@ -67,13 +67,13 @@ def test_yaml_creation_and_loading(some_interdeps):
     for idps in some_interdeps:
         desc = RunDescriber(interdeps=idps)
 
-        yaml_str = serial.make_yaml_for_storage(desc)
+        yaml_str = serial.to_yaml_for_storage(desc)
         assert isinstance(yaml_str, str)
         ydict = dict(yaml.load(yaml_str))
         assert list(ydict.keys()) == ['version', 'interdependencies']
         assert ydict['version'] == serial.STORAGE_VERSION
 
-        new_desc = serial.read_yaml_to_current(yaml_str)
+        new_desc = serial.from_yaml_to_current(yaml_str)
         assert new_desc == desc
 
 
@@ -88,7 +88,7 @@ def test_default_jsonization_as_v0_for_storage(some_interdeps):
     old_json = json.dumps({'version': 0,
                            'interdependencies': idps_old._to_dict()})
 
-    assert serial.make_json_for_storage(new_desc) == old_json
+    assert serial.to_json_for_storage(new_desc) == old_json
 
 
 def test_default_dictization_as_v0_for_storage(some_interdeps):
@@ -103,7 +103,7 @@ def test_default_dictization_as_v0_for_storage(some_interdeps):
     new_desc = RunDescriber(idps_new)
     old_desc = {'version': 0, 'interdependencies': idps_old._to_dict()}
 
-    assert serial.serialize_to_storage(new_desc) == old_desc
+    assert serial.to_dict_for_storage(new_desc) == old_desc
 
 
 def test_dictization_of_version_1(some_interdeps):

qcodes/tests/dataset/test_fix_functions.py

@@ -97,11 +97,11 @@ def make_ps(n):
 
         for run_id in [1, 2, 3]:
             desc_str = get_run_description(conn, run_id)
-            desc = serial.read_json_to_native_version(desc_str)
+            desc = serial.from_json_to_native(desc_str)
             assert desc == expected_description
 
         desc_str = get_run_description(conn, run_id=4)
-        desc = serial.read_json_to_native_version(desc_str)
+        desc = serial.from_json_to_native(desc_str)
         assert desc == empty_description
 
 

qcodes/tests/dataset/test_sqlite_base.py

@@ -198,7 +198,7 @@ def test_update_runs_description(dataset):
             mut_queries.update_run_description(
                 dataset.conn, dataset.run_id, idesc)
 
-    desc = serial.make_json_for_storage(RunDescriber((InterDependencies_())))
+    desc = serial.to_json_for_storage(RunDescriber((InterDependencies_())))
     mut_queries.update_run_description(dataset.conn, dataset.run_id, desc)