-
Section 1 - Essential Scripts¶
+
+
-
-Chapter 1 - Essential Scripts¶
-
Section 1.1 - Argparse Example¶
+
+
Section 1.1 - Argparse Example¶
Example for setting up arguments for your command line utility.
Example Usage:
@@ -225,29 +225,35 @@ module has many more features documented at # description and epilog. The `formatter_class` instructs # argparse to show default values set for parameters. parser = argparse.ArgumentParser( - description='Sample Argparse', + description="Sample Argparse", formatter_class=argparse.ArgumentDefaultsHelpFormatter, - epilog=f"Built by {__author__}, v.{__date__}" + epilog=f"Built by {__author__}, v.{__date__}", ) # The simplest form of adding an argument, the name of the # parameter and a description of its form. - parser.add_argument('INPUT_FILE', help="Input file to parse") - parser.add_argument('OUTPUT_FOLDER', - help="Folder to store output") + parser.add_argument("INPUT_FILE", help="Input file to parse") + parser.add_argument("OUTPUT_FOLDER", help="Folder to store output") # An optional argument with multiple methods of specifying # the parameter. Includes a default value - parser.add_argument('-l', '--log', help="Path to log file", - default=os.path.abspath(os.path.join( - PurePath(__file__).parent, - PurePath(__file__).name.rsplit('.', 1)[0] + '.log')) + parser.add_argument( + "-l", + "--log", + help="Path to log file", + default=os.path.abspath( + os.path.join( + PurePath(__file__).parent, + PurePath(__file__).name.rsplit(".", 1)[0] + ".log", + ) + ), ) # An optional argument which does not accept a value, instead # just modifies functionality. - parser.add_argument('-v', '--verbose', action='store_true', - help='Include debug log messages') + parser.add_argument( + "-v", "--verbose", action="store_true", help="Include debug log messages" + ) # Once we've specified our arguments we can parse them for # reference @@ -259,8 +265,8 @@ module has many more features documented at
-
Section 1.2 - Logging Example¶
+
+
-
-Section 1.2 - Logging Example¶
Example for writing logging information to the console and a log file.
Example Usage:
@@ -280,64 +286,82 @@ to write content to STDOUT uninterrupted. Additionally, you can set different logging levels for the two handlers - generally you keep debugging information in the log file while writing more critical messages to the console in STDERR. -def setup_logging():
- """Function to setup logging configuration and test it."""
- # Allow us to modify the `logger` variable within a function
- global logger
+def setup_logging(logging_obj, verbose=False):
+ """Function to setup logging configuration and test it.
- # Set logger object, uses module's name
- logger = logging.getLogger(name=__name__)
+ Args:
+ logging_obj: A logging instance, returned from logging.getLogger().
+ verbose: Whether or not to enable the debug level in STDERR output.
- # Set default logger level to DEBUG. You can change this later
- logger.setLevel(logging.DEBUG)
+ Examples:
+ >>> sample_logger = logging.getLogger(name=__name__)
+ >>> sample_logger = setup_logging(sample_logger)
+ >>> sample_logger.debug("This is a debug message")
+ >>> sample_logger.info("This is an info message")
+ >>> sample_logger.warning("This is a warning message")
+ >>> sample_logger.error("This is a error message")
+ >>> sample_logger.critical("This is a critical message")
+ """
+ logging_obj.setLevel(logging.DEBUG)
- # Logging formatter. Best to keep consistent for most usecases
+ # Logging formatter. Best to keep consistent for most use cases
log_format = logging.Formatter(
- '%(asctime)s %(filename)s %(levelname)s %(module)s '
- '%(funcName)s %(lineno)d %(message)s')
+ "%(asctime)s %(filename)s %(levelname)s %(module)s "
+ "%(funcName)s %(lineno)d %(message)s"
+ )
# Setup STDERR logging, allowing you uninterrupted
# STDOUT redirection
stderr_handle = logging.StreamHandler(stream=sys.stderr)
- stderr_handle.setLevel(logging.INFO)
+ if verbose:
+ stderr_handle.setLevel(logging.DEBUG)
+ else:
+ stderr_handle.setLevel(logging.INFO)
stderr_handle.setFormatter(log_format)
# Setup file logging
- file_handle = logging.FileHandler('sample.log', 'a')
+ file_handle = logging.FileHandler("sample.log", "a")
file_handle.setLevel(logging.DEBUG)
file_handle.setFormatter(log_format)
# Add handles
- logger.addHandler(stderr_handle)
- logger.addHandler(file_handle)
+ logging_obj.addHandler(stderr_handle)
+ logging_obj.addHandler(file_handle)
- # Sample log messages
- logger.debug("This is a debug message")
- logger.info("This is an info message")
- logger.warning("This is a warning message")
- logger.error("This is a error message")
- logger.critical("This is a critical message")
-
- def sample_function():
- """Sample function to demonstrate logging formatting."""
- logger.info("Called from a function")
-
- sample_function()
+ return logging_obj
Docstring References¶
-
-
-
-
setup_logging()¶
+ -
+
setup_logging(logging_obj, verbose=False)¶ Function to setup logging configuration and test it.
+-
+
- Parameters +
-
+
logging_obj – A logging instance, returned from logging.getLogger().
+verbose – Whether or not to enable the debug level in STDERR output.
+
+
Examples
++>>> sample_logger = logging.getLogger(name=__name__) +>>> sample_logger = setup_logging(sample_logger) +>>> sample_logger.debug("This is a debug message") +>>> sample_logger.info("This is an info message") +>>> sample_logger.warning("This is a warning message") +>>> sample_logger.error("This is a error message") +>>> sample_logger.critical("This is a critical message") +
-
@@ -383,8 +406,8 @@ common text file encodings. Feel free to build and share on this.
Section 1.3 - Open Files¶
+
+
Section 1.3 - Open Files¶
Example for reading data from encoded text files.
Demonstrates how to handle setting the proper encoding for UTF-8, UTF-16-LE, and UTF-16-BE with the ability to easily @@ -364,18 +388,17 @@ common text file encodings. Feel free to build and share on this.
input_file (str): Path to file to open """ - test_encoding = open(input_file, 'rb') + test_encoding = open(input_file, "rb") bom = test_encoding.read(2) - file_encoding = 'utf-8' - if bom == b'FEFF': - file_encoding = 'utf-16-le' - elif bom == b'FFFE': - file_encoding = 'utf-16-be' + file_encoding = "utf-8" + if bom == b"FEFF": + file_encoding = "utf-16-le" + elif bom == b"FFFE": + file_encoding = "utf-16-be" - with open(input_file, 'r', encoding=file_encoding) as fopen: - for raw_line in fopen: + with open(input_file, "r", encoding=file_encoding) as open_input_file: + for raw_line in open_input_file: line = raw_line.strip() - print(line)
-
Section 1.4 - CSV Example¶
+
+
@@ -474,25 +503,33 @@ columns to the CSV.
data (list): List of lists to write to file
headers (list): Header row to use. If empty, will use the
first list in the `data` list.
+
+ Examples:
+ >>> fields = ['name', 'quantity', 'location']
+ >>> list_of_lists = [
+ >>> ['apple', 10, 'VT'],
+ >>> ['orange', 5, 'FL']
+ >>> ]
+ >>> write_csv_lists('list_test.csv', list_of_lists, headers=fields)
"""
- with open(outfile, 'w', newline="") as open_file:
+ with open(outfile, "w", newline="") as open_file:
# Write only provided headers, ignore others
- csvfile = csv.writer(open_file)
+ csv_file = csv.writer(open_file)
for count, entry in enumerate(data):
if count == 0 and headers:
# If headers are defined, write them, otherwise
# continue as they will be written anyways
- csvfile.writerow(headers)
- csvfile.writerow(entry)
+ csv_file.writerow(headers)
+ csv_file.writerow(entry)
Section 1.4 - CSV Example¶
Example for writing datasets into CSV files.
Demonstrates source datasets comprised of lists of dictionaries and lists of lists as separate functions. Example data is @@ -424,7 +447,7 @@ multiple dictionaries to a CSV file. You can optionally provide an ordered list of headers to filter what rows to show, or let the function use the keys of the first dictionary in the list to generate the header information. The latter option may produce -a new order each iteration and is not prefered if you can +a new order each iteration and is not preferred if you can determine the headers in advance.
def write_csv_dicts(outfile, data, headers=None):
"""Writes a list of dictionaries to a CSV file.
@@ -434,18 +457,24 @@ determine the headers in advance.
data (list): List of dictionaries to write to file
headers (list): Header row to use. If empty, will use the
first dictionary in the `data` list.
+
+ Example:
+ >>> list_of_dicts = [
+ >>> {'name': 'apple', 'quantity': 10, 'location': 'VT'},
+ >>> {'name': 'orange', 'quantity': 5, 'location': 'FL'}
+ >>> ]
+ >>> write_csv_dicts('dict_test.csv', list_of_dicts)
"""
if not headers:
# Use the first line of data
headers = [str(x) for x in data[0].keys()]
- with open(outfile, 'w', newline="") as open_file:
+ with open(outfile, "w", newline="") as open_file:
# Write only provided headers, ignore others
- csvfile = csv.DictWriter(open_file, headers,
- extrasaction='ignore')
- csvfile.writeheader()
- csvfile.writerows(data)
+ csv_file = csv.DictWriter(open_file, headers, extrasaction="ignore")
+ csv_file.writeheader()
+ csv_file.writerows(data)
Docstring References¶
-
-
-
-
write_csv_dicts(outfile, data, headers=None)¶
+ -
+
write_csv_dicts(outfile, data, headers=None)¶ Writes a list of dictionaries to a CSV file.
- Parameters @@ -504,11 +541,19 @@ first dictionary in the data list.
Example
+>>> list_of_dicts = [
+>>> {'name': 'apple', 'quantity': 10, 'location': 'VT'},
+>>> {'name': 'orange', 'quantity': 5, 'location': 'FL'}
+>>> ]
+>>> write_csv_dicts('dict_test.csv', list_of_dicts)
+-
-
-
-
write_csv_lists(outfile, data, headers=None)¶
+ -
+
write_csv_lists(outfile, data, headers=None)¶ Writes a list of lists to a CSV file.
- Parameters @@ -520,12 +565,21 @@ first list in the data list.
Examples
+>>> fields = ['name', 'quantity', 'location']
+>>> list_of_lists = [
+>>> ['apple', 10, 'VT'],
+>>> ['orange', 5, 'FL']
+>>> ]
+>>> write_csv_lists('list_test.csv', list_of_lists, headers=fields)
+