Snippets & Templates (python/PwSh/bash)

bash.sh

#!/usr/bin/env bash

# Best practices Bash script template with useful functions
#   github.com/ralish/bash-script-template/blob/main/template.sh

#region INIT
if [[ ${DEBUG-} =~ ^1|yes|true$ ]]; then set -o xtrace; fi # Trace script execution if DEBUG

if ! (return 0 2> /dev/null); then
  set -o errexit             # Exit on Errors
  set -o nounset             # Disallow Unset Variables
  set -o pipefail            # Use last non-zero exit code in a pipeline
fi # Alternative Shell behaviours if not sourced

set -o errtrace              # Ensure the error trap handler is inherited
function script_trap_err() { # Handler for unexpected errors
  local exit_code=1
  trap - ERR                 # Disable trap handler to prevent recursion
  set +o errexit             # Consider further errors non-fatal
  set +o pipefail            #   to ensure script completion

  if [[ ${1-} =~ ^[0-9]+$ ]]; then exit_code="$1"; fi # Check exit code
  if [[ -n ${cron-} ]]; then                          # Print dbg data if in Cron mode
    if [[ -n ${script_output-} ]]; then exec 1>&3 2>&4; fi
    printf '%b\n' "$ta_none"                          # Print basic dbg info
    printf '***** Abnormal termination of script *****\n'
    printf 'Script Path:            %s\n' "$script_path"
    printf 'Script Parameters:      %s\n' "$script_params"
    printf 'Script Exit Code:       %s\n' "$exit_code"
    if [[ -n ${script_output-} ]]; then printf 'Script Output:\n\n%s' "$(cat "$script_output")"
    else printf 'Script Output:          None (failed before log init)\n'; fi
  fi                                                  # Print script log
  exit "$exit_code"                                   # Exit with failure status
} # script_trap_err

function script_trap_exit() { # Handler for exiting the script
  cd "$orig_cwd"
  if [[ -n ${cron-} && -f ${script_output-} ]]; then rm "$script_output"; fi # Remove Cron mode script log
  if [[ -d ${script_lock-} ]]; then rmdir "$script_lock"; fi                 # Remove script execution lock
  printf '%b' "$ta_none" # Restore colours
} # script_trap_exit


# "Minimal" safe bash script
# https://gist.github.com/m-radzikowski/53e0b39e9a59a1518990e76c2bff8038

set -Eeuo pipefail
trap cleanup SIGINT SIGTERM ERR EXIT

script_dir=$(cd "$(dirname "${BASH_SOURCE[0]}")" &>/dev/null && pwd -P)

usage() {
  cat <<EOF
Usage: $(basename "${BASH_SOURCE[0]}") [-h] [-v] [-f] -p param_value arg1 [arg2...]
  Script_Description.
Options:
  -h, --help      Print this help and exit
  -v, --verbose   Print script debug info
  -f, --flag      Some flag description
  -p, --param     Some param description
EOF
  exit
}

cleanup() { trap - SIGINT SIGTERM ERR EXIT ;; } # script cleanup here

setup_colors() {
  if [[ -t 2 ]] && [[ -z "${NO_COLOR-}" ]] && [[ "${TERM-}" != "dumb" ]]; then
    NOFORMAT='\033[0m' RED='\033[0;31m' GREEN='\033[0;32m' ORANGE='\033[0;33m' BLUE='\033[0;34m' PURPLE='\033[0;35m' CYAN='\033[0;36m' YELLOW='\033[1;33m'
  else NOFORMAT='' RED='' GREEN='' ORANGE='' BLUE='' PURPLE='' CYAN='' YELLOW=''; fi
}

msg() { echo >&2 -e "${1-}"; }

die() {
  local msg=$1; local code=${2-1} # default exit status 1
  msg "$msg"; exit "$code"
}

parse_params() {
  flag=0; param=''; # default values of variables set from params

  while :; do
    case "${1-}" in
    -h | --help) usage ;;
    -v | --verbose) set -x ;;
    --no-color) NO_COLOR=1 ;;
    -f | --flag) flag=1 ;; # example flag
    -p | --param) # example named parameter
      param="${2-}"
      shift
      ;;
    -?*) die "Unknown option: $1" ;;
    *) break ;;
    esac
    shift
  done

  args=("$@")

  [[ -z "${param-}" ]] && die "Missing required parameter: param"
  [[ ${#args[@]} -eq 0 ]] && die "Missing script arguments"
  return 0
}

parse_params "$@"; setup_colors

# script logic here

msg "${RED}Read parameters:${NOFORMAT}"
msg "- flag: ${flag}"
msg "- param: ${param}"
msg "- arguments: ${args[*]-}"

pip-upgrade-outdated.sh

# Upgrade all outdated pip packages as a one-liner
pip list --outdated | tail -n +3 | cut -d' ' -f1 | xargs -n1 pip install --upgrade

# ... or when using pip.conf
export PIP_CONFIG_FILE=".vscode/pip.conf"
pip list --outdated | tail -n +3 | cut -d' ' -f1 | xargs -n1 pip install

pip.conf

#!/usr/bin/env python -m pip
#
# https://pip.pypa.io/en/stable/topics/configuration/
#
# Environment Variable: PIP_CONFIG_FILE
#   Usage: export PIP_CONFIG_FILE=".vscode/pip.conf"
#

[install]
# Upgrade packages to the newest version
upgrade = true

# Fail After: 1 second
timeout = 5

# Fail After: 1 Error
retries = 1

# Don't output anything except errors
quiet = 3

# Don't ask for user input
no-input = true

# Don't output colors to avoid parsing errors
no-color = true

# Don't check python version
no-python-version-warning = true

# Don't check pip version
disable-pip-version-check = true

pyton_script_template.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# -*-python-*- vim:ft=py:

# /// script
# ///
#region init
#   Disable black formatter
# fmt: off
#   Disable pylint error message for line-too-long
# pylint: disable=line-too-long

""" One-line Short Description.

  A longer description that spans multiple lines: Explain the purpose.
  This DocString is shown on import: Write reasonably useful and informative!
  more text...

  Args:
    var_name(var_type): description. Default: 'var_name value'
    ...

  Returns:
    A python object containing something.
"""


__version__    = "0.6.9"
__date__       = "2024-06-09"
__status__     = "Development"
__license__    = "MIT"
__credits__    = "© iown-homecontrol"
__copyright__  = "© iown-homecontrol"
__author__     = "Velocet"
__maintainer__ = "Velocet"
__email__      = "[email protected]"


import argparse # Argument Parser
import pathlib  # file and path handling
import sys      # Python Version and standard system functionality (stdin/stdout)
# import pprint                                   # Pretty printer for data
# pprint = pprint.PrettyPrinter(width=256).pprint # Pretty printer configuration
# print = pprint                                  # redefine pprint as print

is_even = lambda number: number % 2 == 0

print(f"{__debug__ = }")
if __debug__:
  def assert_python3():
    """ Assert Python >= 3.11 is used. """
    assert(sys.version_info.major == 3)
    assert(sys.version_info.minor >= 11)
else:
  if sys.version_info.minor < 11: raise Exception("Python >= 3.11 is required!")

""" Global Variables """
verbose:bool = False       # Verbose Output
#endregion init

def main(args: Any) -> None:
  """ Main Entry Point """

# def main(*args: Any, **kwargs: Any) -> None:
#     kwargs["arg_name"] = arg_value
#     super().main(*args, **kwargs)

  global verbose
  if (args.verbose): verbose = True
  # verbose = (False, True)[args.verbose] # type: ignore

  if not args and not sys.argv[1:]:
    # exit if no arguments are given
    print('[ERROR] No args/argv given!')
    sys.exit(1)
#
#   if args or sys.argv[1:]:
#     if args.verbose:
#       print('[args] Found!')
#     if sys.argv[1:]:
#       args = sys.argv[1:] # strip file name
#     else:
#       verbose:bool = (False, True)[args.verbose] # type: ignore
#
#     argc = vars(args) # convert to dict. access via argc['arg_name']

  # Create list with 8 elements, all containing 0.
  # data:list = [0] * 8 # Always initialize your variables with a value!
  # do_something(data)


# def do_something(data:list = None) -> None:
#   """ It does something! """
#   print("Do something with this: ", data)


# # simple print error function
# # TODO create verbose function
# def prettyprinterror(*args, **kwargs):
#
#   # Version 1: print to stderr using print()
#   print(*args, file=sys.stderr, **kwargs)
#
#   # Version 2: print to stderr using sys.stderr.write()
#   sys.stderr.write('Error Message!\n')
#
#   # Version 3: print to stderr using logging
#   #   https://docs.python.org/3/library/logging.html
#   import logging
#   logging.basicConfig(format='%(message)s')
#   log = logging.getLogger(__name__)
#   log.warning('Error Message!')


if __name__ == "__main__":
  """ Executed when run from CLI or the module is not initialized from an import statement """

  #region Arguments
  #
  # Parser Configuration
  parser = argparse.ArgumentParser(
    # Program Name (default: os.path.basename(sys.argv[0]))
    prog="Program-Name",
    # Usage description (default: generated from args)
    usage="%(prog)s --input [FILE] --output [FILE(optional)]",
    # Text before argument help (default: None)
    description="%(prog)s description text before argument help.",
    # Text after the argument help (default: None)
    epilog="Alex: It's funny how the colors of the real world only seem really real when you viddy them on the screen...",
  )
  #
  # Parser Definition
  #
  #   NOTE: If FileType is used and a subsequent argument fails the file is not closed!
  #         Better wait after the parser has run and then use the with-statement to manage the files.
  #   dest:    Specify the attribute name used in the result namespace
  #   metavar: Alternate display name for the argument as shown in help
  #   type:    Automatically convert an argument to the given type
  #
  # test if input exists: "type=pathlib.Path.is_file()"
  parser.add_argument("-i", "--input", metavar="FILE", dest="infile", type=str, required=True, help="Input File Description")
  parser.add_argument("-o", "--output", metavar="FILE", dest="outfile", type=str, required=False, help="Output File Description")
  # test if dir exists: "pathlib.Path.is_dir()"
  parser.add_argument("-p", "--path", metavar="PATH", dest="outdir", type=str, required=False, default="./output", help="Output Directory (default: %(default)s)")
  # Optional: Verbosity
  parser.add_argument("-V", "--verbose", action="store_true", dest="verbose", default=False, help="Verbose Output")
  # Optional: Version output
  parser.add_argument("-v","--version", action="version", version="%(prog)s v{version}".format(version=__version__))

  # Parse Arguments
  args = parser.parse_args()
  # args = parser.parse_args(['--arg1', 'arg1_value', '--arg2']) # Test arguments with predefined values
  #endregion Arguments

  # terminate with defined status and message
  #   if (args.argument):
  #     parser.exit(status=0, message="Write Message and exit")

  # if (args.some_argument):
  #   print(some_argument)

  if (not pathlib.Path(args.infile).is_file()):
    parser.error("--input must be a file!") # print message and exit with status = 2

  # Use this if you have multiple input values
  #   input_items = itertools.chain.from_iterable(map(glob.iglob, args.input))
  #   input_files = filter(os.path.isfile, input_items)

  main(args) # https://docs.python.org/3/library/__main__.html

  # Re-Activate black
  # fmt: on

Update-PipPackages.ps1

function Update-PythonPipPackages {
<#
.SYNOPSIS
  Update/Upgrade all outdated pip packages.


.DESCRIPTION
  Upgrade every outdated pip package and take care of error handling.
  
  This version uses the JSON output of the pip command and uses the native ConvertFrom-JSON
  command to get rid of those obscure methods trying to manipulate strings.
  
  Includes Verbose Output (use -verbose switch).
  

.ONELINER: ConvertFrom-Json -InputObject (pip list --outdated --format json) | % {py -m pip install --upgrade $_.name}
.ONELINER: ConvertFrom-Json (pip list -o --format json) | % {pip install -U $_.name}


.LINK
  https://pip.pypa.io/en/stable/user_guide/#command-completion
    python -m pip completion --powershell | Out-File -Encoding default -Append $PROFILE


.NOTES
  Author:  Velocet
  Website: github.com/velocet
#>

  [CmdletBinding()]

  BEGIN {
    #region PipEnviromentVars
    #   https://pip.pypa.io/en/stable/topics/configuration/#environment-variables
    Write-Verbose -Message '[PIP] Set pip env vars.'

    $env:PIP_CONFIG_FILE               = 'pip.conf'

    $env:PIP_DISABLE_PIP_VERSION_CHECK = $true # Don't check pip version
    $env:PIP_NO_PYTHON_VERSION_WARNING = $true # Don't check python version
    $env:PIP_NO_INPUT                  = $true # Don't ask for user input
    $env:PIP_NO_COLOR                  = $true # Don't output colors to avoid parsing errors
    $env:PIP_QUIET                     = 3     # Don't output anything except errors
    $env:PIP_RETRIES                   = 1     # Fail after 1 error
    $env:PIP_TIMEOUT                   = 1     # Fail after 1 second

    Write-Verbose -Message "[PIP] Use py on Windows as it takes care of versions, etc."
    $PyRun = $IsWindows ? 'py' : 'python'
    $PipRun = $("$PyRun -m pip")
    #endregion PipEnviromentVars

    #region PipEnsurePip
    Write-Verbose -Message "[PIP][VERSION] Check correct install."
    $PythonVersion = Invoke-Expression -Command $("$PyRun --version")  # Display python version
    $PipVersion = Invoke-Expression -Command $("$PipRun --version") # Display pip version
    Write-Verbose -Message "[PIP][VERSION] $PipVersion ($PythonVersion)."
    if ($LastExitCode) {                              # Check if pip version failed...
      # https://docs.python.org/3/library/ensurepip.html
      Write-Verbose -Message "[PIP] Bootstrap."
      Invoke-Expression -Command $("$PyRun -m ensurepip --upgrade --default-pip")
    }

    Write-Verbose -Message "[PIP][UPGRADE] pip, setuptools, wheel."
    Invoke-Expression -Command $("$PipRun install --upgrade pip setuptools wheel")
    #endregion PipEnsurePip

  } PROCESS {
    Write-Verbose -Message "[PIP][LIST][OUTDATED] Get..."
    $outdated = ConvertFrom-Json -InputObject (py -m pip list --outdated --format json) | % {py -m pip install --upgrade $_.name}
    $Packages = Invoke-Expression -Command $("$PipRun list --outdated --format json")

    if ($LastExitCode) { Write-Error -Message '[PIP][LIST][OUTDATED] Error!'; exit 1 }
    else {
      # Parse JSON list of outdated packages as PwSh object
      $Packages = ConvertFrom-Json -InputObject $Packages

      if ($Packages.Count) {
        Write-Verbose -Message "[PIP][OUTDATED] Number of packages: ($Packages.Count)"

        foreach ($Package in $Packages) {
          # Try to run the upgrade command on the package
          Invoke-Expression -Command $("$PipRun install --upgrade ($Package.Name)")

          if ($LastExitCode) {
            Write-Error -Message "[PIP][UPGRADE] Failed! ($Package.Name)"
          } else {
            Write-Verbose -Message "[PIP][UPGRADE] Success! ($Package.Name)"
          } # $LastExitCode
        } # foreach $Package 
      } else { Write-Verbose -Message "[PIP][UPGRADE] Nothing to do." }
    }
  } END {
    Write-Verbose -Message "[PIP] Unset env vars ..."

    $env:PIP_CONFIG_FILE               = ''
    $env:PIP_DISABLE_PIP_VERSION_CHECK = ''
    $env:PIP_NO_PYTHON_VERSION_WARNING = ''
    $env:PIP_NO_INPUT                  = ''
    $env:PIP_NO_COLOR                  = ''
    $env:PIP_QUIET                     = ''
    $env:PIP_RETRIES                   = ''
    $env:PIP_TIMEOUT                   = ''
  }
}