QTube 2.2.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

QTube/scripts/qtube.py

@@ -127,7 +127,7 @@ def main():
             ["internal"],
         )
     QTube.utils.helpers.print2(
-        f"The following verbosity options are enabled: {verb}.\n",
+        f"The following verbosity options are enabled: {', '.join(verb)}.\n",
         fancy,
         "info",
         ["internal"],
@@ -383,6 +383,8 @@ def main():
             vid_dicts = partial["items"]
             responses["items"].extend(vid_dicts)
 
+    video_IDs_lst = [vid["id"] for vid in responses["items"]]
+
     # Titles retrieving
     titles = QTube.utils.youtube.videos.get_titles(response=responses)
 
@@ -390,7 +392,9 @@ def main():
     durations = QTube.utils.youtube.videos.get_durations(response=responses)
 
     # Shorts retrieving
-    shorts = QTube.utils.youtube.videos.is_short(response=responses)
+    shorts = QTube.utils.youtube.videos.is_short(
+        response=responses, video_IDs=video_IDs_lst
+    )
 
     # Languages retrieving
     languages = QTube.utils.youtube.videos.get_languages(response=responses)
@@ -410,6 +414,33 @@ def main():
     # Live status retrieving
     live_statuses = QTube.utils.youtube.videos.is_live(response=responses)
 
+    # View counts retrieving
+    view_counts = QTube.utils.youtube.videos.get_view_counts(response=responses)
+
+    # Like counts retrieving
+    like_counts = QTube.utils.youtube.videos.get_like_counts(response=responses)
+
+    # Comment counts retrieving
+    comment_counts = QTube.utils.youtube.videos.get_comment_counts(response=responses)
+
+    # Likes/views ratio retrieving
+    likes_to_views_ratio = QTube.utils.youtube.videos.get_likes_to_views_ratio(
+        like_counts, view_counts
+    )
+
+    # Comments/views ratio retrieving
+    comments_to_views_ratio = QTube.utils.youtube.videos.get_likes_to_views_ratio(
+        comment_counts, view_counts
+    )
+
+    # Paid promotions retrieving
+    paid_advertising = QTube.utils.youtube.videos.has_paid_advertising(
+        response=responses
+    )
+
+    # Made for Kids retrieving
+    made_for_kids = QTube.utils.youtube.videos.is_made_for_kids(response=responses)
+
     # Resolutions retrieving (does not use YT API)
     lowest_resolution = user_params_dict.get("lowest_resolution")
     if lowest_resolution is not None:
@@ -469,6 +500,27 @@ def main():
         # Live statuses
         vid_info.update({"live status": live_statuses[index]})
 
+        # Views
+        vid_info.update({"views": view_counts[index]})
+
+        # Likes
+        vid_info.update({"likes": like_counts[index]})
+
+        # Comments
+        vid_info.update({"comments": comment_counts[index]})
+
+        # Likes/views
+        vid_info.update({"likes_to_views_ratio": likes_to_views_ratio[index]})
+
+        # Comments/views
+        vid_info.update({"comments_to_views_ratio": comments_to_views_ratio[index]})
+
+        # Paid promotions
+        vid_info.update({"has_paid_ad": paid_advertising[index]})
+
+        # Made for kids
+        vid_info.update({"made_for_kids": made_for_kids[index]})
+
         # Resolutions
         if lowest_resolution is not None:
             vid_info.update({"resolutions": resolutions[index]})
@@ -543,6 +595,12 @@ def main():
     lowest_definition = user_params_dict.get("lowest_definition")
     preferred_dimensions = user_params_dict.get("preferred_dimensions")
 
+    views_threshold = user_params_dict.get("views_threshold")
+    likes_threshold = user_params_dict.get("likes_threshold")
+    comments_threshold = user_params_dict.get("comments_threshold")
+    likes_to_views_ratio_threshold = user_params_dict.get("likes_to_views_ratio")
+    comments_to_views_ratio_threshold = user_params_dict.get("comments_to_views_ratio")
+
     # Duration filtering
     if min_max_durations is not None:
         for vid_info in videos.values():
@@ -621,6 +679,22 @@ def main():
             if vid_ID in new_vid_IDs:
                 videos[vid_ID].update({"to add": False})
 
+    # Paid advertisement filtering
+    if user_params_dict["allow_paid_promotions"] is False:
+        for vid_ID, vid_info in videos.items():
+            if vid_info["to add"] is False:
+                continue
+            elif vid_info["has_paid_ad"]:
+                vid_info.update({"to add": False})
+
+    # Made for kids filtering
+    if user_params_dict["only_made_for_kids"] is True:
+        for vid_ID, vid_info in videos.items():
+            if vid_info["to add"] is False:
+                continue
+            elif not vid_info["made_for_kids"]:
+                vid_info.update({"to add": False})
+
     # Language filtering
     if preferred_languages is not None:
         preferred_languages.append("unknown")
@@ -771,6 +845,43 @@ def main():
             ):
                 vid_info.update({"to add": False})
 
+    # Views filtering
+    if views_threshold > 0:
+        for vid_ID, vid_info in videos.items():
+            if vid_info["to add"] and vid_info["views"] < views_threshold:
+                vid_info.update({"to add": False})
+
+    # Likes Filtering
+    if likes_threshold > 0:
+        for vid_ID, vid_info in videos.items():
+            if vid_info["to add"] and vid_info["likes"] < likes_threshold:
+                vid_info.update({"to add": False})
+
+    # Comments filtering
+    if comments_threshold > 0:
+        for vid_ID, vid_info in videos.items():
+            if vid_info["to add"] and vid_info["comments"] < comments_threshold:
+                vid_info.update({"to add": False})
+
+    # Likes/views ratio filtering
+    if likes_to_views_ratio_threshold > 0:
+        for vid_ID, vid_info in videos.items():
+            if (
+                vid_info["to add"]
+                and vid_info["likes_to_views_ratio"] < likes_to_views_ratio_threshold
+            ):
+                vid_info.update({"to add": False})
+
+    # Comments/views ratio filtering
+    if comments_to_views_ratio_threshold > 0:
+        for vid_ID, vid_info in videos.items():
+            if (
+                vid_info["to add"]
+                and vid_info["comments_to_views_ratio"]
+                < comments_to_views_ratio_threshold
+            ):
+                vid_info.update({"to add": False})
+
     ## Selecting correct videos
     videos_to_add = {
         vid_ID: vid_info for vid_ID, vid_info in videos.items() if vid_info["to add"]

QTube/utils/checks.py

@@ -334,6 +334,23 @@ def check_user_params(params_dict: dict) -> bool:
         isinstance(params_dict.get("ignore_premieres"), bool),
         # Fancy text
         isinstance(params_dict.get("fancy_mode"), bool),
+        # Views
+        isinstance(params_dict.get("views_threshold"), int)
+        and params_dict.get("views_threshold") >= 0,
+        # Likes
+        isinstance(params_dict.get("likes_threshold"), int)
+        and params_dict.get("likes_threshold") >= 0,
+        # Comments
+        isinstance(params_dict.get("comments_threshold"), int)
+        and params_dict.get("comments_threshold") >= 0,
+        # Likes/views ratio
+        isinstance(params_dict.get("likes_to_views_ratio"), (int, float))
+        and 0 <= params_dict.get("likes_to_views_ratio") <= 1,
+        # Comments/views ratio
+        isinstance(params_dict.get("comments_to_views_ratio"), (int, float))
+        and 0 <= params_dict.get("comments_to_views_ratio") <= 1,
+        # Paid promotions
+        isinstance(params_dict.get("allow_paid_promotions"), bool),
     ]
 
     ok = all(checks)
@@ -404,7 +421,7 @@ def check_version() -> tuple[str]:
     return version, latest_release
 
 
-def compare_software_versions(version1, version2):
+def compare_software_versions(version1, version2) -> str:
     """Compare two software versions, using version2 as the reference against which version1 is compared.
 
     Args:
@@ -440,3 +457,18 @@ def compare_software_versions(version1, version2):
             return "older"
 
     return "same"
+
+
+def check_URL_redirect(url: str, redirect_code: int) -> bool:
+    """Checks if the provided URL redirects to another page.
+
+    Args:
+        url (str): URL to check for redirection
+        redirect_code (int): Status code to check for (3xx)
+
+    Returns:
+        (bool): True if the URL redirects to another page with the correct status code, False otherwise.
+    """
+    r = requests.get(url)
+
+    return any([resp.status_code == redirect_code for resp in r.history])

QTube/utils/helpers.py

@@ -7,7 +7,7 @@ from googleapiclient.errors import HttpError
 from colorama import Fore, Style
 
 
-def handle_http_errors(verbosity: list[str],fancy, func, *args, **kwargs):
+def handle_http_errors(verbosity: list[str], fancy, func, *args, **kwargs):
     """Handles http errors when making API queries.
     If after 5 tries, the function could not be executed, it shuts the program down.
 
@@ -27,7 +27,11 @@ def handle_http_errors(verbosity: list[str],fancy, func, *args, **kwargs):
         try:
             res = func(*args, **kwargs)
             print2(
-                f"{func.__name__} successfully executed.",fancy,"success", ["all", "func"], verbosity
+                f"{func.__name__} successfully executed.",
+                fancy,
+                "success",
+                ["all", "func"],
+                verbosity,
             )
             return res  # Return the response if no error occurs
         except HttpError as err:
@@ -61,7 +65,7 @@ def handle_http_errors(verbosity: list[str],fancy, func, *args, **kwargs):
             sys.exit()  # Exit the program after 5 retries
 
 
-def fancify_text(text, color, style, emoji):
+def fancify_text(text, color, style, emoji) -> str:
     """Modifies the color and content of a string.
 
     Args:
@@ -100,9 +104,9 @@ def print2(
             elif fancy_type == "fail":
                 print(fancify_text(message, Fore.RED, Style.BRIGHT, "❌"))
             elif fancy_type == "warning":
-                print(fancify_text(message, Fore.YELLOW, Style.NORMAL, "⚠️"))
+                print(fancify_text(message, Fore.YELLOW, Style.BRIGHT, "⚠️"))
             elif fancy_type == "info":
-                print(fancify_text(message, Fore.WHITE, Style.BRIGHT,"📢"))
+                print(fancify_text(message, Fore.WHITE, Style.BRIGHT, "📢"))
             elif fancy_type == "video":
                 print(fancify_text(message, Fore.BLUE, Style.BRIGHT, "🎞️"))
             else:
@@ -157,7 +161,7 @@ def merge_dicts(list_of_dicts: list) -> dict:
     return {key: value for d in list_of_dicts for key, value in d.items()}
 
 
-def strip_emojis(text):
+def strip_emojis(text) -> str:
     """Strips emojis from a string.
 
     Args:
@@ -186,7 +190,7 @@ def strip_emojis(text):
     return remove_multiple_spaces(clean_text)
 
 
-def strip_punctuation(text):
+def strip_punctuation(text) -> str:
     """Strips punctuation from a string (all of these characters: !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~).
 
     Args:
@@ -200,7 +204,7 @@ def strip_punctuation(text):
     return remove_multiple_spaces(clean_text)
 
 
-def make_lowercase(text):
+def make_lowercase(text) -> str:
     """Converts all uppercase letters to lowercase from a string.
 
     Args:
@@ -213,7 +217,7 @@ def make_lowercase(text):
     return text.lower()
 
 
-def remove_multiple_spaces(text):
+def remove_multiple_spaces(text) -> str:
     """Removes multiple spaces in a string and replaces them with a single space.
 
     Args:
@@ -223,3 +227,21 @@ def remove_multiple_spaces(text):
         (str): Same text string, but with multiple spaces replaced by a single space.
     """
     return re.sub(" +", " ", text)
+
+
+def divide_lists(list1, list2, percentage: False) -> list[int | float]:
+    """Divides two python lists element-wise.
+
+    Args:
+        list1 (lst[int|float]): Dividend list.
+        list2 (lst[inf|float]): Divisor list.
+        percentage (bool): Determines if the result of the division is expressed as a percentage.
+
+    Returns:
+        res (lst[int|float]): List containing the results of the element-wise division.
+    """
+    if percentage:
+        res = [(a / b) * 100 if b != 0 else None for a, b in zip(list1, list2)]
+    else:
+        res = [a / b if b != 0 else None for a, b in zip(list1, list2)]
+    return res

QTube/utils/parsing.py

@@ -3,7 +3,7 @@ import json
 import re
 
 
-def parse_arguments():
+def parse_arguments() -> dict:
     """Parses command line arguments.
 
     Args:
@@ -217,6 +217,46 @@ def parse_arguments():
         help="Projection the videos need to be in. Default: None",
     )
 
+    parser.add_argument(
+        "-vt",
+        "--views_threshold",
+        metavar="",
+        type=int,
+        help="Minimum number of views. Default: 0",
+    )
+
+    parser.add_argument(
+        "-lt",
+        "--likes_threshold",
+        metavar="",
+        type=int,
+        help="Minimum number of likes. Default: 0",
+    )
+
+    parser.add_argument(
+        "-ct",
+        "--comments_threshold",
+        metavar="",
+        type=int,
+        help="Minimum number of comments. Default: 0",
+    )
+
+    parser.add_argument(
+        "-lvr",
+        "--likes_to_views_ratio",
+        metavar="",
+        type=float,
+        help="Minimum ratio of likes to views. Default: 0",
+    )
+
+    parser.add_argument(
+        "-cvr",
+        "--comments_to_views_ratio",
+        metavar="",
+        type=float,
+        help="Minimum ratio of comments to views. Default: 0",
+    )
+
     parser.add_argument(
         "-rf",
         "--run_frequency",
@@ -233,6 +273,20 @@ def parse_arguments():
         help="Determines whether to add shorts. Default: True",
     )
 
+    parser.add_argument(
+    "-app",
+    "--allow_paid_promotions",
+    action="store_false",
+    help="Allow videos containing paid advertising. Default: True",
+    )
+
+    parser.add_argument(
+    "-mfk",
+    "--only_made_for_kids",
+    action="store_true",
+    help="Determines whether to only add videos that are made for kids, based on Youtube and FTC guidelines. Default: False",
+    )
+
     parser.add_argument(
         "-kd",
         "--keep_duplicates",
@@ -268,7 +322,7 @@ def parse_arguments():
     return vars(parser.parse_args())
 
 
-def format_arguments(args_dict):
+def format_arguments(args_dict) -> dict:
     """Formats the parsed command line arguments (written with the help of AI, regex is witchcraft to me).
 
     Args:
@@ -306,7 +360,7 @@ def format_arguments(args_dict):
     return args_dict
 
 
-def format_arguments_legacy(args_dict):
+def format_arguments_legacy(args_dict) -> dict:
     """Formats the parsed command line arguments (legacy function).
 
     Args:

QTube/utils/youtube/channels.py

@@ -36,7 +36,7 @@ def get_subscriptions(youtube, next_page_token=None) -> dict:
     return channels
 
 
-def get_channel_info(youtube, handle: str):
+def get_channel_info(youtube, handle: str) -> dict:
     """Retrieves basic information about a YT channel.
 
     Args:
@@ -49,9 +49,7 @@ def get_channel_info(youtube, handle: str):
     channel = {}
 
     response = (
-        youtube.channels()
-        .list(part="snippet", forHandle=handle)
-        .execute(num_retries=5)
+        youtube.channels().list(part="snippet", forHandle=handle).execute(num_retries=5)
     )
 
     if "items" in response.keys():

QTube/utils/youtube/playlists.py

@@ -66,7 +66,7 @@ def get_playlist_content(youtube, playlist_ID: str) -> list[str]:
     return videos_IDs
 
 
-def get_playlists_titles(youtube=None, playlist_IDs: list[str] = None):
+def get_playlists_titles(youtube=None, playlist_IDs: list[str] = None) -> list[str]:
     """Retrieves the titles of a list of YT playlists.
 
     Args:
@@ -88,7 +88,9 @@ def get_playlists_titles(youtube=None, playlist_IDs: list[str] = None):
     return titles
 
 
-def get_playlists_video_counts(youtube=None, playlist_IDs: list[str] = None):
+def get_playlists_video_counts(
+    youtube=None, playlist_IDs: list[str] = None
+) -> list[int]:
     """Retrieves the number of videos of a list of YT playlists.
 
     Args:

QTube/utils/youtube/videos.py

@@ -2,6 +2,8 @@ import isodate
 
 from pytube import YouTube
 
+from QTube.utils import helpers, checks
+
 
 def make_video_requests(youtube, video_IDs: list[str]) -> dict:
     """Retrieves information on a list of YT videos.
@@ -16,7 +18,10 @@ def make_video_requests(youtube, video_IDs: list[str]) -> dict:
     video_IDs_str = ",".join(video_IDs)
     response = (
         youtube.videos()
-        .list(part="snippet,contentDetails", id=video_IDs_str)
+        .list(
+            part="snippet,contentDetails,statistics,paidProductPlacementDetails,status",
+            id=video_IDs_str,
+        )
         .execute(num_retries=5)
     )
     return response
@@ -338,6 +343,158 @@ def get_projections(
     return projections
 
 
+def get_view_counts(
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+) -> list[int]:
+    """Retrieves the number of views of a list of YT videos.
+
+    Args:
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        views (list[int]): List of YT videos views.
+    """
+    if use_API:
+        video_IDs_str = ",".join(video_IDs)
+        response = (
+            youtube.videos()
+            .list(part="statistics", id=video_IDs_str)
+            .execute(num_retries=5)
+        )
+
+    views = [int(vid["statistics"]["viewCount"]) for vid in response["items"]]
+
+    return views
+
+
+def get_like_counts(
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+) -> list[int]:
+    """Retrieves the number of likes of a list of YT videos.
+
+    Args:
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        likes (list[int]): List of YT videos likes.
+    """
+    if use_API:
+        video_IDs_str = ",".join(video_IDs)
+        response = (
+            youtube.videos()
+            .list(part="statistics", id=video_IDs_str)
+            .execute(num_retries=5)
+        )
+
+    likes = [int(vid["statistics"]["likeCount"]) for vid in response["items"]]
+
+    return likes
+
+
+def get_comment_counts(
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+) -> list[int]:
+    """Retrieves the number of comments of a list of YT videos.
+
+    Args:
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        comment_counts (list[int]): List of YT videos comment counts.
+    """
+    if use_API:
+        video_IDs_str = ",".join(video_IDs)
+        response = (
+            youtube.videos()
+            .list(part="statistics", id=video_IDs_str)
+            .execute(num_retries=5)
+        )
+
+    comment_counts = [
+        int(vid["statistics"]["commentCount"]) for vid in response["items"]
+    ]
+
+    return comment_counts
+
+
+def get_likes_to_views_ratio(
+    likes,
+    views,
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+) -> list[int | float]:
+    """Retrieves the likes to views ratio of a list of YT videos.
+
+    Args:
+        likes (list[int]): List of the number of likes.
+        views (list[int]): List of the number of views.
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        ratio (list[int|float]): List of YT videos' likes to views ratios.
+    """
+    if use_API:
+        views = get_view_counts(youtube, response, video_IDs, use_API)
+        likes = get_like_counts(youtube, response, video_IDs, use_API)
+
+    ratio = helpers.divide_lists(likes, views, False)
+
+    return ratio
+
+
+def get_comments_to_views_ratio(
+    likes,
+    views,
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+) -> list[int | float]:
+    """Retrieves the comments to views ratio of a list of YT videos.
+
+    Args:
+        comments (list[int]): List of the number of comments.
+        views (list[int]): List of the number of views.
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        views (list[int|float]): List of YT videos' comments to views ratios.
+    """
+    if use_API:
+        views = get_view_counts(youtube, response, video_IDs, use_API)
+        comments = get_comment_counts(youtube, response, video_IDs, use_API)
+
+    ratio = helpers.divide_lists(comments, views, False)
+
+    return ratio
+
+
 def has_captions(
     youtube=None,
     response: dict = None,
@@ -372,8 +529,8 @@ def is_short(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
-    """Determines if videos are a short or not by putting a threshold on video duration.
+) -> list[bool]:
+    """Determines if videos are a short or not by putting a threshold on video duration and checking for a redirection at the youtube.com/shorts/*vid_ID* URL.
 
     Args:
         youtube (Resource): YT API resource.
@@ -382,13 +539,21 @@ def is_short(
         use_API (bool): Determines if a new API request is made or if the response dictionary is used.
 
     Returns:
-        is_short (list[bool]): True if the video is shorter than 65 seconds, False otherwise.
+        is_a_short (list[bool]): True if the video is shorter than 181 seconds and there is no URL redirection, False otherwise.
     """
     durations = get_durations(youtube, response, video_IDs, use_API=use_API)
 
-    is_short = [True if length <= 65.0 else False for length in durations]
+    is_short_vid = [
+        True if length <= 181 else False for length in durations
+    ]  # Shorts cannot last over 3 minutes.
 
-    return is_short
+    is_not_redirected = [
+        not checks.check_URL_redirect("https://www.youtube.com/shorts/" + vid_ID, 303)
+        for vid_ID in video_IDs
+    ]  # Shorts do not trigger a redirection.
+
+    is_a_short = is_short_vid and is_not_redirected
+    return is_a_short
 
 
 def is_live(
@@ -396,7 +561,7 @@ def is_live(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-):
+) -> list[str]:
     """Retrieves the live status of YT videos.
 
     Args:
@@ -421,3 +586,64 @@ def is_live(
     ]
 
     return live_statuses
+
+
+def has_paid_advertising(
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+)-> list[bool]:
+    """Determines if a video contains paid advertising.
+
+    Args:
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        (list[bool]): True if the video contains paid advertising, False otherwise.
+    """
+
+    if use_API:
+        video_IDs_str = ",".join(video_IDs)
+        response = (
+            youtube.videos()
+            .list(part="paidProductPlacementDetails", id=video_IDs_str)
+            .execute(num_retries=5)
+        )
+
+    return [
+        vid["paidProductPlacementDetails"]["hasPaidProductPlacement"]
+        for vid in response["items"]
+    ]
+
+
+def is_made_for_kids(
+    youtube=None,
+    response: dict = None,
+    video_IDs: list[str] = None,
+    use_API: bool = False,
+)-> list[bool]:
+    """Determines if a video is appropriate for children (based on YT's guidelines).
+
+    Args:
+        youtube (Resource): YT API resource.
+        response (dict[dict]): YT API response from the make_video_request function.
+        video_IDs (list[str]): List of video IDs.
+        use_API (bool): Determines if a new API request is made or if the response dictionary is used.
+
+    Returns:
+        (list(bool)): True if the video is made for kids, False otherwise.
+    """
+
+    if use_API:
+        video_IDs_str = ",".join(video_IDs)
+        response = (
+            youtube.videos()
+            .list(part="status", id=video_IDs_str)
+            .execute(num_retries=5)
+        )
+
+    return [vid["status"]["madeForKids"] for vid in response["items"]]

{QTube-2.2.0.dist-info → QTube-2.4.0.dist-info}/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [2024] [Killian Lebreton]
+Copyright (c) [2025] [Killian Lebreton]
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{QTube-2.2.0.dist-info → QTube-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: QTube
-Version: 2.2.0
+Version: 2.4.0
 Summary: Automatically add Youtube videos to a playlist.
 Home-page: https://github.com/Killian42/QTube
 Author: Killian Lebreton
@@ -8,7 +8,7 @@ Author-email: Killian Lebreton <killian.lebreton35@gmail.com>
 Maintainer-email: Killian Lebreton <killian.lebreton35@gmail.com>
 License: MIT License
         
-        Copyright (c) [2024] [Killian Lebreton]
+        Copyright (c) [2025] [Killian Lebreton]
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -98,11 +98,14 @@ Each of these rules is based on putting some kind of constraint on video propert
 * Language filtering
 * Caption filtering
 * Duration filtering
+* Views, likes & comments counts filtering
 * Livestream filtering
 * Premiere filtering
 * Quality filtering
 * Upload date filtering
 * Shorts filtering
+* Paid promotion filtering
+* Made for Kids filtering
 * Duplicate checking
 
 ## How to use
@@ -145,8 +148,15 @@ For more versatile uses, you can also use command line arguments with the [qtube
 |`lowest_framerate`|Yes|Minimum framerate. Videos with framerates stricly lower than this value will not be added.|Positive integer|
 |`preferred_dimensions`|Yes|Dimension the videos need to be in.|*2D*, *3D* or both|
 |`preferred_projections`|Yes|Projection the videos need to be in.|*rectangular*, *360* or both|
+|`views_threshold`|No|Minimum number of times videos have been viewed.|Positive integer|
+|`likes_threshold`|No|Minimum number of times videos have been liked.|Positive integer|
+|`comments_threshold`|No|Minimum number of times videos have been commented on.|Positive integer|
+|`likes_to_views_ratio`|No|Minimum likes to views ratio.|Positive float between 0 & 1|
+|`comments_to_views_ratio`|No|Minimum comments to views ratio.|Positive float between 0 & 1|
 |`run_frequency`|No|Defines the duration, in days, of the timeframe considered by the software. Can be interpreted as the frequency the program should be run.|*daily*, *weekly*, *monthly* or any positive integer|
 |`keep_shorts`|No|Determines whether to add shorts.|boolean|
+|`allow_paid_promotions`|No|Determines whether to add videos containing paid advertisement.|boolean|
+|`only_made_for_kids`|No|Determines whether to only add videos that are *Made for Kids* (based on [Youtube and FTC guidelines](https://support.google.com/youtube/answer/9528076)).|boolean|
 |`keep_duplicates`|No|Determines whether to add videos that are already in the playlist.|boolean|
 |`upload_playlist_ID`|No|ID of the playlist the videos will be added to. Playlist IDs are found at the end of their URL: `https://www.youtube.com/playlist?list=*playlist_ID*`|Playlist ID|
 |`override_json`|No|Allow command line arguments to override user_params.json parameters.|boolean|
@@ -193,8 +203,15 @@ The following *user_params.json* file would add every new videos from channels y
 "lowest_framerate": null,
 "preferred_dimensions": null,
 "preferred_projections": null,
+"views_threshold": 0,
+"likes_threshold": 0,
+"comments_threshold": 0,
+"likes_to_views_ratio": 0,
+"comments_to_views_ratio": 0,
 "run_frequency":"daily",
 "keep_shorts": true,
+"allow_paid_promotions": true,
+"only_made_for_kids": false,
 "keep_duplicates": false,
 "upload_playlist_ID": "your_playlist_ID",
 "override_json":false,
@@ -230,8 +247,15 @@ The following *user_params.json* file would only add videos with good quality.
 "lowest_framerate": 60,
 "preferred_dimensions": ["2D"],
 "preferred_projections": ["rectangular"],
+"views_threshold": 0,
+"likes_threshold": 0,
+"comments_threshold": 0,
+"likes_to_views_ratio": 0,
+"comments_to_views_ratio": 0,
 "run_frequency":"daily",
 "keep_shorts": true,
+"allow_paid_promotions": true,
+"only_made_for_kids": false,
 "keep_duplicates": false,
 "upload_playlist_ID": "your_playlist_ID",
 "override_json":false,
@@ -267,8 +291,15 @@ The following *user_params.json* file would only add the *$1 vs.* MrBeast videos
 "lowest_framerate": null,
 "preferred_dimensions": ["2D"],
 "preferred_projections": ["rectangular"],
+"views_threshold": 0,
+"likes_threshold": 0,
+"comments_threshold": 0,
+"likes_to_views_ratio": 0,
+"comments_to_views_ratio": 0,
 "run_frequency":"daily",
 "keep_shorts": false,
+"allow_paid_promotions": true,
+"only_made_for_kids": false,
 "keep_duplicates": false,
 "upload_playlist_ID": "your_playlist_ID",
 "override_json":false,

QTube-2.4.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+QTube/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+QTube/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+QTube/scripts/qtube.py,sha256=7sr4UnaNtxjUAK_cxW9_fgLzW3jMD-kCkBKJXmXh0_o,35108
+QTube/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+QTube/utils/checks.py,sha256=EV-oV89Ufd02fAzsT68wyVCziSMlnbo1NR1XiNqGa0k,13159
+QTube/utils/helpers.py,sha256=fl1_fePwy7ot-KRFB9Ieq7fMFtD8Q4TriK8cW17qPy0,9187
+QTube/utils/parsing.py,sha256=LQ7onVUyqef9bQOS54YNixOHdJGkfydsazP7ijQQoNA,10789
+QTube/utils/youtube/captions.py,sha256=0jUs8SH4L4d2RTS4QHJ5J2Zd9qe3SOHf9VZW966NuY8,1591
+QTube/utils/youtube/channels.py,sha256=_IITSU3tZJLqrJkdQOLGAwTyrrsZb-WywRq2LyqXVBQ,3331
+QTube/utils/youtube/playlists.py,sha256=kMWeaxGp09J3IY6UWpB7qKY7peTpIBlJkMUDb7CDIpM,3874
+QTube/utils/youtube/videos.py,sha256=YWhpLQVADr95lp1XMgnkg5z05YOxtBgpEauUz95zMeQ,20607
+QTube-2.4.0.dist-info/LICENSE.txt,sha256=cIZNbD-BZYZPzWYHhtE-iUCasUxQIwWzALL9nZh32pQ,1098
+QTube-2.4.0.dist-info/METADATA,sha256=SyyF5njBo11yORDL9_UBmRSGlni982O2ZNgyXiP-G28,17798
+QTube-2.4.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+QTube-2.4.0.dist-info/entry_points.txt,sha256=Q3SLDyRahuzrNnHC3UOkMH5gM_Um3eCLiLG4vSTPjqE,51
+QTube-2.4.0.dist-info/top_level.txt,sha256=z6oXrT8BiTTZuygjsbfe-NE4rmkHlDK8euAL9m6BT4A,6
+QTube-2.4.0.dist-info/RECORD,,

QTube-2.2.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-QTube/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-QTube/scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-QTube/scripts/qtube.py,sha256=4ZCSNwWJ90ysTOu92VZI2SUXYsmDa9aXGhA_z8s-Cf0,31002
-QTube/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-QTube/utils/checks.py,sha256=g8KLAaOP9cregzfJLou_PkODFtdQNECFOoSoTnECXn8,11819
-QTube/utils/helpers.py,sha256=F2393sh4s3L8Ax8Gljogm3o1o_xzzJe_7MiwxiSWAXo,8433
-QTube/utils/parsing.py,sha256=SIS8wmhv_bQWf8QwH_GGr9yvTOPuh6tTJUjhy-XAiFU,9445
-QTube/utils/youtube/captions.py,sha256=0jUs8SH4L4d2RTS4QHJ5J2Zd9qe3SOHf9VZW966NuY8,1591
-QTube/utils/youtube/channels.py,sha256=8K-5_Ff8zHyKhEM02cdwMEV6HLU14MngxI1v2yJh6iI,3343
-QTube/utils/youtube/playlists.py,sha256=Cdohhb2M4bxKiTnZ-R-0xNXPV050nhhI6hepvtDVpIM,3840
-QTube/utils/youtube/videos.py,sha256=FFQVjHktk1vRAqfL6BE1zGsBmgomMzn49R4wKH_5oVc,13282
-QTube-2.2.0.dist-info/LICENSE.txt,sha256=cctyZoZUseENxkeq5p_C5oCFYpK0-ECku_sCZmWbL0E,1098
-QTube-2.2.0.dist-info/METADATA,sha256=jcN88dOhmghemBpXB_T5oe_8WywvGe4BqmESRTo_U9I,16368
-QTube-2.2.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-QTube-2.2.0.dist-info/entry_points.txt,sha256=Q3SLDyRahuzrNnHC3UOkMH5gM_Um3eCLiLG4vSTPjqE,51
-QTube-2.2.0.dist-info/top_level.txt,sha256=z6oXrT8BiTTZuygjsbfe-NE4rmkHlDK8euAL9m6BT4A,6
-QTube-2.2.0.dist-info/RECORD,,