Source code for symmetria.generators.api

from typing import List, Generator

__all__ = ["permutation_generator"]

_SUPPORTED_ALGORITHM: List[str] = [
    "lexicographic",
]




def permutation_generator(degree: int, algorithm: str = "lexicographic") -> Generator["Permutation", None, None]:
    """Generate all the permutations of the degree based on the chosen algorithm.

    The method generates all the permutations of the given degree using the specified algorithm.

    :param degree: The degree of the permutations to be generated. Must be a non-zero positive integer.
    :type degree: int
    :param algorithm: The algorithm to use for generating permutations. Default is "lexicographic".
    :type algorithm: str, optional

    :return: A generator yielding permutations.
    :rtype: Generator["Permutation", None, None]

    :raises ValueError: If the algorithm is not supported or the degree is invalid.

    # Activate once we have the lexicographic algorithm
    #:examples:
        # >>> from symmetria import permutation_generator
        # ...
        # >>> permutations = permutation_generator(degree=3, algorithm="lexicographic")
        # >>> for perm in permutations:
        # ...     print(perm)
        # Permutation(1, 2, 3)
        # Permutation(1, 3, 2)
        # Permutation(2, 1, 3)
        ...
    """
    _check_algorithm_parameter(value=algorithm)
    _check_degree_parameter(value=degree)
    return _relevant_generator(algorithm=algorithm, degree=degree)



def _check_algorithm_parameter(value: str) -> None:
    """Private method to check the value provided for the parameter `algorithm`.

    Recall that the parameter `algorithm` must be a string present in the list _SUPPORTED_ALGORITHM
    """
    if isinstance(value, str) is False:
        raise TypeError(f"The parameter `algorithm` must be of type string, but {type(value)} was provided.")
    if value not in _SUPPORTED_ALGORITHM:
        raise ValueError(
            f"The given algorithm ({value}) is not supported. \n "
            f"Here, a list of supported algorithm for generations of permutations {_SUPPORTED_ALGORITHM}."
        )


def _check_degree_parameter(value: int) -> None:
    """Private method to check the value provided for the parameter `degree`.

    Recall that the parameter `degree` must be a non-negative integer different from zero.
    """
    if isinstance(value, int) is False:
        raise TypeError(f"The parameter `degree` must be of type int, but {type(value)} was provided.")
    if value < 1:
        raise ValueError(f"The parameter `degree` must be a non-zero positive integer, but {value} was provided.")


def _relevant_generator(algorithm: str, degree: int) -> Generator["Permutation", None, None]:
    """Private method to pick the correct algorithm for generating permutations."""
    raise NotImplementedError(f"To be implemented using {algorithm} and {degree}.")