tipy-asm 1.0.0__tar.gz

tipy_asm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Voblit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tipy_asm-1.0.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: tipy-asm
+Version: 1.0.0
+Summary: TIpy-asm: Python compiler for TI-84 Z80/eZ80 calculators
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tomli>=2; python_version < "3.11"
+Provides-Extra: images
+Requires-Dist: Pillow>=10; extra == "images"
+Dynamic: license-file
+
+# TIpy-asm
+
+TIpy-asm is a Python-based fork of [Voblit/py2ez80](https://github.com/Voblit/py2ez80),
+a compiler for writing TI calculator programs in a restricted, Python-like
+language. It compiles source on a computer; Python itself does not run on the
+calculator.
+
+## Quick start
+
+Requires Python 3.10 or newer:
+
+```powershell
+python -m pip install .
+tipy-asm new mygame
+cd mygame
+tipy-asm build
+```
+
+That creates a program you can move around with the arrow keys, and writes
+`bin\MYGAME.8xp`. CE builds need nothing else and work offline: the package
+includes fasmg for Windows and Linux (x64 and x86), plus its CE includes. On other
+systems, put fasmg on PATH. Run `tipy-asm doctor` to see what is installed.
+
+`examples\catch` is a complete small game. The package also installs the shorter
+command alias `ti84py`.
+
+## Targets
+
+- **TI-84 Plus CE assembly:** eZ80 assembly, or a `.8xp` program built with the
+  bundled fasmg.
+- **Classic TI-83+/TI-84 Plus:** Z80 assembly, or a `.8xp` program built with
+  SPASM-ng, which you install yourself.
+- **TI-84 Plus CE Flash App:** translated to C, then built and packaged with
+  CEdev and an installer project that you provide.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `tipy-asm new FOLDER` | Create a project that builds straight away |
+| `tipy-asm build [SOURCE]` | Build `.8xp` programs and assets. Add `--watch` to rebuild on save, or `--keep-asm` to keep the assembly |
+| `tipy-asm check [SOURCE]` | Report errors on each target without writing files. `--target flash` checks the Flash App backend |
+| `tipy-asm compile [SOURCE]` | Write assembly without assembling it |
+| `tipy-asm flash-app [SOURCE]` | Build a CE Flash App and its installer |
+| `tipy-asm api [LIBRARY]` | List library methods and the targets that support them |
+| `tipy-asm doctor` | Show installed tools and the project's setup |
+| `tipy-asm clean` | Delete the project's build folder |
+| `tipy-asm convert-project PATH` | Convert a CEdev or ICE project into a TIpy-asm project |
+| `tipy-asm convbin`, `convimg`, `convert-image` | Convert data and images by hand |
+| `tipy-asm convfont` | Convert `.fnt` and text-format fonts, matching CEdev's `convfont` byte for byte |
+
+With no source, commands use the project in the current folder or the nearest
+parent folder. Errors are printed as `FILE:LINE: error: MESSAGE` with the source
+line, in the original file, so editors can link to them.
+
+## Projects
+
+A project is configured under `[tool.tipy]` in its `pyproject.toml`:
+
+```toml
+[tool.tipy]
+name = "BOUNCE"          # calculator program name, 1-8 letters or digits
+main = "src/main.py"     # default
+target = "ce"            # classic, ce, or both; default ce
+bindir = "bin"           # default
+keep_asm = false
+
+[tool.tipy.toolchain]    # optional; the default is to search PATH
+ce_assembler = "tools/fasmg.exe"
+classic_assembler = "tools/spasm.exe"
+
+[tool.tipy.flash]        # used by `tipy-asm flash-app`
+project_dir = "flash"    # folder containing installer/makefile
+optimize = "speed"       # or size
+
+[[tool.tipy.assets]]     # converted into bindir by each build, when out of date
+source = "assets/hero.png"
+name = "HERO"            # AppVar name; the default comes from the file name
+kind = "sprite"          # sprite, image, font, or binary; guessed from the suffix
+```
+
+`from settings import SPEED` includes `settings.py` from the main file's folder,
+and `from game.player import move` includes `game/player.py`.
+
+Image assets need Pillow: `python -m pip install "tipy-asm[images]"`. Send the
+asset's `.8xv` to the calculator along with the program:
+
+```python
+from ti84 import sprite
+hero = sprite.load("HERO")     # 0 if the AppVar is missing
+sprite.draw(hero, x, y)
+```
+
+## Language on the assembly targets
+
+The Flash App backend supports more of Python. The assembly targets support:
+
+- Functions with parameters, defaults, keyword arguments, return values, and
+  `global`. Recursion is rejected, because function variables are static.
+- `if`/`elif`/`else`, `while`, `for ... in range()` with runtime bounds, `break`,
+  `continue`, and `exit()`.
+- `+ - * // % << >> & | ^ ~`, comparisons, `and`, `or`, `not`, and `a if c else b`.
+  Integers are signed, 24-bit on CE and 16-bit on classic, and wrap on overflow.
+  `x // 0` is 0 and `x % 0` is `x`, because a calculator program cannot raise.
+- Module-level arrays: `TABLE = (1, 2, 3)` is read-only, and `scores = [0] * 10`
+  is writable. Runtime indexes are not bounds-checked.
+- `print()` of string literals and integers, and `abs`, `min`, and `max`.
+
+Strings exist only as literals, and there are no floats, classes, or lists of
+lists.
+
+## Libraries
+
+Import them with `from ti84 import graphics, keyboard`. Run `tipy-asm api NAME`
+for each method's signature and targets. The `ti84` package also has stubs, so
+VS Code/Pylance can complete these names.
+
+| Library | Provides |
+|---|---|
+| `graphics` | Pixels, lines, rectangles, circles, triangles, text, and sprites. Coordinates and colors can be runtime values, and are clipped to the screen |
+| `keyboard` | `read()` waits for a key, `get()` returns at once, `is_down(key)` tests a held key |
+| `math` | `abs min max clamp sign sqrt pow sin cos`, all integer; `sin` and `cos` take degrees and scale by 256 |
+| `random` | `seed randrange randint` |
+| `storage`, `file` | AppVar bytes that persist between runs |
+| `sprite` | AppVar sprites from project assets (CE only) |
+| `color` | Color constants and conversions. On classic, colors are 0 (white) or 1 (black) |
+| `graph` | The Flash App's graph screen (Flash App only) |
+
+Not implemented: FontLibC fonts (`ti84.font` has only color constants, so use
+`graphics.text()`), and scaled or rotated sprites. Calling these gives an error
+rather than doing nothing. Text with runtime coordinates and `text_int()` need
+the CE target. A failed `storage` read or write, such as a missing AppVar or a
+bad offset, ends the program.
+
+## Converting CEdev and ICE projects
+
+```powershell
+tipy-asm convert-project path\to\project -o converted
+```
+
+This writes a normal project, then compiles it and tells you whether it worked.
+Code with no TIpy equivalent, such as pointers, structs, and `switch`, becomes a
+`# TODO(convert)` comment and is listed in `CONVERSION_NOTES.md`. CEdev palette
+indices are not RGB565 colors, so check the colors of a converted program.
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests
+```
+
+`tests/asm_sim.py` runs generated assembly on a model of both CPUs, with the OS
+stubbed, and compares results with CPython. It is not an emulator, so test on
+CEmu or a calculator as well.
+
+## Documentation
+
+The guide and method reference live on the
+[`docs` branch](https://github.com/XSamuraiCoder/TIpy-asm/tree/docs). That branch holds
+only the documentation, and this one holds only the package.
+
+## Repository layout
+
+- `ti84asm/` contains the compiler, runtime helpers, CLI, and build drivers.
+- `ti84asm/toolchain/` contains the bundled [fasmg](https://flatassembler.net/) (see
+  `fasmg-license.txt`) and CE includes from
+  [CE-Programming/asm-docs](https://github.com/CE-Programming/asm-docs).
+- `ti84libs/` contains the built-in libraries; `ti84libs/api.py` is the table of
+  public methods.
+- `ti84/` contains the editor stubs.
+- `examples/` contains example projects.
+
+This fork retains the upstream [MIT license](LICENSE).

tipy_asm-1.0.0/README.md

@@ -0,0 +1,173 @@
+# TIpy-asm
+
+TIpy-asm is a Python-based fork of [Voblit/py2ez80](https://github.com/Voblit/py2ez80),
+a compiler for writing TI calculator programs in a restricted, Python-like
+language. It compiles source on a computer; Python itself does not run on the
+calculator.
+
+## Quick start
+
+Requires Python 3.10 or newer:
+
+```powershell
+python -m pip install .
+tipy-asm new mygame
+cd mygame
+tipy-asm build
+```
+
+That creates a program you can move around with the arrow keys, and writes
+`bin\MYGAME.8xp`. CE builds need nothing else and work offline: the package
+includes fasmg for Windows and Linux (x64 and x86), plus its CE includes. On other
+systems, put fasmg on PATH. Run `tipy-asm doctor` to see what is installed.
+
+`examples\catch` is a complete small game. The package also installs the shorter
+command alias `ti84py`.
+
+## Targets
+
+- **TI-84 Plus CE assembly:** eZ80 assembly, or a `.8xp` program built with the
+  bundled fasmg.
+- **Classic TI-83+/TI-84 Plus:** Z80 assembly, or a `.8xp` program built with
+  SPASM-ng, which you install yourself.
+- **TI-84 Plus CE Flash App:** translated to C, then built and packaged with
+  CEdev and an installer project that you provide.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `tipy-asm new FOLDER` | Create a project that builds straight away |
+| `tipy-asm build [SOURCE]` | Build `.8xp` programs and assets. Add `--watch` to rebuild on save, or `--keep-asm` to keep the assembly |
+| `tipy-asm check [SOURCE]` | Report errors on each target without writing files. `--target flash` checks the Flash App backend |
+| `tipy-asm compile [SOURCE]` | Write assembly without assembling it |
+| `tipy-asm flash-app [SOURCE]` | Build a CE Flash App and its installer |
+| `tipy-asm api [LIBRARY]` | List library methods and the targets that support them |
+| `tipy-asm doctor` | Show installed tools and the project's setup |
+| `tipy-asm clean` | Delete the project's build folder |
+| `tipy-asm convert-project PATH` | Convert a CEdev or ICE project into a TIpy-asm project |
+| `tipy-asm convbin`, `convimg`, `convert-image` | Convert data and images by hand |
+| `tipy-asm convfont` | Convert `.fnt` and text-format fonts, matching CEdev's `convfont` byte for byte |
+
+With no source, commands use the project in the current folder or the nearest
+parent folder. Errors are printed as `FILE:LINE: error: MESSAGE` with the source
+line, in the original file, so editors can link to them.
+
+## Projects
+
+A project is configured under `[tool.tipy]` in its `pyproject.toml`:
+
+```toml
+[tool.tipy]
+name = "BOUNCE"          # calculator program name, 1-8 letters or digits
+main = "src/main.py"     # default
+target = "ce"            # classic, ce, or both; default ce
+bindir = "bin"           # default
+keep_asm = false
+
+[tool.tipy.toolchain]    # optional; the default is to search PATH
+ce_assembler = "tools/fasmg.exe"
+classic_assembler = "tools/spasm.exe"
+
+[tool.tipy.flash]        # used by `tipy-asm flash-app`
+project_dir = "flash"    # folder containing installer/makefile
+optimize = "speed"       # or size
+
+[[tool.tipy.assets]]     # converted into bindir by each build, when out of date
+source = "assets/hero.png"
+name = "HERO"            # AppVar name; the default comes from the file name
+kind = "sprite"          # sprite, image, font, or binary; guessed from the suffix
+```
+
+`from settings import SPEED` includes `settings.py` from the main file's folder,
+and `from game.player import move` includes `game/player.py`.
+
+Image assets need Pillow: `python -m pip install "tipy-asm[images]"`. Send the
+asset's `.8xv` to the calculator along with the program:
+
+```python
+from ti84 import sprite
+hero = sprite.load("HERO")     # 0 if the AppVar is missing
+sprite.draw(hero, x, y)
+```
+
+## Language on the assembly targets
+
+The Flash App backend supports more of Python. The assembly targets support:
+
+- Functions with parameters, defaults, keyword arguments, return values, and
+  `global`. Recursion is rejected, because function variables are static.
+- `if`/`elif`/`else`, `while`, `for ... in range()` with runtime bounds, `break`,
+  `continue`, and `exit()`.
+- `+ - * // % << >> & | ^ ~`, comparisons, `and`, `or`, `not`, and `a if c else b`.
+  Integers are signed, 24-bit on CE and 16-bit on classic, and wrap on overflow.
+  `x // 0` is 0 and `x % 0` is `x`, because a calculator program cannot raise.
+- Module-level arrays: `TABLE = (1, 2, 3)` is read-only, and `scores = [0] * 10`
+  is writable. Runtime indexes are not bounds-checked.
+- `print()` of string literals and integers, and `abs`, `min`, and `max`.
+
+Strings exist only as literals, and there are no floats, classes, or lists of
+lists.
+
+## Libraries
+
+Import them with `from ti84 import graphics, keyboard`. Run `tipy-asm api NAME`
+for each method's signature and targets. The `ti84` package also has stubs, so
+VS Code/Pylance can complete these names.
+
+| Library | Provides |
+|---|---|
+| `graphics` | Pixels, lines, rectangles, circles, triangles, text, and sprites. Coordinates and colors can be runtime values, and are clipped to the screen |
+| `keyboard` | `read()` waits for a key, `get()` returns at once, `is_down(key)` tests a held key |
+| `math` | `abs min max clamp sign sqrt pow sin cos`, all integer; `sin` and `cos` take degrees and scale by 256 |
+| `random` | `seed randrange randint` |
+| `storage`, `file` | AppVar bytes that persist between runs |
+| `sprite` | AppVar sprites from project assets (CE only) |
+| `color` | Color constants and conversions. On classic, colors are 0 (white) or 1 (black) |
+| `graph` | The Flash App's graph screen (Flash App only) |
+
+Not implemented: FontLibC fonts (`ti84.font` has only color constants, so use
+`graphics.text()`), and scaled or rotated sprites. Calling these gives an error
+rather than doing nothing. Text with runtime coordinates and `text_int()` need
+the CE target. A failed `storage` read or write, such as a missing AppVar or a
+bad offset, ends the program.
+
+## Converting CEdev and ICE projects
+
+```powershell
+tipy-asm convert-project path\to\project -o converted
+```
+
+This writes a normal project, then compiles it and tells you whether it worked.
+Code with no TIpy equivalent, such as pointers, structs, and `switch`, becomes a
+`# TODO(convert)` comment and is listed in `CONVERSION_NOTES.md`. CEdev palette
+indices are not RGB565 colors, so check the colors of a converted program.
+
+## Tests
+
+```powershell
+python -m unittest discover -s tests
+```
+
+`tests/asm_sim.py` runs generated assembly on a model of both CPUs, with the OS
+stubbed, and compares results with CPython. It is not an emulator, so test on
+CEmu or a calculator as well.
+
+## Documentation
+
+The guide and method reference live on the
+[`docs` branch](https://github.com/XSamuraiCoder/TIpy-asm/tree/docs). That branch holds
+only the documentation, and this one holds only the package.
+
+## Repository layout
+
+- `ti84asm/` contains the compiler, runtime helpers, CLI, and build drivers.
+- `ti84asm/toolchain/` contains the bundled [fasmg](https://flatassembler.net/) (see
+  `fasmg-license.txt`) and CE includes from
+  [CE-Programming/asm-docs](https://github.com/CE-Programming/asm-docs).
+- `ti84libs/` contains the built-in libraries; `ti84libs/api.py` is the table of
+  public methods.
+- `ti84/` contains the editor stubs.
+- `examples/` contains example projects.
+
+This fork retains the upstream [MIT license](LICENSE).

tipy_asm-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tipy-asm"
+version = "1.0.0"
+description = "TIpy-asm: Python compiler for TI-84 Z80/eZ80 calculators"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["tomli>=2; python_version < '3.11'"]
+
+[project.optional-dependencies]
+images = ["Pillow>=10"]
+
+[project.scripts]
+tipy-asm = "ti84asm.cli:main"
+ti84py = "ti84asm.cli:main"
+convbin = "ti84asm.convbin:run_with_args"
+convimg = "ti84asm.convimg:run_with_args"
+convfont = "ti84asm.convfont:run_with_args"
+
+[tool.setuptools]
+packages = ["ti84asm", "ti84asm.project_convert", "ti84libs", "ti84"]
+
+[tool.setuptools.package-data]
+ti84asm = ["toolchain/bin/*", "toolchain/include/*", "toolchain/*.txt"]
+ti84 = ["*.pyi", "py.typed"]

tipy_asm-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tipy_asm-1.0.0/tests/test_api.py

@@ -0,0 +1,113 @@
+"""The API table, the compiler, the assembler, and the editor stubs must agree.
+
+Run with:  python -m unittest discover -s tests -v
+"""
+import ast
+import subprocess
+import tempfile
+import unittest
+from pathlib import Path
+
+from ti84asm.compiler import Compiler
+from ti84asm.errors import CompileError
+from ti84libs.api import API
+
+STUBS = Path(__file__).resolve().parent.parent / "ti84"
+
+
+def program(library: str, example: str) -> str:
+    imports = sorted({library, "keyboard", "color"})
+    lines = [f"from ti84 import {name}" for name in imports]
+    return "\n".join((*lines, "x = 3", "y = 4", "z = 0", "score = 5", "hero = 0", example, ""))
+
+
+def examples():
+    for library, methods in API.items():
+        for name, method in methods.items():
+            if method.example:
+                yield library, name, method
+
+
+class ApiTableTests(unittest.TestCase):
+    def test_every_example_compiles_on_its_targets(self):
+        for library, name, method in examples():
+            for target in method.targets:
+                with self.subTest(library=library, method=name, target=target):
+                    assembly = Compiler("T", target).compile(program(library, method.example))
+                    self.assertNotIn("TODO", assembly)
+
+    def test_every_ce_example_assembles_with_fasmg(self):
+        from ti84asm.fasmg import ensure_ce_includes, ensure_fasmg
+
+        root, fasmg = ensure_ce_includes(), ensure_fasmg()
+        for library, name, method in examples():
+            if "ce" not in method.targets:
+                continue
+            with self.subTest(library=library, method=name), tempfile.TemporaryDirectory() as folder:
+                source, output = Path(folder) / "t.asm", Path(folder) / "t.8xp"
+                source.write_text(Compiler("T", "ce").compile(program(library, method.example)), encoding="ascii")
+                result = subprocess.run([fasmg, str(source), str(output)], cwd=root,
+                                        text=True, capture_output=True)
+                self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
+                self.assertTrue(output.is_file())
+
+    def test_methods_unavailable_on_a_target_say_so(self):
+        for library, name, method in examples():
+            for target in {"ce", "classic"} - set(method.targets):
+                with self.subTest(library=library, method=name, target=target):
+                    with self.assertRaisesRegex(CompileError, "not available on the"):
+                        Compiler("T", target).compile(program(library, method.example))
+
+    def test_stubs_declare_exactly_the_public_api(self):
+        for library, methods in API.items():
+            if library == "graph":
+                continue
+            tree = ast.parse((STUBS / f"{library}.pyi").read_text(encoding="utf-8"))
+            declared = {node.name for node in tree.body if isinstance(node, ast.FunctionDef)}
+            with self.subTest(library=library):
+                self.assertTrue({name for name, method in methods.items() if method.targets} <= declared,
+                                f"missing from the stub: {sorted(set(methods) - declared)}")
+                from ti84libs.api import flash_available
+                extra = {name for name in declared - set(methods) if not flash_available(library, name)}
+                self.assertFalse(extra, f"stub declares methods nothing implements: {sorted(extra)}")
+
+
+class ErrorMessageTests(unittest.TestCase):
+    def error(self, source: str, target: str = "ce") -> str:
+        with self.assertRaises(CompileError) as caught:
+            Compiler("T", target).compile(source)
+        return str(caught.exception)
+
+    def test_misspelled_method_gets_a_suggestion(self):
+        message = self.error("from ti84 import graphics\ngraphics.pixl(1, 2)\n")
+        self.assertIn("line 2:", message)
+        self.assertIn("did you mean graphics.pixel()", message)
+
+    def test_missing_import_says_what_to_add(self):
+        self.assertIn("from ti84 import graphics", self.error("graphics.clear()\n"))
+
+    def test_misspelled_library_and_function_get_suggestions(self):
+        self.assertIn("did you mean graphics", self.error("from ti84 import grafics\n"))
+        self.assertIn("did you mean spin()", self.error("def spin():\n    pass\nspinn()\n"))
+
+    def test_void_method_cannot_be_used_as_a_value(self):
+        self.assertIn("does not return a value", self.error("from ti84 import graphics\nx = graphics.clear()\n"))
+
+    def test_retired_and_flash_only_libraries_point_elsewhere(self):
+        self.assertIn("ti84.storage", self.error("from ti84 import fileioc\n"))
+        self.assertIn("flash-app", self.error("from ti84 import graph\n"))
+
+    def test_font_methods_point_to_graphics_text(self):
+        self.assertIn("graphics.text", self.error('from ti84 import font\nx = font.load("F")\n'))
+
+    def test_unsupported_syntax_names_the_feature_and_line(self):
+        message = self.error("x = 1\ny = x / 2\n")
+        self.assertTrue(message.startswith("line 2:"), message)
+        self.assertIn("true division", message)
+
+    def test_undefined_variable_gets_a_suggestion(self):
+        self.assertIn("did you mean 'score'", self.error("score = 1\nx = scor + 1\n"))
+
+
+if __name__ == "__main__":
+    unittest.main()