scitex-logging 0.2.2__tar.gz → 0.2.4__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/CHANGELOG.md +6 -0
  2. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/PKG-INFO +41 -4
  3. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/README.md +35 -0
  4. scitex_logging-0.2.4/docs/logging-auditor.md +80 -0
  5. scitex_logging-0.2.4/docs/stream-behavior.md +92 -0
  6. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/pyproject.toml +21 -5
  7. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/__init__.py +13 -2
  8. scitex_logging-0.2.4/src/scitex_logging/_audit_plugin.py +7 -0
  9. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_config.py +11 -8
  10. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_console.py +58 -24
  11. scitex_logging-0.2.4/src/scitex_logging/_diagnostic.py +33 -0
  12. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_handlers.py +2 -2
  13. scitex_logging-0.2.4/src/scitex_logging/_hook_rules.py +44 -0
  14. scitex_logging-0.2.4/src/scitex_logging/_linter_plugin.py +72 -0
  15. scitex_logging-0.2.4/src/scitex_logging/_output/_auditor.py +155 -0
  16. scitex_logging-0.2.4/src/scitex_logging/_output/_backend.py +148 -0
  17. scitex_logging-0.2.4/src/scitex_logging/_output/_detector.py +415 -0
  18. scitex_logging-0.2.4/src/scitex_logging/_output/_hook.py +90 -0
  19. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_print_capture.py +22 -9
  20. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/SKILL.md +19 -0
  21. scitex_logging-0.2.4/src/scitex_logging/hooks/enforce_output.sh +3 -0
  22. scitex_logging-0.2.4/src/scitex_logging/hooks/enforce_output_after.sh +3 -0
  23. scitex_logging-0.2.4/tests/integration/test__stream_boundaries.py +314 -0
  24. scitex_logging-0.2.4/tests/integration/test_cross_package_imports.py +71 -0
  25. scitex_logging-0.2.4/tests/scitex_logging/_output/__init__.py +0 -0
  26. scitex_logging-0.2.4/tests/scitex_logging/_output/test__auditor.py +216 -0
  27. scitex_logging-0.2.4/tests/scitex_logging/_output/test__detector.py +356 -0
  28. scitex_logging-0.2.4/tests/scitex_logging/_output/test__hook.py +120 -0
  29. scitex_logging-0.2.4/tests/scitex_logging/llm/__init__.py +0 -0
  30. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__console.py +6 -2
  31. scitex_logging-0.2.4/tests/scitex_logging/test__diagnostic.py +35 -0
  32. scitex_logging-0.2.2/tests/integration/test_cross_package_imports.py +0 -43
  33. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.env.example +0 -0
  34. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.gitattributes +0 -0
  35. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/ci/build-in-sif.sh +0 -0
  36. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/ci/exec-in-sif.sh +0 -0
  37. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/ci/publish-in-sif.sh +0 -0
  38. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/ci/run-in-sif.sh +0 -0
  39. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/workflows/ci.yml +0 -0
  40. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/workflows/cla.yml +0 -0
  41. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.github/workflows/pypi-publish-and-github-release-on-tag.yml +0 -0
  42. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.gitignore +0 -0
  43. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/.readthedocs.yaml +0 -0
  44. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/CLA.md +0 -0
  45. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/CONTRIBUTING.md +0 -0
  46. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/LICENSE +0 -0
  47. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/codecov.yml +0 -0
  48. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/scitex-icon-navy-inverted.png +0 -0
  49. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/scitex-logo-blue-cropped.png +0 -0
  50. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/_static/.gitkeep +0 -0
  51. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/api/scitex_logging.rst +0 -0
  52. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/conf.py +0 -0
  53. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/index.rst +0 -0
  54. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/installation.rst +0 -0
  55. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/quickstart.rst +0 -0
  56. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/docs/sphinx/requirements.txt +0 -0
  57. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/examples/quickstart.py +0 -0
  58. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/README.md +0 -0
  59. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_Tee.py +0 -0
  60. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_context.py +0 -0
  61. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_errors.py +0 -0
  62. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_formatters.py +0 -0
  63. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_levels.py +0 -0
  64. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_logger.py +0 -0
  65. {scitex_logging-0.2.2/tests → scitex_logging-0.2.4/src/scitex_logging/_output}/__init__.py +0 -0
  66. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/01_installation.md +0 -0
  67. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/02_quick-start.md +0 -0
  68. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/03_python-api.md +0 -0
  69. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/10_quick-start.md +0 -0
  70. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/11_python-api.md +0 -0
  71. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_skills/scitex-logging/20_env-vars.md +0 -0
  72. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/_warnings.py +0 -0
  73. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/__init__.py +0 -0
  74. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/__main__.py +0 -0
  75. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_actions.py +0 -0
  76. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_dag.py +0 -0
  77. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_dashboard.py +0 -0
  78. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_parser.py +0 -0
  79. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_renderer.py +0 -0
  80. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_replay.py +0 -0
  81. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_spa.py +0 -0
  82. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_spa_css.py +0 -0
  83. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/src/scitex_logging/llm/_spa_js.py +0 -0
  84. {scitex_logging-0.2.2/tests/examples → scitex_logging-0.2.4/tests}/__init__.py +0 -0
  85. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/conftest.py +0 -0
  86. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/develop/__init__.py +0 -0
  87. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/develop/test_audit.py +0 -0
  88. {scitex_logging-0.2.2/tests/integration → scitex_logging-0.2.4/tests/examples}/__init__.py +0 -0
  89. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/examples/test_examples_smoke.py +0 -0
  90. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/examples/test_quickstart.py +0 -0
  91. {scitex_logging-0.2.2/tests/scitex_logging → scitex_logging-0.2.4/tests/integration}/__init__.py +0 -0
  92. {scitex_logging-0.2.2/tests/scitex_logging/llm → scitex_logging-0.2.4/tests/scitex_logging}/__init__.py +0 -0
  93. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/conftest.py +0 -0
  94. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test___main__.py +0 -0
  95. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test___main___output_boundary.py +0 -0
  96. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__actions.py +0 -0
  97. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__dag.py +0 -0
  98. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__dashboard.py +0 -0
  99. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__parser.py +0 -0
  100. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__renderer.py +0 -0
  101. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__replay.py +0 -0
  102. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/llm/test__spa.py +0 -0
  103. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__Tee.py +0 -0
  104. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test___init__.py +0 -0
  105. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__config.py +0 -0
  106. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__context.py +0 -0
  107. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__errors.py +0 -0
  108. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__formatters.py +0 -0
  109. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__handlers.py +0 -0
  110. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__levels.py +0 -0
  111. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__logger.py +0 -0
  112. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__print_capture.py +0 -0
  113. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/scitex_logging/test__warnings.py +0 -0
  114. {scitex_logging-0.2.2 → scitex_logging-0.2.4}/tests/skills/test_skills_quality.py +0 -0
@@ -5,6 +5,12 @@ All notable changes to `scitex-logging` are documented here.
5
5
  The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
6
6
  versions follow [Semantic Versioning](https://semver.org/).
7
7
 
8
+ ## [0.2.4] - 2026-11-01
9
+
10
+ - Enforce PS-220 through logging-owned native edit/shell hooks plus the shared auditor and linter detector.
11
+ - Reject ad hoc `logging.basicConfig` and direct stdlib console handlers outside proved backend operations.
12
+ - Add `getDiagnostic()` for canonical, non-propagating stderr output in embedded protocol producers.
13
+
8
14
  ## [Unreleased]
9
15
 
10
16
  ## [0.2.2] - 2026-10-02
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scitex-logging
3
- Version: 0.2.2
3
+ Version: 0.2.4
4
4
  Summary: Logging utilities for the SciTeX ecosystem
5
5
  Project-URL: Homepage, https://github.com/ywatanabe1989/scitex-logging
6
6
  Project-URL: Repository, https://github.com/ywatanabe1989/scitex-logging
@@ -15,18 +15,20 @@ Classifier: Environment :: Console
15
15
  Classifier: Intended Audience :: Science/Research
16
16
  Classifier: Operating System :: OS Independent
17
17
  Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.9
18
19
  Classifier: Programming Language :: Python :: 3.10
19
20
  Classifier: Programming Language :: Python :: 3.11
20
21
  Classifier: Programming Language :: Python :: 3.12
21
22
  Classifier: Programming Language :: Python :: 3.13
22
23
  Classifier: Topic :: System :: Logging
23
- Requires-Python: >=3.10
24
+ Requires-Python: >=3.9
25
+ Requires-Dist: tomli>=2.0; python_version < '3.11'
24
26
  Provides-Extra: all
25
27
  Requires-Dist: myst-parser>=2.0; extra == 'all'
26
28
  Requires-Dist: pytest; extra == 'all'
27
29
  Requires-Dist: pytest-cov; extra == 'all'
28
30
  Requires-Dist: pytest-timeout>=2.1.0; extra == 'all'
29
- Requires-Dist: scitex-dev>=0.62.1; extra == 'all'
31
+ Requires-Dist: scitex-dev>=0.62.3; extra == 'all'
30
32
  Requires-Dist: scitex-io; extra == 'all'
31
33
  Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'all'
32
34
  Requires-Dist: sphinx-copybutton>=0.5; extra == 'all'
@@ -36,7 +38,7 @@ Provides-Extra: dev
36
38
  Requires-Dist: pytest; extra == 'dev'
37
39
  Requires-Dist: pytest-cov; extra == 'dev'
38
40
  Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
39
- Requires-Dist: scitex-dev>=0.62.1; extra == 'dev'
41
+ Requires-Dist: scitex-dev>=0.62.3; extra == 'dev'
40
42
  Requires-Dist: scitex-io; extra == 'dev'
41
43
  Provides-Extra: docs
42
44
  Requires-Dist: myst-parser>=2.0; extra == 'docs'
@@ -125,6 +127,10 @@ log.render("out.html")
125
127
 
126
128
  </details>
127
129
 
130
+ Use `getLogger()` for diagnostics, `getConsole()` for formatted stdout, and
131
+ `getPlainConsole()` for exact result lines. See [stream behavior](docs/stream-behavior.md)
132
+ for filtering, caller-owned streams, and configuration ownership.
133
+
128
134
  ## Architecture
129
135
 
130
136
  ```
@@ -187,3 +193,34 @@ AGPL-3.0-only — see [LICENSE](LICENSE).
187
193
  <p align="center">
188
194
  <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
189
195
  </p>
196
+
197
+
198
+ ## Enforced output policy
199
+
200
+ The logging distribution owns PS-220's shared AST detector, auditor plugin,
201
+ linter plugin, and executable `scitex_dev.hooks` provider. Besides raw print
202
+ and stdlib logger acquisition, it rejects `logging.basicConfig` and direct
203
+ `logging.StreamHandler` construction outside individually proved logger-backend
204
+ operations. Importing a helper must not install an extra console handler.
205
+
206
+ With a scitex-dev version exposing federated provider installation:
207
+
208
+ ```bash
209
+ scitex-dev dev hooks install --provider scitex-logging --harness claude --config .claude/settings.local.json --dry-run
210
+ scitex-dev dev hooks install --provider scitex-logging --harness claude --config .claude/settings.local.json
211
+ ```
212
+
213
+ For Hermes use `--harness hermes --config <profile>/config.yaml` from an
214
+ environment with Hermes' atomic configuration writer available. `--python`
215
+ selects the interpreter **inside the target environment**; it must have both
216
+ packages installed. Discovery alone does not install or activate a hook.
217
+ Hermes' own first-use command consent also applies.
218
+
219
+ Native Write/Edit/MultiEdit and Hermes write_file/patch are checked against the
220
+ complete proposed source before execution. Shell/patch-tool changes are checked
221
+ against tracked diffs and untracked Python source; a post-tool report cannot
222
+ undo a completed shell command, while the next guarded shell invocation and
223
+ the auditor enforce the resulting source. A missing required provider fails
224
+ closed. Tests exercise actual entry-point discovery, subprocess exit status,
225
+ and shared detector results. The detector is static; dynamically generated
226
+ calls are outside its proof.
@@ -77,6 +77,10 @@ log.render("out.html")
77
77
 
78
78
  </details>
79
79
 
80
+ Use `getLogger()` for diagnostics, `getConsole()` for formatted stdout, and
81
+ `getPlainConsole()` for exact result lines. See [stream behavior](docs/stream-behavior.md)
82
+ for filtering, caller-owned streams, and configuration ownership.
83
+
80
84
  ## Architecture
81
85
 
82
86
  ```
@@ -139,3 +143,34 @@ AGPL-3.0-only — see [LICENSE](LICENSE).
139
143
  <p align="center">
140
144
  <a href="https://scitex.ai" target="_blank"><img src="docs/scitex-icon-navy-inverted.png" alt="SciTeX" width="40"/></a>
141
145
  </p>
146
+
147
+
148
+ ## Enforced output policy
149
+
150
+ The logging distribution owns PS-220's shared AST detector, auditor plugin,
151
+ linter plugin, and executable `scitex_dev.hooks` provider. Besides raw print
152
+ and stdlib logger acquisition, it rejects `logging.basicConfig` and direct
153
+ `logging.StreamHandler` construction outside individually proved logger-backend
154
+ operations. Importing a helper must not install an extra console handler.
155
+
156
+ With a scitex-dev version exposing federated provider installation:
157
+
158
+ ```bash
159
+ scitex-dev dev hooks install --provider scitex-logging --harness claude --config .claude/settings.local.json --dry-run
160
+ scitex-dev dev hooks install --provider scitex-logging --harness claude --config .claude/settings.local.json
161
+ ```
162
+
163
+ For Hermes use `--harness hermes --config <profile>/config.yaml` from an
164
+ environment with Hermes' atomic configuration writer available. `--python`
165
+ selects the interpreter **inside the target environment**; it must have both
166
+ packages installed. Discovery alone does not install or activate a hook.
167
+ Hermes' own first-use command consent also applies.
168
+
169
+ Native Write/Edit/MultiEdit and Hermes write_file/patch are checked against the
170
+ complete proposed source before execution. Shell/patch-tool changes are checked
171
+ against tracked diffs and untracked Python source; a post-tool report cannot
172
+ undo a completed shell command, while the next guarded shell invocation and
173
+ the auditor enforce the resulting source. A missing required provider fails
174
+ closed. Tests exercise actual entry-point discovery, subprocess exit status,
175
+ and shared detector results. The detector is static; dynamically generated
176
+ calls are outside its proof.
@@ -0,0 +1,80 @@
1
+ # Logging output auditor
2
+
3
+ SciTeX logging owns PS-220, the mandatory error rule for output in package
4
+ source. SciTeX dev discovers the provider, invokes it, and reports findings.
5
+ The rule definition and detector live in this package, so project audits and
6
+ the AST linter apply the same policy.
7
+
8
+ The wheel advertises two entry points:
9
+
10
+ | Group | Name | Factory |
11
+ | --- | --- | --- |
12
+ | `scitex_dev.audit.project` | `scitex-logging` | `scitex_logging._audit_plugin:get_plugin` |
13
+ | `scitex_dev.linter.plugins` | `scitex-logging` | `scitex_logging._linter_plugin:get_plugin` |
14
+
15
+ The project factory supplies rule five-tuples and a checker accepting
16
+ `(repo, violation_class, out, *, config=None)`. The linter factory constructs
17
+ `Rule` and `Issue` through the public `scitex_dev.linter.spi` only when the
18
+ plugin activates. Its checker opts into filepath metadata with
19
+ `accepts_filepath=True`; existing two-argument plugins retain their interface.
20
+ Importing SciTeX logging or its project factory does not import SciTeX dev.
21
+
22
+ Every Python file under `src/` is in scope, including bundled directories
23
+ named `tests`, `scripts`, `examples`, or `docs`. Repository directories outside
24
+ `src/` are outside this source policy. Builtin `print`, `pprint`, Rich console
25
+ printing, stdlib logger acquisition, and direct stdlib diagnostic calls fail.
26
+ JSON payloads, explicit `file=` streams, and content-rendering function names
27
+ do not exempt raw print. `noqa`, severity settings, category overrides,
28
+ disabled rules, and skip lists cannot weaken the error tier.
29
+
30
+ Choose the logging primitive that matches the destination:
31
+
32
+ | Destination | Primitive |
33
+ | --- | --- |
34
+ | Diagnostics on stderr | `scitex_logging.getLogger(__name__)` and level methods |
35
+ | Human results on stdout | `scitex_logging.getConsole(__name__)` and level methods |
36
+ | Exact protocol stdout | `scitex_logging.getPlainConsole(__name__).emit(payload)` |
37
+ | Caller-owned protocol stream | `scitex_logging.getPlainConsole(__name__).emit(payload, stream=stream)` |
38
+
39
+ `emit` preserves a message without level prefixes and propagates write and
40
+ flush failures. Transport callers remain responsible for serialization.
41
+ See [stream behavior](stream-behavior.md) for destination, capture, and
42
+ configuration behavior.
43
+
44
+ The detector parses source without importing it. It follows import and
45
+ assignment aliases, literal `builtins.print` access, literal `getattr`, and
46
+ Rich console constructor/method aliases within lexical scopes. Definition-time
47
+ expressions are scanned in their enclosing scope; comprehensions and local
48
+ bindings shadow outer aliases. Proved output fields are followed between
49
+ methods of the same class. Unrelated
50
+ methods named `print`, including the SciTeX plain-console adapter, are not
51
+ classified as builtin or Rich printing. Nonliteral dynamic imports, computed attribute
52
+ names, and runtime call-graph behavior are outside this static proof.
53
+
54
+ The logging implementation needs stdlib logging to implement its public API.
55
+ That is the sole backend allowance. It requires the declared distribution
56
+ name, the actual public `getLogger` wiring, the `SciTeXLogger` subclass, and
57
+ the logger setup statements. Each allowed call must then match an exact module,
58
+ lexical scope, and complete AST statement. Foreign symlink targets, copied
59
+ folder names, and diagnostics added to an allowed module do not acquire an
60
+ exemption. Backend code remains subject to the raw-print ban.
61
+
62
+ Older developer tooling cannot enforce mandatory filepath-aware plugins.
63
+ Install the compatible logging/dev release pair when enabling this provider;
64
+ missing or broken mandatory providers must fail visibly, rather than report a
65
+ successful audit that skipped logging checks.
66
+
67
+ The provider and caller-stream writer are introduced in logging 0.2.3.
68
+ Logging's developer extra requires SciTeX dev 0.62.4.dev0 or later, containing
69
+ the mandatory provider and filepath contracts. The coordinated source changes
70
+ must be released together; older public Dev 0.62.3 is not that compatible
71
+ engine. Before publication, install both locally built wheels together in an
72
+ isolated environment. A private Dev candidate can use the standard
73
+ `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_SCITEX_DEV=0.62.4.dev0` build override,
74
+ with its source commit recorded; this does not publish a release or create a
75
+ Git tag.
76
+
77
+ Logging's runtime supports Python 3.9 and later. The optional Dev toolchain has
78
+ additional dependencies with their own Python minimums; testing the logging
79
+ runtime and provider interface on Python 3.9 does not establish that Dev's
80
+ entire dependency graph installs there.
@@ -0,0 +1,92 @@
1
+ # Output streams and configuration
2
+
3
+ Choose the writer according to what the output means:
4
+
5
+ | Writer | Destination | Format and filtering |
6
+ | --- | --- | --- |
7
+ | `getLogger(name)` | Root diagnostics: stderr and the log file by default | Level prefix; logger and configured handler thresholds apply |
8
+ | `getConsole(name)` | Current stdout | Same level prefix; a new console inherits the root threshold unless an explicit level is supplied |
9
+ | `getPlainConsole(name).emit(text)` | Current stdout, or the supplied `stream` | Exact text plus one newline; no prefix, diagnostic capture, or level filtering |
10
+
11
+ An embedding application's configured diagnostic handlers remain in control.
12
+ For example, a root handler deliberately writing to stdout will continue to do
13
+ so. SciTeX's default stderr destination applies when SciTeX configures the root.
14
+
15
+ ## Diagnostic and console names are independent
16
+
17
+ `getLogger("app")` and `getConsole("app")` return separate objects. Acquiring
18
+ a console does not change the diagnostic logger's handlers, threshold, or
19
+ propagation. Repeated console acquisition with the same name returns the same
20
+ console and does not add duplicate stdout handlers. Console records keep the
21
+ requested name, but do not propagate into root diagnostics or file logging.
22
+
23
+ A new console with no explicit level follows `set_level()` and the root logger's
24
+ level. `getConsole("app", level=DEBUG)` selects an independent threshold;
25
+ reacquiring it without a level preserves that choice. `console.setLevel()` also
26
+ works. Standard `logging.disable()` and `console.disabled` remain effective.
27
+ Exact protocol results should use the plain writer so quiet diagnostic levels
28
+ cannot suppress them or add a prefix.
29
+
30
+ ## Caller-owned output
31
+
32
+ ```python
33
+ import scitex_logging as slog
34
+
35
+ with open("result.jsonl", "w", encoding="utf-8") as destination:
36
+ slog.getPlainConsole().emit('{"ok": true}', stream=destination, flush=False)
37
+ ```
38
+
39
+ The existing default remains stdout with immediate flushing. Both `stream` and
40
+ `flush` are optional keyword arguments; the `write` and `print` method aliases
41
+ have the same behavior. The writer does not open, close, or otherwise take
42
+ ownership of the supplied stream. Write and flush errors propagate to the
43
+ caller. Foreign wrappers retain their own behavior, even if they expose an
44
+ attribute named `original_stdout`.
45
+
46
+ ## Import and explicit configuration
47
+
48
+ Import installs default console/file handlers only when root has no handlers.
49
+ An already configured root retains its handlers, handler thresholds, root
50
+ threshold, and current stdout capture. The root still gains SciTeX's
51
+ `success()`/`fail()` methods, preserving `getLogger()` without a name.
52
+
53
+ An explicit `configure(...)` call opts into replacing the process-wide root
54
+ configuration. Replaced handlers are closed, including their open file streams.
55
+ `capture_prints=True` enables SciTeX's stdout capture; `capture_prints=False`
56
+ disables its global capture. An explicit configuration call is consequently
57
+ best placed in the application's entry point rather than an imported library.
58
+
59
+ ## Capture and redirects
60
+
61
+ SciTeX's print capture forwards raw stdout and also creates diagnostic records.
62
+ Both formatted and plain console writers bypass every SciTeX capture wrapper,
63
+ so a result reaches stdout without being copied into diagnostics. They resolve
64
+ the current destination on each write and preserve caller-owned redirects.
65
+
66
+ Capture refreshes its forwarding destination whenever it is activated again.
67
+ Stopping capture restores stdout only if that capture currently owns stdout;
68
+ it never replaces another active redirect. A redirect can later restore an
69
+ inactive capture wrapper. That wrapper forwards bytes without creating records,
70
+ and can be safely stopped or restarted. Distinct nested captures and repeated
71
+ contexts using the same capture restore the appropriate outer destination.
72
+
73
+ Capture operates on the process-wide `sys.stdout`, not a thread-local stream.
74
+ Coordinate capture and redirects in the application, and stop a capture that
75
+ targets a temporary stream before closing that stream. Captured raw writes are
76
+ recorded as write fragments, rather than assembled complete lines; distinct
77
+ nested active captures each record the raw writes that pass through them.
78
+
79
+ ## Remaining formatting limits
80
+
81
+ The console formatter currently checks stdout's terminal status even when the
82
+ diagnostic handler writes to stderr. A terminal stdout paired with redirected
83
+ stderr can therefore put ANSI color codes into the redirected diagnostic
84
+ stream. The existing force-color environment settings also take precedence
85
+ without implementing `NO_COLOR`. The plain writer remains prefix-free and
86
+ color-free regardless of these formatter settings.
87
+
88
+ The console formatter modifies its input record's message when applying
89
+ indentation. Multiple console formatters handling the same record can therefore
90
+ accumulate indentation, and a later foreign handler can observe that modified
91
+ message. These formatting limitations are separate from console destination
92
+ isolation and capture ownership; they are not changed by this update.
@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "scitex-logging"
7
- version = "0.2.2"
7
+ version = "0.2.4"
8
8
  description = "Logging utilities for the SciTeX ecosystem"
9
9
  readme = "README.md"
10
10
  license = "AGPL-3.0-only"
11
- requires-python = ">=3.10"
11
+ requires-python = ">=3.9"
12
12
  authors = [
13
13
  { name = "Yusuke Watanabe", email = "noreply@scitex.ai" },
14
14
  ]
@@ -24,20 +24,26 @@ classifiers = [
24
24
  "Intended Audience :: Science/Research",
25
25
  "Operating System :: OS Independent",
26
26
  "Programming Language :: Python :: 3",
27
+ "Programming Language :: Python :: 3.9",
27
28
  "Programming Language :: Python :: 3.10",
28
29
  "Programming Language :: Python :: 3.11",
29
30
  "Programming Language :: Python :: 3.12",
30
31
  "Programming Language :: Python :: 3.13",
31
32
  "Topic :: System :: Logging",
32
33
  ]
33
- dependencies = []
34
+ dependencies = ['tomli>=2.0; python_version < "3.11"']
34
35
 
35
36
  [project.optional-dependencies]
36
37
  dev = [
37
38
  "pytest",
38
39
  "pytest-cov",
39
40
  "pytest-timeout>=2.1.0",
40
- "scitex-dev>=0.62.1",
41
+ # Bootstrap floor: 0.62.3 is the newest published Dev. The linter SPI
42
+ # additions (Issue/ProviderReplacement) land in 0.62.4; the SPI-needing
43
+ # tests skip explicitly until then (see _requires_dev_linter_spi in
44
+ # tests/scitex_logging/_output/test__auditor.py). Re-raise to
45
+ # >=0.62.4.dev0 with the 0.2.4 follow-up once it publishes.
46
+ "scitex-dev>=0.62.3",
41
47
  # Registers scitex-dev's IO/PA rule categories. Without it the linter
42
48
  # loads, reports success, and SILENTLY SKIPS STX-IO001-014 and
43
49
  # STX-PA001-005 — every `open()`, `pickle.dump/load`, `np.load/save`,
@@ -70,6 +76,16 @@ scitex-logging = "scitex_logging"
70
76
  [project.entry-points."scitex_dev.skills"]
71
77
  scitex-logging = "scitex_logging"
72
78
 
79
+ # Policy ownership stays here; developer tooling discovers and executes it.
80
+ [project.entry-points."scitex_dev.audit.project"]
81
+ scitex-logging = "scitex_logging._audit_plugin:get_plugin"
82
+
83
+ [project.entry-points."scitex_dev.hooks"]
84
+ scitex-logging = "scitex_logging._hook_rules:provide"
85
+
86
+ [project.entry-points."scitex_dev.linter.plugins"]
87
+ scitex-logging = "scitex_logging._linter_plugin:get_plugin"
88
+
73
89
  [tool.hatch.build.targets.wheel]
74
90
  packages = ["src/scitex_logging"]
75
91
 
@@ -81,7 +97,7 @@ markers = ["slow: longer Logger subprocess and formatting controls"]
81
97
 
82
98
  [tool.ruff]
83
99
  line-length = 88
84
- target-version = "py310"
100
+ target-version = "py39"
85
101
 
86
102
  [tool.ruff.lint]
87
103
  select = ["E", "F", "W", "I"]
@@ -138,6 +138,7 @@ getLogger = _logging.getLogger
138
138
  # prefix-free stdout for protocol frames (paths, verdicts) where a level
139
139
  # prefix would corrupt the payload. See `._console`.
140
140
  from ._console import getConsole, getPlainConsole # noqa: E402
141
+ from ._diagnostic import getDiagnostic # noqa: E402
141
142
  _basicConfig = _logging.basicConfig
142
143
  _disable = _logging.disable
143
144
 
@@ -161,8 +162,17 @@ _level_map = {
161
162
  }
162
163
  _level = _level_map.get(_level_by_env, INFO)
163
164
 
164
- # Auto-configure logging on import with file logging enabled, print capture disabled by default
165
- configure(level=_level, enable_file=True, enable_console=True, capture_prints=False)
165
+ # Named loggers retain the SciTeX methods even in an embedding application.
166
+ # A configured root belongs to that application: import must not replace its
167
+ # handlers, level, or stdout capture. Keep the existing root's SciTeX method
168
+ # enrichment, including getLogger().success/fail. Explicit configure() opts
169
+ # into process-wide root reconfiguration.
170
+ # logging.getLogger() with no name IS logging.root; spell the singleton
171
+ # directly where root mechanics (not logger acquisition) are meant.
172
+ if _logging.root.handlers:
173
+ _setup_logger_class()
174
+ else:
175
+ configure(level=_level, enable_file=True, enable_console=True, capture_prints=False)
166
176
 
167
177
  # Export public API
168
178
  __all__ = [
@@ -170,6 +180,7 @@ __all__ = [
170
180
  # Core logging functions
171
181
  "getLogger",
172
182
  "getConsole",
183
+ "getDiagnostic",
173
184
  "getPlainConsole",
174
185
  # Log levels
175
186
  "DEBUG",
@@ -0,0 +1,7 @@
1
+ """Project-audit entry point owned by scitex-logging."""
2
+
3
+
4
+ def get_plugin() -> dict:
5
+ from ._output._auditor import PRINT_FORBIDDEN_RULES, check_ps220_no_print
6
+
7
+ return {"rules": PRINT_FORBIDDEN_RULES, "checks": [check_ps220_no_print]}
@@ -42,8 +42,8 @@ def set_level(level: Union[str, int]):
42
42
  if isinstance(level, str):
43
43
  level = level_map.get(level.lower(), level)
44
44
 
45
- _GLOBAL_LEVEL = level
46
45
  logging.getLogger().setLevel(level)
46
+ _GLOBAL_LEVEL = logging.root.level
47
47
 
48
48
  # Update all existing handlers
49
49
  for handler in logging.getLogger().handlers:
@@ -52,7 +52,7 @@ def set_level(level: Union[str, int]):
52
52
 
53
53
  def get_level():
54
54
  """Get current global log level."""
55
- return _GLOBAL_LEVEL or logging.getLogger().level
55
+ return _GLOBAL_LEVEL if _GLOBAL_LEVEL is not None else logging.root.level
56
56
 
57
57
 
58
58
  def enable_file_logging(enabled: bool = True):
@@ -77,6 +77,9 @@ def configure(
77
77
  ):
78
78
  """Configure logging for SciTeX with both console and file output.
79
79
 
80
+ An explicit call replaces and closes the root logger's existing
81
+ handlers. Importing SciTeX logging preserves an already configured root.
82
+
80
83
  Args:
81
84
  level: Log level (string or logging constant)
82
85
  log_file: Path to log file (default: ~/.scitex/logging/runtime/scitex-YYYY-MM-DD.log)
@@ -106,11 +109,6 @@ def configure(
106
109
  # Set global level
107
110
  set_level(level)
108
111
 
109
- # Clear any existing handlers
110
- root_logger = logging.getLogger()
111
- for handler in root_logger.handlers[:]:
112
- root_logger.removeHandler(handler)
113
-
114
112
  handlers = []
115
113
 
116
114
  # Add console handler if enabled
@@ -128,7 +126,8 @@ def configure(
128
126
  )
129
127
  handlers.append(file_handler)
130
128
 
131
- # Configure basic logging with our handlers
129
+ # basicConfig(force=True) removes AND closes replaced handlers. Removing
130
+ # them first would hide them from that cleanup and leak open log files.
132
131
  logging.basicConfig(
133
132
  level=level,
134
133
  handlers=handlers,
@@ -140,6 +139,10 @@ def configure(
140
139
  from ._print_capture import enable_print_capture
141
140
 
142
141
  enable_print_capture()
142
+ else:
143
+ from ._print_capture import disable_print_capture
144
+
145
+ disable_print_capture()
143
146
 
144
147
 
145
148
  def get_log_path():
@@ -34,22 +34,42 @@ surface is available: ``debug`` / ``info`` / ``success`` / ``warning`` /
34
34
  from __future__ import annotations
35
35
 
36
36
  import logging
37
+ import threading
38
+ from typing import TextIO
37
39
 
38
40
  from ._handlers import LazyStdoutStreamHandler, create_stdout_handler
41
+ from ._logger import SciTeXLogger
39
42
  from ._print_capture import PrintCapture
40
43
 
41
- # Distinct from any application logger name, so attaching a stdout
42
- # handler here can never add stdout output to somebody's existing logger.
44
+ # Console objects are cached separately from diagnostic logger names.
43
45
  DEFAULT_CONSOLE_NAME = "scitex.console"
46
+ _CONSOLES: dict[str, SciTeXLogger] = {}
47
+ _CONSOLE_LOCK = threading.RLock()
44
48
 
45
49
 
46
- def getConsole(name: str | None = None, level: int = logging.INFO):
50
+ class _ConsoleLogger(SciTeXLogger):
51
+ """An independent stdout logger with live inherited thresholds."""
52
+
53
+ def isEnabledFor(self, level):
54
+ # These loggers deliberately do not belong to loggerDict. The
55
+ # manager cannot invalidate their usual Logger._cache when root's
56
+ # level or logging.disable changes, so read both values directly.
57
+ return (
58
+ not self.disabled
59
+ and self.manager.disable < level
60
+ and level >= self.getEffectiveLevel()
61
+ )
62
+
63
+
64
+ def getConsole(name: str | None = None, level: int | None = None):
47
65
  """Return a logger that writes to **stdout**.
48
66
 
49
67
  Args:
50
68
  name: Logger name. Defaults to ``scitex.console``. Pass a name to
51
69
  keep an independent console (its own level) for a subsystem.
52
- level: Threshold for both the logger and its stdout handler.
70
+ level: Explicit threshold, or inherit the global/root threshold
71
+ for a new console. Omitting it preserves an existing console's
72
+ explicit level.
53
73
 
54
74
  Returns:
55
75
  The ``SciTeXLogger`` for *name*, carrying exactly one stdout
@@ -64,22 +84,29 @@ def getConsole(name: str | None = None, level: int = logging.INFO):
64
84
  handler :func:`scitex_logging.configure` installs there. The caller
65
85
  asked for stdout, so stdout is where the line goes — once.
66
86
  """
67
- console = logging.getLogger(name or DEFAULT_CONSOLE_NAME)
68
- console.setLevel(level)
69
-
70
- # Ancestors (including root) carry stderr handlers. Propagating would
71
- # duplicate every line onto the stream the caller explicitly did not
72
- # ask for.
73
- console.propagate = False
74
-
75
- for handler in console.handlers:
76
- if isinstance(handler, LazyStdoutStreamHandler):
77
- handler.setLevel(level)
78
- break
79
- else:
80
- console.addHandler(create_stdout_handler(level))
81
-
82
- return console
87
+ with _CONSOLE_LOCK:
88
+ console_name = name or DEFAULT_CONSOLE_NAME
89
+ if not isinstance(console_name, str):
90
+ raise TypeError("A logger name must be a string")
91
+ console = _CONSOLES.get(console_name)
92
+ if console is None:
93
+ # The requested name remains visible in records, but must not
94
+ # share the diagnostic logger's handlers, level or propagation.
95
+ console = _ConsoleLogger(console_name)
96
+ console.parent = logging.root
97
+ console.manager = console.parent.manager
98
+ console.propagate = False
99
+ _CONSOLES[console_name] = console
100
+ if level is not None:
101
+ console.setLevel(level)
102
+ for handler in console.handlers:
103
+ if isinstance(handler, LazyStdoutStreamHandler):
104
+ break
105
+ else:
106
+ # The logger applies its effective threshold. Keeping the
107
+ # handler at NOTSET also respects later console.setLevel calls.
108
+ console.addHandler(create_stdout_handler(logging.NOTSET))
109
+ return console
83
110
 
84
111
 
85
112
  class PlainConsole:
@@ -100,18 +127,25 @@ class PlainConsole:
100
127
  def __init__(self, name: str | None = None) -> None:
101
128
  self._name = name or DEFAULT_CONSOLE_NAME
102
129
 
103
- def emit(self, message: str) -> None:
104
- """Write a result to current stdout without capturing it as a log."""
130
+ def emit(
131
+ self, message: str, *, stream: TextIO | None = None, flush: bool = True
132
+ ) -> None:
133
+ """Write one unprefixed line to stdout or a caller-owned stream.
134
+
135
+ Only SciTeX print-capture wrappers are bypassed. Other streams keep
136
+ their own write/flush behavior, and failures propagate to the caller.
137
+ """
105
138
  import sys
106
139
 
107
- stream = sys.stdout
140
+ stream = sys.stdout if stream is None else stream
108
141
  # Print capture owns diagnostic duplication. A plain result must
109
142
  # bypass only our wrappers, while respecting the current redirected
110
143
  # stream and any foreign wrapper's own write/flush behavior.
111
144
  while isinstance(stream, PrintCapture):
112
145
  stream = stream.original_stdout
113
146
  stream.write(f"{message}\n")
114
- stream.flush()
147
+ if flush:
148
+ stream.flush()
115
149
 
116
150
  # Alias parity with the logger surface — all unprefixed.
117
151
  print = emit
@@ -0,0 +1,33 @@
1
+ """Canonical isolated stderr diagnostics for embedded protocol producers."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import threading
7
+
8
+ from ._handlers import create_console_handler
9
+
10
+ _DIAGNOSTICS = {}
11
+ _LOCK = threading.RLock()
12
+
13
+
14
+ def getDiagnostic(name=None, level=None):
15
+ """Return one non-propagating SciTeX stderr logger.
16
+
17
+ Unlike getLogger, this channel never inherits a caller's stdout handler.
18
+ Formatting and thresholds still use the canonical SciTeX implementation.
19
+ Repeated acquisition preserves an explicit level and never stacks handlers.
20
+ """
21
+ with _LOCK:
22
+ name = name or "scitex.diagnostic"
23
+ if not isinstance(name, str):
24
+ raise TypeError("A logger name must be a string")
25
+ logger = _DIAGNOSTICS.get(name)
26
+ if logger is None:
27
+ logger = logging.getLogger(name)
28
+ logger.propagate = False
29
+ logger.addHandler(create_console_handler(logging.NOTSET))
30
+ _DIAGNOSTICS[name] = logger
31
+ if level is not None:
32
+ logger.setLevel(level)
33
+ return logger
@@ -129,8 +129,8 @@ class LazyStdoutStreamHandler(logging.StreamHandler):
129
129
  # So write past the tee, to the stdout it replaced. Lazy resolution
130
130
  # is preserved: this still reads ``sys.stdout`` per emit, so
131
131
  # ``redirect_stdout`` and pytest's ``capsys`` keep working.
132
- if isinstance(stream, PrintCapture):
133
- return stream.original_stdout
132
+ while isinstance(stream, PrintCapture):
133
+ stream = stream.original_stdout
134
134
  return stream
135
135
 
136
136
  @stream.setter