.. py:module:: arelle.cntlr
   :copyright: See for copyright information.
   :license: Apache-2.
   :synopsis: Common controller class to initialize for platform and setup common logger functions

Module Contents



Initialization sets up for platform




arelle.Cntlr._: arelle.typing.TypeGetText


arelle.Cntlr.osPrcs: Any






arelle.Cntlr.resourcesDir() str
class arelle.Cntlr.Cntlr(hasGui: bool = False, logFileName: str | None = None, logFileMode: str | None = None, logFileEncoding: str | None = None, logFormat: str | None = None, uiLang: str | None = None, disable_persistent_config: bool = False, betaFeatures: dict[str, bool] | None = None)

Initialization sets up for platform

  • Platform directories for application, configuration, locale, and cache

  • Context menu click event (TKinter)

  • Clipboard presence

  • Update URL

  • Reloads prior config user preferences (saved in json file)

  • Sets up proxy and web cache

  • Sets up logging

A controller subclass object is instantiated, CntlrWinMain for the GUI and CntlrCmdLine for command line batch operation. (Other controller modules and/or objects may be subordinate to a CntlrCmdLine, such as CntlrWebMain, and CntlrQuickBooks).

This controller base class initialization sets up specifics such as directory paths, for its environment (Mac, Windows, or Unix), sets up a web file cache, and retrieves a configuration dictionary of prior user choices (such as window arrangement, validation choices, and proxy settings).

The controller sub-classes (such as CntlrWinMain, CntlrCmdLine, and CntlrWebMain) most likely will load an XBRL related object, such as an XBRL instance, taxonomy, testcase file, versioning report, or RSS feed, by requesting the model manager to load and return a reference to its modelXbrl object. The modelXbrl object loads the entry modelDocument object(s), which in turn load documents they discover (for the case of instance, taxonomies, and versioning reports), but defer loading instances for test case and RSS feeds. The model manager may be requested to validate the modelXbrl object, or views may be requested as below. (Validating a testcase or RSS feed will validate the test case variations or RSS feed items, one by one.)

.. attribute:: isMac
True if system is MacOS

.. attribute:: isMSW
True if system is Microsoft Windows

.. attribute:: userAppDir
Full pathname to application directory (for persistent json files, cache, etc).

.. attribute:: configDir
Full pathname to config directory as installed (validation options, redirection URLs, common xsds).

.. attribute:: imagesDir
Full pathname to images directory as installed (images for GUI and web server).

.. attribute:: localeDir
Full pathname to locale directory as installed (for support of gettext localization feature).

.. attribute:: hasClipboard
True if a system platform clipboard is implemented on current platform




betaFeatures: dict[str, bool]


hasWin32gui: bool


hasGui: bool


hasFileSystem: bool


isGAE: bool


isCGI: bool


systemWordSize: int


uiLang: str


configDir: str


imagesDir: str


localeDir: str


pluginDir: str


userAppDir: str


isMac: bool


isMSW: bool


hasClipboard: bool


contextMenuClick: str


hasWebServer: bool


config: dict[str, Any] | None


configJsonFile: str


webCache: arelle.WebCache.WebCache


modelManager: arelle.ModelManager.ModelManager


logger: logging.Logger | None


logHandler: logging.Handler


property uiLangDir: str
property uiLocale: str | None
postLoggingInit(localeSetupMessage: str | None = None) None
setUiLanguage(locale: str | None, fallbackToDefault: bool = False) None
startLogging(logFileName: str | None = None, logFileMode: str | None = None, logFileEncoding: str | None = None, logFormat: str | None = None, logLevel: str | None = None, logHandler: logging.Handler | None = None, logToBuffer: bool = False, logTextMaxLength: int | None = None, logRefObjectProperties: bool = True) None
setLogLevelFilter(logLevelFilter: str) None
setLogCodeFilter(logCodeFilter: str) None
addToLog(message: str, messageCode: str = '', messageArgs: dict[str, Any] | None = None, file: str = '', refs: list[dict[str, Any]] | None = None, level: int | str = logging.INFO) None

Add a simple info message to the default logger

  • message (str) – Text of message to add to log.

  • messageArgs (dict) – optional dict of message format-string key-value pairs

  • messageCode – Message code (e.g., a prefix:id of a standard error)

  • messageCode – str

  • file (str) – File name (and optional line numbers) pertaining to message

showStatus(message: str, clearAfter: int | None = None) None

Dummy method for specialized controller classes to specialize, provides user feedback on status line of GUI or web page

  • message (str) – Message to display on status widget.

  • clearAfter (int) – Time, in ms., after which to clear the message (e.g., 5000 for 5 sec.)

close(saveConfig: bool = False) None

Closes the controller and its logger, optionally saving the user preferences configuration


saveConfig (bool) – save the user preferences configuration

saveConfig() None

Save user preferences configuration (in json configuration file).

viewModelObject(modelXbrl: arelle.ModelXbrl.ModelXbrl, objectId: str) None

Notify any watching views to show and highlight selected object. Generally used to scroll list control to object and highlight it, or if tree control, to find the object and open tree branches as needed for visibility, scroll to and highlight the object.

  • modelXbrl (ModelXbrl) – ModelXbrl (DTS) whose views are to be notified

  • objectId (str) – Selected object id (string format corresponding to ModelObject.objectId() )

reloadViews(modelXbrl: arelle.ModelXbrl.ModelXbrl) None

Notification to reload views (probably due to change within modelXbrl). Dummy for subclasses to specialize when they have a GUI or web page.


modelXbrl (ModelXbrl) – ModelXbrl (DTS) whose views are to be notified

rssWatchUpdateOption(**args: Any) None

Notification to change rssWatch options, as passed in, usually from a modal dialog.

onPackageEnablementChanged() None

Notification that package enablement changed, usually from a modal dialog.

internet_user_password(host: str, realm: str) tuple[str, str]

Request (for an interactive UI or web page) to obtain user ID and password (usually for a proxy or when getting a web page that requires entry of a password). This function must be overridden in a subclass that provides interactive user interface, as the superclass provides only a dummy method.

  • host (str) – The host that is requesting the password

  • realm (str) – The domain on the host that is requesting the password


tuple – (‘myusername’,’mypassword’)

internet_logon(url: str, quotedUrl: str, dialogCaption: str, dialogText: str) str

Web file retrieval results in html that appears to require user logon, if interactive allow the user to log on.


The URL as requested (by an import, include, href, schemaLocation, …)


The processed and retrievable URL


The dialog caption for the situation


The dialog text for the situation at hand


string – ‘retry’ if user logged on and file can be retried, ‘cancel’ to abandon retrieval ‘no’ if the file is expected and valid contents (not a logon request)

clipboardData(text: str | None = None) Any

Places text onto the clipboard (if text is not None), otherwise retrieves and returns text from the clipboard. Only supported for those platforms that have clipboard support in the current python implementation (macOS or ActiveState Windows Python).


text (str) – Text to place onto clipboard if not None, otherwise retrieval of text from clipboard.


str – text from clipboard if parameter text is None, otherwise returns None if text is provided

property memoryUsed: float | int
workingOnlineOrInCache(url: str) bool

Determines if the given URL should be requested based on the web cache’s internet connectivity status and whether the URL already exists in the cache.


url – Web URL


True if the URL should be requested, False if not

getPluginData(pluginName: str) arelle.utils.PluginData.PluginData | None
setPluginData(pluginData: arelle.utils.PluginData.PluginData) None
_clearPluginData() None