Merge pull request #10 from wkaisertexas/qol

Quality of life changes

Author: wkaisertexas

.gitignore

@@ -1,5 +1,7 @@
 # Customized items
 test.py
+*.txt
+*.mp4
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -2,10 +2,28 @@
 
 ![Forks](https://img.shields.io/github/forks/wkaisertexas/tiktok-uploader)
 ![Stars](https://img.shields.io/github/stars/wkaisertexas/tiktok-uploader)
-![Forks](https://img.shields.io/github/watchers/wkaisertexas/tiktok-uploader)
+![Watchers](https://img.shields.io/github/watchers/wkaisertexas/tiktok-uploader)
 
 > A **Selenium**-based automated **TikTok** video uploader
 
+# Table of Contents
+- [Installation](#installation)
+  - [MacOS, Windows and Linux](#macos-windows-and-linux)
+    - [Downloading from PyPI (Recommended)](#downloading-from-pypi-recommended)
+  - [Building from source](#building-from-source)
+- [Usage](#usage)
+  - [💻 Commmand Line Interface (CLI)](#💻-commmand-line-interface-cli)
+  - [⬆️ Uploading Videos](#️⬆️-uploading-videos)
+  - [🫵 Mentions and Hashtags](#🫵-mentions-and-hashtags)
+  - [🪡 Stitches, Duets and Comments](#🪡-stitches-duets-and-comments)
+  - [🔐 Authentication](#🔐-authentication)
+  - [👀 Browser Selection](#👀-browser-selection)
+  - [🚲 Custom WebDriver Driver Options](#🚲-custom-webdriver-driver-options)
+  - [🤯 Headless Browsers](#🤯-headless-browsers)
+  - [🔨 Initial Setup](#🔨-initial-setup)
+- [♻️ Examples](#♻️-examples)
+- [📝 Notes](#📝-notes)
+- [Accounts made with](#accounts-made-using-tiktok-uploader)
 # Installation
 
 A prequisite to using this program is the installation of a [Selenium-compatable](https://www.selenium.dev/documentation/webdriver/getting_started/install_drivers/) web browser. [Google Chrome](https://www.google.com/chrome/) is recommended.
@@ -18,21 +36,21 @@ Install Python 3 or greater from [python.org](https://www.python.org/downloads/)
 
 Install `tiktok-uploader` using `pip`
 
-```bash
-$ pip install tiktok-uploader
+```console
+pip install tiktok-uploader
 ```
 
 ## Building from source
 
 Installing from source allows greater flexability to modify the module's code to extend default behavior. 
 
 First, `clone` and move into the repository. Next, install `hatch`, the build tool used for this project [^1]. Then, `build` the projet. Finally, `install` the project with the `-e` or editable flag.  
-```bash
-$ git clone https://github.com/wkaisertexas/tiktok-uploader.git
-$ cd tiktok-uploader
-$ pip install hatch
-$ hatch build
-$ pip install -e . 
+```console
+git clone https://github.com/wkaisertexas/tiktok-uploader.git
+cd tiktok-uploader
+pip install hatch
+hatch build
+pip install -e . 
 ```
 
 # Usage
@@ -43,11 +61,8 @@ While TikTok is strict about login in from Selenium, simply copying your session
 
 Using the CLI is as simple as calling `tiktok-uploader` with your videos: `path` (-v), `description`(-d) and `cookies` (-c)
 
-```bash
-$ tiktok-uploader \
--v video.mp4 \
--d "this is my escaped \"description\"" \
--c cookies.txt
+```console
+tiktok-uploader -v video.mp4 -d "this is my escaped \"description\"" -c cookies.txt
 ```
 
 ```python
@@ -75,7 +90,7 @@ auth = AuthBackend(cookies='cookies.txt')
 upload_videos(videos=videos, auth=auth)
 ```
 
-## ⬆️ Uploading videos
+## ⬆️ Uploading Videos
 
 This library revolves around the `upload_videos` function which takes in a list of videos which have **filenames** and **descriptions** and are passed as follows:
 
@@ -210,17 +225,21 @@ On intial startup, you **may** be prompted to install the correct driver for you
 
 # ♻️ Examples
 
+[Basic Upload Example](exmples/basic_upload.py) is a simple automation which uses `upload_video`.
+
+[Series Upload Example](examples/series_upload.py) is a automation which uploads the same video multiple times using `upload_videos`.
+
 [Scheduled Uploader Example](examples/example_series_upload.py) is an automation which is based off this package. Videos are read from a CSV file using [Pandas](https://pandas.pydata.org). A video upload attempt is made and **if and only if** it is successful will the video be marked as uploaded.
 
-## 📝 Notes
+# 📝 Notes
 
 This bot is not fool proof. Though I have not gotten an official ban, when the video will fail to upload after too many uploads. When testing, waiting several hours was sufficient to fix this problem. For this reason, please thing of this more as a scheduled uploader for TikTok videos, rather than a spam bot.
 
 > Please think of this package as more of a scheduled uploader for TikTok videos, rather than a spam bot
 
-## Accounts made using `tiktok-uploader`
+# Accounts made using `tiktok-uploader`
 
 - [@C_Span](https://www.tiktok.com/@c_span?lang=en) - A split-screen channel with mobile games below featuring clips from C-Span's YouTube channel
-- [@habit_track](https://www.tiktok.com/@habit_track?lang=en) - A generic Dhar Mann TikTok bot
+- [@habit_track](https://www.tiktok.com/@habit_track?lang=en) - A Reddit to TikTok bot for a data science project
 
 [^1]: If interested in Hatch, checkout the [website](https://hatch.pypa.io/latest/build/)

examples/basic_upload.py

@@ -0,0 +1,17 @@
+"""Gets a video from the internet and uplaods it"""
+
+import urllib.request
+
+from tiktok_uploader.upload import upload_video
+
+URL = "https://raw.githubusercontent.com/wkaisertexas/wkaisertexas.github.io/main/upload.mp4"
+FILENAME = "upload.mp4"
+
+if __name__ == "__main__":
+    # download random video
+    urllib.request.urlretrieve(URL, FILENAME)
+    
+    # upload video to TikTok
+    upload_video(FILENAME,
+                 description="This is a video I just downloaded",
+                 cookies="cookies.txt")

examples/multiple_videos_at_once.py

@@ -0,0 +1,30 @@
+"""
+Uploads multiple videos downloaded from the internet
+"""
+from tiktok_uploader.upload import upload_videos
+
+import urllib.request
+
+URL = "https://raw.githubusercontent.com/wkaisertexas/wkaisertexas.github.io/main/upload.mp4"
+FILENAME = "upload.mp4"
+
+videos = [
+    {
+        "path": "upload.mp4",
+        "description": "This is the first upload"
+    },
+    {
+        "filename": "upload.mp4",
+        "desc": "This is my description"
+    }
+]
+
+if __name__ == "__main__":
+    # download random video
+    urllib.request.urlretrieve(URL, FILENAME)
+    
+    # authentication backend
+    auth = AuthBackend(cookies="cookies.txt")
+
+    # upload video to TikTok
+    upload_videos(videos, auth=auth)

examples/example_series_upload.py examples/series_upload.pyexamples/example_series_upload.py renamed to examples/series_upload.py

@@ -196,3 +196,19 @@ class InsufficientAuth(Exception):
     """
     Raised when there is insufficient authentication
     """
+
+    # sets the exception message
+    def __init__(self, message="""
+    Insufficient authentication:
+
+    > TikTok uses cookies to keep track of the user's authentication or session.
+
+    Either:
+        - Use a cookies file passed as the `cookies` argument
+            - easily obtained using https://github.com/kairi003/Get-cookies.txt-LOCALLY
+        - Use a cookies list passed as the `cookies_list` argument
+            - can be obtained from your browser's developer tools under storage -> cookies
+            - only the `sessionid` cookie is required
+    """):
+        self.message = message
+        super().__init__(self.message)

src/tiktok_uploader/auth.py

@@ -3,6 +3,10 @@
 headless = false
 quit_on_end = true
 
+# Messing around with inputs
+valid_path_names = ["path", "filename", "video", "video_path"]
+valid_descriptions = ["description", "desc", "caption"]
+
 # Selenium Webdriver Waits
 implicit_wait = 3 # seconds
 explicit_wait = 60 # seconds

src/tiktok_uploader/config.toml

@@ -7,6 +7,7 @@
 upload_videos : Uploads multiple TikTok videos
 """
 from os.path import abspath, exists
+from typing import List
 import time
 
 from selenium.webdriver.common.by import By
@@ -75,9 +76,7 @@ def upload_videos(videos: list = None, auth: AuthBackend = None, browser='chrome
     failed : list
         A list of videos which failed to upload
     """
-    if not videos:
-        print("No videos were provided")
-        return
+    videos = _convert_videos_dict(videos)
 
     if not browser_agent: # user-specified browser agent
         driver = get_browser(name=browser, headless=headless, *args, **kwargs)
@@ -182,7 +181,6 @@ def _set_description(driver, description: str) -> None:
         while description:
             nearest_mention = description.find('@')
             nearest_hash = description.find('#')
-            print("description: ", description)
 
             if nearest_mention == 0 or nearest_hash == 0:
                 desc.send_keys('@' if nearest_mention == 0 else '#')
@@ -191,8 +189,6 @@ def _set_description(driver, description: str) -> None:
                 time.sleep(config['implicit_wait'])
 
                 name = description[1:].split(' ')[0]
-                print("name: ", name)
-                # TODO: sending keys directly for mentions may not work
                 if nearest_mention == 0: # @ case
                     mention_xpath = config['selectors']['upload']['mention_box']
                     condition = EC.presence_of_element_located((By.XPATH, mention_xpath))
@@ -205,7 +201,6 @@ def _set_description(driver, description: str) -> None:
 
                 if nearest_mention == 0: # @ case
                     mention_xpath = config['selectors']['upload']['mentions'].format('@' + name)
-                    print(mention_xpath)
                     condition = EC.presence_of_element_located((By.XPATH, mention_xpath))
                 else:
                     hashtag_xpath = config['selectors']['upload']['hashtags'].format(name)
@@ -236,8 +231,6 @@ def _clear(element) -> None:
     element
         The text box to clear
     """
-    # element.send_keys(Keys.CONTROL + 'a')
-    # element.send_keys(Keys.DELETE)
 
     element.send_keys(2 * len(element.text) * Keys.BACKSPACE) # margin of safety
 
@@ -381,3 +374,65 @@ def _get_splice_index(nearest_mention: int, nearest_hashtag: int, description: s
         return nearest_hashtag
     else:
         return min(nearest_mention, nearest_hashtag)
+
+def _convert_videos_dict(videos_list_of_dictionaries) -> List:
+    """
+    Takes in a videos dictionary and converts it.
+
+    This allows the user to use the wrong stuff and thing to just work
+    """
+    if not videos_list_of_dictionaries:
+        raise RuntimeError("No videos to upload")
+
+    valid_path = config['valid_path_names']
+    valid_description = config['valid_descriptions']
+
+    correct_path = valid_path[0]
+    correct_description = valid_description[0]
+
+    def intersection(lst1, lst2):
+        """ return the intersection of two lists """
+        return list(set(lst1) & set(lst2))
+
+    return_list = []
+    for elem in videos_list_of_dictionaries:
+        # preprocesses the dictionary
+        elem = {k.strip().lower(): v for k, v in elem.items()}
+
+        keys = elem.keys()
+        path_intersection = intersection(valid_path, keys)
+        description_interesection = intersection(valid_description, keys)
+
+        if path_intersection:
+            # we have a path
+            path = elem[path_intersection.pop()]
+
+            if not _check_valid_path(path):
+                raise RuntimeError("Invalid path: " + path)
+
+            elem[correct_path] = path
+        else:
+            # iterates over the elem and find a key which is a path with a valid extension
+            for _, value in elem.items():
+                if _check_valid_path(value):
+                    elem[correct_path] = value
+                    break
+            else:
+                # no valid path found
+                raise RuntimeError("Path not found in dictionary: " + str(elem))
+
+        if description_interesection:
+            # we have a description
+            elem[correct_description] = elem[description_interesection.pop()]
+        else:
+            # iterates over the elem and finds a description which is not a valid path
+            for _, value in elem.items():
+                if not _check_valid_path(value):
+                    elem[correct_description] = value
+                    break
+            else:
+                elem[correct_description] = '' # null description is fine
+
+        return_list.append(elem)
+
+    return return_list

src/tiktok_uploader/upload.py

@@ -0,0 +1,75 @@
+"""
+Tests uploader
+"""
+
+from tiktok_uploader.upload import _convert_videos_dict
+
+import os
+
+from pytest import raises
+
+# before each create a file called test.mp4 and test.jpg
+FILENAME = 'test.mp4'
+
+def setup_function():
+    """
+    Creates a dummy file
+    """
+    with open(FILENAME, 'w', encoding='utf-8') as file:
+        file.write('test')
+
+# delete the file after each test
+def teardown_function():
+    """
+    Deletes the dummy file
+    """
+    os.remove(FILENAME)
+
+def test_convert_videos_dict_good():
+    """Tests the videos dictionary with the good names"""
+    good_dict = {
+        "path": FILENAME,
+        "description": "this is my description",
+    }
+
+    array = _convert_videos_dict([good_dict])
+
+    assert array[0]['path'] == FILENAME
+    assert array[0]['description'] == "this is my description"
+
+def test_convert_videos_dict_wrong_names():
+    """
+    Tests the videos dictionary with the wrong names
+    """
+    wrong_dict = {
+        'video': FILENAME,
+        'desc': 'this is my description',
+    }
+
+    array = _convert_videos_dict([wrong_dict])
+
+    assert array[0]['path'] == FILENAME
+    assert array[0]['description'] == "this is my description"
+
+def test_convert_videos_bad():
+    """
+    Tests the videos dictionary with the wrong dictionaries
+    """
+    bad_dict = {
+        'nothing': 'asfs',
+        'wrong': 'wrong',
+    }
+    with raises(RuntimeError):
+        _convert_videos_dict([bad_dict])
+
+def test_convert_videos_filename():
+    """
+    Tests the videos dictionary with the wrong dictionaries
+    """
+    bad_dict = {
+        'nothing': FILENAME,
+    }
+    array = _convert_videos_dict([bad_dict])
+
+    assert array[0]['path'] == FILENAME
+    assert array[0]['description'] == ""