Deprecate Tree.num_nodes?

[hyanwong]

Even though it's documented, I think it's super confusing that Tree.num_nodes returns the number of nodes in the entire tree sequence, not the number of nodes in the tree itself. I suggest we might want to deprecate it and say that the user should use Tree.tree_sequence.num_nodes instead, which is much clearer.

[jeromekelleher]

That is confusing, I agree. Happy to mark it as deprecated/undocument it, etc.

[hyanwong]

My vote would be to deliberately mark it for deprecation, rather than simply undocument it, because there's a good chance that it's actually an error if it's being used.

[jeromekelleher]

OK. I don't think we have a formal deprecation process yet. Let's use the sphinx directive for now, "deprecated since 0.4.0"

[hyanwong]

Cool. I was going to issue a warnings.warn on use too, like we do if you use the impute_missing_data parameter for haplotypes. Reasonable?

[benjeffery]

Might be worth using https://deprecation.readthedocs.io/en/latest/ to check we are emiting the right kind of warning.

[molpopgen]

OK. I don't think we have a formal deprecation process yet. Let's use the sphinx directive for now, "deprecated since 0.4.0"

Raising a FutureWarning when accessing it may also be handy??

[hyanwong]

FutureWarning is a great idea, thanks @molpopgen - I've just incorporated it.

[molpopgen]

Great. This is one of python's great gotchas. DeprecationWarning seems like what you want, but it is suppressed by default because it is only for developers.

[hyanwong]

Wrongly tagged by me as fixed by 64cb77d