.. 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



.. class:: LogToPrintHandler()



.. class:: LogToXmlHandler(filename)


.. class:: LogToBufferHandler()




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

arelle.Cntlr.logRefsFileLines(refs: list[dict[str, Any]]) str#
class arelle.Cntlr.LogFormatter(fmt: str | None = None, datefmt: str | None = None)#

Bases: logging.Formatter

fileLines(record: logging.LogRecord) str#
format(record: logging.LogRecord) str#
class arelle.Cntlr.LogToPrintHandler(logOutput: str)#

Bases: logging.Handler

.. class:: LogToPrintHandler()

A log handler that emits log entries to standard out as they are logged.

CAUTION: Output is utf-8 encoded, which is fine for saving to files, but may not display correctly in terminal windows.


logOutput (str) – ‘logToStdErr’ to cause log print to stderr instead of stdout


Initializes the instance - basically setting the formatter to None and the filter list to empty.

logFile: str | TextIO | None#


emit(logRecord: logging.LogRecord) None#
class arelle.Cntlr.LogHandlerWithXml#

Bases: logging.Handler

logTextMaxLength: int#


recordToXml(logRec: logging.LogRecord) str#
recordToJson(logRec: logging.LogRecord) dict[str, Any]#
recordToHtml(logRec: logging.LogRecord) str#
class arelle.Cntlr.LogToXmlHandler(filename: str | None = None, mode: str = 'w')#

Bases: arelle.Cntlr.LogHandlerWithXml

.. class:: LogToXmlHandler(filename)

A log handler that writes log entries to named XML file (utf-8 encoded) upon closing the application.


Initializes the instance - basically setting the formatter to None and the filter list to empty.

logRecordBuffer: list[logging.LogRecord]#


filename: str | None#


filemode: str#


htmlTitle: str#

‘Arelle Message Log’

flush() None#
clearLogBuffer() None#
getXml(clearLogBuffer: bool = True) str#

Returns an XML document (as a string) representing the messages in the log buffer, and clears the buffer.


str – XML document string of messages in the log buffer.

getJson(clearLogBuffer: bool = True) str#

Returns an JSON string representing the messages in the log buffer, and clears the buffer.


str – json representation of messages in the log buffer

getHtml(clearLogBuffer: bool = True) str#

Returns an HTML string representing the messages in the log buffer, and clears the buffer.


str – HTML representation of messages in the log buffer

getLines(clearLogBuffer: bool = True) list[str]#

Returns a list of the message strings in the log buffer, and clears the buffer.


[str] – list of strings representing messages corresponding to log buffer entries

getText(separator: str = '\n', clearLogBuffer: bool = True) str#

Returns a string of the lines in the log buffer, separated by newline or provided separator.


separator (str) – Line separator (default is platform os newline character)


str – joined lines of the log buffer.

emit(logRecord: logging.LogRecord) None#
class arelle.Cntlr.LogToBufferHandler#

Bases: arelle.Cntlr.LogToXmlHandler

.. class:: LogToBufferHandler()

A log handler that writes log entries to a memory buffer for later retrieval (to a string) in XML, JSON, or text lines, usually for return to a web service or web page call.


Initializes the instance - basically setting the formatter to None and the filter list to empty.

flush() None#