Code cleanup

9 files changed, 35 insertions, 26 deletions

diff --git a/src/wikiget/__init__.py b/src/wikiget/__init__.py
index 3946868..e0584bb 100644
--- a/src/wikiget/__init__.py
+++ b/src/wikiget/__init__.py
@@ -17,7 +17,7 @@
 
 from mwclient import __version__ as mwclient_version
 
-from wikiget.version import __version__ as wikiget_version
+from wikiget.version import __version__
 
 # set some global constants
 BLOCKSIZE = 65536
@@ -25,7 +25,7 @@ CHUNKSIZE = 1024
 DEFAULT_SITE = "commons.wikimedia.org"
 DEFAULT_PATH = "/w/"
 USER_AGENT = (
-    f"wikiget/{wikiget_version} (https://github.com/clpo13/wikiget) "
+    f"wikiget/{__version__} (https://github.com/clpo13/wikiget) "
     f"mwclient/{mwclient_version}"
 )
 STD_VERBOSE = 1
diff --git a/src/wikiget/dl.py b/src/wikiget/dl.py
index 845d136..f210182 100644
--- a/src/wikiget/dl.py
+++ b/src/wikiget/dl.py
@@ -50,7 +50,7 @@ def batch_download(args: Namespace) -> int:
     try:
         dl_list = read_batch_file(args.FILE)
     except OSError as e:
-        logger.error(f"File could not be read. {e}")
+        logger.error(f"File could not be read: {e}")
         sys.exit(1)
 
     # TODO: validate file contents before download process starts
@@ -102,15 +102,16 @@ def download(f: File, args: Namespace) -> int:
         adapter.info(f"{file_url}")
 
         if os.path.isfile(dest) and not args.force:
-            adapter.warning("File already exists, skipping download (use -f to force)")
+            # TODO: check for this before the download process starts
+            adapter.warning("File already exists; skipping download (use -f to force)")
             errors += 1
         elif args.dry_run:
-            adapter.warning("Dry run, so nothing actually downloaded")
+            adapter.warning("Dry run; download skipped")
         else:
             try:
                 fd = open(dest, "wb")
             except OSError as e:
-                adapter.error(f"File could not be written. {e}")
+                adapter.error(f"File could not be written: {e}")
                 errors += 1
                 return errors
             # download the file(s)
@@ -133,7 +134,7 @@ def download(f: File, args: Namespace) -> int:
             try:
                 dl_sha1 = verify_hash(dest)
             except OSError as e:
-                adapter.error(f"File downloaded but could not be verified. {e}")
+                adapter.error(f"File downloaded but could not be verified: {e}")
                 errors += 1
                 return errors
 
diff --git a/src/wikiget/exceptions.py b/src/wikiget/exceptions.py
index 94ed6b2..02ffe50 100644
--- a/src/wikiget/exceptions.py
+++ b/src/wikiget/exceptions.py
@@ -17,4 +17,9 @@
 
 
 class ParseError(Exception):
+    """
+    This exception is raised when the program's input is unable to be parsed as a valid
+    download target.
+    """
+
     pass
diff --git a/src/wikiget/file.py b/src/wikiget/file.py
index b890e63..16402b0 100644
--- a/src/wikiget/file.py
+++ b/src/wikiget/file.py
@@ -21,6 +21,11 @@ from wikiget import DEFAULT_SITE
 
 
 class File:
+    """
+    This class represents a file with the properties name, destination, host site, and
+    mwclient.image.Image object as retrieved from the host site.
+    """
+
     def __init__(self, name: str, dest: str = "", site: str = "") -> None:
         """
         Initializes a new file with the specified name and an optional destination name.
diff --git a/src/wikiget/logging.py b/src/wikiget/logging.py
index c0b5c12..9dec9c3 100644
--- a/src/wikiget/logging.py
+++ b/src/wikiget/logging.py
@@ -26,9 +26,9 @@ class FileLogAdapter(logging.LoggerAdapter):
 
 
 def configure_logging(verbosity: int, logfile: str, *, quiet: bool) -> None:
-    loglevel = logging.WARNING
+    loglevel = logging.WARNING  # default log level
     if verbosity >= wikiget.VERY_VERBOSE:
-        # this includes API and library messages
+        # this includes API and library messages, not just from wikiget
         loglevel = logging.DEBUG
     elif verbosity >= wikiget.STD_VERBOSE:
         loglevel = logging.INFO
diff --git a/src/wikiget/parse.py b/src/wikiget/parse.py
index 847cfa4..b41f0fe 100644
--- a/src/wikiget/parse.py
+++ b/src/wikiget/parse.py
@@ -37,8 +37,8 @@ def get_dest(dl: str, args: Namespace) -> File:
         site_name = url.netloc
         if args.site is not wikiget.DEFAULT_SITE:
             # this will work even if the user specifies 'commons.wikimedia.org' since
-            # we're comparing objects instead of values (is not vs. !=)
-            logger.warning("Target is a URL, ignoring site specified with --site")
+            # we're comparing objects instead of values ('is not' vs. '!=')
+            logger.warning("Target is a URL; ignoring site specified with --site")
     else:
         filename = dl
         site_name = args.site
@@ -55,12 +55,8 @@ def get_dest(dl: str, args: Namespace) -> File:
         raise ParseError(msg)
 
     filename = unquote(filename)  # remove URL encoding for special characters
-
     dest = args.output or filename
-
-    file = File(filename, dest, site_name)
-
-    return file
+    return File(filename, dest, site_name)
 
 
 def read_batch_file(batch_file: str) -> Dict[int, str]:
diff --git a/src/wikiget/validations.py b/src/wikiget/validations.py
index c9e7bcf..6926f06 100644
--- a/src/wikiget/validations.py
+++ b/src/wikiget/validations.py
@@ -43,8 +43,10 @@ def valid_site(search_string: str) -> Optional[re.Match]:
     """
     Determines if the given string contains a valid site name, defined as a string
     ending with 'wikipedia.org' or 'wikimedia.org'. This covers all subdomains of those
-    domains. Eventually, it should be possible to support any MediaWiki site, regardless
-    of domain name.
+    domains.
+
+    Currently unused since any site is accepted as input, and we rely on the user to
+    ensure the site has a compatible API.
 
     :param search_string: string to validate
     :type search_string: str
diff --git a/src/wikiget/wikiget.py b/src/wikiget/wikiget.py
index 693decb..0b08f68 100644
--- a/src/wikiget/wikiget.py
+++ b/src/wikiget/wikiget.py
@@ -34,7 +34,7 @@ def construct_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="""
         A tool for downloading files from MediaWiki sites using the file name or
-        description page URL
+        description page URL.
         """,
         epilog="""
         Copyright (C) 2018-2023 Cody Logan and contributors. License GPLv3+: GNU GPL
@@ -46,7 +46,7 @@ def construct_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "FILE",
         help="""
-        name of the file to download with the File: prefix, or the URL of its file
+        name of the file to download, with the File: prefix, or the URL of its file
         description page
         """,
     )
@@ -54,7 +54,7 @@ def construct_parser() -> argparse.ArgumentParser:
         "-V",
         "--version",
         action="version",
-        version=f"%(prog)s {wikiget.wikiget_version}",
+        version=f"%(prog)s {wikiget.__version__}",
     )
     message_options = parser.add_mutually_exclusive_group()
     message_options.add_argument(
@@ -116,8 +116,8 @@ def construct_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "-n",
         "--dry-run",
-        action="store_true",
         help="check the download or batch file without actually downloading anything",
+        action="store_true",
     )
 
     return parser
@@ -131,7 +131,7 @@ def main() -> None:
 
     # log events are appended to the file if it already exists, so note the start of a
     # new download session
-    logger.info(f"Starting download session using wikiget {wikiget.wikiget_version}")
+    logger.info(f"Starting download session using wikiget {wikiget.__version__}")
     logger.debug(f"User agent: {wikiget.USER_AGENT}")
 
     if args.batch:
@@ -143,7 +143,7 @@ def main() -> None:
             logger.warning(
                 f"{errors} problem{'s'[:errors^1]} encountered during batch processing"
             )
-            sys.exit(1)
+            sys.exit(1)  # completed with errors
     else:
         # single download mode
         try:
@@ -155,4 +155,4 @@ def main() -> None:
             sys.exit(1)
         errors = download(file, args)
         if errors:
-            sys.exit(1)
+            sys.exit(1)  # completed with errors
diff --git a/tests/test_parse.py b/tests/test_parse.py
index a04b30f..7ba7f0c 100644
--- a/tests/test_parse.py
+++ b/tests/test_parse.py
@@ -70,4 +70,4 @@ class TestGetDest:
             ]
         )
         _ = get_dest(args.FILE, args)
-        assert "Target is a URL, ignoring site specified with --site" in caplog.text
+        assert "Target is a URL; ignoring site specified with --site" in caplog.text