forked from Github/Axter-Stash
127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# 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.
|
|
``` python
|
|
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.
|
|
``` python
|
|
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.
|
|
``` python
|
|
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`
|