|
| 1 | +# Python Gonol Construction |
| 2 | + |
| 3 | +Stack-local research implementation for affixiating Python source into gonols from its lowest admitted source units upward. |
| 4 | + |
| 5 | +## Construction |
| 6 | + |
| 7 | +```text |
| 8 | +exact decoded source occurrences |
| 9 | + -> character gonols |
| 10 | + -> character-definition gonols sharing each character origin |
| 11 | + -> Python lexical-form gonols from closed character occurrences |
| 12 | + -> matched delimiter gonols |
| 13 | + -> recursive Python grammar-construction gonols |
| 14 | + -> module gonol |
| 15 | +``` |
| 16 | + |
| 17 | +Every source occurrence remains independently addressable. Every character may close multiple definition gonols without changing the character's identity: Unicode category/name, Python identifier eligibility, exact-token membership, layout role, quote/comment introducer role, and other profile-backed definitions may coexist. Lexical forms consume the already-closed character occurrences atomically; larger constructions consume already-closed lexical or construction gonols atomically. |
| 18 | + |
| 19 | +`character` means one exact decoded Unicode scalar occurrence. Spaces, newlines, digits, operators, delimiters, letters, and punctuation are all character gonols. Nothing is normalized, deduplicated, trimmed, or silently discarded. |
| 20 | + |
| 21 | +## Recognition boundary |
| 22 | + |
| 23 | +```text |
| 24 | +METAPAT affixiation semantics |
| 25 | + -> UCNS geometry and Public Gonol positions |
| 26 | + -> Python Gonol Python source admission and construction |
| 27 | + -> CPython pinned recognition witness only |
| 28 | +``` |
| 29 | + |
| 30 | +The private `_recognition` module uses CPython 3.12 `tokenize` and `ast` after the source occurrence floor has been admitted. Its former public "letter" vocabulary is deprecated and removed from the public receipt: it is now only an internal recognition plan. Token, AST, compiler, and code objects never become gonols and never replace the source-built relation graph. |
| 31 | + |
| 32 | +Any valid Python 3.12 file-input source accepted by the pinned recognition witness is traversed recursively without a grammar-node whitelist. The broad Python 3.12 surface fixture remains a regression witness; exhaustive parity against CPython's complete grammar/test corpus remains `hmmm` rather than being claimed from that fixture alone. |
| 33 | + |
| 34 | +Standing: **implemented stack-local candidate; not canon and not an independent release**. |
| 35 | + |
| 36 | +## Usage guidance |
| 37 | + |
| 38 | +Run from this directory with Python 3.12: |
| 39 | + |
| 40 | +```bash |
| 41 | +python -m python_gonol path/to/source.py --out source.gonol.json --pretty |
| 42 | +python -m python_gonol --verify source.gonol.json |
| 43 | +python -m pytest -q tests |
| 44 | +``` |
| 45 | + |
| 46 | +Use the bytes entry point for files so an encoding declaration and exact original bytes remain bound: |
| 47 | + |
| 48 | +```python |
| 49 | +from pathlib import Path |
| 50 | +from python_gonol import affixiate_python_bytes, replay_python_affixiation |
| 51 | + |
| 52 | +path = Path("example.py") |
| 53 | +receipt = affixiate_python_bytes(path.read_bytes(), source_id=path.as_posix()) |
| 54 | +replay_python_affixiation(receipt) |
| 55 | +``` |
| 56 | + |
| 57 | +For invalid or unfinished source, the constructor retains every admitted character, character-definition, lexical, and matched-delimiter closure available beneath the failure, closes a `python.source.hmmm` root, records the exact tokenizer/delimiter/grammar boundary, and the CLI exits `2`. A missing end parenthesis therefore remains visible without discarding prior construction. |
| 58 | + |
| 59 | +See [`docs/PYTHON_AFFIXIATION_BOUNDARY.md`](docs/PYTHON_AFFIXIATION_BOUNDARY.md) for the contract and [`WORK_GRAPH.json`](WORK_GRAPH.json) for exact inputs. |
| 60 | + |
| 61 | +## hmmm |
| 62 | + |
| 63 | +- exact UCNS geometric operation of Public Gonol function positions; |
| 64 | +- exact UCNS Möbius-carrier affixiation/coupling law; |
| 65 | +- exhaustive parity replay against the complete CPython 3.12 grammar/test corpus; |
| 66 | +- Python language profiles after Python 3.12 file input; |
| 67 | +- streaming/checkpointed receipt materialization for unusually large source trees. |
0 commit comments