Metadata-Version: 2.4
Name: px-idle
Version: 0.1.0
Summary: Offline keyword-driven practical-code expansion for Python IDLE Editors
License-Expression: LicenseRef-PxIdle-Local-Use
Project-URL: Practical Source, https://github.com/mcc-exam/src
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
Requires-Python: !=3.5.4,>=3.3
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# px-idle

Offline practical-code expansion inside normal Python IDLE Editor windows.
Type `#>` on a dedicated comment line to discover the complete catalogue, or
`#>spell` to filter it. Up/Down navigate, Enter or Tab insert, Escape dismisses.
The exact bundled source replaces the active trigger directly in the Text buffer
as one undo operation. Each editor has an independent popup. Shell is excluded.

## Local installation

The owner of this project and the upstream practical repository selected all
rights reserved, local use only, and authorized distribution through PyPI.
Recipients may install and use the package locally; redistribution rights are
reserved. See LICENSE. Publication awaits configured account access and
TestPyPI verification. Until then, install the local wheel:

```
python -m pip install dist/px_idle-0.1.0-py3-none-any.whl
px-idle install
```

Use the same Python installation to launch IDLE. Restart IDLE after registration.
Registration is explicit; pip installation never modifies your IDLE settings.

`px-idle status` reports registration. `px-idle doctor` checks Python, Tk, IDLE,
shim import and all bundled source hashes. `px-idle uninstall` removes only
PxIdle configuration sections; it leaves the Python package installed.
Use `--config-dir DIRECTORY` for an isolated test configuration. Existing
configuration is backed up before mutation and written atomically; malformed
configuration is backed up and left unchanged.

## Source and offline behavior

13 source entries from [mcc-exam/src](https://github.com/mcc-exam/src), snapshot
`a44c65dee9eadf37310a54bcbc90fe78df2289f3`, are bundled. See
[the audit](docs/engineering-research.md) and generated registry for mappings,
aliases, imports and resource requirements. No git, internet, clipboard or
third-party runtime packages are required for expansion. px-idle never executes
practicals. Their own execution may require matplotlib, numpy, networkx,
requests/beautifulsoup4, scikit-learn, nltk or NLTK punkt_tab data; the crawler
itself uses the internet. These dependencies are not installed by px-idle.

## Compatibility and limitations

Requires-Python is `>=3.3,!=3.5.4`, based on actual Python 3.3.5 installation
and IDLE tests. Runtime syntax deliberately avoids post-3.3 features. Source research
covers 2.7 and every 3.0–3.15 generation; it does not prove runtime compatibility.
See `research/idle-source-matrix.json` for primary-source evidence.
Exact executed Windows environments are listed below. Every passing row includes
wheel installation, CLI lifecycle, the actual IDLE loader and Editor, popup
controls, source insertion, undo, repeat expansion, real Shell exclusion,
multiple editors and safe uninstall. Full artifact results, including sdist
tests and Linux evidence, are in [the matrix](docs/compatibility-matrix.md) and
its machine-readable JSON. Metadata's minimum does not assert that untested
patch releases or operating systems have passed.

| Python on Windows 11 | Tk | Result / tier |
| --- | --- | --- |
| 3.3.5 | 8.5.11 | Passed / legacy |
| 3.4.4 | 8.6.1 | Passed / legacy |
| 3.5.4 | 8.6.4 | Unsupported: native IDLE undo segfault, also without px-idle |
| 3.6.8 | 8.6.6 | Passed / legacy |
| 3.7.9 | 8.6.9 | Passed / legacy |
| 3.8.10 | 8.6.9 | Passed / extended |
| 3.9.13 | 8.6.12 | Passed / extended |
| 3.10.11 | 8.6.12 | Passed / primary |
| 3.11.9 | 8.6.12 | Passed / primary |
| 3.12.10 | 8.6.15 | Passed / primary |
| 3.13.14 | 8.6.15 | Passed / primary |
| 3.14.8 | 9.0.4 | Passed / primary |
| 3.15.0rc3 | 9.0.4 | Passed / experimental prerelease |

Python 2.7 and 3.0–3.2 are unsupported. macOS and CPython main have no executed
runtime evidence here. Configured CI jobs do not count as observed passes.
Linux tests use Ubuntu WSL with WSLg or isolated Xvfb (recorded per run), with
distro Python 3.14.4/Tk 8.6.17 and
portable Python 3.11.17, 3.12.15, 3.13.16, 3.14.8 and 3.15.0rc3/Tk 9.0.4.
The portable Linux Python 3.10.22/Tk 9.0.4 build fails native IDLE startup even
with px-idle unregistered and is unsupported. Consult the matrix for each
artifact result; a Python version alone does not identify a tested Tk environment.
Old pip installation uses a small setup.py fallback justified by an actual
pip 9 sdist failure. Build tooling runs on modern Python; runtime has no external
dependencies. A tested local wheel is the legacy fallback. See
[publication status](docs/testpypi.md).

Triggers activate only on a line containing optional whitespace and `#>query`.
Normal comments and inline strings do not activate. Existing IDLE STRING tags
suppress multiline string triggers; delayed coloring is a known limitation to
be checked in GUI tests. Companion files require a saved primary file with the
matching original filename. Existing meaningful content is never overwritten.
The current catalogue has no companion files. Source fidelity takes priority
over modernization: practical syntax may require a newer Python than expansion.

## Development

Fetch the authoritative repository into `upstream/` and run
`python scripts/import_practicals.py upstream`. The importer reads data and ASTs,
never imports or runs repository scripts. Run `python -m unittest discover -s tests`.
Build using `python -m build`, inspect with `python -m twine check dist/*`, then
test each built artifact in a clean environment. Public upload must follow
TestPyPI validation first. Unexecuted CI jobs are never recorded as passes.
