proto-arbegla type topology typology bootstraping function

### IMPORTS..

class BasicArbTypeBundlePart(py_struct):  # component of BasicArbTypeBundleSet
    atb_name: str  # enum member name
    atb_enum_int: Type[IntEnum] | IntEnum  # enum member of integer values
    atb_enum_str: Type[StrEnum] | StrEnum  # enum member of string values
    atb_enum_base: Type[Enum] | Enum  # enum member general-purpose type specific values
    atb_closure: callable  # the function or closure it represents!


basic_symbol_bundle_parts_t = NewType('basic_symbol_bundle_parts_t', Tuple[str, IntEnum, StrEnum, Enum, callable])  # simple repr of BasicArbTypeBundlePart
basic_symbol_bundle_union_t = NewType('basic_symbol_bundle_union_t', Union[str, IntEnum, StrEnum, Enum, callable, BasicArbTypeBundlePart])  # pre-EMUS domain type for BasicArbTypeBundlePart and its members
basic_symbol_closure_table_t = NewType('basic_symbol_closure_table_t', Mapping[basic_symbol_bundle_union_t, BasicArbTypeBundlePart])  # # resolve any BasicArbTypeBundlePart uniquely through any of it members


class BasicArbTypeBundleSet(py_struct):  # assemblage of BasicArbTypeBundlePart members
    ats_name: str  # master_type_name
    ats_enum_int: Type[IntEnum]  # the type's dedicated integer-value enum
    ats_enum_str: Type[StrEnum]  # the type's dedicated string-value enum
    ats_enum_base: Type[Enum]  # the type's dedicated reserve-value enum
    ats_closure: basic_symbol_closure_table_t  # member to BasicArbTypeBundlePart resolver
    ats_array: Tuple[basic_symbol_bundle_parts_t, ...]  # int-enum-ordered array of BasicArbTypeBundlePart members


def new_basic_arb_type(master_type_name: str, *members: basic_symbol_bundle_parts_t, int_enum: Type[IntEnum], str_enum: Type[StrEnum], base_enum: Type[Enum]) -> BasicArbTypeBundleSet:
    """
     Create or retrieve a new Arbegla basic type bundle set based on provided parameters.

     Function Input:
         - master_type_name (str): The master type name representing the Arbegla type.    It should be a unique string identifier and follow specific naming conventions.
         - *members (basic_symbol_bundle_parts_t): A variable length tuple containing the member details for the Arbegla type. Each member should contain:
             1. Enum member name (str)
             2. Enum member of integer values (IntEnum)
             3. Enum member of string values (StrEnum)
             4. Enum member of general-purpose specific values (Enum)
             5. A function or closure it represents (callable)
         - int_enum (Type[IntEnum]): The dedicated integer-value enum type for the new Arbegla type.
         - str_enum (Type[StrEnum]): The dedicated string-value enum type for the new Arbegla type.
         - base_enum (Type[Enum]): The dedicated reserve-value enum type for the new Arbegla type.

     Returns:
         - BasicArbTypeBundleSet: A data structure representing the complete Arbegla type, including all its components and members.

     Behavior:
         - If an Arbegla type with the same master_type_name exists in the global type repository (__GLOBAL_PY_ARB_BASE_TYPE_REPO__), the function returns the existing type.
         - Otherwise, it creates a new Arbegla type, ensuring that it adheres to naming conventions, has valid member definitions, and the member count matches the provided enum types.
         - The function will raise RuntimeError with detailed descriptions if inconsistencies are found during type creation.
         - Upon successful type creation, it updates the global type repository and another mapping (__GLOBAL_TOP_LEVEL_SYMBOL_TSS__) with the new type details.

     Notes:
         - The function heavily relies on multiple global data structures and helper functions for error-checkin and validation, including __GLOBAL_PY_ARB_BASE_TYPE_REPO__, __GLOBAL_TOP_LEVEL_SYMBOL_TSS__, and more.
         - It's important to ensure the integrity of these global structures and the consistency of provided members and enums when using this function.

     Raises:
         - RuntimeError: When inconsistencies are found in the provided members, enums, or naming conventions.
         - TypeError: When retrieving an existing type but the enums provided don't match the original ones.

     Dependencies:
        - Uses several helper functions such as is_isb_enum_type, check_type_map_table, and more to assist with its operations.
     """

    elem_tri_type: Tuple[Type[IntEnum], Type[StrEnum], Type[Enum]] = (int_enum, str_enum, base_enum)

    if (tmp_a := (__GLOBAL_PY_ARB_BASE_TYPE_REPO__.get(master_type_name, None))) is not None:
        answer: BasicArbTypeBundleSet = tmp_a
        ga_types: Type[elem_tri_type] = (answer.ats_enum_int, answer.ats_enum_str, answer.ats_enum_base)
        if not (ga_types == elem_tri_type):  #
            raise TypeError(f'In retrieving the basic Arbegla {repr(master_type_name)} type, the {repr(ga_types)} enum must be given to this function (got {repr(elem_tri_type)} instead).') \
                from ArbeglaBaseEntityError(answer, RuntimeError, elem_tri_type, ga_types, typing = True)
        return answer
    del tmp_a  # keep it tidy

    num_elements: int = len(members)
    illegal_var_chars: Set[str] = {'(UNDETERMINED)'}
    if not (num_elements >= 1 and isinstance(master_type_name, str) and len(master_type_name) >= 5 and
            (master_type_name in __GLOBAL_TOP_LEVEL_SYMBOL_TSS__ or len(illegal_var_chars := (set(master_type_name).difference(valid_english_character_frozenset)))) == 0):
        raise RuntimeError(
            f'All basic Arbegla data types must have at least one member ({num_elements} given) and a type name string ({repr(master_type_name)} given) of ≥5 characters ({len(master_type_name)} given) '
            f'from the string {repr(valid_english_character_string)} ({{({", ".join(map(repr, illegal_var_chars))}) don\'t conform}} has length {len(illegal_var_chars)}); '
            f'and, it must be unique — the __GLOBAL_TOP_LEVEL_SYMBOL_TSS__ has {"an" if master_type_name in __GLOBAL_TOP_LEVEL_SYMBOL_TSS__ else "no"} entry.')
    if illegal_var_chars == {'(UNDETERMINED)'} or len(illegal_var_chars) != 0:
        raise RuntimeError(f'The Arbegla basic type name {repr(master_type_name)} must have characters only from {repr(valid_english_character_frozenset)}.')
    del illegal_var_chars  # descope now unneeded set.

    tuple_enum_master_record: Tuple[Tuple[Type[IntEnum], Type[StrEnum], Type[Enum]], ...] = ()
    if not (is_isb_enum_type(int_enum, str_enum, base_enum) and (len(int_enum) == len(str_enum) == len(base_enum) == num_elements) and
            len((tuple_enum_master_record := (tuple(zip(int_enum, str_enum, base_enum)))) == num_elements) and
            all((test for (ei, (xi, xs, xb)) in enumerate(tuple_enum_master_record) for test in
                 (is_isb_enum_type(xi, xs, xb), (xi.__class__ is int_enum and xs.__class__ is str_enum and xb.__class__ is base_enum),
                  (tuple(map(type, (xi, xs, xb))) == elem_tri_type), (xi.name == xs.name == xb.name), (ei == xi.value),))) and
            all(isinstance(x_member, tuple) and len(x_member) == 5 for x_member in members)):
        raise RuntimeError(
            f'The (int_enum, str_enum, base_enum) ({repr(elem_tri_type)} given) must all have {num_elements} members and the int_enum must increment from zero [expected {repr(range(num_elements))}, got {repr(tuple(int_enum))}] and '
            f'all three enums must have {repr(set(xv.name for xe in map(tuple, elem_tri_type) for xv in xe))} ({(repr(tuple(int_enum)))} in order for all three enums).')
    del num_elements  # keep it tidy still

    if not (all((test for (xi, xs, xb), (member_name, member_xim, member_xsm, member_xbm, member_closure) in zip(tuple_enum_master_record, members) for test in (
            (xi.name == member_xim.name == member_xsm.name == member_xbm.name == member_name), (callable(member_closure)),)))):
        raise RuntimeError(
            f'The members must have, for each triplet of ({repr(elem_tri_type)}), enum key names in {repr(tuple(ixe.name for ixe, _, __ in tuple_enum_master_record))} and in that order; and, '
            f'the members must have a callable to which each tuple ({repr(elem_tri_type)}) [enum key names] is tied.')

    ats_tmp_closure: basic_symbol_closure_table_t = {}
    ats_tmp_array: Deque[Optional[BasicArbTypeBundlePart]] = deque()
    for (xi, xs, xb), (member_name, member_xim, member_xsm, member_xbm, member_closure) in zip(tuple_enum_master_record, members):
        ats_tmp_array.append((new_member := BasicArbTypeBundlePart(member_name, member_xim, member_xsm, member_xbm, member_closure)))
        ats_tmp_closure[xi.name] = new_member
        for xt in xi, xs, xb:
            ats_tmp_closure[xt.value] = new_member

    ats_tmp_closure: basic_symbol_closure_table_t = frozendict(ats_tmp_closure)  # freeze lookup mappings
    ats_tmp_array: Tuple[basic_symbol_bundle_parts_t, ...] = tuple(ats_tmp_array)  # freeze the type's members' array

    check_lookup_tests_sequence: Tuple[Tuple[int, type_map_check_return_t], ...] = tuple(enumerate(map(check_type_map_table(ats_tmp_closure), ats_tmp_array)))

    x_bap_answers: Tuple[basic_symbol_bundle_union_t, ...]
    x_bap_o: Optional[BasicArbTypeBundlePart] = None
    x_bap_true: basic_symbol_bundle_parts_t
    x_bap_test: basic_symbol_bundle_parts_t
    for x_bap_i, (x_bap_answers, x_bap_o, x_bap_true, x_bap_test) in check_lookup_tests_sequence:
        if not ((x_bap_o is not None and x_bap_i == x_bap_o.atb_enum_int.value) and (x_bap_true == x_bap_test) and (x_bap_answers == x_bap_test)):
            res = (x_bap_answers, x_bap_true, x_bap_test)
            raise RuntimeError(  # save all the progress for downstream debugging.
                f'While inspecting the new Arbegla type\'s {repr(x_bap_o) if x_bap_o is not None else "(unknown)"} at index {x_bap_i}, the mapping (x_bap_answers, x_bap_true, x_bap_test) of {repr(res)} need '
                f'to map to [0] all ({repr(x_bap_o)},) * {len(x_bap_answers)} (got {repr(x_bap_answers)}), [1] same (got {repr(x_bap_true)}), and [2] same (got {repr(x_bap_test)}).') \
                from ArbeglaBaseEntityError(master_type_name, RuntimeError, ats_tmp_closure, ats_tmp_array, *res,
                                            x_objext = x_bap_o, x_index = x_bap_i, members = members, check_lookup_tests_sequence = check_lookup_tests_sequence)

    if x_bap_o is None:
        raise RuntimeError(  # save all the progress for downstream debugging.
            f'No iterations upon {repr(check_lookup_tests_sequence)} detected. Internal error.') \
            from ArbeglaBaseEntityError(master_type_name, RuntimeError, ats_tmp_closure, ats_tmp_array,
                                        members = members, check_lookup_tests_sequence = check_lookup_tests_sequence)

    new_arbegla_type_object = BasicArbTypeBundleSet(master_type_name, int_enum, str_enum, base_enum, ats_tmp_closure, ats_tmp_array)  # success!
    __GLOBAL_PY_ARB_BASE_TYPE_REPO__[master_type_name] = new_arbegla_type_object  # BasicArbTypeBundleSet
    __GLOBAL_TOP_LEVEL_SYMBOL_TSS__[master_type_name] = {new_arbegla_type_object}  # Set[basic_symbol_bundle_union_t] | FrozenSet[basic_symbol_bundle_union_t]
    return new_arbegla_type_object


__GLOBAL_PY_ARB_BASE_TYPE_REPO__: Dict[str, BasicArbTypeBundleSet] = {}  # fast name lookup
__GLOBAL_TOP_LEVEL_SYMBOL_TSS__: MutableMapping[basic_symbol_bundle_union_t, Set[basic_symbol_bundle_union_t] | FrozenSet[basic_symbol_bundle_union_t]] = {}  # general member-wise lookup

type_map_check_return_t = NewType(  # (x_bap_answers, x_bap_o, x_bap_m_true, x_bap_m_test)
    'type_map_check_return_t', Tuple[Tuple[basic_symbol_bundle_union_t, ...], Optional[BasicArbTypeBundlePart], basic_symbol_bundle_parts_t, basic_symbol_bundle_parts_t])


def check_type_map_table(ats_tmp_closure: basic_symbol_closure_table_t) -> Callable[[basic_symbol_bundle_parts_t], type_map_check_return_t]:
    def _i(bundle: basic_symbol_bundle_parts_t) -> type_map_check_return_t:  # (x_bap_answers, x_bap_o, x_bap_m_true, x_bap_m_test)
        read_from_mapping = ats_tmp_closure.get  # a closure!
        answers: Tuple[basic_symbol_bundle_union_t, ...] = tuple(map(read_from_mapping, bundle))
        if None not in answers:
            true_int_member: BasicArbTypeBundlePart = answers[1]  # load its IntEnum member
            return answers, true_int_member, bundle, tuple(map(read_from_mapping, unpack_basic_type_bundle(true_int_member)))
        return answers, None, bundle, ()

    return _i


def unpack_basic_type_bundle(btb: BasicArbTypeBundlePart) -> basic_symbol_bundle_parts_t:
    return btb.atb_name, btb.atb_enum_int, btb.atb_enum_str, btb.atb_enum_base, btb.atb_closure


def is_isb_enum_type(int_enum: Type[IntEnum], str_enum: Type[StrEnum], base_enum: Type[Enum]) -> bool:
    return (issubclass(int_enum.__class__, IntEnum) and
            issubclass(str_enum.__class__, StrEnum) and
            issubclass(base_enum.__class__, Enum))