Plugin Hooks

Important

It’s not considered a breaking change if additional parameters are passed to these hooks in a future version of Arelle. To ensure your plugin continues to work with future versions of Arelle it’s important to include *args, **kwargs in the function signature so an exception isn’t thrown if a new argument is passed.

It’s recommended to implement plugin hooks by extending the PluginHooks abstract class and overriding the static methods that refer to the hooks you need and assigning them to __pluginInfo__.

from typing import Any

from arelle.utils.PluginHooks import PluginHooks
from arelle.ValidateXbrl import ValidateXbrl


class MyPlugin(PluginHooks):
    @staticmethod
    def validateFinally(val: ValidateXbrl, *args: Any, **kwargs: Any) -> None:
        if "Cash" not in val.modelXbrl.factsByLocalName:
            val.modelXbrl.error(codes="01.01", msg="Cash must be reported.")


__pluginInfo__ = {
    "name": "My Plugin",
    "version": "0.0.1",
    "Validate.Finally": MyPlugin.validateFinally,
}
class 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 of skip-routes or skip-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:

  1. a validation type (matching a validation type from a disclosure system config.

  2. 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 and false 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 or False 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