refactor!: use clearer names for translation methods

notebooks/getting_started/1_Quick_Start.ipynb

@@ -181,7 +181,7 @@
     }
    ],
    "source": [
-    "vrs_from_spdi = translator.translate_from(\"NC_000005.10:80656509:C:TT\", \"spdi\")\n",
+    "vrs_from_spdi = translator.to_vrs(\"NC_000005.10:80656509:C:TT\", \"spdi\")\n",
     "vrs_from_spdi.model_dump(exclude_none=True)"
    ]
   },
@@ -237,7 +237,7 @@
     }
    ],
    "source": [
-    "vrs_from_hgvs = translator.translate_from(\"NC_000005.10:g.80656510delinsTT\", \"hgvs\")\n",
+    "vrs_from_hgvs = translator.to_vrs(\"NC_000005.10:g.80656510delinsTT\", \"hgvs\")\n",
     "vrs_from_hgvs.model_dump(exclude_none=True)"
    ]
   },

notebooks/getting_started/4_Exploring_the_AlleleTranslator.ipynb

@@ -126,7 +126,7 @@
    },
    "source": [
     "#### From/To HGVS\n",
-    "This example will translate an HGVS variant to VRS using the *AlleleTranslator* *translate_from* method."
+    "This example will translate an HGVS variant to VRS using the *AlleleTranslator* *to_vrs* method."
    ]
   },
   {
@@ -167,7 +167,7 @@
    ],
    "source": [
     "allele_translator = AlleleTranslator(data_proxy=seqrepo_dataproxy)\n",
-    "allele = allele_translator.translate_from(\"NC_000005.10:g.80656489C>T\", \"hgvs\")\n",
+    "allele = allele_translator.to_vrs(\"NC_000005.10:g.80656489C>T\", \"hgvs\")\n",
     "allele.model_dump(exclude_none=True)"
    ]
   },
@@ -181,7 +181,7 @@
     }
    },
    "source": [
-    "The output from above is the VRS representation of the *Allele*. Using the *AlleleTranslator* *translate_to* method we can get back to the HGVS representation."
+    "The output from above is the VRS representation of the *Allele*. Using the *AlleleTranslator* *from_vrs* method we can get back to the HGVS representation."
    ]
   },
   {
@@ -211,7 +211,7 @@
     }
    ],
    "source": [
-    "allele_translator.translate_to(allele, \"hgvs\")"
+    "allele_translator.from_vrs(allele, \"hgvs\")"
    ]
   },
   {
@@ -267,7 +267,7 @@
     }
    ],
    "source": [
-    "allele = allele_translator.translate_from(\"NC_000005.9:g.79952308C>T\", \"hgvs\")\n",
+    "allele = allele_translator.to_vrs(\"NC_000005.9:g.79952308C>T\", \"hgvs\")\n",
     "allele.model_dump(exclude_none=True)"
    ]
   },
@@ -298,7 +298,7 @@
     }
    ],
    "source": [
-    "allele_translator.translate_to(allele, \"hgvs\")"
+    "allele_translator.from_vrs(allele, \"hgvs\")"
    ]
   },
   {
@@ -352,7 +352,7 @@
     }
    ],
    "source": [
-    "allele = allele_translator.translate_from(\"NC_000005.10:80656488:C:T\",\"spdi\")\n",
+    "allele = allele_translator.to_vrs(\"NC_000005.10:80656488:C:T\",\"spdi\")\n",
     "allele.model_dump(exclude_none=True)"
    ]
   },
@@ -383,7 +383,7 @@
     }
    ],
    "source": [
-    "allele_translator.translate_to(allele, \"spdi\")"
+    "allele_translator.from_vrs(allele, \"spdi\")"
    ]
   },
   {
@@ -397,7 +397,7 @@
    },
    "source": [
     "#### From gnomAD style VCF\n",
-    "For variants represented in the gnomad nomenclature, the *AlleleTranslator* currently only supports *translate_from* to convert to VRS. *translate_to* is not yet supported."
+    "For variants represented in the gnomad nomenclature, the *AlleleTranslator* currently only supports *to_vrs* to convert to VRS. *from_vrs* is not yet supported."
    ]
   },
   {
@@ -437,7 +437,7 @@
     }
    ],
    "source": [
-    "allele = allele_translator.translate_from(\"5-80656489-C-T\", \"gnomad\")\n",
+    "allele = allele_translator.to_vrs(\"5-80656489-C-T\", \"gnomad\")\n",
     "allele.model_dump(exclude_none=True)"
    ]
   }

notebooks/getting_started/5_Exploring_the_CnvTranslator.ipynb

@@ -148,7 +148,7 @@
     }
    },
    "source": [
-    "This example depicts a *CopyNumberChange* representing a deletion, or copy number loss. The Experimental Factor Ontology code specifying the type of copy number change is passed as a keyword argument \"copy_change\" to *translate_from*. This variant can be viewed in [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/variation/984438)."
+    "This example depicts a *CopyNumberChange* representing a deletion, or copy number loss. The Experimental Factor Ontology code specifying the type of copy number change is passed as a keyword argument \"copy_change\" to *to_vrs*. This variant can be viewed in [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/variation/984438)."
    ]
   },
   {
@@ -189,7 +189,7 @@
    ],
    "source": [
     "cnv_translator = CnvTranslator(data_proxy=seqrepo_dataproxy)\n",
-    "cnc = cnv_translator.translate_from(\"NC_000014.9:g.45002867_45015056del\", \"hgvs\", copy_change=\"loss\")\n",
+    "cnc = cnv_translator.to_vrs(\"NC_000014.9:g.45002867_45015056del\", \"hgvs\", copy_change=\"loss\")\n",
     "cnc.model_dump(exclude_none=True)"
    ]
   },
@@ -243,7 +243,7 @@
     }
    ],
    "source": [
-    "cnx = cnv_translator.translate_from(\"NC_000009.12:g.75502958_76045032dup\", \"hgvs\", copy_change=\"gain\")\n",
+    "cnx = cnv_translator.to_vrs(\"NC_000009.12:g.75502958_76045032dup\", \"hgvs\", copy_change=\"gain\")\n",
     "cnx.model_dump(exclude_none=True)"
    ]
   },
@@ -270,7 +270,7 @@
     }
    },
    "source": [
-    "This example depicts a *CopyNumberCount* with a copy number gain. With copy number count variation, the \"copies\" keyword argument is passed to *translate_from* with the appropriate \"EFO\" ontology code. This variant can be viewed in [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/variation/2579174/)."
+    "This example depicts a *CopyNumberCount* with a copy number gain. With copy number count variation, the \"copies\" keyword argument is passed to *to_vrs* with the appropriate \"EFO\" ontology code. This variant can be viewed in [ClinVar](https://www.ncbi.nlm.nih.gov/clinvar/variation/2579174/)."
    ]
   },
   {
@@ -310,7 +310,7 @@
     }
    ],
    "source": [
-    "cnc = cnv_translator.translate_from(\"NC_000004.12:g.85624_57073230dup\", \"hgvs\", copies=\"3\")\n",
+    "cnc = cnv_translator.to_vrs(\"NC_000004.12:g.85624_57073230dup\", \"hgvs\", copies=\"3\")\n",
     "cnc.model_dump(exclude_none=True)"
    ]
   },
@@ -364,7 +364,7 @@
     }
    ],
    "source": [
-    "cnc = cnv_translator.translate_from(\"NC_000021.9:g.46111353_46119948del\", \"hgvs\", copies=\"1\")\n",
+    "cnc = cnv_translator.to_vrs(\"NC_000021.9:g.46111353_46119948del\", \"hgvs\", copies=\"1\")\n",
     "cnc.model_dump(exclude_none=True)"
    ]
   }

notebooks/getting_started/6_Upcoming_features.ipynb

@@ -164,7 +164,7 @@
     }
    ],
    "source": [
-    "allele = translator.translate_from(\"NC_000005.10:80656509:C:TT\", \"spdi\")\n",
+    "allele = translator.to_vrs(\"NC_000005.10:80656509:C:TT\", \"spdi\")\n",
     "allele.model_dump(exclude_none=True)"
    ]
   },

notebooks/getting_started/7_Uncertain_Range_HGVS.ipynb

@@ -113,7 +113,7 @@
     }
    ],
    "source": [
-    "cnc = cnv_tlr.translate_from(\n",
+    "cnc = cnv_tlr.to_vrs(\n",
     "    \"NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup\", \"hgvs\"\n",
     ")\n",
     "cnc.model_dump(exclude_none=True)"
@@ -178,7 +178,7 @@
     }
    ],
    "source": [
-    "cnc = cnv_tlr.translate_from(\n",
+    "cnc = cnv_tlr.to_vrs(\n",
     "    \"NC_000002.12:g.(?_202376935)_(202377551_202464808)del\", \"hgvs\"\n",
     ")\n",
     "cnc.model_dump(exclude_none=True)"
@@ -235,7 +235,7 @@
     }
    ],
    "source": [
-    "cnc = cnv_tlr.translate_from(\n",
+    "cnc = cnv_tlr.to_vrs(\n",
     "    \"NC_000017.11:g.(?_58709859)_(58734342_?)del\", \"hgvs\"\n",
     ")\n",
     "cnc.model_dump(exclude_none=True)"
@@ -286,7 +286,7 @@
     }
    ],
    "source": [
-    "cn = cnv_tlr.translate_from(\n",
+    "cn = cnv_tlr.to_vrs(\n",
     "    \"NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup\",\n",
     "    \"hgvs\",\n",
     "    copies=3,\n",
@@ -301,7 +301,7 @@
    "source": [
     "## Example 5 — VRS → HGVS (round-trip)\n",
     "\n",
-    "A VRS `Allele` whose `SequenceLocation` has `Range` bounds can be serialized back to uncertain-range HGVS via `AlleleTranslator.translate_to`. Here we build the Allele directly (since `from_hgvs` on the Allele path refuses uncertain ranges) and confirm it round-trips."
+    "A VRS `Allele` whose `SequenceLocation` has `Range` bounds can be serialized back to uncertain-range HGVS via `AlleleTranslator.from_vrs`. Here we build the Allele directly (since `from_hgvs` on the Allele path refuses uncertain ranges) and confirm it round-trips."
    ]
   },
   {
@@ -339,7 +339,7 @@
     "    ),\n",
     "    state=models.LiteralSequenceExpression(sequence=models.sequenceString(root=\"\")),\n",
     ")\n",
-    "allele_tlr.translate_to(allele, \"hgvs\")"
+    "allele_tlr.from_vrs(allele, \"hgvs\")"
    ]
   },
   {
@@ -375,7 +375,7 @@
    ],
    "source": [
     "try:\n",
-    "    allele_tlr.translate_from(\n",
+    "    allele_tlr.to_vrs(\n",
     "        \"NC_000019.9:g.(11211022_11213339)_(11217364_11218067)dup\", \"hgvs\"\n",
     "    )\n",
     "except ValueError as err:\n",

src/ga4gh/vrs/extras/translator.py

@@ -48,7 +48,7 @@ class _Translator(ABC):  # noqa: B024
 
      Translates various variation formats to and from GA4GH VRS models
 
-    All `from_` methods follow this pattern:
+    Private `_from_*` parsers follow this pattern:
     * If the argument does not appear to be an appropriate type, None is returned
     * Otherwise, the argument is expected to be of the correct type.  If an error occurs during processing,
       an exception is raised.
@@ -71,22 +71,29 @@ def __init__(
         identify: bool = True,
         rle_seq_limit: int | None = 50,
     ) -> None:
+        """Initialize shared translation settings and format dispatch dictionaries.
+
+        :param data_proxy: Sequence data provider used during translation.
+        :param default_assembly_name: Default assembly for inputs without an assembly.
+        :param identify: Whether to assign GA4GH identifiers to translated objects.
+        :param rle_seq_limit: Maximum RLE sequence length to include, or None for no limit.
+        """
         self.default_assembly_name = default_assembly_name
         self.data_proxy = data_proxy
         self.identify = identify
         self.rle_seq_limit = rle_seq_limit
-        self.from_translators: dict[str, VariationFromStrProtocol] = {}
-        self.to_translators: dict[str, VariationToStrProtocol] = {}
+        self.to_vrs_translators: dict[str, VariationFromStrProtocol] = {}
+        self.from_vrs_translators: dict[str, VariationToStrProtocol] = {}
 
-    def translate_from(
+    def to_vrs(
         self, var: str, fmt: str | None = None, **kwargs
     ) -> models._VariationBase:
         """Translate variation `var` to VRS object
 
         If `fmt` is None, guess the appropriate format and return the variant.
         If `fmt` is specified, try only that format.
 
-        See also notes about `from_` and `to_` methods.
+        See the class notes about private `_from_*` parsers.
 
         kwargs:
             For CnvTranslator
@@ -111,7 +118,7 @@ def translate_from(
         """
         if fmt:
             try:
-                t = self.from_translators[fmt]
+                t = self.to_vrs_translators[fmt]
             except KeyError as e:
                 msg = f"{fmt} is not supported"
                 raise NotImplementedError(msg) from e
@@ -122,16 +129,16 @@ def translate_from(
                     raise ValueError(msg)
                 return o
 
-        for t in self.from_translators.values():
+        for t in self.to_vrs_translators.values():
             o = t(var, **kwargs)
             if o:
                 return o
 
-        formats = list(self.from_translators.keys())
+        formats = list(self.to_vrs_translators.keys())
         msg = f"Unable to parse data as {', '.join(formats)}"
         raise ValueError(msg)
 
-    def translate_to(self, vo: models._VariationBase, fmt: str, **kwargs) -> list[str]:
+    def from_vrs(self, vo: models._VariationBase, fmt: str, **kwargs) -> list[str]:
         """Translate vrs object `vo` to named format `fmt`
 
         kwargs:
@@ -140,7 +147,7 @@ def translate_to(self, vo: models._VariationBase, fmt: str, **kwargs) -> list[st
         :raise NotImplementedError: If `fmt` is not supported
         """
         try:
-            t = self.to_translators[fmt]
+            t = self.from_vrs_translators[fmt]
         except KeyError as e:
             msg = f"{fmt} is not supported"
             raise NotImplementedError(msg) from e
@@ -179,14 +186,14 @@ def __init__(
         """Initialize AlleleTranslator class"""
         super().__init__(data_proxy, default_assembly_name, identify)
 
-        self.from_translators = {
+        self.to_vrs_translators = {
             "gnomad": self._from_gnomad,
             "hgvs": self._from_hgvs,
             "spdi": self._from_spdi,
             "vrs": self._from_vrs,
         }
 
-        self.to_translators = {
+        self.from_vrs_translators = {
             "hgvs": self._to_hgvs,
             "spdi": self._to_spdi,
         }
@@ -481,7 +488,7 @@ def __init__(
     ) -> None:
         """Initialize CnvTranslator class"""
         super().__init__(data_proxy, default_assembly_name, identify)
-        self.from_translators = {
+        self.to_vrs_translators = {
             "hgvs": self._from_hgvs,
         }