Deprecate Tree.num_nodes

Fixes tskit-dev#1966

python/CHANGELOG.rst

@@ -4,6 +4,10 @@
 
 **Breaking changes**
 
+- The ``Tree.num_nodes`` method is now deprecated with a warning, because it confusingly
+  returns the number of nodes in the entire tree sequence, rather than in the tree.
+  (:user:`hyanwong`, :issue:`1966` :pr:`1968`)
+
 - The CLI ``info`` command now gives more detailed information on the tree sequence
   (:user:`benjeffery`, :pr:`1611`)
 

python/tskit/trees.py

@@ -1403,11 +1403,21 @@ def is_descendant(self, u, v):
     def num_nodes(self):
         """
         Returns the number of nodes in the :class:`TreeSequence` this tree is in.
-        Equivalent to ``tree.tree_sequence.num_nodes``. To find the number of
-        nodes that are reachable from all roots use ``len(list(tree.nodes()))``.
+        Equivalent to ``tree.tree_sequence.num_nodes``.
+
+        .. deprecated:: 0.4
+            Use :func:`Tree.tree_sequence.num_nodes` if you want the number of nodes
+            in the entire tree sequence, or ``len(list(tree.nodes()))`` to find the
+            number of nodes that are reachable from all roots in this tree.
 
         :rtype: int
+
         """
+        warnings.warn(
+            "This property is a deprecated alias for Tree.tree_sequence.num_nodes"
+            "and will be removed in the future",
+            RuntimeWarning,
+        )
         return self._ll_tree.get_num_nodes()
 
     @property