kernelcontract 0.1.0a3__tar.gz → 0.1.0a4__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 (24) hide show
  1. kernelcontract-0.1.0a4/PKG-INFO +246 -0
  2. kernelcontract-0.1.0a4/README.md +198 -0
  3. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/pyproject.toml +1 -1
  4. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/__init__.py +1 -1
  5. kernelcontract-0.1.0a4/src/kernelcontract.egg-info/PKG-INFO +246 -0
  6. kernelcontract-0.1.0a3/PKG-INFO +0 -188
  7. kernelcontract-0.1.0a3/README.md +0 -140
  8. kernelcontract-0.1.0a3/src/kernelcontract.egg-info/PKG-INFO +0 -188
  9. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/LICENSE +0 -0
  10. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/setup.cfg +0 -0
  11. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/__main__.py +0 -0
  12. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/cli.py +0 -0
  13. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/diagnostics.py +0 -0
  14. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/discovery.py +0 -0
  15. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/models.py +0 -0
  16. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract.egg-info/SOURCES.txt +0 -0
  17. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract.egg-info/dependency_links.txt +0 -0
  18. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract.egg-info/entry_points.txt +0 -0
  19. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract.egg-info/requires.txt +0 -0
  20. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract.egg-info/top_level.txt +0 -0
  21. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/tests/test_cli.py +0 -0
  22. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/tests/test_diagnostics.py +0 -0
  23. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/tests/test_discovery.py +0 -0
  24. {kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/tests/test_models.py +0 -0
kernelcontract-0.1.0a4/PKG-INFO ADDED
@@ -0,0 +1,246 @@
1
+ Metadata-Version: 2.4
2
+ Name: kernelcontract
3
+ Version: 0.1.0a4
4
+ Summary: Read-only diagnostics for Jupyter kernels and Python environments
5
+ Author: KernelContract contributors
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 KernelContract contributors
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Keywords: jupyter,notebook,kernel,diagnostics,python-environments
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Environment :: Console
31
+ Classifier: Intended Audience :: Developers
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Operating System :: OS Independent
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Programming Language :: Python :: 3.13
39
+ Classifier: Topic :: Scientific/Engineering
40
+ Classifier: Topic :: Software Development :: Debuggers
41
+ Classifier: Topic :: Utilities
42
+ Requires-Python: >=3.10
43
+ Description-Content-Type: text/markdown
44
+ License-File: LICENSE
45
+ Provides-Extra: test
46
+ Requires-Dist: pytest>=8.0; extra == "test"
47
+ Dynamic: license-file
48
+
49
+ # KernelContract
50
+
51
+ **Stop guessing which Jupyter kernel your notebook is using.**
52
+
53
+ KernelContract performs local, read-only diagnostics on Jupyter kernelspecs, Python executables, and notebook kernel metadata to identify configuration problems and environment drift before execution.
54
+
55
+ [![PyPI Version](https://img.shields.io/pypi/v/kernelcontract?include_prereleases)](https://pypi.org/project/kernelcontract/)
56
+ [![Python Versions](https://img.shields.io/pypi/pyversions/kernelcontract)](https://pypi.org/project/kernelcontract/)
57
+ [![MIT License](https://img.shields.io/github/license/Ayushxsingh100/kernelcontract)](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
58
+ [![CI Status](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml)
59
+
60
+ > **Alpha Release (`0.1.0a4`):** KernelContract is published on [PyPI](https://pypi.org/project/kernelcontract/) (see [version 0.1.0a4](https://pypi.org/project/kernelcontract/0.1.0a4/)) and tagged on [GitHub](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4) as an early-stage diagnostic tool. It performs strictly local, read-only checks and will never modify your packages, configuration files, or notebook contents.
61
+
62
+ ---
63
+
64
+ ## Quick start
65
+
66
+ ### Prerequisites
67
+
68
+ * **Python:** 3.10, 3.11, 3.12, or 3.13.
69
+ * **Jupyter CLI on PATH:** KernelContract has **zero external runtime dependencies** (Python standard library only), but requires that the `jupyter` command (such as via `jupyter-core`) is available on your `PATH` for kernel discovery (`jupyter kernelspec list --json`). The Jupyter CLI is not automatically bundled with KernelContract.
70
+
71
+ ### Installation
72
+
73
+ #### Primary: Install from PyPI
74
+
75
+ Install the published alpha release directly from [PyPI](https://pypi.org/project/kernelcontract/):
76
+
77
+ ```bash
78
+ python -m pip install --pre kernelcontract==0.1.0a4
79
+ ```
80
+
81
+ *(The `--pre` flag is required because `0.1.0a4` is an alpha pre-release; `pip` requires `--pre` to allow installing alpha and pre-release packages).*
82
+
83
+ #### Alternative: Install from tagged GitHub release (for developers)
84
+
85
+ Developers or contributors who wish to install directly from the tagged release on GitHub can use:
86
+
87
+ ```bash
88
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a4"
89
+ ```
90
+
91
+ To install the latest development snapshot from the default `master` branch:
92
+
93
+ ```bash
94
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
95
+ ```
96
+
97
+ ---
98
+
99
+ ## The problem: silent notebook mismatches
100
+
101
+ Jupyter notebook failures are frequently caused by environment mismatches rather than faulty notebook code:
102
+
103
+ * **Missing kernels:** A shared or cloned `.ipynb` references a kernel (e.g. `pytorch-env` or `python-3.11`) that was never registered on your machine.
104
+ * **Broken executables:** A registered kernelspec points to a Python interpreter in a virtual environment that was moved, upgraded, or deleted.
105
+ * **Interpreter drift:** The Jupyter server runs in one environment while a kernel executes in another environment that lacks `ipykernel` or companion packages like `jupyterlab_widgets`.
106
+ * **Metadata drift:** A notebook declares a display name (e.g. `Python (DataScience)`) that silently points to an entirely different interpreter on disk.
107
+
108
+ When these issues occur, notebooks either fail on startup, hang, or silently fall back to an arbitrary default interpreter with different packages installed.
109
+
110
+ **KernelContract gives you deterministic, read-only visibility into your Jupyter setup before running code.**
111
+
112
+ ---
113
+
114
+ ## See it in action
115
+
116
+ ### 1. Diagnose registered kernels: `kernelcontract doctor`
117
+
118
+ Inspect all discovered kernelspecs, check executable paths, and verify control interpreter health:
119
+
120
+ ```console
121
+ $ kernelcontract doctor
122
+ KernelContract 0.1.0a4 - doctor
123
+ ============================================
124
+ PASS Current Python (control environment)
125
+ Python 3.12.10 is executable.
126
+ INFO Server interpreter not inferred
127
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
128
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
129
+ PASS Discover Jupyter kernels
130
+ Found 1 registered kernelspec(s).
131
+ PASS python3: executable exists
132
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
133
+ PASS python3: ipykernel importable
134
+ Python 3.12.10 starts and ipykernel is installed (version 6.29.5).
135
+
136
+ Summary: 4 pass, 1 info, 0 warning(s), 0 failure(s).
137
+ Overall status: PASS
138
+ KernelContract did not modify packages or environments.
139
+ ```
140
+
141
+ ### 2. Validate notebook kernel metadata: `kernelcontract notebook`
142
+
143
+ Check whether a notebook file's declared kernel exists and matches registered kernelspecs:
144
+
145
+ ```console
146
+ $ kernelcontract notebook analysis.ipynb
147
+ KernelContract 0.1.0a4 - notebook
148
+ ============================================
149
+ PASS Current Python (control environment)
150
+ Python 3.12.10 is executable.
151
+ INFO Server interpreter not inferred
152
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
153
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
154
+ PASS Discover Jupyter kernels
155
+ Found 1 registered kernelspec(s).
156
+ PASS python3: executable exists
157
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
158
+ FAIL Notebook kernel is registered
159
+ Notebook requests kernel 'pytorch-env', but that name is not in the discovered kernelspec list.
160
+ Next: Register the intended kernel or select an installed kernel in Jupyter and save the notebook. Do not assume a fallback kernel is equivalent.
161
+
162
+ Summary: 3 pass, 1 info, 0 warning(s), 1 failure(s).
163
+ Overall status: FAIL
164
+ KernelContract did not modify packages or environments.
165
+ ```
166
+
167
+ *In this example, KernelContract caught a missing `pytorch-env` kernel before the user ran the notebook, preventing silent fallback to an unintended environment.*
168
+
169
+ ---
170
+
171
+ ## Key capabilities
172
+
173
+ * **Kernelspec discovery:** Enumerates registered Jupyter kernels using standard `jupyter kernelspec list --json`.
174
+ * **Executable resolution:** Resolves the `argv[0]` command across platforms, including Windows `PATHEXT` (`.exe`, `.cmd`, `.bat`), quoted paths with spaces, and environment variable expansion.
175
+ * **Environment inspection:** Checks that Python interpreters can start and verifies the presence of `ipykernel`.
176
+ * **Notebook validation:** Confirms that notebook `.ipynb` files reference valid, registered kernels and detects display-name drift.
177
+ * **Structured JSON output:** Export versioned machine-readable reports (`--json`) for automation, pre-commit hooks, and CI pipelines.
178
+ * **Strict CI mode:** Exit non-zero on warnings with `--strict` (failures always exit with code 1; passes/warnings exit 0 by default).
179
+ * **Companion package checks:** Detects presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
180
+ * **Opt-in external probing:** Probes external Python kernels only when explicitly authorized with `--probe-python`.
181
+
182
+ ---
183
+
184
+ ## Capability summary
185
+
186
+ | Capability | What KernelContract does |
187
+ |---|---|
188
+ | **Kernelspec Discovery** | Queries Jupyter CLI for registered kernelspecs; returns structured discovery errors if output is missing or malformed. |
189
+ | **Executable Verification** | Validates that `argv[0]` resolves to a real executable file on disk without executing third-party code. |
190
+ | **Environment Drift Detection** | Compares the control Python prefix with the kernel Python prefix to detect cross-environment execution. |
191
+ | **Notebook Validation** | Reads notebook JSON metadata and verifies that the requested `kernelspec.name` is registered on the local machine. |
192
+ | **CI & Tooling Integration** | Provides predictable exit codes (`0` for pass/warn, `1` for fail, `--strict` fails on warn) and versioned JSON output. |
193
+ | **Remediation Suggestions** | Supplies concrete, human-readable `Next:` steps for every failing or warning check. |
194
+ | **System Modification** | **None.** Operates strictly read-only; never installs, uninstalls, or modifies files or environments. |
195
+
196
+ ---
197
+
198
+ ## Scope and boundaries
199
+
200
+ * **Strictly read-only:** KernelContract will not repair environments, modify paths, install packages, or rewrite notebook files automatically.
201
+ * **Execution guarantee:** Passing KernelContract checks confirms kernel configuration integrity; it does not guarantee that a notebook's internal code will execute without Python runtime errors.
202
+ * **Server vs. control interpreter:** KernelContract cannot automatically determine which Python interpreter runs an existing Jupyter server process across all containers, services, and launchers. By default, the Python interpreter running KernelContract acts as the **control environment**. To specify the server Python interpreter explicitly, use:
203
+ ```bash
204
+ kernelcontract doctor --server-python /path/to/server/python
205
+ ```
206
+ * **External interpreter probing:** By default, KernelContract only executes package inspection on the control Python interpreter. External interpreters are not executed unless you pass `--probe-python`.
207
+
208
+ ---
209
+
210
+ ## Security and privacy
211
+
212
+ * **100% Local:** Runs entirely on your machine. No telemetry, analytics, or remote network calls are made.
213
+ * **Bounded execution:** Subprocess checks employ strict execution timeouts to prevent hanging processes.
214
+ * **No shell execution:** Commands are executed directly as argument vectors (`shell=False`).
215
+ * **Security boundary on `--probe-python`:** Because a kernelspec `argv` can point to any program, running `--probe-python` executes that interpreter. Only pass `--probe-python` for kernelspecs and environments you trust.
216
+
217
+ ---
218
+
219
+ ## Development
220
+
221
+ KernelContract has zero external runtime dependencies and requires Python 3.10+.
222
+
223
+ ```bash
224
+ git clone https://github.com/Ayushxsingh100/kernelcontract.git
225
+ cd kernelcontract
226
+ python -m venv .venv
227
+ # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
228
+ python -m pip install -e ".[test]"
229
+ python -m unittest discover -s tests -v
230
+ python -m pytest -q
231
+ ```
232
+
233
+ Issues and feature requests are welcome at [GitHub Issues](https://github.com/Ayushxsingh100/kernelcontract/issues).
234
+
235
+ ---
236
+
237
+ ## Status and metadata
238
+
239
+ * **Published version:** `0.1.0a4` (Alpha release)
240
+ * **PyPI project page:** [https://pypi.org/project/kernelcontract/](https://pypi.org/project/kernelcontract/)
241
+ * **PyPI version page (0.1.0a4):** [https://pypi.org/project/kernelcontract/0.1.0a4/](https://pypi.org/project/kernelcontract/0.1.0a4/)
242
+ * **GitHub release:** [v0.1.0a4 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4)
243
+ * **GitHub repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
244
+ * **License:** [MIT License](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
245
+
246
+ > **Note on PyPI metadata:** Package distributions published to PyPI are permanent and immutable. Version `0.1.0a4` on PyPI was built and published from release tag `v0.1.0a4`.
kernelcontract-0.1.0a4/README.md ADDED
@@ -0,0 +1,198 @@
1
+ # KernelContract
2
+
3
+ **Stop guessing which Jupyter kernel your notebook is using.**
4
+
5
+ KernelContract performs local, read-only diagnostics on Jupyter kernelspecs, Python executables, and notebook kernel metadata to identify configuration problems and environment drift before execution.
6
+
7
+ [![PyPI Version](https://img.shields.io/pypi/v/kernelcontract?include_prereleases)](https://pypi.org/project/kernelcontract/)
8
+ [![Python Versions](https://img.shields.io/pypi/pyversions/kernelcontract)](https://pypi.org/project/kernelcontract/)
9
+ [![MIT License](https://img.shields.io/github/license/Ayushxsingh100/kernelcontract)](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
10
+ [![CI Status](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml)
11
+
12
+ > **Alpha Release (`0.1.0a4`):** KernelContract is published on [PyPI](https://pypi.org/project/kernelcontract/) (see [version 0.1.0a4](https://pypi.org/project/kernelcontract/0.1.0a4/)) and tagged on [GitHub](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4) as an early-stage diagnostic tool. It performs strictly local, read-only checks and will never modify your packages, configuration files, or notebook contents.
13
+
14
+ ---
15
+
16
+ ## Quick start
17
+
18
+ ### Prerequisites
19
+
20
+ * **Python:** 3.10, 3.11, 3.12, or 3.13.
21
+ * **Jupyter CLI on PATH:** KernelContract has **zero external runtime dependencies** (Python standard library only), but requires that the `jupyter` command (such as via `jupyter-core`) is available on your `PATH` for kernel discovery (`jupyter kernelspec list --json`). The Jupyter CLI is not automatically bundled with KernelContract.
22
+
23
+ ### Installation
24
+
25
+ #### Primary: Install from PyPI
26
+
27
+ Install the published alpha release directly from [PyPI](https://pypi.org/project/kernelcontract/):
28
+
29
+ ```bash
30
+ python -m pip install --pre kernelcontract==0.1.0a4
31
+ ```
32
+
33
+ *(The `--pre` flag is required because `0.1.0a4` is an alpha pre-release; `pip` requires `--pre` to allow installing alpha and pre-release packages).*
34
+
35
+ #### Alternative: Install from tagged GitHub release (for developers)
36
+
37
+ Developers or contributors who wish to install directly from the tagged release on GitHub can use:
38
+
39
+ ```bash
40
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a4"
41
+ ```
42
+
43
+ To install the latest development snapshot from the default `master` branch:
44
+
45
+ ```bash
46
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
47
+ ```
48
+
49
+ ---
50
+
51
+ ## The problem: silent notebook mismatches
52
+
53
+ Jupyter notebook failures are frequently caused by environment mismatches rather than faulty notebook code:
54
+
55
+ * **Missing kernels:** A shared or cloned `.ipynb` references a kernel (e.g. `pytorch-env` or `python-3.11`) that was never registered on your machine.
56
+ * **Broken executables:** A registered kernelspec points to a Python interpreter in a virtual environment that was moved, upgraded, or deleted.
57
+ * **Interpreter drift:** The Jupyter server runs in one environment while a kernel executes in another environment that lacks `ipykernel` or companion packages like `jupyterlab_widgets`.
58
+ * **Metadata drift:** A notebook declares a display name (e.g. `Python (DataScience)`) that silently points to an entirely different interpreter on disk.
59
+
60
+ When these issues occur, notebooks either fail on startup, hang, or silently fall back to an arbitrary default interpreter with different packages installed.
61
+
62
+ **KernelContract gives you deterministic, read-only visibility into your Jupyter setup before running code.**
63
+
64
+ ---
65
+
66
+ ## See it in action
67
+
68
+ ### 1. Diagnose registered kernels: `kernelcontract doctor`
69
+
70
+ Inspect all discovered kernelspecs, check executable paths, and verify control interpreter health:
71
+
72
+ ```console
73
+ $ kernelcontract doctor
74
+ KernelContract 0.1.0a4 - doctor
75
+ ============================================
76
+ PASS Current Python (control environment)
77
+ Python 3.12.10 is executable.
78
+ INFO Server interpreter not inferred
79
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
80
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
81
+ PASS Discover Jupyter kernels
82
+ Found 1 registered kernelspec(s).
83
+ PASS python3: executable exists
84
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
85
+ PASS python3: ipykernel importable
86
+ Python 3.12.10 starts and ipykernel is installed (version 6.29.5).
87
+
88
+ Summary: 4 pass, 1 info, 0 warning(s), 0 failure(s).
89
+ Overall status: PASS
90
+ KernelContract did not modify packages or environments.
91
+ ```
92
+
93
+ ### 2. Validate notebook kernel metadata: `kernelcontract notebook`
94
+
95
+ Check whether a notebook file's declared kernel exists and matches registered kernelspecs:
96
+
97
+ ```console
98
+ $ kernelcontract notebook analysis.ipynb
99
+ KernelContract 0.1.0a4 - notebook
100
+ ============================================
101
+ PASS Current Python (control environment)
102
+ Python 3.12.10 is executable.
103
+ INFO Server interpreter not inferred
104
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
105
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
106
+ PASS Discover Jupyter kernels
107
+ Found 1 registered kernelspec(s).
108
+ PASS python3: executable exists
109
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
110
+ FAIL Notebook kernel is registered
111
+ Notebook requests kernel 'pytorch-env', but that name is not in the discovered kernelspec list.
112
+ Next: Register the intended kernel or select an installed kernel in Jupyter and save the notebook. Do not assume a fallback kernel is equivalent.
113
+
114
+ Summary: 3 pass, 1 info, 0 warning(s), 1 failure(s).
115
+ Overall status: FAIL
116
+ KernelContract did not modify packages or environments.
117
+ ```
118
+
119
+ *In this example, KernelContract caught a missing `pytorch-env` kernel before the user ran the notebook, preventing silent fallback to an unintended environment.*
120
+
121
+ ---
122
+
123
+ ## Key capabilities
124
+
125
+ * **Kernelspec discovery:** Enumerates registered Jupyter kernels using standard `jupyter kernelspec list --json`.
126
+ * **Executable resolution:** Resolves the `argv[0]` command across platforms, including Windows `PATHEXT` (`.exe`, `.cmd`, `.bat`), quoted paths with spaces, and environment variable expansion.
127
+ * **Environment inspection:** Checks that Python interpreters can start and verifies the presence of `ipykernel`.
128
+ * **Notebook validation:** Confirms that notebook `.ipynb` files reference valid, registered kernels and detects display-name drift.
129
+ * **Structured JSON output:** Export versioned machine-readable reports (`--json`) for automation, pre-commit hooks, and CI pipelines.
130
+ * **Strict CI mode:** Exit non-zero on warnings with `--strict` (failures always exit with code 1; passes/warnings exit 0 by default).
131
+ * **Companion package checks:** Detects presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
132
+ * **Opt-in external probing:** Probes external Python kernels only when explicitly authorized with `--probe-python`.
133
+
134
+ ---
135
+
136
+ ## Capability summary
137
+
138
+ | Capability | What KernelContract does |
139
+ |---|---|
140
+ | **Kernelspec Discovery** | Queries Jupyter CLI for registered kernelspecs; returns structured discovery errors if output is missing or malformed. |
141
+ | **Executable Verification** | Validates that `argv[0]` resolves to a real executable file on disk without executing third-party code. |
142
+ | **Environment Drift Detection** | Compares the control Python prefix with the kernel Python prefix to detect cross-environment execution. |
143
+ | **Notebook Validation** | Reads notebook JSON metadata and verifies that the requested `kernelspec.name` is registered on the local machine. |
144
+ | **CI & Tooling Integration** | Provides predictable exit codes (`0` for pass/warn, `1` for fail, `--strict` fails on warn) and versioned JSON output. |
145
+ | **Remediation Suggestions** | Supplies concrete, human-readable `Next:` steps for every failing or warning check. |
146
+ | **System Modification** | **None.** Operates strictly read-only; never installs, uninstalls, or modifies files or environments. |
147
+
148
+ ---
149
+
150
+ ## Scope and boundaries
151
+
152
+ * **Strictly read-only:** KernelContract will not repair environments, modify paths, install packages, or rewrite notebook files automatically.
153
+ * **Execution guarantee:** Passing KernelContract checks confirms kernel configuration integrity; it does not guarantee that a notebook's internal code will execute without Python runtime errors.
154
+ * **Server vs. control interpreter:** KernelContract cannot automatically determine which Python interpreter runs an existing Jupyter server process across all containers, services, and launchers. By default, the Python interpreter running KernelContract acts as the **control environment**. To specify the server Python interpreter explicitly, use:
155
+ ```bash
156
+ kernelcontract doctor --server-python /path/to/server/python
157
+ ```
158
+ * **External interpreter probing:** By default, KernelContract only executes package inspection on the control Python interpreter. External interpreters are not executed unless you pass `--probe-python`.
159
+
160
+ ---
161
+
162
+ ## Security and privacy
163
+
164
+ * **100% Local:** Runs entirely on your machine. No telemetry, analytics, or remote network calls are made.
165
+ * **Bounded execution:** Subprocess checks employ strict execution timeouts to prevent hanging processes.
166
+ * **No shell execution:** Commands are executed directly as argument vectors (`shell=False`).
167
+ * **Security boundary on `--probe-python`:** Because a kernelspec `argv` can point to any program, running `--probe-python` executes that interpreter. Only pass `--probe-python` for kernelspecs and environments you trust.
168
+
169
+ ---
170
+
171
+ ## Development
172
+
173
+ KernelContract has zero external runtime dependencies and requires Python 3.10+.
174
+
175
+ ```bash
176
+ git clone https://github.com/Ayushxsingh100/kernelcontract.git
177
+ cd kernelcontract
178
+ python -m venv .venv
179
+ # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
180
+ python -m pip install -e ".[test]"
181
+ python -m unittest discover -s tests -v
182
+ python -m pytest -q
183
+ ```
184
+
185
+ Issues and feature requests are welcome at [GitHub Issues](https://github.com/Ayushxsingh100/kernelcontract/issues).
186
+
187
+ ---
188
+
189
+ ## Status and metadata
190
+
191
+ * **Published version:** `0.1.0a4` (Alpha release)
192
+ * **PyPI project page:** [https://pypi.org/project/kernelcontract/](https://pypi.org/project/kernelcontract/)
193
+ * **PyPI version page (0.1.0a4):** [https://pypi.org/project/kernelcontract/0.1.0a4/](https://pypi.org/project/kernelcontract/0.1.0a4/)
194
+ * **GitHub release:** [v0.1.0a4 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4)
195
+ * **GitHub repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
196
+ * **License:** [MIT License](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
197
+
198
+ > **Note on PyPI metadata:** Package distributions published to PyPI are permanent and immutable. Version `0.1.0a4` on PyPI was built and published from release tag `v0.1.0a4`.
{kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/pyproject.toml RENAMED
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "kernelcontract"
7
- version = "0.1.0a3"
7
+ version = "0.1.0a4"
8
8
  description = "Read-only diagnostics for Jupyter kernels and Python environments"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
{kernelcontract-0.1.0a3 → kernelcontract-0.1.0a4}/src/kernelcontract/__init__.py RENAMED
@@ -1,3 +1,3 @@
1
1
  """KernelContract: read-only diagnostics for Jupyter kernels and Python environments."""
2
2
 
3
- __version__ = "0.1.0a3"
3
+ __version__ = "0.1.0a4"
kernelcontract-0.1.0a4/src/kernelcontract.egg-info/PKG-INFO ADDED
@@ -0,0 +1,246 @@
1
+ Metadata-Version: 2.4
2
+ Name: kernelcontract
3
+ Version: 0.1.0a4
4
+ Summary: Read-only diagnostics for Jupyter kernels and Python environments
5
+ Author: KernelContract contributors
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 KernelContract contributors
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Keywords: jupyter,notebook,kernel,diagnostics,python-environments
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Environment :: Console
31
+ Classifier: Intended Audience :: Developers
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Operating System :: OS Independent
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Programming Language :: Python :: 3.13
39
+ Classifier: Topic :: Scientific/Engineering
40
+ Classifier: Topic :: Software Development :: Debuggers
41
+ Classifier: Topic :: Utilities
42
+ Requires-Python: >=3.10
43
+ Description-Content-Type: text/markdown
44
+ License-File: LICENSE
45
+ Provides-Extra: test
46
+ Requires-Dist: pytest>=8.0; extra == "test"
47
+ Dynamic: license-file
48
+
49
+ # KernelContract
50
+
51
+ **Stop guessing which Jupyter kernel your notebook is using.**
52
+
53
+ KernelContract performs local, read-only diagnostics on Jupyter kernelspecs, Python executables, and notebook kernel metadata to identify configuration problems and environment drift before execution.
54
+
55
+ [![PyPI Version](https://img.shields.io/pypi/v/kernelcontract?include_prereleases)](https://pypi.org/project/kernelcontract/)
56
+ [![Python Versions](https://img.shields.io/pypi/pyversions/kernelcontract)](https://pypi.org/project/kernelcontract/)
57
+ [![MIT License](https://img.shields.io/github/license/Ayushxsingh100/kernelcontract)](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
58
+ [![CI Status](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Ayushxsingh100/kernelcontract/actions/workflows/ci.yml)
59
+
60
+ > **Alpha Release (`0.1.0a4`):** KernelContract is published on [PyPI](https://pypi.org/project/kernelcontract/) (see [version 0.1.0a4](https://pypi.org/project/kernelcontract/0.1.0a4/)) and tagged on [GitHub](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4) as an early-stage diagnostic tool. It performs strictly local, read-only checks and will never modify your packages, configuration files, or notebook contents.
61
+
62
+ ---
63
+
64
+ ## Quick start
65
+
66
+ ### Prerequisites
67
+
68
+ * **Python:** 3.10, 3.11, 3.12, or 3.13.
69
+ * **Jupyter CLI on PATH:** KernelContract has **zero external runtime dependencies** (Python standard library only), but requires that the `jupyter` command (such as via `jupyter-core`) is available on your `PATH` for kernel discovery (`jupyter kernelspec list --json`). The Jupyter CLI is not automatically bundled with KernelContract.
70
+
71
+ ### Installation
72
+
73
+ #### Primary: Install from PyPI
74
+
75
+ Install the published alpha release directly from [PyPI](https://pypi.org/project/kernelcontract/):
76
+
77
+ ```bash
78
+ python -m pip install --pre kernelcontract==0.1.0a4
79
+ ```
80
+
81
+ *(The `--pre` flag is required because `0.1.0a4` is an alpha pre-release; `pip` requires `--pre` to allow installing alpha and pre-release packages).*
82
+
83
+ #### Alternative: Install from tagged GitHub release (for developers)
84
+
85
+ Developers or contributors who wish to install directly from the tagged release on GitHub can use:
86
+
87
+ ```bash
88
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a4"
89
+ ```
90
+
91
+ To install the latest development snapshot from the default `master` branch:
92
+
93
+ ```bash
94
+ python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
95
+ ```
96
+
97
+ ---
98
+
99
+ ## The problem: silent notebook mismatches
100
+
101
+ Jupyter notebook failures are frequently caused by environment mismatches rather than faulty notebook code:
102
+
103
+ * **Missing kernels:** A shared or cloned `.ipynb` references a kernel (e.g. `pytorch-env` or `python-3.11`) that was never registered on your machine.
104
+ * **Broken executables:** A registered kernelspec points to a Python interpreter in a virtual environment that was moved, upgraded, or deleted.
105
+ * **Interpreter drift:** The Jupyter server runs in one environment while a kernel executes in another environment that lacks `ipykernel` or companion packages like `jupyterlab_widgets`.
106
+ * **Metadata drift:** A notebook declares a display name (e.g. `Python (DataScience)`) that silently points to an entirely different interpreter on disk.
107
+
108
+ When these issues occur, notebooks either fail on startup, hang, or silently fall back to an arbitrary default interpreter with different packages installed.
109
+
110
+ **KernelContract gives you deterministic, read-only visibility into your Jupyter setup before running code.**
111
+
112
+ ---
113
+
114
+ ## See it in action
115
+
116
+ ### 1. Diagnose registered kernels: `kernelcontract doctor`
117
+
118
+ Inspect all discovered kernelspecs, check executable paths, and verify control interpreter health:
119
+
120
+ ```console
121
+ $ kernelcontract doctor
122
+ KernelContract 0.1.0a4 - doctor
123
+ ============================================
124
+ PASS Current Python (control environment)
125
+ Python 3.12.10 is executable.
126
+ INFO Server interpreter not inferred
127
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
128
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
129
+ PASS Discover Jupyter kernels
130
+ Found 1 registered kernelspec(s).
131
+ PASS python3: executable exists
132
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
133
+ PASS python3: ipykernel importable
134
+ Python 3.12.10 starts and ipykernel is installed (version 6.29.5).
135
+
136
+ Summary: 4 pass, 1 info, 0 warning(s), 0 failure(s).
137
+ Overall status: PASS
138
+ KernelContract did not modify packages or environments.
139
+ ```
140
+
141
+ ### 2. Validate notebook kernel metadata: `kernelcontract notebook`
142
+
143
+ Check whether a notebook file's declared kernel exists and matches registered kernelspecs:
144
+
145
+ ```console
146
+ $ kernelcontract notebook analysis.ipynb
147
+ KernelContract 0.1.0a4 - notebook
148
+ ============================================
149
+ PASS Current Python (control environment)
150
+ Python 3.12.10 is executable.
151
+ INFO Server interpreter not inferred
152
+ The current Python is used as a control environment; it is not assumed to be the actual Jupyter server Python.
153
+ Next: Re-run with --server-python /absolute/path/to/server/python when Jupyter runs from another environment.
154
+ PASS Discover Jupyter kernels
155
+ Found 1 registered kernelspec(s).
156
+ PASS python3: executable exists
157
+ Resolved kernelspec executable to C:\Users\user\AppData\Local\Programs\Python\Python312\python.exe.
158
+ FAIL Notebook kernel is registered
159
+ Notebook requests kernel 'pytorch-env', but that name is not in the discovered kernelspec list.
160
+ Next: Register the intended kernel or select an installed kernel in Jupyter and save the notebook. Do not assume a fallback kernel is equivalent.
161
+
162
+ Summary: 3 pass, 1 info, 0 warning(s), 1 failure(s).
163
+ Overall status: FAIL
164
+ KernelContract did not modify packages or environments.
165
+ ```
166
+
167
+ *In this example, KernelContract caught a missing `pytorch-env` kernel before the user ran the notebook, preventing silent fallback to an unintended environment.*
168
+
169
+ ---
170
+
171
+ ## Key capabilities
172
+
173
+ * **Kernelspec discovery:** Enumerates registered Jupyter kernels using standard `jupyter kernelspec list --json`.
174
+ * **Executable resolution:** Resolves the `argv[0]` command across platforms, including Windows `PATHEXT` (`.exe`, `.cmd`, `.bat`), quoted paths with spaces, and environment variable expansion.
175
+ * **Environment inspection:** Checks that Python interpreters can start and verifies the presence of `ipykernel`.
176
+ * **Notebook validation:** Confirms that notebook `.ipynb` files reference valid, registered kernels and detects display-name drift.
177
+ * **Structured JSON output:** Export versioned machine-readable reports (`--json`) for automation, pre-commit hooks, and CI pipelines.
178
+ * **Strict CI mode:** Exit non-zero on warnings with `--strict` (failures always exit with code 1; passes/warnings exit 0 by default).
179
+ * **Companion package checks:** Detects presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
180
+ * **Opt-in external probing:** Probes external Python kernels only when explicitly authorized with `--probe-python`.
181
+
182
+ ---
183
+
184
+ ## Capability summary
185
+
186
+ | Capability | What KernelContract does |
187
+ |---|---|
188
+ | **Kernelspec Discovery** | Queries Jupyter CLI for registered kernelspecs; returns structured discovery errors if output is missing or malformed. |
189
+ | **Executable Verification** | Validates that `argv[0]` resolves to a real executable file on disk without executing third-party code. |
190
+ | **Environment Drift Detection** | Compares the control Python prefix with the kernel Python prefix to detect cross-environment execution. |
191
+ | **Notebook Validation** | Reads notebook JSON metadata and verifies that the requested `kernelspec.name` is registered on the local machine. |
192
+ | **CI & Tooling Integration** | Provides predictable exit codes (`0` for pass/warn, `1` for fail, `--strict` fails on warn) and versioned JSON output. |
193
+ | **Remediation Suggestions** | Supplies concrete, human-readable `Next:` steps for every failing or warning check. |
194
+ | **System Modification** | **None.** Operates strictly read-only; never installs, uninstalls, or modifies files or environments. |
195
+
196
+ ---
197
+
198
+ ## Scope and boundaries
199
+
200
+ * **Strictly read-only:** KernelContract will not repair environments, modify paths, install packages, or rewrite notebook files automatically.
201
+ * **Execution guarantee:** Passing KernelContract checks confirms kernel configuration integrity; it does not guarantee that a notebook's internal code will execute without Python runtime errors.
202
+ * **Server vs. control interpreter:** KernelContract cannot automatically determine which Python interpreter runs an existing Jupyter server process across all containers, services, and launchers. By default, the Python interpreter running KernelContract acts as the **control environment**. To specify the server Python interpreter explicitly, use:
203
+ ```bash
204
+ kernelcontract doctor --server-python /path/to/server/python
205
+ ```
206
+ * **External interpreter probing:** By default, KernelContract only executes package inspection on the control Python interpreter. External interpreters are not executed unless you pass `--probe-python`.
207
+
208
+ ---
209
+
210
+ ## Security and privacy
211
+
212
+ * **100% Local:** Runs entirely on your machine. No telemetry, analytics, or remote network calls are made.
213
+ * **Bounded execution:** Subprocess checks employ strict execution timeouts to prevent hanging processes.
214
+ * **No shell execution:** Commands are executed directly as argument vectors (`shell=False`).
215
+ * **Security boundary on `--probe-python`:** Because a kernelspec `argv` can point to any program, running `--probe-python` executes that interpreter. Only pass `--probe-python` for kernelspecs and environments you trust.
216
+
217
+ ---
218
+
219
+ ## Development
220
+
221
+ KernelContract has zero external runtime dependencies and requires Python 3.10+.
222
+
223
+ ```bash
224
+ git clone https://github.com/Ayushxsingh100/kernelcontract.git
225
+ cd kernelcontract
226
+ python -m venv .venv
227
+ # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
228
+ python -m pip install -e ".[test]"
229
+ python -m unittest discover -s tests -v
230
+ python -m pytest -q
231
+ ```
232
+
233
+ Issues and feature requests are welcome at [GitHub Issues](https://github.com/Ayushxsingh100/kernelcontract/issues).
234
+
235
+ ---
236
+
237
+ ## Status and metadata
238
+
239
+ * **Published version:** `0.1.0a4` (Alpha release)
240
+ * **PyPI project page:** [https://pypi.org/project/kernelcontract/](https://pypi.org/project/kernelcontract/)
241
+ * **PyPI version page (0.1.0a4):** [https://pypi.org/project/kernelcontract/0.1.0a4/](https://pypi.org/project/kernelcontract/0.1.0a4/)
242
+ * **GitHub release:** [v0.1.0a4 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a4)
243
+ * **GitHub repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
244
+ * **License:** [MIT License](https://github.com/Ayushxsingh100/kernelcontract/blob/master/LICENSE)
245
+
246
+ > **Note on PyPI metadata:** Package distributions published to PyPI are permanent and immutable. Version `0.1.0a4` on PyPI was built and published from release tag `v0.1.0a4`.
kernelcontract-0.1.0a3/PKG-INFO DELETED
@@ -1,188 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: kernelcontract
3
- Version: 0.1.0a3
4
- Summary: Read-only diagnostics for Jupyter kernels and Python environments
5
- Author: KernelContract contributors
6
- License: MIT License
7
-
8
- Copyright (c) 2026 KernelContract contributors
9
-
10
- Permission is hereby granted, free of charge, to any person obtaining a copy
11
- of this software and associated documentation files (the "Software"), to deal
12
- in the Software without restriction, including without limitation the rights
13
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
- copies of the Software, and to permit persons to whom the Software is
15
- furnished to do so, subject to the following conditions:
16
-
17
- The above copyright notice and this permission notice shall be included in all
18
- copies or substantial portions of the Software.
19
-
20
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
- SOFTWARE.
27
-
28
- Keywords: jupyter,notebook,kernel,diagnostics,python-environments
29
- Classifier: Development Status :: 3 - Alpha
30
- Classifier: Environment :: Console
31
- Classifier: Intended Audience :: Developers
32
- Classifier: License :: OSI Approved :: MIT License
33
- Classifier: Operating System :: OS Independent
34
- Classifier: Programming Language :: Python :: 3
35
- Classifier: Programming Language :: Python :: 3.10
36
- Classifier: Programming Language :: Python :: 3.11
37
- Classifier: Programming Language :: Python :: 3.12
38
- Classifier: Programming Language :: Python :: 3.13
39
- Classifier: Topic :: Scientific/Engineering
40
- Classifier: Topic :: Software Development :: Debuggers
41
- Classifier: Topic :: Utilities
42
- Requires-Python: >=3.10
43
- Description-Content-Type: text/markdown
44
- License-File: LICENSE
45
- Provides-Extra: test
46
- Requires-Dist: pytest>=8.0; extra == "test"
47
- Dynamic: license-file
48
-
49
- # KernelContract
50
-
51
- **Local-first, read-only diagnostics for Jupyter kernels, kernelspecs, and notebook environments.**
52
-
53
- KernelContract inspects registered Jupyter kernelspecs, checks whether their configured executables resolve, probes Python kernel environments, and compares notebook kernel metadata with the kernels available to the current Jupyter CLI. It reports likely configuration mismatches, missing interpreters, and safe next steps without modifying the machine.
54
-
55
- > **Alpha Software — Candidate 0.1.0a3 (Latest tagged pre-release: [v0.1.0a2](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)).** KernelContract is an early-stage diagnostic tool under active development. The latest published GitHub pre-release is `v0.1.0a2`, and the current default branch is preparing candidate `0.1.0a3` for PyPI Trusted Publishing. It has **not** yet been published to PyPI. The project name is provisional and has not been trademark- or registry-cleared.
56
-
57
- ---
58
-
59
- ## Quick start
60
-
61
- ### Prerequisites
62
-
63
- * **Python 3.10 or newer.**
64
- * **Jupyter CLI on PATH:** KernelContract has zero external runtime dependencies (it uses the Python standard library only), but it requires that the `jupyter` command is available on your `PATH` (such as via `jupyter-core`) to discover registered kernels via `jupyter kernelspec list --json`.
65
-
66
- ### End-user installation (pre-release)
67
-
68
- Install the tagged alpha pre-release directly from GitHub using `pip`:
69
-
70
- ```bash
71
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a3"
72
- ```
73
-
74
- Or install the latest development snapshot from the default `master` branch:
75
-
76
- ```bash
77
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
78
- ```
79
-
80
- > **Note on PyPI:** The command `pip install kernelcontract` is reserved for future distribution once the package is officially published to the Python Package Index.
81
-
82
- ---
83
-
84
- ## Core usage
85
-
86
- ### 1. Diagnose registered Jupyter kernels
87
-
88
- Run the `doctor` command to inspect all discovered kernelspecs, verify their executables, and check the active Python environment:
89
-
90
- ```bash
91
- kernelcontract doctor
92
- ```
93
-
94
- ### 2. Validate notebook kernel metadata
95
-
96
- Inspect whether a `.ipynb` file's declared kernel exists and matches currently registered kernelspecs:
97
-
98
- ```bash
99
- kernelcontract notebook path/to/notebook.ipynb
100
- ```
101
-
102
- If the notebook requests an unavailable kernel or if the kernel's stored display name has drifted from disk, KernelContract reports the issue with actionable next steps.
103
-
104
- ### 3. Machine-readable JSON output
105
-
106
- Produce structured, versioned JSON suitable for automated tooling, pre-commit hooks, or CI pipelines:
107
-
108
- ```bash
109
- kernelcontract doctor --json
110
- kernelcontract notebook path/to/notebook.ipynb --json
111
- ```
112
-
113
- The JSON schema output includes `schema_version`, `status` (`PASS`, `WARN`, `FAIL`), check details, and specific remediation suggestions.
114
-
115
- ### 4. Strict CI mode
116
-
117
- By default, `FAIL` makes the command exit with status 1, while warnings exit with status 0. To fail CI on warnings as well as failures, pass `--strict`:
118
-
119
- ```bash
120
- kernelcontract doctor --strict
121
- ```
122
-
123
- ### 5. Probing external Python kernels (opt-in)
124
-
125
- ```bash
126
- kernelcontract doctor --probe-python
127
- ```
128
-
129
- * **Security Note:** By default, KernelContract only executes package inspection on the current control interpreter and kernels that resolve to the exact same executable. Interpreters outside the current environment are **not** executed unless you pass `--probe-python`. Use `--probe-python` only with kernelspecs and environments you trust.
130
-
131
- ---
132
-
133
- ## What it checks
134
-
135
- * **CLI Discovery:** Whether the Jupyter CLI can enumerate kernelspecs using `jupyter kernelspec list --json`.
136
- * **JSON Structure Safety:** Whether kernelspec outputs have valid root structures and dictionary objects.
137
- * **Executable Resolution:** Whether each registered kernelspec has a resolvable `argv[0]` executable (including Windows `PATHEXT` resolution for `.exe`, `.cmd`, `.bat`, quoted paths with spaces, and environment variable expansion).
138
- * **Environment Integrity:** Whether the control Python (and, when opted in, external Python kernels) can start and whether `ipykernel` is installed in that interpreter.
139
- * **Environment Drift:** Whether a probed kernel's Python prefix differs from the control interpreter.
140
- * **Widget Companion Check:** A narrow check for presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
141
- * **Notebook Metadata Check:** Whether a notebook file declares a kernel name that is currently registered and whether the recorded display name matches the kernelspec on disk.
142
-
143
- ---
144
-
145
- ## Server vs. kernel environments
146
-
147
- KernelContract cannot reliably infer which Python interpreter belongs to an already-running Jupyter server across diverse setups (e.g. systemd services, Docker containers, remote SSH tunnels, JupyterHub). By default, it uses the Python interpreter launching KernelContract as its **control environment**.
148
-
149
- If you know the specific Python interpreter running the Jupyter server, pass it explicitly:
150
-
151
- ```bash
152
- kernelcontract doctor --server-python /absolute/path/to/server/python
153
- ```
154
-
155
- ---
156
-
157
- ## Safety and privacy guarantees
158
-
159
- * **Strictly Read-Only:** KernelContract modifies no packages, rewrites no files, and changes no configuration.
160
- * **No Telemetry:** Zero analytics, telemetry, or network calls are made by KernelContract.
161
- * **Bounded Subprocesses:** Subprocess probes use strict execution timeouts to avoid hanging indefinitely.
162
- * **No Shell Execution:** Commands are executed directly with argument lists (`shell=False`).
163
-
164
- ---
165
-
166
- ## Development
167
-
168
- To contribute or run the test suite locally from source:
169
-
170
- ```bash
171
- git clone https://github.com/Ayushxsingh100/kernelcontract.git
172
- cd kernelcontract
173
- python -m venv .venv
174
- # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
175
- python -m pip install -e ".[test]"
176
- python -m unittest discover -s tests -v
177
- python -m pytest -q
178
- ```
179
-
180
- ---
181
-
182
- ## Status
183
-
184
- * **Version:** `0.1.0a3` (alpha candidate; latest tagged pre-release: [`v0.1.0a2`](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2))
185
- * **Repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
186
- * **Pre-release Notes:** [v0.1.0a2 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)
187
- * **License:** [MIT](LICENSE)
188
- * **Stability:** Alpha
kernelcontract-0.1.0a3/README.md DELETED
@@ -1,140 +0,0 @@
1
- # KernelContract
2
-
3
- **Local-first, read-only diagnostics for Jupyter kernels, kernelspecs, and notebook environments.**
4
-
5
- KernelContract inspects registered Jupyter kernelspecs, checks whether their configured executables resolve, probes Python kernel environments, and compares notebook kernel metadata with the kernels available to the current Jupyter CLI. It reports likely configuration mismatches, missing interpreters, and safe next steps without modifying the machine.
6
-
7
- > **Alpha Software — Candidate 0.1.0a3 (Latest tagged pre-release: [v0.1.0a2](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)).** KernelContract is an early-stage diagnostic tool under active development. The latest published GitHub pre-release is `v0.1.0a2`, and the current default branch is preparing candidate `0.1.0a3` for PyPI Trusted Publishing. It has **not** yet been published to PyPI. The project name is provisional and has not been trademark- or registry-cleared.
8
-
9
- ---
10
-
11
- ## Quick start
12
-
13
- ### Prerequisites
14
-
15
- * **Python 3.10 or newer.**
16
- * **Jupyter CLI on PATH:** KernelContract has zero external runtime dependencies (it uses the Python standard library only), but it requires that the `jupyter` command is available on your `PATH` (such as via `jupyter-core`) to discover registered kernels via `jupyter kernelspec list --json`.
17
-
18
- ### End-user installation (pre-release)
19
-
20
- Install the tagged alpha pre-release directly from GitHub using `pip`:
21
-
22
- ```bash
23
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a3"
24
- ```
25
-
26
- Or install the latest development snapshot from the default `master` branch:
27
-
28
- ```bash
29
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
30
- ```
31
-
32
- > **Note on PyPI:** The command `pip install kernelcontract` is reserved for future distribution once the package is officially published to the Python Package Index.
33
-
34
- ---
35
-
36
- ## Core usage
37
-
38
- ### 1. Diagnose registered Jupyter kernels
39
-
40
- Run the `doctor` command to inspect all discovered kernelspecs, verify their executables, and check the active Python environment:
41
-
42
- ```bash
43
- kernelcontract doctor
44
- ```
45
-
46
- ### 2. Validate notebook kernel metadata
47
-
48
- Inspect whether a `.ipynb` file's declared kernel exists and matches currently registered kernelspecs:
49
-
50
- ```bash
51
- kernelcontract notebook path/to/notebook.ipynb
52
- ```
53
-
54
- If the notebook requests an unavailable kernel or if the kernel's stored display name has drifted from disk, KernelContract reports the issue with actionable next steps.
55
-
56
- ### 3. Machine-readable JSON output
57
-
58
- Produce structured, versioned JSON suitable for automated tooling, pre-commit hooks, or CI pipelines:
59
-
60
- ```bash
61
- kernelcontract doctor --json
62
- kernelcontract notebook path/to/notebook.ipynb --json
63
- ```
64
-
65
- The JSON schema output includes `schema_version`, `status` (`PASS`, `WARN`, `FAIL`), check details, and specific remediation suggestions.
66
-
67
- ### 4. Strict CI mode
68
-
69
- By default, `FAIL` makes the command exit with status 1, while warnings exit with status 0. To fail CI on warnings as well as failures, pass `--strict`:
70
-
71
- ```bash
72
- kernelcontract doctor --strict
73
- ```
74
-
75
- ### 5. Probing external Python kernels (opt-in)
76
-
77
- ```bash
78
- kernelcontract doctor --probe-python
79
- ```
80
-
81
- * **Security Note:** By default, KernelContract only executes package inspection on the current control interpreter and kernels that resolve to the exact same executable. Interpreters outside the current environment are **not** executed unless you pass `--probe-python`. Use `--probe-python` only with kernelspecs and environments you trust.
82
-
83
- ---
84
-
85
- ## What it checks
86
-
87
- * **CLI Discovery:** Whether the Jupyter CLI can enumerate kernelspecs using `jupyter kernelspec list --json`.
88
- * **JSON Structure Safety:** Whether kernelspec outputs have valid root structures and dictionary objects.
89
- * **Executable Resolution:** Whether each registered kernelspec has a resolvable `argv[0]` executable (including Windows `PATHEXT` resolution for `.exe`, `.cmd`, `.bat`, quoted paths with spaces, and environment variable expansion).
90
- * **Environment Integrity:** Whether the control Python (and, when opted in, external Python kernels) can start and whether `ipykernel` is installed in that interpreter.
91
- * **Environment Drift:** Whether a probed kernel's Python prefix differs from the control interpreter.
92
- * **Widget Companion Check:** A narrow check for presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
93
- * **Notebook Metadata Check:** Whether a notebook file declares a kernel name that is currently registered and whether the recorded display name matches the kernelspec on disk.
94
-
95
- ---
96
-
97
- ## Server vs. kernel environments
98
-
99
- KernelContract cannot reliably infer which Python interpreter belongs to an already-running Jupyter server across diverse setups (e.g. systemd services, Docker containers, remote SSH tunnels, JupyterHub). By default, it uses the Python interpreter launching KernelContract as its **control environment**.
100
-
101
- If you know the specific Python interpreter running the Jupyter server, pass it explicitly:
102
-
103
- ```bash
104
- kernelcontract doctor --server-python /absolute/path/to/server/python
105
- ```
106
-
107
- ---
108
-
109
- ## Safety and privacy guarantees
110
-
111
- * **Strictly Read-Only:** KernelContract modifies no packages, rewrites no files, and changes no configuration.
112
- * **No Telemetry:** Zero analytics, telemetry, or network calls are made by KernelContract.
113
- * **Bounded Subprocesses:** Subprocess probes use strict execution timeouts to avoid hanging indefinitely.
114
- * **No Shell Execution:** Commands are executed directly with argument lists (`shell=False`).
115
-
116
- ---
117
-
118
- ## Development
119
-
120
- To contribute or run the test suite locally from source:
121
-
122
- ```bash
123
- git clone https://github.com/Ayushxsingh100/kernelcontract.git
124
- cd kernelcontract
125
- python -m venv .venv
126
- # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
127
- python -m pip install -e ".[test]"
128
- python -m unittest discover -s tests -v
129
- python -m pytest -q
130
- ```
131
-
132
- ---
133
-
134
- ## Status
135
-
136
- * **Version:** `0.1.0a3` (alpha candidate; latest tagged pre-release: [`v0.1.0a2`](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2))
137
- * **Repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
138
- * **Pre-release Notes:** [v0.1.0a2 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)
139
- * **License:** [MIT](LICENSE)
140
- * **Stability:** Alpha
kernelcontract-0.1.0a3/src/kernelcontract.egg-info/PKG-INFO DELETED
@@ -1,188 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: kernelcontract
3
- Version: 0.1.0a3
4
- Summary: Read-only diagnostics for Jupyter kernels and Python environments
5
- Author: KernelContract contributors
6
- License: MIT License
7
-
8
- Copyright (c) 2026 KernelContract contributors
9
-
10
- Permission is hereby granted, free of charge, to any person obtaining a copy
11
- of this software and associated documentation files (the "Software"), to deal
12
- in the Software without restriction, including without limitation the rights
13
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
- copies of the Software, and to permit persons to whom the Software is
15
- furnished to do so, subject to the following conditions:
16
-
17
- The above copyright notice and this permission notice shall be included in all
18
- copies or substantial portions of the Software.
19
-
20
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
- SOFTWARE.
27
-
28
- Keywords: jupyter,notebook,kernel,diagnostics,python-environments
29
- Classifier: Development Status :: 3 - Alpha
30
- Classifier: Environment :: Console
31
- Classifier: Intended Audience :: Developers
32
- Classifier: License :: OSI Approved :: MIT License
33
- Classifier: Operating System :: OS Independent
34
- Classifier: Programming Language :: Python :: 3
35
- Classifier: Programming Language :: Python :: 3.10
36
- Classifier: Programming Language :: Python :: 3.11
37
- Classifier: Programming Language :: Python :: 3.12
38
- Classifier: Programming Language :: Python :: 3.13
39
- Classifier: Topic :: Scientific/Engineering
40
- Classifier: Topic :: Software Development :: Debuggers
41
- Classifier: Topic :: Utilities
42
- Requires-Python: >=3.10
43
- Description-Content-Type: text/markdown
44
- License-File: LICENSE
45
- Provides-Extra: test
46
- Requires-Dist: pytest>=8.0; extra == "test"
47
- Dynamic: license-file
48
-
49
- # KernelContract
50
-
51
- **Local-first, read-only diagnostics for Jupyter kernels, kernelspecs, and notebook environments.**
52
-
53
- KernelContract inspects registered Jupyter kernelspecs, checks whether their configured executables resolve, probes Python kernel environments, and compares notebook kernel metadata with the kernels available to the current Jupyter CLI. It reports likely configuration mismatches, missing interpreters, and safe next steps without modifying the machine.
54
-
55
- > **Alpha Software — Candidate 0.1.0a3 (Latest tagged pre-release: [v0.1.0a2](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)).** KernelContract is an early-stage diagnostic tool under active development. The latest published GitHub pre-release is `v0.1.0a2`, and the current default branch is preparing candidate `0.1.0a3` for PyPI Trusted Publishing. It has **not** yet been published to PyPI. The project name is provisional and has not been trademark- or registry-cleared.
56
-
57
- ---
58
-
59
- ## Quick start
60
-
61
- ### Prerequisites
62
-
63
- * **Python 3.10 or newer.**
64
- * **Jupyter CLI on PATH:** KernelContract has zero external runtime dependencies (it uses the Python standard library only), but it requires that the `jupyter` command is available on your `PATH` (such as via `jupyter-core`) to discover registered kernels via `jupyter kernelspec list --json`.
65
-
66
- ### End-user installation (pre-release)
67
-
68
- Install the tagged alpha pre-release directly from GitHub using `pip`:
69
-
70
- ```bash
71
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git@v0.1.0a3"
72
- ```
73
-
74
- Or install the latest development snapshot from the default `master` branch:
75
-
76
- ```bash
77
- python -m pip install "git+https://github.com/Ayushxsingh100/kernelcontract.git"
78
- ```
79
-
80
- > **Note on PyPI:** The command `pip install kernelcontract` is reserved for future distribution once the package is officially published to the Python Package Index.
81
-
82
- ---
83
-
84
- ## Core usage
85
-
86
- ### 1. Diagnose registered Jupyter kernels
87
-
88
- Run the `doctor` command to inspect all discovered kernelspecs, verify their executables, and check the active Python environment:
89
-
90
- ```bash
91
- kernelcontract doctor
92
- ```
93
-
94
- ### 2. Validate notebook kernel metadata
95
-
96
- Inspect whether a `.ipynb` file's declared kernel exists and matches currently registered kernelspecs:
97
-
98
- ```bash
99
- kernelcontract notebook path/to/notebook.ipynb
100
- ```
101
-
102
- If the notebook requests an unavailable kernel or if the kernel's stored display name has drifted from disk, KernelContract reports the issue with actionable next steps.
103
-
104
- ### 3. Machine-readable JSON output
105
-
106
- Produce structured, versioned JSON suitable for automated tooling, pre-commit hooks, or CI pipelines:
107
-
108
- ```bash
109
- kernelcontract doctor --json
110
- kernelcontract notebook path/to/notebook.ipynb --json
111
- ```
112
-
113
- The JSON schema output includes `schema_version`, `status` (`PASS`, `WARN`, `FAIL`), check details, and specific remediation suggestions.
114
-
115
- ### 4. Strict CI mode
116
-
117
- By default, `FAIL` makes the command exit with status 1, while warnings exit with status 0. To fail CI on warnings as well as failures, pass `--strict`:
118
-
119
- ```bash
120
- kernelcontract doctor --strict
121
- ```
122
-
123
- ### 5. Probing external Python kernels (opt-in)
124
-
125
- ```bash
126
- kernelcontract doctor --probe-python
127
- ```
128
-
129
- * **Security Note:** By default, KernelContract only executes package inspection on the current control interpreter and kernels that resolve to the exact same executable. Interpreters outside the current environment are **not** executed unless you pass `--probe-python`. Use `--probe-python` only with kernelspecs and environments you trust.
130
-
131
- ---
132
-
133
- ## What it checks
134
-
135
- * **CLI Discovery:** Whether the Jupyter CLI can enumerate kernelspecs using `jupyter kernelspec list --json`.
136
- * **JSON Structure Safety:** Whether kernelspec outputs have valid root structures and dictionary objects.
137
- * **Executable Resolution:** Whether each registered kernelspec has a resolvable `argv[0]` executable (including Windows `PATHEXT` resolution for `.exe`, `.cmd`, `.bat`, quoted paths with spaces, and environment variable expansion).
138
- * **Environment Integrity:** Whether the control Python (and, when opted in, external Python kernels) can start and whether `ipykernel` is installed in that interpreter.
139
- * **Environment Drift:** Whether a probed kernel's Python prefix differs from the control interpreter.
140
- * **Widget Companion Check:** A narrow check for presence of `jupyterlab_widgets` when the control environment contains JupyterLab and a probed kernel contains `ipywidgets`.
141
- * **Notebook Metadata Check:** Whether a notebook file declares a kernel name that is currently registered and whether the recorded display name matches the kernelspec on disk.
142
-
143
- ---
144
-
145
- ## Server vs. kernel environments
146
-
147
- KernelContract cannot reliably infer which Python interpreter belongs to an already-running Jupyter server across diverse setups (e.g. systemd services, Docker containers, remote SSH tunnels, JupyterHub). By default, it uses the Python interpreter launching KernelContract as its **control environment**.
148
-
149
- If you know the specific Python interpreter running the Jupyter server, pass it explicitly:
150
-
151
- ```bash
152
- kernelcontract doctor --server-python /absolute/path/to/server/python
153
- ```
154
-
155
- ---
156
-
157
- ## Safety and privacy guarantees
158
-
159
- * **Strictly Read-Only:** KernelContract modifies no packages, rewrites no files, and changes no configuration.
160
- * **No Telemetry:** Zero analytics, telemetry, or network calls are made by KernelContract.
161
- * **Bounded Subprocesses:** Subprocess probes use strict execution timeouts to avoid hanging indefinitely.
162
- * **No Shell Execution:** Commands are executed directly with argument lists (`shell=False`).
163
-
164
- ---
165
-
166
- ## Development
167
-
168
- To contribute or run the test suite locally from source:
169
-
170
- ```bash
171
- git clone https://github.com/Ayushxsingh100/kernelcontract.git
172
- cd kernelcontract
173
- python -m venv .venv
174
- # Activate .venv (Windows: .venv\Scripts\activate | Unix: source .venv/bin/activate)
175
- python -m pip install -e ".[test]"
176
- python -m unittest discover -s tests -v
177
- python -m pytest -q
178
- ```
179
-
180
- ---
181
-
182
- ## Status
183
-
184
- * **Version:** `0.1.0a3` (alpha candidate; latest tagged pre-release: [`v0.1.0a2`](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2))
185
- * **Repository:** [https://github.com/Ayushxsingh100/kernelcontract](https://github.com/Ayushxsingh100/kernelcontract)
186
- * **Pre-release Notes:** [v0.1.0a2 Release](https://github.com/Ayushxsingh100/kernelcontract/releases/tag/v0.1.0a2)
187
- * **License:** [MIT](LICENSE)
188
- * **Stability:** Alpha