Updated docstrings for API reference

sws/__init__.py

@@ -0,0 +1,55 @@
+"""An api and cli for doing common web development tasks
+
+Goals
+-----
+This project has several goals:
+
+1. Provide cross-platform implementations of functions (where possible)
+2. Serve as a repository of general knowledge to share solutions to issues with people
+3. Give people access to source code to learn how the functions work and just pull what's needed
+4. Provide a useful API for well developed functions with error catching and testing for commonly annoying situations
+
+Installation
+------------
+### From PyPi
+
+run ```pip install sws``` or ```sudo pip3 install sws```.
+
+### From source
+
+1. Clone the github repo ([https://github.com/Descent098/sws](https://github.com/Descent098/sws))
+2. cd into the 'sws' root directory (where setup.py is) and run ```pip install .``` or ```sudo pip3 install . ```
+
+Modules
+-------
+### domains
+A module for dealing with getting domain information such as:
+
+- If a domain is available
+- Who a domain is registered with
+- Other domain details such as, creation_date, name_servers etc.
+
+### redirects
+Provides a function for tracing redirects
+
+### ssl_utilities
+Get deails about the ssl cert of a hostname such as:
+
+- When the cert will expire
+- The issuer of the cert
+- A full dict of the details of the cert
+
+### youtube
+Provides functionality for working with YouTube videos such as:
+
+- Downloading youtube videos
+- Pulling video metadata
+
+Notes
+-----
+- When using the domain module if ```whois``` is not installed, the package/executable will be installed
+- You should use an FQDN for any ```ssl_utilties``` or ```domains``` functions, so something like https://www.google.ca becomes google.ca
+"""
+
+
+__pdoc__ = {"sws.cli": False} # Ignore the CLI in the API docs

sws/cli.py

@@ -10,36 +10,35 @@
 """
 
 # Python Standard library
-import sys                        # Used to validate arguments are given at the command line
+import sys                        # Used to check number of arguments
 from pprint import pprint         # Used to pretty-print to command line
 
 # External Dependencies
 from docopt import docopt         # Used to parse CLI arguments
 
 # Internal Dependencies
-from sws.domains import *         # Import domain utilities
-from sws.ssl_utilities import *   # Import SSL utilities
-from sws.redirects import trace   # Import redirect utilities
-from sws.youtube import download  # Import youtube utilities
+from sws.domains import *         # Import all domains utilities
+from sws.youtube import *         # Import all youtube utilities
+from sws.ssl_utilities import *   # Import all ssl_utilties functions
+from sws.redirects import trace   # Import trace from redirect utilities
 
 usage = """Super Web Scripts; A command line interface, and set of scripts for web tasks.
 
 Usage:
     sws [-h] [-v]
-    sws redirects <url> [-t]
     sws youtube <url> [<path>]
     sws ssl <hostname> [-e] [-c]
+    sws redirects <url> [<ignored>]
     sws domains <domain> [-e] [-r] [-d] [-a] [-t]
 
 Options:
     -h --help               Show this help message and exit
     -v --version            Show program's version number and exit
     -e --expiry             If specified will check the expiry of ssl cert/domain
     -c --cert               If specified will print the full details of the SSL cert
-    -t --trace              If specified will show the full trace of the provided url
-    -r --registered         Tells you if the domain has been registered
+    -r --registrar          Tells you who the domain is registered through
     -d --details            If specified will show full domain details
-    -a --available          Show this help message and exit
+    -a --available          Gives information on whether a specific domain is available
 """
 
 def main():
@@ -52,26 +51,24 @@ def main():
     if args["ssl"]:  # Begin parsing for ssl subcommand
         if args["--expiry"]:  # If -e or --expiry is specified
             print(f"Domain {args['<hostname>']} Expires on: {check_ssl_expiry(args['<hostname>'])}")
-
         if args["--cert"]:  # If -c or --cert is specified
             pprint(get_ssl_cert(args['<hostname>']))
 
     if args["redirects"]:  # Begin parsing for redirects subcommand
-        if args["--trace"]:  # If -t or --trace is specified
-            if "https://" in args["<url>"]:
-                args["<url>"] = args["<url>"].replace("https://", "http://")
-            trace(args["<url>"], [], print_result=True)
+        print(args["<ignored>"])
+        if args["<ignored>"]:
+            if args["<ignored>"].startswith("["):
+                args["<ignored>"] = list(args["<ignored>"])
+        trace(args["<url>"], args["<ignored>"], print_result=True)
 
     if args["youtube"]:
-        if not args["<path>"]:
-            args["<path>"] = "."
         download(args["<url>"], args["<path>"])
 
     if args["domains"]:  # Begin parsing for ssl subcommand
         domain_details = get_domain_info(args["<domain>"])
         if args["--expiry"]:  # If -e or --expiry is specified
             pprint(domain_details["expiration_date"])
-        if args["--registered"]:
+        if args["--registrar"]:
             if domain_details["registrar"]:
                 print(f"{args['<domain>']} is registered through {domain_details['registrar']}")
             else:

sws/domains.py

@@ -9,7 +9,7 @@
 - If whois is not installed, the package/executable will be installed
 
 Examples
------------
+--------
 ### Getting details about an available domain
 ```
 from sws.domains import get_domain_info, domain_availability
@@ -39,19 +39,19 @@
 
 print(get_domain_info('kieranwood.ca')) # {'creation_date': datetime.datetime(2018, 11, 6, 5, 9, 47), 'expiration_date': datetime.datetime(2020, 11, 6, 5, 9, 47), 'last_updated': datetime.datetime(2020, 1, 8, 8, 9, 44), 'name': 'kieranwood.ca', 'name_servers': {'kevin.ns.cloudflare.com', 'sharon.ns.cloudflare.com'}, 'registrant_cc': 'redacted for privacy', 'registrar': 'Go Daddy Domains Canada, Inc'}
 ```
-
 """
 
-import os
-import sys
-import subprocess
-from shutil import move
-from datetime import datetime
-from calendar import month_name
+# Standard Library Dependencies
+import os                        # Used for path manipulation
+import sys                       # Used to exit safely during errors
+import subprocess                # Used to execute existing binaries
+from shutil import move          # Used to move folders within the os
+from datetime import datetime    # Used for interpreting dates and times
+from calendar import month_name  # Used to convert integer month representations to string representations
 
 # Third Party Dependencies
-import whois
-from pystall.core import build, ZIPResource, _add_to_path, APTResource
+import whois  # Used to pull domain information
+from pystall.core import build, ZIPResource, _add_to_path, APTResource  # Used to install whois binary
 
 
 def get_domain_info(domain: str) -> dict:
@@ -140,6 +140,7 @@ def domain_availability(domain_query: dict) -> tuple:
 
 
 def _install_whois():
+    """Used to install whois binary if it isn't available"""
     # Setting up default downloads folder based on OS
     if os.name == "nt":
         DOWNLOAD_FOLDER = f"{os.getenv('USERPROFILE')}\\Downloads"
@@ -157,5 +158,5 @@ def _install_whois():
                 _add_to_path(INSTALL_FOLDER)
                 print("Whois has been installed, restart script")
                 sys.exit()
-            else: # Linux Installation
+            else:  # Linux Installation
                 build(APTResource("whois", "whois", overwrite_agreement=True))

sws/redirects.py

@@ -1,4 +1,4 @@
-"""Utilities to get information about http redirects
+"""Provides a function for tracing redirects
 
 Examples
 --------
@@ -20,20 +20,24 @@
 ```
 """
 
+# Standard library Dependencies
+from typing import Union        # Used for type hints with multiple types
+
 # External Dependencies
-import requests
+import requests                 # Used to make http requests for redirect tracing
 
 
-def trace(url: str, ignored_domains: list, print_result: bool = True) -> list:
+def trace(url: str, ignored_domains: Union[list, bool], print_result: bool = True) -> list:
     """Trace all redirects associated with a URL.
 
     Arguments
     ---------
     url : str
         The URL to trace, can include or not include a protocol
 
-    ignored_domains : list[str]
-        A list of domains (without protocols) to ignore in the trace
+    ignored_domains : list[str] or bool
+        A list of domains (without protocols) to ignore in the trace; False
+        can be passed in if no domains should be ignored
 
     print_result : bool
         If true then the value will be printed in a human readable format
@@ -68,9 +72,9 @@ def trace(url: str, ignored_domains: list, print_result: bool = True) -> list:
     """
     # Checks if protocols are present
     if "https://" in url:
-        None  # Continue
+        ...  # Continue
     elif "http://" in url:
-        None  # Continue
+        ...  # Continue
     else:  # Add a protocol to URL
         url = "http://" + url
 
@@ -128,6 +132,7 @@ def _skip_ignored_domains(response_trace: list, ignored_domains: list) -> list:
     trace('kieranwood.ca', ["safelinks.protection.outlook.com", "can01.safelinks.protection.outlook.com"], print_result = True)
     ```
     """
+    # Remove instances of ignored domains from the response trace
     for domain in ignored_domains:
         for response in response_trace:
             if domain in response.url:

sws/ssl_utilities.py

@@ -1,8 +1,13 @@
 """Get deails about the ssl cert of a hostname such as:
+
 - When the cert will expire
 - The issuer of the cert
 - A full dict of the details of the cert
 
+Notes
+-----
+- You should use an FQDN for any ssl_utilties functions, so something like https://www.google.ca becomes google.ca
+
 Examples
 --------
 ### Check when kieranwood.ca SSL cert expires

sws/youtube.py

@@ -1,4 +1,7 @@
-"""Provides a simple way to download & get metadata of YouTube videos
+"""Provides functionality for working with YouTube videos such as:
+
+- Downloading youtube videos
+- Pulling video metadata
 
 Examples
 --------
@@ -10,32 +13,37 @@
 ```
 """
 
-from pytube import YouTube      # Used to download and get youtube video info
+# Standard library Dependencies
+import os                       # Used for path validation
 import tkinter as tk            # Used to setup a gui for selecting files
+from typing import Union        # Used for type hints with multiple types
 from tkinter import filedialog  # Used to setup a gui for selecting files
 
+# External Dependencies
+from pytube import YouTube      # Used to download and get youtube video info
+
+
 
-def link_and_path():
+def _request_path():
     """Prompts user for the link to a youtube video, and path of where to download the video to"""
-    video_url = input("What is the URL for the video you want to download?: ")
     root = tk.Tk()
     root.withdraw()
     file_path = str(filedialog.askdirectory(
         title="Select Video Output directory",
         mustexist=False))
-    return video_url, file_path
+    return file_path
 
 
-def download(video_url: str, path: str) -> str:
+def download(video_url: str, path: Union[str, bool]) -> str:
     """Downloads specified video_url to path
 
     Parameters
     ----------
     video_url : (str)
         The full URL you want to download i.e. https://www.youtube.com/watch?v=6j1I3mC0BR0
 
-    path : (str)
-        The path on your system to download the video to.
+    path : (str or bool)
+        The path on your system to download the video to, or False to start pathfinding function
 
     Examples
     --------
@@ -46,6 +54,9 @@ def download(video_url: str, path: str) -> str:
     download("https://www.youtube.com/watch?v=6j1I3mC0BR0", ".") # Downloads video in current folder
     ```
     """
+    if not path:
+        path = os.path.realpath(f"{_request_path()}")
+
     video_title = str(YouTube(video_url).title)
     print(f"Downloading {video_title} to {path}")
     YouTube(video_url).streams.filter(subtype='mp4', progressive=True).order_by('resolution').desc().first().download(path)