feat: add cached factory function (#65)

Author: jsstevenson

src/agct/__init__.py

@@ -1,12 +1,13 @@
 """Provide fast liftover in Python via the ``chainfile`` crate."""
 
 from agct.assembly_registry import Assembly, get_assembly_from_refget_id
-from agct.converter import Converter, LiftoverResult, Strand
+from agct.converter import Converter, LiftoverResult, Strand, get_converter
 
 __all__ = [
     "Assembly",
     "Converter",
     "LiftoverResult",
     "Strand",
     "get_assembly_from_refget_id",
+    "get_converter",
 ]

src/agct/converter.py

@@ -3,6 +3,7 @@
 import logging
 from collections.abc import Callable
 from enum import Enum
+from functools import cache
 from pathlib import Path
 from typing import NamedTuple
 
@@ -53,8 +54,8 @@ def __init__(
           the `wags-tails documentation <https://wags-tails.readthedocs.io/>`_ for more info.
         * If ``chainfile`` arg is provided, all other args are ignored.
 
-        :param from_assembly: Assembly name, e.g. ``<Assembly.HG19>``
-        :param to_assembly: database name, e.g. ``"hg38"``.
+        :param from_assembly: Name of assembly being lifted over from
+        :param to_assembly: Name of assembly to lift over to
         :param chainfile: Path to chainfile
         :raise ValueError: if required arguments are not passed or are invalid
         :raise FileNotFoundError: if unable to open corresponding chainfile
@@ -178,3 +179,17 @@ def convert_coordinate(
                 LiftoverResult(result[0], lifted_over_start, lifted_over_end, strand)
             )
         return formatted_results
+
+
+@cache
+def get_converter(from_assembly: Assembly, to_assembly: Assembly) -> Converter:
+    """Get a converter to lift from one assembly to another.
+
+    This function wraps converter initialization with ``functools.cache``, so successive
+    calls should return the same converter instance.
+
+    :param from_assembly: Name of assembly being lifted over from
+    :param to_assembly: Name of assembly to lift over to
+    :return: Converter instance
+    """
+    return Converter(from_assembly=from_assembly, to_assembly=to_assembly)

tests/test_converter.py

@@ -5,7 +5,7 @@
 
 import pytest
 
-from agct import Assembly, Converter
+from agct import Assembly, Converter, get_converter
 
 
 def test_valid(data_dir: Path):
@@ -34,3 +34,13 @@ def test_invalid():
         ),
     ):
         Converter(Assembly.HG19, "hg18")
+
+
+def test_factory_function():
+    assert id(get_converter(Assembly.HG19, Assembly.HG38)) == id(
+        get_converter(Assembly.HG19, Assembly.HG38)
+    ), "Factory function isn't returning the same instance on successive calls"
+
+    assert id(get_converter(Assembly.HG19, Assembly.HG38)) != id(
+        get_converter(Assembly.HG38, Assembly.HG19)
+    )