def advance_rank():
    """advance the character in the same path as the previous rank
       returns False if this option is not available
    """

    # this function assumes that the character is able to
    # advance in the same path

    from models.advancements.rank import Rank
    adv = Rank()
    # the insight rank
    adv.rank = api.character.insight_rank()
    # this is the current school for this rank
    adv.school = api.character.schools.get_current()
    # no cost advancing in the same rank
    adv.cost = 0
    # description
    adv.desc = api.tr("Insight Rank {0}. School: {1} rank {2} ").format(
        adv.rank,
        api.data.schools.get(adv.school).name,
        api.character.schools.get_school_rank(adv.school) + 1
    )

    # get 3 spells each rank other than the first
    if api.data.schools.is_shugenja(adv.school) and adv.rank > 1:
        adv.gained_spells_count = __api.pc.get_spells_per_rank()

    # get 2 kiho each rank
    if api.data.schools.is_brotherhood_monk(adv.school) and adv.rank > 1:
        adv.gained_kiho_count = 2

    return api.character.append_advancement(adv)
def join_new(school_id):
    """the character joins a new school"""

    school_ = api.data.schools.get(school_id)
    if not school_:
        log.api.error(u"join_new, school not found: %s", school_id)
        return

    from models.advancements.rank import Rank
    adv = Rank()
    # the insight rank
    adv.rank = api.character.insight_rank()
    # this is the current school for this rank
    adv.school = school_id
    # no cost advancing in the same rank
    adv.cost = 0
    # description

    school_rank = api.character.schools.get_school_rank(adv.school)

    # get 3 spells each rank other than the first
    if api.data.schools.is_shugenja(school_id) and adv.rank > 1:
        adv.gained_spells_count = __api.pc.get_spells_per_rank()

    if api.data.schools.is_path(adv.school):
        # replaces current school
        adv.replaced = api.character.schools.get_current()
    else:
        school_rank += 1

        # get 2 kiho each rank
        # alternate path doesn't get the bonus
        if api.data.schools.is_brotherhood_monk(school_id) and adv.rank > 1:
            adv.gained_kiho_count = 2

    if school_.affinity:
        if 'any' in school_.affinity or 'nonvoid' in school_.affinity:
            adv.affinities_to_choose.append(school_.affinity)
        else:
            adv.affinities.append(school_.affinity)

    if school_.deficiency:
        if 'any' in school_.deficiency or 'nonvoid' in school_.deficiency:
            adv.deficiencies_to_choose.append(school_.deficiency)
        else:
            adv.deficiencies.append(school_.deficiency)

    adv.desc = api.tr("Insight Rank {0}. School: {1} rank {2} ").format(
        adv.rank,
        school_.name,
        school_rank
    )

    return api.character.append_advancement(adv)
def leave_path():
    """the character resume its former path"""

    # this function assumes that the character is
    # currently following an alternate path

    former_school_ = query(get_all()).where(
        lambda x: not api.data.schools.is_path(x)).order_by(a_('rank')).first_or_default(None)

    if not former_school_:
        log.api.error(u"former school not found. could not resume old path")
        return False


    from models.advancements.rank import Rank
    adv = Rank()
    # the insight rank
    adv.rank = api.character.insight_rank()
    # this is the current school for this rank
    adv.school = former_school_.school
    # no cost advancing in the same rank
    adv.cost = 0
    # description
    adv.desc = api.tr("Insight Rank {0}. School: {1} rank {2} ").format(
        adv.rank,
        api.data.schools.get(adv.school).name,
        api.character.schools.get_school_rank(adv.school) + 1
    )

    # get 3 spells each rank other than the first
    if api.data.schools.is_shugenja(adv.school) and adv.rank > 1:
        adv.gained_spells_count = __api.pc.get_spells_per_rank()

    # get 2 kiho each rank
    if api.data.schools.is_brotherhood_monk(adv.school) and adv.rank > 1:
        adv.gained_kiho_count = 2

    return api.character.append_advancement(adv)