Extras

Extras module for additional functionality related to RTN processing.

Functions:

Name	Description
- `title_match`	Compare two titles using the Levenshtein ratio to determine similarity.
- `sort_torrents`	Sort a set of Torrent objects by their resolution and rank in descending order.
- `extract_seasons`	Extract season numbers from the title.
- `extract_episodes`	Extract episode numbers from the title.
- `episodes_from_season`	Extract episode numbers for a specific season from the title.

For more details, please refer to the documentation.

episodes_from_season(raw_title, season_num)

Only return episode numbers if the season number is found in the title and the season number matches the input season number.

Parameters:

Name	Type	Description	Default
`raw_title`	str	The original title of the torrent to analyze.	required
`season_num`	int	The season number to extract episodes for.	required

Returns:

Type	Description
List[int]	List[int]: A list of extracted episode numbers for the specified season.

Source code in RTN/extras.py

def episodes_from_season(raw_title: str, season_num: int) -> List[int]:
    """
    Only return episode numbers if the season number is found in the title
    and the season number matches the input season number.

    Args:
        `raw_title` (str): The original title of the torrent to analyze.
        `season_num` (int): The season number to extract episodes for.

    Returns:
        `List[int]`: A list of extracted episode numbers for the specified season.
    """
    if not season_num:
        raise ValueError("The season number must be provided.")
    if not isinstance(season_num, int) or season_num <= 0:
        raise TypeError("The season number must be a positive integer.")
    if not raw_title or not isinstance(raw_title, str):
        raise ValueError("The input title must be a non-empty string.")

    data: dict[str, Any] = parse_title(raw_title)

    season_from_title = data.get("seasons", [])
    episodes_from_title = data.get("episodes", [])

    if isinstance(episodes_from_title, list) and season_num in season_from_title:
        return episodes_from_title
    return []

extract_episodes(raw_title)

Extract episode numbers from the title or filename.

Parameters:

Name	Type	Description	Default
`raw_title`	str	The original title of the torrent to analyze.	required

Returns:

Type	Description
List[int]	List[int]: A list of extracted episode numbers from the title.

Source code in RTN/extras.py

def extract_episodes(raw_title: str) -> List[int]:
    """
    Extract episode numbers from the title or filename.

    Args:
        `raw_title` (str): The original title of the torrent to analyze.

    Returns:
        `List[int]`: A list of extracted episode numbers from the title.
    """
    if not raw_title or not isinstance(raw_title, str):
        raise TypeError("The input title must be a non-empty string.")
    return parse_title(raw_title)["episodes"]

extract_seasons(raw_title)

Extract season numbers from the title or filename.

Parameters:

Name	Type	Description	Default
`raw_title`	str	The original title of the torrent to analyze.	required

Returns:

Type	Description
List[int]	List[int]: A list of extracted season numbers from the title.

Source code in RTN/extras.py

def extract_seasons(raw_title: str) -> List[int]:
    """
    Extract season numbers from the title or filename.

    Args:
        `raw_title` (str): The original title of the torrent to analyze.

    Returns:
        `List[int]`: A list of extracted season numbers from the title.
    """
    if not raw_title or not isinstance(raw_title, str):
        raise TypeError("The input title must be a non-empty string.")
    return parse_title(raw_title)["seasons"]

get_lev_ratio(correct_title, parsed_title, threshold=0.85, aliases={})

Compares two titles using the Levenshtein ratio to determine similarity.

Parameters:

Name	Type	Description	Default
`correct_title`	str	The reference title to compare against.	required
`parsed_title`	str	The title to compare with the reference title.	required
`threshold`	float	The similarity threshold to consider the titles as matching.	required
`aliases`	dict	A dictionary of aliases for the correct title.	required

Returns:

Type	Description
float	float: The highest Levenshtein ratio between the parsed title and any of the correct titles (including aliases if provided).

Source code in RTN/extras.py

def get_lev_ratio(correct_title: str, parsed_title: str, threshold: float = 0.85, aliases: dict = {}) -> float:
    """
    Compares two titles using the Levenshtein ratio to determine similarity.

    Args:
        `correct_title` (str): The reference title to compare against.
        `parsed_title` (str): The title to compare with the reference title.
        `threshold` (float): The similarity threshold to consider the titles as matching.
        `aliases` (dict, optional): A dictionary of aliases for the correct title.

    Returns:
        `float`: The highest Levenshtein ratio between the parsed title and any of the correct titles (including aliases if provided).
    """
    if not (correct_title and parsed_title):
        raise ValueError("Both titles must be provided.")
    if not isinstance(threshold, (int, float)) or not 0 <= threshold <= 1:
        raise ValueError("The threshold must be a number between 0 and 1.")

    normalized_parsed_title = normalize_title(parsed_title)

    # Check correct_title first
    lev_ratio = ratio(normalize_title(correct_title), normalized_parsed_title, score_cutoff=threshold)
    if lev_ratio == 1.0:
        return 1.0
    highest_ratio = lev_ratio

    # Only check aliases if necessary
    if highest_ratio < 1.0 and aliases:
        for alias_list in aliases.values():
            for alias in alias_list:
                lev_ratio = ratio(normalize_title(alias), normalized_parsed_title, score_cutoff=threshold)
                if lev_ratio == 1.0:
                    return 1.0
                highest_ratio = max(highest_ratio, lev_ratio)

    return round(highest_ratio, 3)

sort_torrents(torrents)

Sorts a set of Torrent objects by their resolution bucket and then by their rank in descending order. Returns a dictionary with infohash as keys and Torrent objects as values.

Parameters:

Name	Type	Description	Default
`torrents`	Set[Torrent]	A set of Torrent objects.	required

Raises:

Type	Description
`TypeError`	If the input is not a set of Torrent objects.

Returns:

Type	Description
Dict[str, Torrent]	Dict[str, Torrent]: A dictionary of Torrent objects sorted by resolution and rank in descending order,
Dict[str, Torrent]	with the torrent's infohash as the key.

Source code in RTN/extras.py

def sort_torrents(torrents: Set[Torrent]) -> Dict[str, Torrent]:
    """
    Sorts a set of Torrent objects by their resolution bucket and then by their rank in descending order.
    Returns a dictionary with infohash as keys and Torrent objects as values.

    Args:
        `torrents` (Set[Torrent]): A set of Torrent objects.

    Raises:
        `TypeError`: If the input is not a set of Torrent objects.

    Returns:
        `Dict[str, Torrent]`: A dictionary of Torrent objects sorted by resolution and rank in descending order,
        with the torrent's infohash as the key.
    """

    if not isinstance(torrents, set) or not all(isinstance(t, Torrent) for t in torrents):
        raise TypeError("The input must be a set of Torrent objects.")

    buckets = {
        Resolution.UHD: 4,
        Resolution.UHD_2160P: 4,
        Resolution.UHD_1440P: 4,
        Resolution.FHD: 3,
        Resolution.HD: 2,
        Resolution.SD_576P: 1,
        Resolution.SD_480P: 1,
        Resolution.SD_360P: 1,
        Resolution.UNKNOWN: 0,
    }

    def get_bucket(torrent: Torrent) -> int:
        resolution_map = {
            "4k": Resolution.UHD,
            "2160p": Resolution.UHD_2160P,
            "1440p": Resolution.UHD_1440P,
            "1080p": Resolution.FHD,
            "720p": Resolution.HD,
            "576p": Resolution.SD_576P,
            "480p": Resolution.SD_480P,
            "360p": Resolution.SD_360P,
            "unknown": Resolution.UNKNOWN,
        }
        resolution = resolution_map.get(torrent.data.resolution, Resolution.UNKNOWN)
        return buckets[resolution]

    sorted_torrents: List[Torrent] = sorted(
        torrents,
        key=lambda torrent: (get_bucket(torrent), torrent.rank if torrent.rank is not None else float("-inf")),
        reverse=True
    )

    return {torrent.infohash: torrent for torrent in sorted_torrents}

title_match(correct_title, parsed_title, threshold=0.85, aliases={})

Compares two titles using the Levenshtein ratio to determine similarity.

Parameters:

Name	Type	Description	Default
`correct_title`	str	The reference title to compare against.	required
`parsed_title`	str	The title to compare with the reference title.	required
`threshold`	float	The similarity threshold to consider the titles as matching.	required
`aliases`	dict	A dictionary of aliases for the correct title.	required

Returns: bool: True if the titles match, False otherwise.

Source code in RTN/extras.py

def title_match(correct_title: str, parsed_title: str, threshold: float = 0.85, aliases: dict = {}) -> bool:
    """
    Compares two titles using the Levenshtein ratio to determine similarity.

    Args:
        `correct_title` (str): The reference title to compare against.
        `parsed_title` (str): The title to compare with the reference title.
        `threshold` (float): The similarity threshold to consider the titles as matching.
        `aliases` (dict, optional): A dictionary of aliases for the correct title.
    Returns:
        `bool`: True if the titles match, False otherwise.
    """
    check = get_lev_ratio(correct_title, parsed_title, threshold, aliases)
    return check >= threshold