arelle.utils.PluginHooks
¶
See COPYRIGHT.md for copyright information.
Module Contents¶
Classes¶
These hooks are called at different stages of validation, but all provide a common interface (ValidateXbrl is the first param). |
|
API¶
- class arelle.utils.PluginHooks.ValidationHook(*args, **kwds)¶
Bases:
enum.Enum
These hooks are called at different stages of validation, but all provide a common interface (ValidateXbrl is the first param).
Initialization
- XBRL_START¶
‘Validate.XBRL.Start’
- XBRL_FINALLY¶
‘Validate.XBRL.Finally’
- XBRL_DTS_DOCUMENT¶
‘Validate.XBRL.DTS.document’
- FINALLY¶
‘Validate.Finally’
- class arelle.utils.PluginHooks.PluginHooks¶
Bases:
abc.ABC
- abstract static cntlrCmdLineOptions(parser: optparse.OptionParser, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrCmdLine.Options
This hook is used to add plugin specific options to the command line.
Example:
parser.add_option( "--my-option", dest="myOption", help="My custom option", )
- Parameters:
parser – the parser class to add options to.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrCmdLineUtilityRun(cntlr: arelle.Cntlr.Cntlr, options: arelle.RuntimeOptions.RuntimeOptions, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrCmdLine.Utility.Run
This hook is triggered after command line options have been parsed. It can be used to handle values for parameters configured in
cntlrCmdLineOptions
.Example:
if options.myOption: myOptionEnabled = True
- Parameters:
cntlr – The Cntlr being initialized.
options – Parsed options object.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrInit(cntlr: arelle.Cntlr.Cntlr, *args: Any, **kwargs: Any) None ¶
Plugin hook:
Cntlr.Init
This hook is called while the Cntlr is being initialized and after logging has been setup.
- Parameters:
cntlr – The Cntlr being initialized.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrWebMainStartWebServer(app: arelle.webserver.bottle.Bottle, cntlr: arelle.CntlrCmdLine.CntlrCmdLine, host: str, port: str, server: str, *args: Any, **kwargs: Any) str | None ¶
Plugin hook:
CntlrWebMain.StartWebServer
This hook is for adding routes to the webserver.
Only routes from a single plugin will be applied.
Example:
app.route('/rest/my-test', "GET", my_test) app.route('/rest/my-run/<file:path>', ("GET", "POST"), my_run)
- Parameters:
app – The Bottle server.
cntlr – The controller for the server.
host – The webserver host.
port – The webserver port.
server – The webserver path.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
, a string ofskip-routes
orskip-run
. Example:# Block default Arelle routes. return "skip-routes" # Block default webserver startup. return "skip-run" # Block default Arelle routes and webserver startup. return "skip-routes|skip-run" # Normal routes will be combined with plugin routes and app started. return None
- abstract static cntlrWinMainMenuHelp(cntlr: arelle.CntlrWinMain.CntlrWinMain, menu: tkinter.Menu, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrWinMain.Menu.Help
Hook for adding items to the Arelle GUI help menu.
Example:
menu.add_command(label="Plugin documentation URL", command=self.openHelpDocumentation)
- Parameters:
cntlr – The CntlrWinMain instance that the request is coming from.
menu – The tkinter help menu to extend.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrWinMainMenuTools(cntlr: arelle.CntlrWinMain.CntlrWinMain, menu: tkinter.Menu, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrWinMain.Menu.Tools
Hook for adding items to the Arelle GUI tools menu.
Example:
menu.add_command(label="Plugin Option", command=self.doSomething)
- Parameters:
cntlr – The CntlrWinMain instance that the request is coming from.
menu – The tkinter tools menu to extend.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrWinMainMenuValidation(cntlr: arelle.CntlrWinMain.CntlrWinMain, menu: tkinter.Menu, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrWinMain.Menu.Validation
Hook for adding items to the Arelle GUI validation menu.
Example:
menu.add_command(label="Plugin validation option", command=self.validationOptions)
- Parameters:
cntlr – The CntlrWinMain instance that the request is coming from.
menu – The tkinter validation menu to extend.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static cntlrWinMainMenuView(cntlr: arelle.CntlrWinMain.CntlrWinMain, menu: tkinter.Menu, *args: Any, **kwargs: Any) None ¶
Plugin hook:
CntlrWinMain.Menu.View
Hook for adding items to the Arelle GUI view menu.
Example:
menu.add_command(label="My Plugin Option", command=self.doSomething)
- Parameters:
cntlr – The CntlrWinMain instance that the request is coming from.
menu – The tkinter view menu to extend.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static disclosureSystemConfigURL(disclosureSystem: arelle.DisclosureSystem.DisclosureSystem, *args: Any, **kwargs: Any) str ¶
Plugin hook:
DisclosureSystem.ConfigURL
For validation plugins this provides a path to the disclosure system config file. See arelle/config/disclosuresystems.xml for examples.
- Parameters:
disclosureSystem – The DisclosureSystem instance that the config will be applied to.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
A relative path to a disclosure system XML config file. Example:
return str(Path(__file__).parent / "resources" / "config.xml")
- abstract static disclosureSystemTypes(disclosureSystem: arelle.DisclosureSystem.DisclosureSystem, *args: Any, **kwargs: Any) tuple[tuple[str, str], ...] ¶
Plugin hook:
DisclosureSystem.Types
For validation plugins this should return a tuple of tuples containing:
a validation type (matching a validation type from a disclosure system config.
a test type property that’s applied to the DisclosureSystem. It will be set to
True
if the disclosure system for the validation type above is selected andfalse
otherwise.
- Parameters:
disclosureSystem – The DisclosureSystem instance that the types will be applied to.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
A tuple of two item tuples containing a validation type and test property. Example:
return (("ESEF", "ESEFplugin"),)
- abstract static fileSourceExists(cntlr: arelle.Cntlr.Cntlr, filepath: str, *args: Any, **kwargs: Any) bool | None ¶
Plugin hook:
FileSource.Exists
This hook can be used to override FileSource existence checks. For instance for a plugin that encrypts files, creating a copy with a different file extension, and the filepath should be transformed accordingly.
- Parameters:
cntlr – The controller the current request is running from.
filepath – The path which Arelle is checking for the existence of a file.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None or boolean value indicating if the file exists. Example:
# Defer to other plugins and/or default behavior. return None # Indicate file exists. return True # Indicate file does not exist. return False
- abstract static fileSourceFile(cntlr: arelle.Cntlr.Cntlr, filepath: str, binary: bool, stripDeclaration: bool, *args: Any, **kwargs: Any) tuple[io.BytesIO | None] | tuple[io.TextIOWrapper, str] ¶
Plugin hook:
FileSource.File
fileResult = pluginMethod(self.cntlr, filepath, binary, stripDeclaration)
This hook can be used to override FileSource file open operations.
- Parameters:
cntlr – The controller the current request is running from.
filepath – The path of the file to open.
binary – Indicates if the file should be opened as binary.
stripDeclaration – Indicates if XML declaration should be stripped.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
tuple of text IO and encoding, or binary io and None Example:
# Binary IO return (io.BytesIO(b),) # Text IO return return (io.TextIOWrapper(io.BytesIO(b), encoding="utf-8"), "utf-8")
- abstract static modelDocumentIsPullLoadable(modelXbrl: arelle.ModelXbrl.ModelXbrl, mappedUri: str, normalizedUri: str, filepath: str, isEntry: bool, namespace: str, *args: Any, **kwargs: Any) bool ¶
Plugin hook:
ModelDocument.IsPullLoadable
Plugin hook to signal files which can be opened by the plugin that otherwise would not be supported by Arelle. For instance a plugin that enables opening and loading data from json files.
- Parameters:
modelXbrl – The ModelXbrl being constructed.
mappedUri – The path of the document. May be the same as the
normalizedUri
or a path to a file in a taxonomy package.normalizedUri – The normalized path of the document. This can be a URL or local file system path.
filepath – The path of the document. May be the same as the
normalizedUri
or a path to a file in the local cache.isEntry – Boolean value indicating if the document is an entrypoint.
namespace – The target namespace if the document has one.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
True
if the plugin can load the file orFalse
if not. Example:return Path(filepath).suffix == ".json"
- abstract static modelDocumentPullLoader(modelXbrl: arelle.ModelXbrl.ModelXbrl, normalizedUri: str, filepath: str, isEntry: bool, namespace: str | None, *args: Any, **kwargs: Any) arelle.ModelDocument.ModelDocument | arelle.ModelDocument.LoadingException | None ¶
Plugin hook:
ModelDocument.PullLoader
This plugin hook can be used to override ModelDocument construction.
For instance for a plugin that enables opening and loading data from Excel files.
This hook can also be used to log an initial error and/or return a LoadingException if the XBRL report doesn’t match a naming requirement.
- Parameters:
modelXbrl – The ModelXbrl being constructed.
normalizedUri – The normalized path of the document. This can be a URL or local file system path.
filepath – The path of the document. May be the same as the
normalizedUri
or a path to a file in the local cache.isEntry – Boolean value indicating if the document is an entrypoint.
namespace – The target namespace if the document has one.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
A ModelDocument, a [LoadingException](#arelle.ModelDocument.LoadingException], or
None
. Example:# Defer to other plugins and/or default behavior. return None # Override ModelDocument construction from plugin. return ModelDocument(...) # Signal that document can't be constructed. return LoadingException("Invalid document")
- abstract static modelManagerLoad(manager: arelle.ModelManager.ModelManager, fileSource: arelle.FileSource.FileSource, *args: Any, **kwargs: Any) arelle.ModelXbrl.ModelXbrl | None ¶
Plugin hook:
ModelManager.Load
Hook to override default ModelXbrl loading. Return
None
to defer to other plugins of default loading.- Parameters:
manager – The ModelManager the request is coming from.
fileSource – The FileSource to load.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
Either a ModelXbrl instance or
None
to defer to default loading.
- abstract static modelXbrlInit(modelXbrl: arelle.ModelXbrl.ModelXbrl, *args: Any, **kwargs: Any) None ¶
Plugin hook:
ModelXbrl.Init
This plugin hook is called as the last step of the ModelXbrl constructor which is prior to ModelDocument loading.
- Parameters:
modelXbrl – The XBRL model being constructed.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static modelXbrlLoadComplete(modelXbrl: arelle.ModelXbrl.ModelXbrl, *args: Any, **kwargs: Any) None ¶
Plugin hook:
ModelXbrl.LoadComplete
This plugin hook is called after the ModelXbrl and ModelDocument loading is complete.
- Parameters:
modelXbrl – The constructed ModelXbrl.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateFinally(val: arelle.ValidateXbrl.ValidateXbrl, *args: Any, **kwargs: Any) None ¶
Plugin hook:
Validate.Finally
This plugin hook is called after formula processing and other XBRL validation. This hook is useful for logging errors or warnings based on other errors or warnings that were triggered.
Example:
if "XYZ.01.01" in val.modelXbrl.errors and "XYZ.21.02" not in val.modelXbrl.errors: modelXbrl.error("XYZ.52.04", "Incompatible data reported.")
- Parameters:
val – The ValidateXBRL instance.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateFormulaCompiled(modelXbrl: arelle.ModelXbrl.ModelXbrl, xpathContext: arelle.formula.XPathContext.XPathContext, *args: Any, **kwargs: Any) None ¶
Plugin hook:
ValidateFormula.Compiled
Hook executed after formula rules are compiled, but before they’re executed.
- Parameters:
modelXbrl – The ModelXbrl.
xpathContext – The formula evaluation XPathContext.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateFormulaFinished(val: arelle.ValidateXbrl.ValidateXbrl, *args: Any, **kwargs: Any) None ¶
Plugin hook:
ValidateFormula.Finished
Hook executed after formula evaluation.
- Parameters:
val – The ValidateXBRL instance.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateXbrlDtsDocument(val: arelle.ValidateXbrl.ValidateXbrl, modelDocument: arelle.ModelDocument.ModelDocument, isFilingDocument: bool, *args: Any, **kwargs: Any) None ¶
Plugin hook:
Validate.XBRL.DTS.document
Validation hook for implementing DTS validation rules. Useful for implementing validation rules related to extension taxonomies.
Example:
if ( modelDocument.type == ModelDocument.Type.SCHEMA and modelDocument.targetNamespace is not None and len(modelDocument.targetNamespace) > 100 ): val.modelXbrl.error( codes="XYZ.1.9.13", msg="TargetNamespace is too long.", )
- Parameters:
val – The ValidateXBRL instance.
modelDocument – The ModelDocument to validate.
isFilingDocument – Indicates if document is part of filing or external reference.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateXbrlFinally(val: arelle.ValidateXbrl.ValidateXbrl, *args: Any, **kwargs: Any) None ¶
Plugin hook:
Validate.XBRL.Finally
Hook for executing validation rules after other XBRL validations, but prior to formula processing.
Example:
if "Cash" not in val.modelXbrl.factsByLocalName: val.modelXbrl.error(codes="01.01", msg="Cash must be reported.") if "Assets" not in val.modelXbrl.factsByLocalName: val.modelXbrl.warning(codes=("01.02", "13.04"), msg="Assets should be reported.")
- Parameters:
val – The ValidateXBRL instance.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static validateXbrlStart(val: arelle.ValidateXbrl.ValidateXbrl, parameters: dict[Any, Any], *args: Any, **kwargs: Any) None ¶
Plugin hook:
Validate.XBRL.Start
Hook for executing validation rules prior to other XBRL validations.
Example:
if "Cash" not in val.modelXbrl.factsByLocalName: val.modelXbrl.error(codes="01.01", msg="Cash must be reported.") if "Assets" not in val.modelXbrl.factsByLocalName: val.modelXbrl.warning(codes=("01.02", "13.04"), msg="Assets should be reported.")
- Parameters:
val – The ValidateXBRL instance.
parameters – dictionary of validation parameters.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None
- abstract static modelTestcaseVariationReportPackageIxdsOptions(val: arelle.ValidateXbrl.ValidateXbrl, rptPkgIxdsOptions: dict[str, bool], *args: Any, **kwargs: Any) None ¶
Plugin hook:
ModelTestcaseVariation.ReportPackageIxdsOptions
Hook for other plugins to specify IXDS testcase variation options which will be passed to the inlineXbrlDocumentSet plugin.
Example:
rptPkgIxdsOptions["lookOutsideReportsDirectory"] = True rptPkgIxdsOptions["combineIntoSingleIxds"] = True
- Parameters:
val – The ValidateXBRL instance.
rptPkgIxdsOptions – the dict to set IXDS options on.
args – Argument capture to ensure new parameters don’t break plugin hook.
kwargs – Argument capture to ensure new named parameters don’t break plugin hook.
- Returns:
None