{"id":18989418,"url":"https://github.com/source-academy/py-slang","last_synced_at":"2026-06-15T21:31:36.777Z","repository":{"id":95974826,"uuid":"590053765","full_name":"source-academy/py-slang","owner":"source-academy","description":"Implementations of sublanguages of Python for SICPy","archived":false,"fork":false,"pushed_at":"2026-06-14T06:52:38.000Z","size":1862,"stargazers_count":5,"open_issues_count":15,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-14T08:20:00.493Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/source-academy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-01-17T14:59:49.000Z","updated_at":"2026-06-14T06:51:41.000Z","dependencies_parsed_at":"2025-05-24T09:28:37.074Z","dependency_job_id":"26539dad-05e8-4a06-a1da-abdcdf4d0dda","html_url":"https://github.com/source-academy/py-slang","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/source-academy/py-slang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/source-academy%2Fpy-slang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/source-academy%2Fpy-slang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/source-academy%2Fpy-slang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/source-academy%2Fpy-slang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/source-academy","download_url":"https://codeload.github.com/source-academy/py-slang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/source-academy%2Fpy-slang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34381759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T17:06:38.170Z","updated_at":"2026-06-15T21:31:36.772Z","avatar_url":"https://github.com/source-academy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Python variant for SICP\n\n## What is py-slang?\n\n`py-slang` is a Python implementation developed specifically for the Source Academy online learning environment. Unlike previous versions where Python was treated as a subset within [js-slang](https://github.com/source-academy/js-slang), py-slang now stands as an independent language implementation. It features its own parser, csemachine, and runtime, designed to process a tailored subset of Python for educational purposes.\n\nIt contains multiple [engines](https://github.com/source-academy/py-slang/tree/main/src/engines) including the CSE machine, a WASM compiler and an SVML compiler.\n\n## Usage\n\nTo create a production build, run\n\n```shell\n# prompts for the evaluator to build\nyarn build\n\n# OR\n\n# specifies the evaluator to build (list given below)\nyarn build --evaluator PyCseEvaluator1\n\n# OR\n\n# builds all evaluators\nyarn build --all\n```\n\nFor development builds, run\n\n```shell\nyarn dev\n\n# OR\n\nyarn dev --evaluator PyCseEvaluator1\n\n# OR\n\nyarn dev --all\n```\n\nThe difference between `yarn build` and `yarn dev` is that `yarn dev` enters [watch mode](https://rollupjs.org/command-line-interface/#w-watch) after building the initial changes. It monitors source files for any changes and automatically rebuilds only affected code when files are modified, making builds much faster during development.\n\nIn either case, the evaluator is compiled to `dist/\u003cevaluatorName\u003e.js` and `dist/\u003cevaluatorName\u003e.cjs`.\n\n### List of evaluators\n\n| Name                                                                                                                                             | Description                                                                                                                                                                                        |\n| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [PyCseEvaluator1](https://github.com/source-academy/py-slang/blob/36351039fcd1f6dfbac3df10bf1ef084a44f029b/src/conductor/PyCseEvaluator.ts#L95)  | Interprets Python §1 programs using the CSE machine                                                                                                                                                |\n| [PyCseEvaluator2](https://github.com/source-academy/py-slang/blob/36351039fcd1f6dfbac3df10bf1ef084a44f029b/src/conductor/PyCseEvaluator.ts#L101) | Interprets Python §2 programs using the CSE machine                                                                                                                                                |\n| [PyCseEvaluator3](https://github.com/source-academy/py-slang/blob/36351039fcd1f6dfbac3df10bf1ef084a44f029b/src/conductor/PyCseEvaluator.ts#L107) | Interprets Python §3 programs using the CSE machine                                                                                                                                                |\n| [PyCseEvaluator4](https://github.com/source-academy/py-slang/blob/36351039fcd1f6dfbac3df10bf1ef084a44f029b/src/conductor/PyCseEvaluator.ts#L113) | Interprets Python §4 programs using the CSE machine                                                                                                                                                |\n| [PyWasmEvaluator](https://github.com/source-academy/py-slang/tree/main/src/conductor/PyWasmEvaluator.ts)                                         | Compiles Python §4 programs into WebAssembly and runs it                                                                                                                                           |\n| [PySvmlEvaluator](https://github.com/source-academy/py-slang/tree/main/src/conductor/PySvmlEvaluator.ts)                                         | Evaluates the Python AST via a handwritten Typescript compiler and interpreter                                                                                                                     |\n| [PySvmlSinterEvaluator](https://github.com/source-academy/py-slang/tree/main/src/conductor/PySvmlSinterEvaluator.ts)                             | Evaluates the Python AST with the same compiler as `PySvmlEvaluator`, but a different interpreter. It uses the WebAssembly port of the [Sinter](https://github.com/source-academy/sinter) project. |\n\n### Using the evaluators\n\nRefer to the [Conductor's Quick Start Guide](https://github.com/source-academy/conductor?tab=readme-ov-file#quick-start-guide)\n\n### Running the Wasm evaluator locally\n\nTo run the Wasm compiler locally, run\n\n```shell\nyarn wasm \u003cpath to python file\u003e\n```\n\n### Running the test suite\n\nEnsure that all tests pass before committing.\n\n```shell\nyarn test\n```\n\n### Regenerating the AST types and Parser\n\nThe AST types need to be regenerated after changing\nthe AST type definitions in `generate-ast.ts`.\n\n```shell\nyarn regen\n```\n\nSimilarly, the parser needs to be regenerated after changing\nthe Python grammar in `python.ne`.\n\n```shell\nyarn compile-grammar\n```\n\n## Prior Reading\n\nThese repositories are relevant to `py-slang`, and may be useful if stuck\n\n- The [Conductor](https://github.com/source-academy/conductor) repository -- the framework which provides a communication framework between languages and hosts\n- The [Language Directory](https://github.com/source-academy/language-directory) -- the repository for languages using the Conductor framework\n\n## How it works\n\nThe evaluation of the program generally consists of several stages\n\n- The Conductor runner plugin's (`Py...Evaluator`) entry point -- gets called via RPC and calls the rest of the steps\n- Tokenization (refer to `src/parser/lexer.ts`) -- splits the program into tokens using Moo.\n- Parsing (refer to `src/parser/parser-adapter.ts`) -- converts the tokens into an AST using Nearley.\n- Resolution (refer to `src/resolver/resolver.ts`) -- visits every node and checks variable bindings. It also runs the validators on every node.\n- Validation (refer to `docs/parsing/validators.md`) -- restricts features based on the Python chapter (e.g., for loops banned in chapter 1).\n- Execution -- the actual code execution, logically depends on the evaluator used.\n- Output -- The outputs and errors are sent via the Conductor framework\n\n_Note: the Wasm compiler uses a different resolver and validator, refer to `src/engines/wasm/builderGenerator.ts`_\n\n## Acknowledgements\n\nThis project adapts the `Conductor Interface` from [source-academy/conductor](https://github.com/source-academy/conductor), which is part of the Source Academy ecosystem.\n\nSpecifically, all files under the following folders are derived from the conductor repository:\n\n- `src/conductor/`\n- `src/common/`\n- `src/conduit/`\n\nAll credits go to the original authors of the Source Academy Conductor Interface.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsource-academy%2Fpy-slang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsource-academy%2Fpy-slang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsource-academy%2Fpy-slang/lists"}