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.
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/PKG-INFO +10 -4
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/README.md +4 -0
- scitex_logging-0.2.3/docs/logging-auditor.md +80 -0
- scitex_logging-0.2.3/docs/stream-behavior.md +92 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/pyproject.toml +18 -5
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/__init__.py +11 -2
- scitex_logging-0.2.3/src/scitex_logging/_audit_plugin.py +7 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_config.py +11 -8
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_console.py +58 -24
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_handlers.py +2 -2
- scitex_logging-0.2.3/src/scitex_logging/_linter_plugin.py +72 -0
- scitex_logging-0.2.3/src/scitex_logging/_output/_auditor.py +155 -0
- scitex_logging-0.2.3/src/scitex_logging/_output/_backend.py +144 -0
- scitex_logging-0.2.3/src/scitex_logging/_output/_detector.py +414 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_print_capture.py +22 -9
- scitex_logging-0.2.3/tests/integration/test__stream_boundaries.py +314 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/integration/test_cross_package_imports.py +9 -2
- scitex_logging-0.2.3/tests/scitex_logging/_output/__init__.py +0 -0
- scitex_logging-0.2.3/tests/scitex_logging/_output/test__auditor.py +216 -0
- scitex_logging-0.2.3/tests/scitex_logging/_output/test__detector.py +357 -0
- scitex_logging-0.2.3/tests/scitex_logging/llm/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__console.py +6 -2
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.env.example +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.gitattributes +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/build-in-sif.sh +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/exec-in-sif.sh +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/publish-in-sif.sh +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/ci/run-in-sif.sh +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/ci.yml +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/cla.yml +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.github/workflows/pypi-publish-and-github-release-on-tag.yml +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.gitignore +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/.readthedocs.yaml +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CHANGELOG.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CLA.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/CONTRIBUTING.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/LICENSE +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/codecov.yml +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/scitex-icon-navy-inverted.png +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/scitex-logo-blue-cropped.png +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/_static/.gitkeep +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/api/scitex_logging.rst +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/conf.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/index.rst +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/installation.rst +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/quickstart.rst +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/docs/sphinx/requirements.txt +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/examples/quickstart.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/README.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_Tee.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_context.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_errors.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_formatters.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_levels.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_logger.py +0 -0
- {scitex_logging-0.2.2/tests → scitex_logging-0.2.3/src/scitex_logging/_output}/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/01_installation.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/02_quick-start.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/03_python-api.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/10_quick-start.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/11_python-api.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/20_env-vars.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_skills/scitex-logging/SKILL.md +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/_warnings.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/__main__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_actions.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_dag.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_dashboard.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_parser.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_renderer.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_replay.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa_css.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/src/scitex_logging/llm/_spa_js.py +0 -0
- {scitex_logging-0.2.2/tests/examples → scitex_logging-0.2.3/tests}/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/conftest.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/develop/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/develop/test_audit.py +0 -0
- {scitex_logging-0.2.2/tests/integration → scitex_logging-0.2.3/tests/examples}/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/examples/test_examples_smoke.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/examples/test_quickstart.py +0 -0
- {scitex_logging-0.2.2/tests/scitex_logging → scitex_logging-0.2.3/tests/integration}/__init__.py +0 -0
- {scitex_logging-0.2.2/tests/scitex_logging/llm → scitex_logging-0.2.3/tests/scitex_logging}/__init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/conftest.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test___main__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test___main___output_boundary.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__actions.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__dag.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__dashboard.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__parser.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__renderer.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__replay.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/llm/test__spa.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__Tee.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test___init__.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__config.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__context.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__errors.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__formatters.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__handlers.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__levels.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__logger.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__print_capture.py +0 -0
- {scitex_logging-0.2.2 → scitex_logging-0.2.3}/tests/scitex_logging/test__warnings.py +0 -0
- {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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
-
|
|
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 = "
|
|
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
|
-
#
|
|
165
|
-
|
|
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__ = [
|
|
@@ -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
|
|
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
|
-
#
|
|
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
|
-
#
|
|
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
|
-
|
|
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:
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
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(
|
|
104
|
-
|
|
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
|
-
|
|
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
|
-
|
|
133
|
-
|
|
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
|
+
}
|