Axter-Stash/StashPluginHelper/README.md

StashPluginHelper: Ver 0.1.0 (By David Maisonave)

StashPluginHelper is a class that performs common implementation used in most plugins.

Features

• Log Features:
  • Optionally log out to multiple outputs for each Log or Trace call.
  • Logging includes source code line number.
  • Sets a maximum plugin log file size.
• Stash Interface Features:
  • Sets STASH_INTERFACE with StashInterface
  • Gets STASH_URL value from command line argument and/or from STDIN_READ
  • Sets FRAGMENT_SERVER based on command line arguments or STDIN_READ
  • Sets PLUGIN_ID based on the main script file name (in lower case)
  • Gets PLUGIN_TASK_NAME value
  • Sets pluginSettings (The plugin UI settings)
• Misc Features:
  • Gets DRY_RUN value from command line argument and/or from UI and/or from config file.
  • Gets DEBUG_TRACING value from command line argument and/or from UI and/or from config file.
  • Sets RUNNING_IN_COMMAND_LINE_MODE to True if detects multiple arguments
  • Sets CALLED_AS_STASH_PLUGIN to True if it's able to read from STDIN_READ

StashPluginHelper Usage

Example #1

• All the arguments for StashPluginHelper class are optional.
  • StashPluginHelper can be called with no arguments if the plugin has NO UI settings and NO associated (*_config.py) file.

from StashPluginHelper import StashPluginHelper
plugin = StashPluginHelper()

# Trace command which logs out only when DEBUG_TRACING is enabled, and by default only logs to plugin log file.
plugin.Trace()

Example #2

• This is an example for a plugin that has UI settings and settings from MyPlugin_config.py file.

from StashPluginHelper import StashPluginHelper
from MyPlugin_config import config
settings = {
    "enableFooFoo": False,
    "zzdebugTracing": False,
    "zzdryRun": False,
}

plugin = StashPluginHelper(settings=settings, config=config)

fooFoo = plugin.pluginSettings["enableFooFoo"]  # Gets plugin UI setting named enableFooFoo
TIMEOUT = plugin.pluginConfig['timeOut'] # Gets setting from MyPlugin_config.py

 # By default, logging level is INFO, and output goes to the console and plugin log file.
plugin.Log(f"Value for TIMEOUT = {TIMEOUT}")

# Trace logs out only when DEBUG_TRACING is enabled.
plugin.Trace(f"plugin.PLUGIN_TASK_NAME = {plugin.PLUGIN_TASK_NAME}")

Example #3

• An example for a plugin that can also run in command line mode. It parses command line argument using argparse before calling StashPluginHelper. This allows it to pass in the stash-url and/or trace option to StashPluginHelper constructor.

from StashPluginHelper import StashPluginHelper
from MyPlugin_config import config
import argparse
parser = argparse.ArgumentParser()
parser.add_argument('--url', '-u', dest='stash_url', type=str, help='Add Stash URL')
parser.add_argument('--trace', '-t', dest='trace', action='store_true', help='Enables debug trace mode.')
parse_args = parser.parse_args()

plugin = StashPluginHelper(
        stash_url=parse_args.stash_url,
        debugTracing=parse_args.trace,
        config=config)

plugin.Log(f"plugin.DEBUG_TRACING = {plugin.DEBUG_TRACING}")

plugin.Log(f"Value for RUNNING_IN_COMMAND_LINE_MODE = {plugin.RUNNING_IN_COMMAND_LINE_MODE}")

plugin.Log(f"Value for CALLED_AS_STASH_PLUGIN = {plugin.CALLED_AS_STASH_PLUGIN}")

if not plugin.RUNNING_IN_COMMAND_LINE_MODE and not plugin.CALLED_AS_STASH_PLUGIN:
    # By default, errors go out to both plugin log file and std-err.
    #     In plugin mode, std-err get sent to stash log file.
    #     In command line mode, std-err goes out to console.
    plugin.Error("This should never happen.")

StashPluginHelper arguments

• debugTracing
  • Default: False
  • Set to true to enable debug tracing, and to open the plugin log file with logging level logging.DEBUG.
  • When debugTracing is false, the Trace logging does not output any logging unless argument (logAlways=True) is pass to Trace.
• logFormat
  • Plugin log line format. Default = "[%(asctime)s] %(message)s"
• dateFmt
  • Date format when logging to plugin log file. Default = "%y%m%d %H:%M:%S"
• maxbytes
  • Maximum size of plugin log file. Default = 1MB
• backupcount
  • Backup counts when log file size reaches max size
• logToWrnSet
  • Customize the target output set which will get warning logging
• logToErrSet
  • Customize the target output set which will get error logging
• logToNormSet
  • Customize the target output set which will get normal logging
• logFilePath
  • Plugin log file. If empty, the log file name will be set based on current python file name and path
• mainScriptName
  • The main plugin script file name (full path)
• pluginID
  • Plugin ID
• settings
  • Default settings for the plugin UI fields
• config
  • From pluginName_config.py or pluginName_setting.py
• fragmentServer
  • Fragment server data.
• stash_url
  • Stash URL (endpoint URL) Example: http://localhost:9999
• DebugTraceFieldName
  • Field name (in settings or config) for DebugTrace. Default = "zzdebugTracing"
• DryRunFieldName
  • Field name (in settings or config) for DryRun. Default = "zzdryRun"

Requirements

pip install stashapp-tools --upgrade