From 84ab0733e12afbc01dba51223cb5cd6e2c0ee4ae Mon Sep 17 00:00:00 2001 From: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com> Date: Sat, 21 Nov 2026 00:52:22 +0000 Subject: [PATCH 1/2] document the logger names for scripts, apps and modules The logging docs only showed the "file" path, so apps (and modules and scripts) were hard to configure, and they claimed Jupyter shows log output regardless of the logger settings, which isn't true. Add a table of logging paths per location, a full logger example, note where internal trigger messages are logged, and correct the Jupyter note in the reference and tutorial. Refs #821, #520, #265. Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com> --- docs/reference.rst | 39 +++++++++++++++++++++++++++++++++++++-- docs/tutorial.rst | 6 +++--- 2 files changed, 40 insertions(+), 5 deletions(-) diff --git a/docs/reference.rst b/docs/reference.rst index d649c9b..6e0b9c7 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -1356,6 +1356,24 @@ where ``FUNCNAME`` is the name of the top-level Python function (e.g., the one c or service), defined in the script file ``SCRIPTNAME.py``. See the `Global Context <#global-context>`__ section for the logging paths for other cases. +The path starts with the global context name, so it depends on where the file lives. Replace +``file.SCRIPTNAME`` in the path above with: + +=========================================== ===================================================== +Location Logging path +=========================================== ===================================================== +``pyscript/SCRIPTNAME.py`` ``custom_components.pyscript.file.SCRIPTNAME`` +``pyscript/scripts/SCRIPTNAME.py`` ``custom_components.pyscript.scripts.SCRIPTNAME`` +``pyscript/apps/APP.py`` or ``APP/`` ``custom_components.pyscript.apps.APP`` +``pyscript/modules/MODULE.py`` ``custom_components.pyscript.modules.MODULE`` +Jupyter session ``custom_components.pyscript.jupyter_NNN`` +=========================================== ===================================================== + +An app is not under ``file``, so ``custom_components.pyscript.file`` settings don't apply to it; use +``custom_components.pyscript.apps`` instead. Pyscript's own internal messages (for example, a +trigger that is ignored because it is not active) are logged under ``custom_components.pyscript`` +itself (for example, ``custom_components.pyscript.trigger``), not under the script or app. + That allows you to set the log level for each Python top-level script or function separately if necessary. That setting also applies to any other Python functions that the top-level Python function calls. For example, these settings: @@ -1372,13 +1390,30 @@ will log all messages at ``info`` or higher (i.e., ``log.info()``, ``log.warning ``log.error()``), and inside ``my_function`` defined in the script file ``my_script.py`` (and any other functions it calls) will log all messages at ``debug`` or higher. +Here is a fuller example: quiet by default, pyscript's own messages and the app ``my_app`` at ``info``, +and the script ``my_script.py`` at ``debug``: + +.. code:: yaml + + logger: + default: warning + logs: + custom_components.pyscript: info + custom_components.pyscript.apps.my_app: info + custom_components.pyscript.file.my_script: debug + +Setting ``custom_components.pyscript`` to ``debug`` also shows the internal trigger messages (such as +``trigger ... got ... trigger, but not active``), which can be very noisy. + Note that debug logging also includes pyscript's own internal messages, which can show the full arguments passed to your functions, such as webhook payloads, service call data and event data. These can contain tokens or other sensitive information, so review debug logs before sharing them (e.g., in a GitHub issue), and turn debug logging off when you no longer need it. -Note that in Jupyter, all the ``log`` functions will display output in your session, independent of -the ``logger`` configuration settings. +Note that in Jupyter, the ``log`` functions display their output in your session, but only for messages +that pass the ``logger`` configuration settings for your session's path +(``custom_components.pyscript.jupyter_NNN``, which falls under ``custom_components.pyscript``). If you +see no output, enable that path (for example, ``custom_components.pyscript: info``). Changing the log level via the main configuration yaml file will typically require a restart of HASS. To avoid that, you can set the log level for any specific logging path by calling the ``logger.set_level`` diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 177442c..093c915 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -63,9 +63,9 @@ hey, this is just an example.) .. note:: - You'll need to look at the log messages to see the output (unless you are using Jupyter, in which - case all log messages will be displayed, independent of the log setting). The log message won't - be visible unless the ``Logger`` is enabled at least for level ``info``, for example: + You'll need to look at the log messages to see the output (in Jupyter, they are displayed in your + session). The log message won't be visible, including in Jupyter, unless the ``Logger`` is enabled + at least for level ``info``, for example: .. code:: yaml From 374ed3af81bb70d6715eb938994a7cb0f3e35606 Mon Sep 17 00:00:00 2001 From: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com> Date: Sat, 21 Nov 2026 14:20:25 +0000 Subject: [PATCH 2/2] correct where the trigger not active message is logged Signed-off-by: Sean Stoube <31805425+HoneyBearTech@users.noreply.github.com> --- docs/reference.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/reference.rst b/docs/reference.rst index 6e0b9c7..bd3b774 100644 --- a/docs/reference.rst +++ b/docs/reference.rst @@ -1370,9 +1370,16 @@ Jupyter session ``custom_components.pyscript.jupyter =========================================== ===================================================== An app is not under ``file``, so ``custom_components.pyscript.file`` settings don't apply to it; use -``custom_components.pyscript.apps`` instead. Pyscript's own internal messages (for example, a -trigger that is ignored because it is not active) are logged under ``custom_components.pyscript`` -itself (for example, ``custom_components.pyscript.trigger``), not under the script or app. +``custom_components.pyscript.apps`` instead. Files in subfolders of ``scripts/`` get dotted names, for +example ``custom_components.pyscript.scripts.sub.SCRIPTNAME``. + +With the default (non-legacy) decorators, the message for a trigger that is ignored because it is not +active is ``Trigger not active due to ...``. It is logged at ``debug`` through the logger of the script +(or app or module) that defines the function (for example, ``custom_components.pyscript.file.my_script``), +not under ``custom_components.pyscript.trigger``. Only ``legacy_decorators: true`` uses the message +``trigger ... got ... trigger, but not active``, which is logged under +``custom_components.pyscript.trigger``. Other internal messages from pyscript itself are logged under +``custom_components.pyscript``. That allows you to set the log level for each Python top-level script or function separately if necessary. That setting also applies to any other Python functions that the top-level Python function calls. @@ -1402,8 +1409,9 @@ and the script ``my_script.py`` at ``debug``: custom_components.pyscript.apps.my_app: info custom_components.pyscript.file.my_script: debug -Setting ``custom_components.pyscript`` to ``debug`` also shows the internal trigger messages (such as -``trigger ... got ... trigger, but not active``), which can be very noisy. +Setting a script to ``debug`` shows the ``Trigger not active due to ...`` messages for its functions. +Setting ``custom_components.pyscript`` to ``debug`` also shows pyscript's other internal messages, which can +be very noisy. Note that debug logging also includes pyscript's own internal messages, which can show the full arguments passed to your functions, such as webhook payloads, service call data and event data.