feat(io.yaml): factor model_from_yaml_data out of read_yaml_model

read_yaml_model now opens+parses the file then delegates the
post-parse work (capturing per-entry side-fields onto notes,
restoring legacy metaData id/name, stashing unknown top-level
sections onto model.notes['_yaml_sections']) to a new
model_from_yaml_data(raw: dict) helper.

This lets downstream packages that need to pre-normalise their YAML
before cobra reads it (e.g. geckopy, which lifts legacy MATLAB
ec-model quirks like top-level per-metabolite `smiles` into
`annotation` and merges bare-`-` sequence-of-single-key-maps
back to a mapping) hand the cleaned dict directly to the post-parse
pipeline, without round-tripping through a temp file.

Both functions are exported from raven_python.io.yaml. Pure
refactor on the read side; no behaviour change for existing
read_yaml_model callers.

Author: edkerk

src/raven_python/io/yaml.py

@@ -86,13 +86,33 @@ def _capture_entry_fields(entries, fields):
 
 
 def read_yaml_model(path: str | Path) -> cobra.Model:
-    """Read a RAVEN/cobrapy YAML model into a ``cobra.Model``."""
+    """Read a RAVEN/cobrapy YAML model into a ``cobra.Model``.
+
+    Convenience wrapper around :func:`model_from_yaml_data` that opens the
+    file (transparently un-gzipping ``.gz``) and parses the YAML. Callers
+    that need to pre-process the document (e.g. lift legacy fields that
+    cobra doesn't recognise) can read+normalise themselves and call
+    :func:`model_from_yaml_data` with the resulting dict.
+    """
     with _open_text(path, "r") as handle:
         raw = _to_plain(_cobra_yaml.load(handle))
 
     if not isinstance(raw, dict):
         raise ValueError(f"{path}: top-level YAML is a {type(raw).__name__}, not a mapping.")
+    return model_from_yaml_data(raw)
+
 
+def model_from_yaml_data(raw: dict) -> cobra.Model:
+    """Build a ``cobra.Model`` from an already-parsed RAVEN/cobrapy YAML dict.
+
+    Strips and restores the RAVEN per-entry side-fields onto each entry's
+    ``.notes``, lifts ``id``/``name`` out of legacy ``metaData``, and
+    stashes everything else (``version``, the ``metaData`` block itself,
+    and any unknown top-level keys such as ``ec-rxns``/``ec-enzymes``)
+    onto ``model.notes`` so a round-trip via :func:`write_yaml_model`
+    preserves them. ``raw`` is mutated in place — copy it first if the
+    caller needs the original.
+    """
     metadata = raw.pop("metaData", None) or {}
     version = raw.pop("version", None)
     foreign = {k: raw.pop(k) for k in list(raw) if k not in _COBRA_TOP_KEYS}