{"id":50678562,"url":"https://github.com/dbohdan/starlark-python","last_synced_at":"2026-06-20T06:03:18.130Z","repository":{"id":356159311,"uuid":"1229127170","full_name":"dbohdan/starlark-python","owner":"dbohdan","description":"Starlark in pure Python (ported from Java)","archived":false,"fork":false,"pushed_at":"2026-06-09T23:13:12.000Z","size":611,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-09T23:19:56.409Z","etag":null,"topics":["interpreter","python","starlark","starlark-python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/starlark/","language":"Python","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/dbohdan.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security/2026-05-05-review-deepseek-v4-pro.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-04T18:18:33.000Z","updated_at":"2026-05-31T18:34:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dbohdan/starlark-python","commit_stats":null,"previous_names":["dbohdan/starlark-python"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/dbohdan/starlark-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbohdan%2Fstarlark-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbohdan%2Fstarlark-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbohdan%2Fstarlark-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbohdan%2Fstarlark-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbohdan","download_url":"https://codeload.github.com/dbohdan/starlark-python/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbohdan%2Fstarlark-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34558894,"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-20T02:00:06.407Z","response_time":98,"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":["interpreter","python","starlark","starlark-python"],"created_at":"2026-06-08T17:00:35.069Z","updated_at":"2026-06-20T06:03:18.125Z","avatar_url":"https://github.com/dbohdan.png","language":"Python","funding_links":[],"categories":["Getting Started"],"sub_categories":[],"readme":"# Starlark in Python\n\n[![PyPI package version badge.](https://img.shields.io/pypi/v/starlark)](https://pypi.org/project/starlark/)\n![Python 3.11, 3.12, 3.13, 3.14 supported.](https://img.shields.io/badge/python-3.11_%7C_3.12_%7C_3.13_%7C_3.14-blue)\n[![PyPI download statistics badge.](https://img.shields.io/pypi/dm/starlark)](https://pypistats.org/packages/starlark)\n\nThis project provides a pure-Python implementation of the [Starlark][starlark] configuration language.\nStarlark in Python was ported by AI from the Java reference implementation that ships with [Bazel][bazel].\nYou can read [how it was ported](https://dbohdan.com/starlark-python).\n\n[starlark]: https://github.com/bazelbuild/starlark\n[bazel]: https://github.com/bazelbuild/bazel\n\n## Status\n\nConformance test files are passing with the exception of 4 [expected failures](https://docs.pytest.org/en/stable/how-to/skipping.html).\nThose are all documented divergences from the Java reference (UTF-16 string indexing, 32-bit `range()` bounds, and a Bazel-specific `mutablestruct` test helper).\n\n## Goals\n\n- Pure Python\n  - Therefore usable in a cross-platform [zipapp](https://docs.python.org/3/library/zipapp.html)\n- No dependencies\n- Simple implementation (a tree-walking interpreter)\n- [Safe to run untrusted code](#security)\n- Passes the conformance suite from Bazel (copied verbatim in [`conformance/`](conformance/))\n\n## Non-goals\n\n- Performance\n- Supporting old Python versions (3.11+ is currently required)\n\n## Quick start\n\n```python\nimport starlark\n\n# Evaluate an expression.\nstarlark.eval(\"1 + 2 * 3\")  # 7\n\n# Run a Starlark file.\nm = starlark.exec_file('''\ndef fact(n):\n    result = 1\n    for i in range(1, n + 1):\n        result *= i\n    return result\n\nz = fact(5)\n''')\n\nm.globals[\"z\"]  # 120\n```\n## Users\n\n- [dbohdan.com SSG](https://dbohdan.com/about#metadata-reuse): the site owner has switched the custom static site generator from TOML to Starlark for metadata reuse.\n- [Lark Cycles](https://github.com/dbohdan/lark-cycles): this Python/Tkinter/Starlark port of the 1988 Amiga programming game [_Warrior Cycles_](https://corewar.co.uk/warriorcycles.htm) by Rico Mariana was developed as a demo for Starlark in Python.\n- [Remarshal](https://github.com/remarshal-project/remarshal): a format converter between CBOR, JSON, MessagePack, TOML, and YAML 1.1 \u0026 1.2.\n  Remarshal gained the ability to modify the data it converted with Starlark.\n  Part of the motivation for Starlark in Python was to add this functionality without a Go or Rust dependency.\n\n## API\n\nSee [`docs/`](docs/).\n\n## CLI\n\nThe package installs a `starlark-python` console script.\n(We picked a suffixed name so it doesn't shadow `starlark` from go.starlark.net, which we use for cross-validation.)\nIt can also be run as a zipapp:\n\n```sh\npoe zipapp                                 # builds ./starlark-python.pyz (~560K)\n./starlark-python.pyz -c \"1 + 2 * 3\"       # 7\n./starlark-python.pyz path/to/script.star\n```\n\n## `load()` and the host API\n\nThe runtime does not load files itself; the host supplies a `Loader` callable.\n`eval/loader.py` ships a simple file-based loader you can plug in:\n\n```python\nfrom starlark.eval.loader import FileLoader\nimport starlark\n\nloader = FileLoader(exec_file=starlark.exec_file, search_paths=[\".\", \"lib\"])\nstarlark.exec_file(open(\"main.star\").read(), loader=loader)\n```\n\n`load(\"foo.star\", \"bar\")` then resolves `foo.star` against `loader`.\n`FileLoader` only allows loading files from the directories in `search_paths`;\nit rejects absolute paths, `..` traversal, and symlink escapes.\nList just those directories that you want Starlark code to access.\n\n## Security\n\nStarlark in Python is new and has **not** been extensively reviewed and tested.\n\nStarlark is a sandboxed language.\nA `.star` program cannot read or write files, open sockets, spawn processes, or reach any Python object the host did not explicitly hand it.\nOpt-on resource limits (`max_steps`, `max_allocs`) limit CPU and memory for hosts that accept untrusted input.\n\nWhat we defend against, what we don't defend against, and the\npublic limits API are documented in [`security/threat-model.md`](security/threat-model.md).\nIn short: we mitigate DoS-style malicious values; defending against deliberately crafted (but otherwise valid) values is a host responsibility, the same as with JSON or TOML.\n\n## Documented divergences from the Java reference\n\nThese are intentional:\n\n- **Integers are Python `int`.**\n  Arbitrary precision; no overflow.\n  The Java reference uses a `StarlarkInt` type that is a union of `int32`, `int64`, and `BigInteger`.\n- **Integer magnitude is bounded.**\n  A Starlark integer is hard-capped at `MAX_INT_BITS = 2^19` bits (~158k decimal digits) to bound per-operation CPU.\n  The Java reference's `BigInteger` is unbounded; this cap is far above any realistic configuration value, and operations that would exceed it raise a clean `EvalError`.\n- **Strings are indexed by Unicode code point.**\n  The Java reference indexes by UTF-16 code unit, which produces surprising results for non-BMP characters.\n  The spec leaves this implementation-defined.\n- **No 32-bit range checks for `range()`, `*` repeat, etc.**\n  The Java reference rejects allocations whose length doesn't fit in a signed 32-bit int.\n  We instead cap container allocations at 16M elements with a less specific error message.\n\nThe conformance suite includes a handful of tests that depend on the Java reference's exact error wording for these checks;\nthey are listed in `XFAIL_FILES` in `tests/test_conformance.py`.\n\n## Layout\n\n- [**`conformance/`**](conformance/) – `.star` conformance tests, copied from Bazel.\n- [**`src/starlark/`**](src/starlark/) – The actual port.\n  - [`eval/`](src/starlark/eval/) – Value model, evaluator, builtins, methods, loader.\n  - [`syntax/`](src/starlark/syntax/) – Lexer, parser, AST, resolver.\n  - [`cmd.py`](src/starlark/cmd.py) – CLI entry point.\n- [`tests/`](tests/) – Pytest suite (unit + conformance + property-based).\n- [`HISTORY.md`](HISTORY.md) – Original 14-phase plan + append-only journal.\n\n## Development\n\nInstall [Poe the Poet](https://poethepoet.natn.io/) to run the tasks (`uv tool install poethepoet`, `pipx install poethepoet`).\n\n```sh\nuv sync           # Install deps\npoe test          # ~610 tests, ~3s\npoe lint          # Ruff\npoe typecheck     # Pyright\npoe zipapp        # Build ./starlark-python.pyz\n```\n\n`tests/test_cross_validation.py` runs a curated set of programs under both this interpreter and the [starlark-go][starlark-go] CLI and asserts they produce identical output.\nTo enable, install the Go implementation and make sure it's on `PATH`:\n\n```sh\ngo install go.starlark.net/cmd/starlark@latest\n```\n\n[starlark-go]: https://github.com/google/starlark-go\n\n## License\n\nApache 2.0.\nSee [`LICENSE`](LICENSE).\n\nThis is a derivative work: the lexer, parser, resolver, evaluator, and value model are ported from the Java reference implementation maintained by **The Bazel Authors** as part of [bazelbuild/bazel][bazel].\nThe conformance test files under [`conformance/`](conformance/) are copied verbatim from that\nproject.\n[`docs/spec.md`](docs/spec.md) is fetched verbatim from [bazelbuild/starlark][starlark-spec] for reference.\n\n[starlark-spec]: https://github.com/bazelbuild/starlark\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbohdan%2Fstarlark-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbohdan%2Fstarlark-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbohdan%2Fstarlark-python/lists"}