pll-python 0.2.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Daniel Patterson.
+
+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.

package/README.md

@@ -11,11 +11,13 @@ Needs **Node 22 or newer** (the oldest Node still receiving support).
 npx pll-python hw.py
 ```
 
+(Not `npx pll`, which is a different package.)
+
 Or install it:
 
 ```bash
 npm install -g pll-python
-pll hw.py
+pll hw.py            # or: pll-python hw.py
 ```
 
 ## Language levels
@@ -41,25 +43,31 @@ same way everywhere, which is the point of putting it in the file.
 
 ## Tests
 
-`test_*` functions in the same file run before the file does, as they do in
-the editor:
+`test_*` functions in the same file run once the program finishes, against
+what it defined, as they do in the editor. A test that prints shows what it
+printed under its result; `@pytest.mark.skip`, `skipif` and `xfail` work as
+in pytest:
 
 ```bash
-pll hw.py            # tests, then the program
+pll hw.py            # the program, then its tests
 pll hw.py --no-tests # just the program
 ```
 
 ## Options
 
 ```
---no-tests           do not run the file's test_* functions first
+--no-tests           do not run the file's test_* functions, which
+                     otherwise run once the program finishes
 --save-images <dir>  write pictures there as .svg
--q, --quiet          only the program's own output
+-q, --quiet          only the program's own output and what went wrong:
+                     errors, failed tests, files not loaded or not saved
 --no-color           never use ANSI colour
 -h, --help
--v, --version
+-V, --version
 ```
 
+`-v` is not an option: Python's `-v` means something else entirely.
+
 ## Authoring Examplar bundles
 
 Examplar assesses a *test suite* rather than an implementation: students
@@ -147,6 +155,11 @@ Publish the bundle at a URL and point students at it from their file:
 #examplar https://cs2000.example/hw3.json
 ```
 
+The check runs wherever the file does - in the editor, and with `pll
+hw3.py`, which prints the same cards to stderr. Fetched bundles are cached
+(under `$PLL_CACHE_DIR`, `$XDG_CACHE_HOME` or `~/.cache`), so a run without a
+network still gets its verdict. The verdict does not change the exit code.
+
 If any of your students use **vscode.dev** or a codespace, the extension host
 there is a browser, so serve the bundle with CORS
 (`samples/examplar_serve.mjs` in the repository is a dependency-free server
@@ -188,14 +201,22 @@ be fast and honest rather than secret.
 | Code | Meaning |
 | --- | --- |
 | 0 | Ran, and any tests passed |
-| 1 | The program raised |
+| 1 | The program raised, or Ctrl+C stopped it (even if it caught the `KeyboardInterrupt`; its tests are then not run) |
 | 2 | Level checks found problems, so it was not run |
 | 3 | A test failed |
-| 64 | Bad usage, or PLL could not start |
+| 64 | Bad usage, or Python could not start (it is given two minutes) |
+| 130 | A second Ctrl+C gave up waiting for the program to stop |
+| 141 | Its output could no longer be read - `pll hw.py \| head` |
+| 143 | It was ended by SIGTERM |
 
 Distinct codes so an autograder can tell "the level rejected this" from
 "the tests failed" from "it crashed".
 
+A program that ends itself with `sys.exit(n)` exits with `n` instead, as it
+would under `python` - so a program can produce any of these codes itself.
+`sys.exit()` is 0, and `sys.exit("message")` prints the message and is 1.
+A status other than 0 outranks a failed test's 3.
+
 ## Piping
 
 The program's own stdout is the **only** thing on stdout. Everything
@@ -206,22 +227,29 @@ goes to stderr. So this captures exactly what the program printed:
 pll hw.py > output.txt
 ```
 
-`input()` reads stdin, so piping works too:
+`input()` and `sys.stdin.read()` read stdin, exactly as given, so piping
+works too:
 
 ```bash
 printf 'Ada\n' | pll greet.py
 ```
 
+Ctrl+C stops the program wherever it is - waiting for input, in
+`time.sleep`, or waiting for an address to answer - as it would under
+`python`.
+
 ## What differs from the editor
 
 - **Pictures cannot be drawn in a terminal.** Each one prints a note with
-  its size; `--save-images` writes them as `.svg` instead.
+  its size; `--save-images` writes them as `.svg` instead. A matplotlib
+  figure is a picture like any other: `plt.show()` prints the note.
 - **Reactors (`big_bang`, `animate`) do not run.** They need the editor's
   interactions panel to animate; here they print a note and the rest of the
   program continues. Their logic is still testable — `simulate_trace(n)`
   works fine and needs no clock.
 - **Tables do print**, as text. Their content is already text, so there is
-  nothing to lose.
+  nothing to lose; a tab, a new line or an escape in a cell is written out,
+  as `\t`, `\n` and `\x1b`.
 
 Everything else is the same code: the same Pyodide worker, the same Python
 libraries, the same analyzers and the same wording for errors.
@@ -229,8 +257,30 @@ libraries, the same analyzers and the same wording for errors.
 ## Files next to your program
 
 `open("data.csv")` and `pd.read_csv("data.csv")` read files in the same
-folder as the script, and files the program writes appear there afterwards —
-the same as in the editor.
+folder as the script or a folder inside it (`open("data/2024.csv")`), and
+`__file__` is set, so `Path(__file__).parent` works. Files the program
+writes appear there afterwards, and files it deletes are deleted — the same
+as in the editor, with the same limits: at most 100 files, each at most
+2 MB and 8 MB in all, nearest first; hidden and tools' folders (`.git`,
+`venv`, `node_modules`) are left out. Files move as bytes, so a CSV in
+another encoding or a picture arrives exactly as it is.
+
+What is not loaded or not saved is said, even with `-q`, with why. A
+file is never saved over when the program was not given it (it was over a
+limit, say: saving would replace it with only what the program wrote), when
+it changed on disk while the program ran, or when it is an existing `.py`.
+
+## Packages
+
+`import pandas`, `numpy`, `matplotlib`, `requests`, pytest (for the tests)
+and the rest of Pyodide's packages are downloaded the first time they are
+used, which needs the network; `pll` says so. They are found from the
+program's imports wherever they are written, and from those of the files of
+yours it imports. A URL read with `urllib`, `requests` or pandas arrives
+byte for byte; an error page raises `HTTPError`, and an address that does
+not answer gives up after 60 seconds, or the program's own `timeout`. They are kept beside Pyodide in the install, or in your cache
+(`$XDG_CACHE_HOME/pll-python` or `~/.cache/pll-python`) when the install
+cannot be written to.
 
 ## Licence