Skip to content

Docs: logger names for scripts, apps and modules (#520) - #913

Merged
craigbarratt merged 2 commits into
custom-components:masterfrom
HoneyBearTech:docs-logger-names
Nov 21, 2026
Merged

craigbarratt merged 2 commits into
custom-components:masterfrom
HoneyBearTech:docs-logger-names

Conversation

@HoneyBearTech

Copy link
Copy Markdown
Contributor

Closes #520, refs #821 and #265

What was missing
The logging docs only showed the file path, so it wasn't clear how to set the level for apps, modules or scripts/. The docs also said Jupyter shows log output regardless of the logger settings, which isn't what the code does.

What I changed

  • In the Logging section of docs/reference.rst:
    • a table of logger paths by location: file.NAME, scripts.NAME, apps.APP, modules.MODULE and jupyter_NNN, all under custom_components.pyscript;
    • a note that apps aren't under file;
    • where internal messages such as "trigger ... not active" are logged (custom_components.pyscript.trigger);
    • one full logger: example.
  • The Jupyter note in docs/reference.rst and docs/tutorial.rst now says Jupyter shows the messages that pass the logger's level.

Each path was checked against how the global contexts build their logger names.

Testing
sphinx-build -W builds the docs with no warnings, and codespell is clean.

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 custom-components#821, custom-components#520, custom-components#265.

Signed-off-by: Sean Stoube <[email protected]>

@craigbarratt craigbarratt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @HoneyBearTech. The logger path table and the Jupyter correction are both accurate.

One fix: with the default (non-legacy) decorators, the "not active" message is Trigger not active due to .... It's logged at debug through the function's own logger (e.g. custom_components.pyscript.file.my_script.my_function), not under custom_components.pyscript.trigger. Only legacy_decorators: true uses trigger.py's trigger ... got ... trigger, but not active. Could you update that paragraph, and the note after the example, to match? Setting a script to debug shows these messages for its functions.

Optionally, you could also mention that files in subdirectories of scripts/ get dotted names, e.g. scripts.sub.NAME.

@HoneyBearTech

Copy link
Copy Markdown
Contributor Author

@craigbarratt thanks for checking! I've updated both passages.

One small difference from your suggestion: the Trigger not active due to ... message goes through the script's logger (e.g. custom_components.pyscript.file.my_script), not a function-qualified one. EvalFunc builds its logger from the global context name only (eval.py L335 and L377), and FunctionDecoratorManager reuses it (decorator.py L250). So setting just ...my_script.my_function to debug doesn't show it, but ...my_script does. The text now says that. I also added the note that files in subfolders of scripts/ get dotted names.

@craigbarratt craigbarratt left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @HoneyBearTech, and you're right about the logger name: EvalFunc uses the global context's logger, so it's the script, not the function. Looks good.

@craigbarratt
craigbarratt merged commit 818b4bf into custom-components:master Nov 21, 2026
6 checks passed
@craigbarratt

Copy link
Copy Markdown
Member

Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Logging Documentation for Apps vs Scripts

2 participants