Add type stub

taxonomy.pyi

@@ -0,0 +1,172 @@
+from typing import Any, List, Optional, Tuple, Iterator
+
+class TaxonomyError(Exception):
+    """Raised when an error occurs in the taxonomy library."""
+
+    ...
+
+class TaxonomyNode:
+    """The data returned when looking up a taxonomy by id or by name"""
+
+    id: str
+    name: str
+    parent: Optional[str]
+    rank: str
+
+    def __hash__(self) -> int: ...
+    def __repr__(self) -> str: ...
+    def __getitem__(self, key: str) -> Any: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+
+class Taxonomy:
+    """
+    The Taxonomy object provides the primary interface for exploring a
+    biological taxonomy.
+    """
+    @property
+    def root(self) -> TaxonomyNode: ...
+    @classmethod
+    def from_gtdb(cls, value: str) -> "Taxonomy":
+        """Load a Taxonomy from a GTDB-encoded string."""
+        ...
+
+    @classmethod
+    def from_json(cls, value: str, json_pointer: Optional[str] = None) -> "Taxonomy":
+        """
+        Load a Taxonomy from a JSON-encoded string. The format can either be
+        of the tree or node_link_data types and will be automatically detected.
+        If `path` is specified, the JSON will be traversed to that sub-object
+        before being parsed as a taxonomy. `path` has to be a valid JSON path string.
+        """
+        ...
+
+    @classmethod
+    def from_newick(cls, value: str) -> "Taxonomy":
+        """Load a Taxonomy from a Newick-encoded string."""
+        ...
+
+    @classmethod
+    def from_ncbi(cls, dump_dir: str) -> "Taxonomy":
+        """
+        Load a Taxonomy from a directory.
+        The directory must contain the `nodes.dmp` and `names.dmp` files.
+        """
+        ...
+
+    @classmethod
+    def from_phyloxml(cls, value: str) -> "Taxonomy":
+        """Load a Taxonomy from a PhyloXML-encoded string. Experimental."""
+        ...
+
+    def clone(self) -> "Taxonomy":
+        """Clone the current taxonomy"""
+        ...
+
+    def to_json_tree(self) -> bytes:
+        """Export a Taxonomy as a JSON-encoded byte string in a tree format"""
+        ...
+
+    def to_json_node_links(self) -> bytes:
+        """Export a Taxonomy as a JSON-encoded byte string in a node link format"""
+        ...
+
+    def to_newick(self) -> bytes:
+        """Export a Taxonomy as a Newick-encoded byte string."""
+        ...
+
+    def node(self, tax_id: str) -> Optional[TaxonomyNode]:
+        """Find a node by its id. Returns `None` if not found"""
+        ...
+
+    def find_all_by_name(self, name: str) -> List[TaxonomyNode]:
+        """Find a node by its name, Raises an exception if not found."""
+        ...
+
+    def parent_with_distance(
+        self, tax_id: str, at_rank: Optional[str] = None
+    ) -> Tuple[Optional[TaxonomyNode], Optional[float]]:
+        """
+        Return the immediate parent taxonomy node of the node id provided and the distance to it.
+        If `at_rank` is provided, scan all the nodes in the node's lineage and return
+        the parent id at that rank.
+        """
+        ...
+
+    def parent(self, tax_id: str, at_rank: Optional[str] = None) -> Optional[TaxonomyNode]:
+        """
+        Return the immediate parent taxonomy node of the node id provided.
+        If `at_rank` is provided, scan all the nodes in the node's lineage and return
+        the parent id at that rank.
+        """
+        ...
+
+    def children(self, tax_id: str) -> List[TaxonomyNode]:
+        """Return a list of direct child taxonomy nodes from the node id provided."""
+        ...
+
+    def descendants(self, tax_id: str) -> List[TaxonomyNode]:
+        """Return a list of all child taxonomy nodes from the node id provided."""
+        ...
+
+    def lineage(self, tax_id: str) -> List[TaxonomyNode]:
+        """
+        Return a list of all the parent taxonomy nodes of the node id provided
+        (including that node itself).
+        """
+        ...
+
+    def internal_index(self, tax_id: str) -> int:
+        """Return the internal integer ID generated by the taxonomy library"""
+        ...
+
+    def parents(self, tax_id: str) -> List[TaxonomyNode]:
+        """
+        Return a list of all the parent taxonomy nodes of the node id provided.
+        It is equivalent to `lineage` except it doesn't include itself
+        """
+        ...
+
+    def lca(self, id1: str, id2: str) -> Optional[TaxonomyNode]:
+        """Return the lowest common ancestor of two taxonomy nodes."""
+        ...
+
+    def prune(
+        self, keep: Optional[List[str]] = None, remove: Optional[List[str]] = None
+    ) -> "Taxonomy":
+        """
+        Return a copy of the taxonomy containing:
+         - only the nodes in `keep` and their parents if provided
+         - all of the nodes except those in remove and their children if provided
+        """
+        ...
+
+    def remove_node(self, tax_id: str) -> None:
+        """Remove the node from the tree."""
+        ...
+
+    def add_node(self, parent_id: str, tax_id: str, name: str, rank: str) -> None:
+        """Add a new node to the tree at the parent provided."""
+        ...
+
+    def edit_node(
+        self,
+        tax_id: str,
+        name: Optional[str] = None,
+        rank: Optional[str] = None,
+        parent_id: Optional[str] = None,
+        parent_distance: Optional[float] = None,
+    ) -> None:
+        """Edit properties on a taxonomy node."""
+        ...
+
+    def __repr__(self) -> str: ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, tax_id: str) -> TaxonomyNode: ...
+    def __delitem__(self, tax_id: str) -> None: ...
+    def __contains__(self, tax_id: str) -> bool: ...
+    def __iter__(self) -> Iterator[str]: ...
+
+class TaxonomyIterator:
+    def __next__(self) -> Optional[str]: ...
+    def __iter__(self) -> "TaxonomyIterator": ...