diff --git a/python/CHANGELOG.rst b/python/CHANGELOG.rst index 9e577eb79d..0911d5a5bb 100644 --- a/python/CHANGELOG.rst +++ b/python/CHANGELOG.rst @@ -13,6 +13,7 @@ In development two-locus statistics in site and branch mode. (:user:`lkirk`, :user:`apragsdale`, :pr:`3416`) - Add `node_labels` parameter to `write_nexus`. (:user:`kaathewisegit`, :pr:`3442`) +- Document ``TableCollection.load`` (:user:`hyanwong`, :issue:`3406` :pr:`3453`) -------------------- [1.0.2] - 2026-03-06 diff --git a/python/tskit/tables.py b/python/tskit/tables.py index 40523248f8..c8d6622d71 100644 --- a/python/tskit/tables.py +++ b/python/tskit/tables.py @@ -3455,6 +3455,24 @@ def __getstate__(self): @classmethod def load(cls, file_or_path, *, skip_tables=False, skip_reference_sequence=False): + """ + Load a :class:`TableCollection` from a file or path, saved in the format defined + by :meth:`.dump`. Although the file must be in the correct format, unlike + :func:`tskit.load` further validation is not performed to check that the tables + meet the :ref:`sec_valid_tree_sequence_requirements`. For instance, + unsorted tables can be loaded without error and then sorted before + :meth:`creating ` a :class:`TreeSequence`. + + :param file_or_path: The file object or path from which to load the + TableCollection. + :param bool skip_tables: If True, no tables are read from the file and + only the top-level information is populated in the returned TableCollection. + :param bool skip_reference_sequence: If True, tables are read + without loading any reference sequence. + :return: A TableCollection instance + :rtype: TableCollection + :raises: **tskit.FileFormatError** -- If the file is not in a valid format. + """ file, local_file = util.convert_file_like_to_open_file(file_or_path, "rb") ll_tc = _tskit.TableCollection() try: @@ -3474,7 +3492,8 @@ def dump(self, file_or_path): """ Writes the table collection to the specified path or file object. - :param str file_or_path: The file object or path to write the TreeSequence to. + :param str file_or_path: The file object or path to which to write this + TableCollection. """ file, local_file = util.convert_file_like_to_open_file(file_or_path, "wb") try: