QTube 2.3.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)
@@ -429,6 +433,14 @@ def main():
         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:
@@ -503,6 +515,12 @@ def main():
         # 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]})
@@ -661,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")

QTube/utils/checks.py

@@ -349,6 +349,8 @@ def check_user_params(params_dict: dict) -> bool:
         # 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)
@@ -419,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:
@@ -455,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

@@ -65,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:
@@ -161,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:
@@ -190,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:
@@ -204,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:
@@ -217,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:
@@ -229,7 +229,7 @@ def remove_multiple_spaces(text):
     return re.sub(" +", " ", text)
 
 
-def divide_lists(list1, list2, percentage: False):
+def divide_lists(list1, list2, percentage: False) -> list[int | float]:
     """Divides two python lists element-wise.
 
     Args:

QTube/utils/parsing.py

@@ -3,7 +3,7 @@ import json
 import re
 
 
-def parse_arguments():
+def parse_arguments() -> dict:
     """Parses command line arguments.
 
     Args:
@@ -273,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",
@@ -308,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:
@@ -346,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,7 +2,7 @@ import isodate
 
 from pytube import YouTube
 
-from QTube.utils import helpers
+from QTube.utils import helpers, checks
 
 
 def make_video_requests(youtube, video_IDs: list[str]) -> dict:
@@ -18,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,statistics", id=video_IDs_str)
+        .list(
+            part="snippet,contentDetails,statistics,paidProductPlacementDetails,status",
+            id=video_IDs_str,
+        )
         .execute(num_retries=5)
     )
     return response
@@ -345,7 +348,7 @@ def get_view_counts(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
+) -> list[int]:
     """Retrieves the number of views of a list of YT videos.
 
     Args:
@@ -375,7 +378,7 @@ def get_like_counts(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
+) -> list[int]:
     """Retrieves the number of likes of a list of YT videos.
 
     Args:
@@ -405,7 +408,7 @@ def get_comment_counts(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
+) -> list[int]:
     """Retrieves the number of comments of a list of YT videos.
 
     Args:
@@ -439,7 +442,7 @@ def get_likes_to_views_ratio(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
+) -> list[int | float]:
     """Retrieves the likes to views ratio of a list of YT videos.
 
     Args:
@@ -469,7 +472,7 @@ def get_comments_to_views_ratio(
     response: dict = None,
     video_IDs: list[str] = None,
     use_API: bool = False,
-) -> list[str]:
+) -> list[int | float]:
     """Retrieves the comments to views ratio of a list of YT videos.
 
     Args:
@@ -526,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.
@@ -536,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(
@@ -550,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:
@@ -575,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.3.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.3.0.dist-info → QTube-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: QTube
-Version: 2.3.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
@@ -104,6 +104,8 @@ Each of these rules is based on putting some kind of constraint on video propert
 * Quality filtering
 * Upload date filtering
 * Shorts filtering
+* Paid promotion filtering
+* Made for Kids filtering
 * Duplicate checking
 
 ## How to use
@@ -153,6 +155,8 @@ For more versatile uses, you can also use command line arguments with the [qtube
 |`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|
@@ -206,6 +210,8 @@ The following *user_params.json* file would add every new videos from channels y
 "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,
@@ -248,6 +254,8 @@ The following *user_params.json* file would only add videos with good quality.
 "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,
@@ -290,6 +298,8 @@ The following *user_params.json* file would only add the *$1 vs.* MrBeast videos
 "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.3.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=wzEkhjGgmRFtN9kNBZfqd_6rklX11hwzadh_DAQGZpM,33916
-QTube/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-QTube/utils/checks.py,sha256=wq__Xj_NEZa9tjliRTh-kZcHHbll0rqdjBXwIfZso9E,12569
-QTube/utils/helpers.py,sha256=cOhy4hauguO5-eJK9pK7NvPOtF5ZWp4zfFipA-DY1QM,9131
-QTube/utils/parsing.py,sha256=Q9GnSZSKwX7-AVQDlIoXlQ4xIgQIwMZfOIKXZWi7xSk,10359
-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=lHl-MrloJODCbGD38lwrPQmyEE8t-ZvLA0B4gfMSG0c,18159
-QTube-2.3.0.dist-info/LICENSE.txt,sha256=cctyZoZUseENxkeq5p_C5oCFYpK0-ECku_sCZmWbL0E,1098
-QTube-2.3.0.dist-info/METADATA,sha256=Ftm4t0X_hgyJelTS1v46YehDTPbZglWR5Hp4d3iMIio,17265
-QTube-2.3.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-QTube-2.3.0.dist-info/entry_points.txt,sha256=Q3SLDyRahuzrNnHC3UOkMH5gM_Um3eCLiLG4vSTPjqE,51
-QTube-2.3.0.dist-info/top_level.txt,sha256=z6oXrT8BiTTZuygjsbfe-NE4rmkHlDK8euAL9m6BT4A,6
-QTube-2.3.0.dist-info/RECORD,,