Documentation and formatting updates. No functional changes.

helper.py TUPLE_STR_BYTES, while functionally the same, should be str, bytes

constants.py, put DEFAULT_EXECUTABLE into a one-liner so that it's properly documented by AutoAPI

Author: sylikc

docs/source/examples.rst

@@ -190,7 +190,7 @@ Setting Tags
                 params=["-P", "-overwrite_original"]
             )
 
-    (No output is returned if successful)
+    (*No output is returned if successful*)
 
 * Setting keywords for a file.
 
@@ -203,7 +203,7 @@ Setting Tags
                 tags={"Keywords": ["sunny", "nice day", "cool", "awesome"]}
             )
 
-    (No output is returned if successful)
+    (*No output is returned if successful*)
 
 
 
@@ -218,7 +218,7 @@ By default, ExifToolHelper has some **built-in error checking**, making the meth
 
 * Example using get_tags() on a list which includes a non-existent file
 
-    * Using ExifToolHelper.get_tags()
+    * ExifToolHelper with error-checking, using :py:meth:`exiftool.ExifToolHelper.get_tags`
 
         .. code-block::
 
@@ -245,7 +245,7 @@ By default, ExifToolHelper has some **built-in error checking**, making the meth
             exiftool.exceptions.ExifToolExecuteError: execute returned a non-zero exit status: 1
 
 
-    * Using ExifTool.execute_json()  (Note how the missing file is silently ignored and doesn't show up in returned list.)
+    * ExifTool only, without error checking, using :py:meth:`exiftool.ExifTool.execute_json` (**Note how the missing file is silently ignored and doesn't show up in returned list.**)
 
         .. code-block::
 
@@ -263,9 +263,9 @@ By default, ExifToolHelper has some **built-in error checking**, making the meth
             [{'SourceFile': 'rose.jpg', 'File:FileSize': 4949}, {'SourceFile': 'skyblue.png', 'File:FileSize': 206}]
 
 
-* Example using get_tags() with a typo.  Let's say you wanted to get_tags, but accidentally copy/pasted something and left a ``=`` character behind...
+* Example using :py:meth:`exiftool.ExifToolHelper.get_tags` with a typo.  Let's say you wanted to ``get_tags()``, but accidentally copy/pasted something and left a ``=`` character behind (deletes tag rather than getting!)...
 
-    * Using ExifToolHelper.get_tags()
+    * Using :py:meth:`exiftool.ExifToolHelper.get_tags`
 
         .. code-block::
 
@@ -286,7 +286,7 @@ By default, ExifToolHelper has some **built-in error checking**, making the meth
                 raise ExifToolTagNameError(t)
             exiftool.exceptions.ExifToolTagNameError: Invalid Tag Name found: "XMP:Subject=hi"
 
-    * Using ExifTool.execute_json().  It still errors out, but more cryptic
+    * Using :py:meth:`exiftool.ExifTool.execute_json`.  It still raises an exception, but more cryptic and difficult to debug
 
         .. code-block::
 
@@ -305,7 +305,7 @@ By default, ExifToolHelper has some **built-in error checking**, making the meth
                 raise ExifToolOutputEmptyError(self._last_status, self._last_stdout, self._last_stderr, params)
             exiftool.exceptions.ExifToolOutputEmptyError: execute_json expected output on stdout but got none
 
-    * Using ExifTool.execute().  **No errors, but you have now written to the file instead of reading from it!**
+    * Using :py:meth:`exiftool.ExifTool.execute`.  **No errors, but you have now written to the file instead of reading from it!**
 
         .. code-block::
 

docs/source/intro.rst

@@ -38,7 +38,7 @@ What PyExifTool Is NOT
 Nomenclature
 ============
 
-PyExifTool's namespace is *exiftool*.  While naming the library the same name of the tool it's meant to interface with, it can cause some ambiguity when describing it in docs.
+PyExifTool's namespace is *exiftool*.  Since library name the same name of the tool it's meant to interface with, it can cause some ambiguity when describing it in docs.
 Hence, here's some common nomenclature used.
 
 Because the term `exiftool` is overloaded (lowercase, CapWords case, ...) and can mean several things:

exiftool/constants.py

@@ -51,20 +51,23 @@
 
 
 # specify the extension so exiftool doesn't default to running "exiftool.py" on windows (which could happen)
-DEFAULT_EXECUTABLE: str
+DEFAULT_EXECUTABLE: str = "exiftool.exe" if PLATFORM_WINDOWS else "exiftool"
 """The name of the default executable to run.
 
-``exiftool`` (Linux) or ``exiftool.exe`` (Windows)
+``exiftool.exe`` (Windows) or ``exiftool`` (Linux/Mac/non-Windows platforms)
 
 By default, the executable is searched for on one of the paths listed in the
-``PATH`` environment variable.  If it's not on the ``PATH``, a full path should be given to the ExifTool constructor.
+``PATH`` environment variable.  If it's not on the ``PATH``, a full path should be specified in the
+``executable`` argument of the ExifTool constructor (:py:meth:`exiftool.ExifTool.__init__`).
 """
 
-if PLATFORM_WINDOWS:
-	DEFAULT_EXECUTABLE = "exiftool.exe"
-else:  # pytest-cov:windows: no cover
+"""
+# flipped the if/else so that the sphinx documentation shows "exiftool" rather than "exiftool.exe"
+if not PLATFORM_WINDOWS:  # pytest-cov:windows: no cover
 	DEFAULT_EXECUTABLE = "exiftool"
-
+else:
+	DEFAULT_EXECUTABLE = "exiftool.exe"
+"""
 
 
 ##################################
@@ -96,7 +99,7 @@
 should be fine, though other values might give better performance in
 some cases."""
 
-EXIFTOOL_MINIMUM_VERSION = "12.15"
+EXIFTOOL_MINIMUM_VERSION: str = "12.15"
 """this is the minimum *exiftool* version required for current version of PyExifTool
 
 * 8.40 / 8.60 (production): implemented the -stay_open flag

exiftool/helper.py

@@ -35,7 +35,7 @@
 from .exceptions import ExifToolOutputEmptyError, ExifToolJSONInvalidError, ExifToolExecuteError, ExifToolTagNameError
 
 # basestring makes no sense in Python 3, so renamed tuple to this const
-TUPLE_STR_BYTES = (bytes, str)
+TUPLE_STR_BYTES: tuple = (str, bytes,)
 
 from typing import Any, Union, Optional, List, Dict
 
@@ -124,7 +124,7 @@ def execute(self, *params: Any, **kwargs) -> Union[str, bytes]:
 		# this was originally to support Path() but it's now generic enough to support any object that str() to something useful
 		#
 		# Thanks @jangop for the single line contribution!
-		str_bytes_params = [x if isinstance(x, TUPLE_STR_BYTES) else str(x) for x in params]
+		str_bytes_params: Union[str, bytes] = [x if isinstance(x, TUPLE_STR_BYTES) else str(x) for x in params]
 		# TODO: this list copy could be expensive if the input is a very huge list.  Perhaps in the future have a flag that takes the lists in verbatim without any processing?
 
 
@@ -549,7 +549,7 @@ def _check_tag_list(tags: List) -> None:
 		# we can check self.version ... then this method will no longer
 		# be static and requires the underlying exiftool process to be running to get the self.version
 		#
-		# This is not done right now because the odds of the tag name format changing is very low, and requirin
+		# This is not done right now because the odds of the tag name format changing is very low, and requiring
 		# exiftool to be running during this tag check could introduce unneccesary overhead at this time
 
 
@@ -560,7 +560,7 @@ def _check_tag_list(tags: List) -> None:
 		# \w in Perl => https://perldoc.perl.org/perlrecharclass#Backslash-sequences
 		# \w in Python => https://docs.python.org/3/library/re.html#regular-expression-syntax
 		#
-		# Perl vs Python's "\w" seem to mean slightly different things, so we write our own regex / matching algo
+		# Perl vs Python's "\w" seem to mean slightly different things, so we write our own regex / matching algorithm
 
 
 		# * make sure the first character is not a special one