scitex-logging 0.2.2__tar.gz → 0.2.3__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 (106) hide show
  1. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/PKG-INFO +10 -4
  2. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/README.md +4 -0
  3. scitex_logging-0.2.3/docs/logging-auditor.md +80 -0
  4. scitex_logging-0.2.3/docs/stream-behavior.md +92 -0
  5. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/pyproject.toml +18 -5
  6. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/__init__.py +11 -2
  7. scitex_logging-0.2.3/src/scitex_logging/_audit_plugin.py +7 -0
  8. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_config.py +11 -8
  9. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_console.py +58 -24
  10. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_handlers.py +2 -2
  11. scitex_logging-0.2.3/src/scitex_logging/_linter_plugin.py +72 -0
  12. scitex_logging-0.2.3/src/scitex_logging/_output/_auditor.py +155 -0
  13. scitex_logging-0.2.3/src/scitex_logging/_output/_backend.py +144 -0
  14. scitex_logging-0.2.3/src/scitex_logging/_output/_detector.py +414 -0
  15. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_print_capture.py +22 -9
  16. scitex_logging-0.2.3/tests/integration/test__stream_boundaries.py +314 -0
  17. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/integration/test_cross_package_imports.py +9 -2
  18. scitex_logging-0.2.3/tests/scitex_logging/_output/__init__.py +0 -0
  19. scitex_logging-0.2.3/tests/scitex_logging/_output/test__auditor.py +216 -0
  20. scitex_logging-0.2.3/tests/scitex_logging/_output/test__detector.py +357 -0
  21. scitex_logging-0.2.3/tests/scitex_logging/llm/__init__.py +0 -0
  22. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__console.py +6 -2
  23. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.env.example +0 -0
  24. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.gitattributes +0 -0
  25. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/build-in-sif.sh +0 -0
  26. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/exec-in-sif.sh +0 -0
  27. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/publish-in-sif.sh +0 -0
  28. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/run-in-sif.sh +0 -0
  29. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/ci.yml +0 -0
  30. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/cla.yml +0 -0
  31. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/pypi-publish-and-github-release-on-tag.yml +0 -0
  32. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.gitignore +0 -0
  33. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.readthedocs.yaml +0 -0
  34. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CHANGELOG.md +0 -0
  35. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CLA.md +0 -0
  36. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CONTRIBUTING.md +0 -0
  37. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/LICENSE +0 -0
  38. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/codecov.yml +0 -0
  39. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/scitex-icon-navy-inverted.png +0 -0
  40. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/scitex-logo-blue-cropped.png +0 -0
  41. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/_static/.gitkeep +0 -0
  42. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/api/scitex_logging.rst +0 -0
  43. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/conf.py +0 -0
  44. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/index.rst +0 -0
  45. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/installation.rst +0 -0
  46. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/quickstart.rst +0 -0
  47. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/requirements.txt +0 -0
  48. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/examples/quickstart.py +0 -0
  49. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/README.md +0 -0
  50. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_Tee.py +0 -0
  51. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_context.py +0 -0
  52. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_errors.py +0 -0
  53. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_formatters.py +0 -0
  54. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_levels.py +0 -0
  55. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_logger.py +0 -0
  56. {scitex_logging-0.2.2/tests → scitex_logging-0.2.3/src/scitex_logging/_output}/__init__.py +0 -0
  57. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/01_installation.md +0 -0
  58. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/02_quick-start.md +0 -0
  59. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/03_python-api.md +0 -0
  60. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/10_quick-start.md +0 -0
  61. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/11_python-api.md +0 -0
  62. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/20_env-vars.md +0 -0
  63. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/SKILL.md +0 -0
  64. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_warnings.py +0 -0
  65. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/__init__.py +0 -0
  66. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/__main__.py +0 -0
  67. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_actions.py +0 -0
  68. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_dag.py +0 -0
  69. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_dashboard.py +0 -0
  70. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_parser.py +0 -0
  71. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_renderer.py +0 -0
  72. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_replay.py +0 -0
  73. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa.py +0 -0
  74. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa_css.py +0 -0
  75. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa_js.py +0 -0
  76. {scitex_logging-0.2.2/tests/examples → scitex_logging-0.2.3/tests}/__init__.py +0 -0
  77. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/conftest.py +0 -0
  78. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/develop/__init__.py +0 -0
  79. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/develop/test_audit.py +0 -0
  80. {scitex_logging-0.2.2/tests/integration → scitex_logging-0.2.3/tests/examples}/__init__.py +0 -0
  81. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/examples/test_examples_smoke.py +0 -0
  82. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/examples/test_quickstart.py +0 -0
  83. {scitex_logging-0.2.2/tests/scitex_logging → scitex_logging-0.2.3/tests/integration}/__init__.py +0 -0
  84. {scitex_logging-0.2.2/tests/scitex_logging/llm → scitex_logging-0.2.3/tests/scitex_logging}/__init__.py +0 -0
  85. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/conftest.py +0 -0
  86. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test___main__.py +0 -0
  87. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test___main___output_boundary.py +0 -0
  88. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__actions.py +0 -0
  89. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__dag.py +0 -0
  90. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__dashboard.py +0 -0
  91. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__parser.py +0 -0
  92. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__renderer.py +0 -0
  93. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__replay.py +0 -0
  94. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__spa.py +0 -0
  95. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__Tee.py +0 -0
  96. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test___init__.py +0 -0
  97. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__config.py +0 -0
  98. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__context.py +0 -0
  99. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__errors.py +0 -0
  100. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__formatters.py +0 -0
  101. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__handlers.py +0 -0
  102. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__levels.py +0 -0
  103. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__logger.py +0 -0
  104. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__print_capture.py +0 -0
  105. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__warnings.py +0 -0
  106. {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/skills/test_skills_quality.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scitex-logging
3
- Version: 0.2.2
3
+ Version: 0.2.3
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
  ```
@@ -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
  ```
@@ -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.3"
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,13 @@ 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.linter.plugins"]
84
+ scitex-logging = "scitex_logging._linter_plugin:get_plugin"
85
+
73
86
  [tool.hatch.build.targets.wheel]
74
87
  packages = ["src/scitex_logging"]
75
88
 
@@ -81,7 +94,7 @@ markers = ["slow: longer Logger subprocess and formatting controls"]
81
94
 
82
95
  [tool.ruff]
83
96
  line-length = 88
84
- target-version = "py310"
97
+ target-version = "py39"
85
98
 
86
99
  [tool.ruff.lint]
87
100
  select = ["E", "F", "W", "I"]
@@ -161,8 +161,17 @@ _level_map = {
161
161
  }
162
162
  _level = _level_map.get(_level_by_env, INFO)
163
163
 
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)
164
+ # Named loggers retain the SciTeX methods even in an embedding application.
165
+ # A configured root belongs to that application: import must not replace its
166
+ # handlers, level, or stdout capture. Keep the existing root's SciTeX method
167
+ # enrichment, including getLogger().success/fail. Explicit configure() opts
168
+ # into process-wide root reconfiguration.
169
+ # logging.getLogger() with no name IS logging.root; spell the singleton
170
+ # directly where root mechanics (not logger acquisition) are meant.
171
+ if _logging.root.handlers:
172
+ _setup_logger_class()
173
+ else:
174
+ configure(level=_level, enable_file=True, enable_console=True, capture_prints=False)
166
175
 
167
176
  # Export public API
168
177
  __all__ = [
@@ -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
@@ -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
@@ -0,0 +1,72 @@
1
+ """Linter adapter for the logging-owned mandatory output detector."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ast
6
+ from pathlib import Path
7
+
8
+ from ._output._auditor import _FIX_HINT, PRINT_FORBIDDEN_RULES, find_output_calls
9
+ from ._output._detector import source_repo
10
+
11
+
12
+ def get_plugin() -> dict:
13
+ # SPI objects exist only at plugin activation, never at runtime import.
14
+ # Guarded: lean installs run without scitex-dev; the Dev loader warns
15
+ # and continues without our rules when activation fails here.
16
+ try:
17
+ from scitex_dev.linter.spi import Issue, Rule
18
+ except ImportError as exc:
19
+ raise ImportError(
20
+ "logging linter plugin needs scitex-dev (install scitex-logging[dev])"
21
+ ) from exc
22
+
23
+ rule = Rule(
24
+ id="PS-220",
25
+ severity="error",
26
+ category="logging",
27
+ message=PRINT_FORBIDDEN_RULES[0][2],
28
+ suggestion=_FIX_HINT,
29
+ requires="",
30
+ )
31
+
32
+ class LoggingOutputChecker(ast.NodeVisitor):
33
+ mandatory = True
34
+ accepts_filepath = True
35
+ category = "logging"
36
+
37
+ def __init__(self, source_lines, config, *, filepath="<stdin>"):
38
+ del config
39
+ self.source_lines = source_lines
40
+ self.filepath = filepath
41
+ self.issues = []
42
+
43
+ def visit(self, tree):
44
+ del tree
45
+ repo = source_repo(self.filepath)
46
+ if repo is None:
47
+ return
48
+ text = "\n".join(self.source_lines)
49
+ for site in find_output_calls(
50
+ text, repo=repo, filepath=Path(self.filepath).absolute()
51
+ ):
52
+ line = site.call.lineno
53
+ source = (
54
+ self.source_lines[line - 1]
55
+ if line <= len(self.source_lines)
56
+ else ""
57
+ )
58
+ self.issues.append(
59
+ Issue(
60
+ rule=rule,
61
+ line=line,
62
+ col=site.call.col_offset,
63
+ source_line=source,
64
+ )
65
+ )
66
+
67
+ return {
68
+ "rules": [rule],
69
+ "call_rules": {},
70
+ "axes_hints": {},
71
+ "checkers": [LoggingOutputChecker],
72
+ }