nomcompile3: Build a set of nomenclature files

# - - -   T a x a T r e e . c a n A d d C h i l d

    def canAddChild ( self, parent, childRankCode ):
        '''Can a new taxon of rank (childRankCode) be added to parent?
        '''

Instead of returning True or False, this method raises an exception so that we can pass a more detailed message back in the case that the taxon cannot be added.

For the related verification function, see Section 7.3, “can-add-child: Can a given parent have a given child?”. There are two parts to the condition. First we check that this parent-child relationship is legal in the rank hierarchy.

        #-- 1 --
        # [ childRank  :=  the Rank from self.hier with code
        #                  (childRankCode) ]
        childRank = self.hier.lookupRankCode ( childRankCode )

        #-- 2 --
        # [ if (parent.rank < childRank) and
        #   (there are no missing required ranks in self.hier
        #   between parent.rank and childRank) ->
        #     I
        #   else -> raise ValueError
        if not self.hier.canParentHaveChild ( parent.rank, childRank ):
            raise ValueError ( "Taxon '%s' of rank '%s' can never "
                "have a child of rank '%s'." %
                (parent, parent.rank, childRank) )

The second condition is the requirement that all children of a given parent have the same rank. For example, if a family has at least one subfamily child, it cannot also have genus-rank children.

        #-- 3 --
        # [ if (parent has no children) or
        #   (parent's last child's rank == childRank) ->
        #     return None
        #   else -> raise ValueError ]
        if ( ( len(parent) > 0 ) and
             ( parent[-1].rank != childRank ) ):
            raise ValueError ( "Parent taxon '%s' has child '%s' "
                "of rank '%s'\n"
                "and so cannot also have this child of rank '%s'." %
                (parent, parent[-1], parent[-1].rank, childRank) )